docs: publish stale PR salvage ledger (#1788)

2026-05-13 08:03:04 +08:00 · 2026-05-12 03:50:34 -04:00
parent de559bddd2
commit 8cbf6763c4
4 changed files with 200 additions and 3 deletions
--- a/docs/ECC-2.0-GA-ROADMAP.md
+++ b/docs/ECC-2.0-GA-ROADMAP.md
@@ -33,6 +33,9 @@ As of 2026-05-12:
 - `docs/legacy-artifact-inventory.md` records that no `_legacy-documents-*`
  directories exist in the current checkout and classifies
  `legacy-command-shims/` as an opt-in archive/no-action surface.
+- `docs/stale-pr-salvage-ledger.md` records stale PR salvage outcomes,
+  skipped PRs, superseded work, and the remaining #1687 translator/manual
+  review tail.
 - AgentShield PR #53 reduced two context-rule false positives and closed the
  remaining AgentShield issues.
 - ECC PR #1778 recovered the useful stale #1413 network/homelab architect-agent
@@ -192,5 +195,3 @@ Acceptance:
   AgentShield repo.
 2. Audit ECC Tools billing and check-run surfaces before any native GitHub
   payments announcement.
-3. Build the stale-PR salvage ledger from closed cleanup batches, then port
-   useful pieces in small attributed maintainer PRs.
--- a/docs/legacy-artifact-inventory.md
+++ b/docs/legacy-artifact-inventory.md
@@ -35,7 +35,7 @@ The only tracked legacy directory currently found by filename scan is
 | --- | --- | --- | --- |
 | `_legacy-documents-*` directories | Archive/no-action | No matching directories exist in the tracked checkout as of 2026-05-12. | Re-run the scan before release. If any appear, add each directory to this table before publishing. |
 | `legacy-command-shims/` | Archive/no-action | `legacy-command-shims/README.md` states these retired short-name shims are opt-in and no longer loaded by the default plugin command surface. | Keep as an explicit compatibility archive. Do not move these back into the default plugin surface without a migration decision. |
-| Closed-stale PR salvage ledger | Landed | `~/.cluster-swarm/handoffs/ecc-stale-salvage-ledger-20260512-0210.md` records useful stale work recovered through maintainer PRs. | Continue using the ledger pattern for future stale closures. |
+| Closed-stale PR salvage ledger | Landed | `docs/stale-pr-salvage-ledger.md` records useful stale work recovered through maintainer PRs. | Continue using the ledger pattern for future stale closures. |
 | #1687 zh-CN localization tail | Translator/manual review | Large safe subsets landed in #1746-#1752; remaining pieces require translator/manual review per salvage ledger. | Do not blindly cherry-pick. Split by docs, commands, agents, and skills if a translator review lane opens. |

 ## Legacy Command Shim Contents
--- a/docs/stale-pr-salvage-ledger.md
+++ b/docs/stale-pr-salvage-ledger.md
@@ -0,0 +1,99 @@
+# Stale PR Salvage Ledger
+
+This ledger records useful work recovered from stale, conflicted, or closed PRs.
+The rule is simple: queue cleanup closes stale PRs, but it does not discard
+useful work. Maintainers should inspect the closed diff, port compatible pieces
+on fresh branches, and credit the source PR.
+
+## Classification States
+
+| State | Meaning |
+| --- | --- |
+| Salvaged | Useful work was ported to current `main` through a maintainer PR. |
+| Already present | Current `main` already contained the useful work before salvage. |
+| Superseded | Current `main` solved the same problem differently. |
+| Skipped | The PR was accidental, too broad, unsafe, or too low-signal to port. |
+| Translator/manual review | Content may be useful, but needs human language/domain review before import. |
+
+## Salvaged Into Current Main
+
+| Source PR | Original contribution | Salvage result |
+| --- | --- | --- |
+| #1309 | Trading/community project material | Salvaged in #1761 as a neutral community-project README listing. |
+| #1322 | Vietnamese README translation | Salvaged in #1764 as `docs/vi-VN/README.md` plus selector updates. |
+| #1326 | Angular developer skill and rules | Salvaged in #1763 with current skill, rules, install wiring, and catalog updates. |
+| #1328 | Continuous-learning Windows UTF-8 stdout fix | Salvaged in #1761. |
+| #1329 | Plugin install detection hardening | Salvaged in #1761 through current harness audit detection support. |
+| #1334 | Windows desktop E2E skill | Salvaged in #1762 with install, package, and catalog wiring. |
+| #1352 | Qwen install target | Salvaged in #1738 through the current Qwen install target. |
+| #1413 | Network and homelab skills/agents | Salvaged through #1729, #1731, #1745, and #1778. |
+| #1429 | JoyCode install target | Salvaged in #1737 through the current JoyCode install target. |
+| #1467 | Scientific skills and OpenCode discovery work | Useful USPTO and gget pieces salvaged in #1740; stale generated claims were not copied. |
+| #1493 | SessionStart context scoping | Salvaged in #1774 with current hook semantics and tests. |
+| #1498 | PRD planning flow | Salvaged in #1777. |
+| #1504 | Statusline/context monitor hooks | Salvaged in #1776 with current hook manifest structure and tests. |
+| #1528/#1529/#1547 | Astraflow and UModelVerse provider support | Salvaged in #1775 with current provider wiring and defensive tool-call parsing. |
+| #1558 | `agentic-os` skill | Salvaged in #1772. |
+| #1559 | `error-handling` skill | Salvaged in #1772. |
+| #1566 | Agent architecture audit skill | Salvaged in #1772. |
+| #1578 | OpenCode file-probe hardening | Salvaged in #1773. |
+| #1674 | Production audit skill | Salvaged in #1732 after supply-chain/privacy review and rewrite. |
+| #1687 | zh-CN localization sync | Large safe subsets salvaged in #1746-#1752; remaining pieces require translator/manual review. |
+| #1694 | Portfolio curation | Useful focused curation updates salvaged in #1723 and #1724. |
+| #1695 | Russian README translation | Ported in #1722. |
+| #1697 | Saved LLM selector config | Salvaged as part of provider config/tool schema work in #1720. |
+| #1699 | Windows post-edit-format path guard | Ported in #1719. |
+| #1700 | Provider tool serialization | Ported in #1720. |
+| #1705/#1780 | Production UI motion system | Salvaged in #1772, #1781, and #1782 with examples fixed before merge. |
+| #1713 | Swift language support | Ported in #1721. |
+| #1715 | CI personal-path validator hardening | Ported through CI validator hardening in #1717. |
+| #1727 | MySQL patterns skill | Salvaged in #1733. |
+| #1757 | Machine-learning engineering workflow | Salvaged in #1758 and tuned in #1759. |
+
+## Already Present Or Superseded
+
+| Source PR | Disposition |
+| --- | --- |
+| #1306 | Hook bug workarounds already exist on `main` as `docs/hook-bug-workarounds.md`. |
+| #1318 | Gemini agent adaptation utility was already present on current `main`. |
+| #1323 | Hook config update was already present on current `main`. |
+| #1337 | Catalog count update was superseded by current catalog-count sync. |
+| #1682/#1701 | Strategic compact hook-path fixes were merged directly or superseded by current docs fixes. |
+| JARVIS #4/#5/#6 | Stale failing dependency-only PRs; future dependency state should be regenerated by Dependabot. |
+
+## Skipped
+
+| Source PR | Reason |
+| --- | --- |
+| #1308 | Stale zh-CN sync would rewind or delete too much current tree state; concrete selector-link fix was already present. |
+| #1320 | Package-manager removal conflicts with the current npm/pnpm/yarn/bun CI policy. |
+| #1341 | Very large low-signal generated change with no safe focused salvage unit. |
+| #1416/#1465 | Accidental fork-sync PRs with no focused contribution. |
+| #1475 | One-line Gemini CLI bridge idea was too stale and underspecified to port safely. |
+
+## Remaining Manual-Review Backlog
+
+Only the #1687 localization tail remains plausibly useful but unsafe to
+auto-port.
+
+Handling rule:
+
+1. Keep #1687 in translator/manual review.
+2. Split any future work by surface: agents, commands, top-level docs, release
+   and count surfaces, then skills.
+3. Do not import stale top-level docs that carry old version or catalog-count
+   facts.
+4. Do not reopen old PRs unless the original author returns with a current
+   rebase; maintainer-side salvage should happen on fresh branches with
+   attribution.
+
+## Future Cleanup Rule
+
+For every stale/conflicted PR cleanup batch:
+
+1. Close or comment on the PR based on the queue policy.
+2. Add the source PR to this ledger or a dated successor ledger.
+3. Classify it as salvaged, already present, superseded, skipped, or
+   translator/manual review.
+4. If useful, port a small compatible slice on a fresh maintainer branch.
+5. Credit the source PR and author in the maintainer PR body.
--- a/tests/docs/stale-pr-salvage-ledger.test.js
+++ b/tests/docs/stale-pr-salvage-ledger.test.js
@@ -0,0 +1,97 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const repoRoot = path.resolve(__dirname, '..', '..');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    failed++;
+  }
+}
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8');
+}
+
+console.log('\n=== Testing stale PR salvage ledger ===\n');
+
+test('stale PR salvage ledger defines every disposition state', () => {
+  const source = read('docs/stale-pr-salvage-ledger.md');
+
+  for (const state of [
+    'Salvaged',
+    'Already present',
+    'Superseded',
+    'Skipped',
+    'Translator/manual review',
+  ]) {
+    assert.ok(source.includes(state), `Missing salvage state ${state}`);
+  }
+});
+
+test('stale PR salvage ledger preserves representative source attribution', () => {
+  const source = read('docs/stale-pr-salvage-ledger.md');
+
+  for (const pr of [
+    '#1309',
+    '#1322',
+    '#1326',
+    '#1413',
+    '#1493',
+    '#1528/#1529/#1547',
+    '#1674',
+    '#1687',
+    '#1705/#1780',
+    '#1757',
+  ]) {
+    assert.ok(source.includes(pr), `Missing source PR attribution for ${pr}`);
+  }
+});
+
+test('stale PR salvage ledger records skipped junk and superseded work', () => {
+  const source = read('docs/stale-pr-salvage-ledger.md');
+
+  for (const pr of ['#1306', '#1337', '#1341', '#1416/#1465', '#1475']) {
+    assert.ok(source.includes(pr), `Missing skipped or superseded PR ${pr}`);
+  }
+
+  assert.ok(source.includes('Accidental fork-sync PRs'));
+  assert.ok(source.includes('too low-signal'));
+});
+
+test('stale PR salvage ledger keeps the zh-CN tail manual-review only', () => {
+  const source = read('docs/stale-pr-salvage-ledger.md');
+
+  assert.ok(source.includes('Only the #1687 localization tail remains'));
+  assert.ok(source.includes('translator/manual review'));
+  assert.ok(source.includes('Do not import stale top-level docs'));
+});
+
+test('legacy inventory and roadmap link to the durable salvage ledger', () => {
+  const inventory = read('docs/legacy-artifact-inventory.md');
+  const roadmap = read('docs/ECC-2.0-GA-ROADMAP.md');
+
+  assert.ok(inventory.includes('docs/stale-pr-salvage-ledger.md'));
+  assert.ok(roadmap.includes('docs/stale-pr-salvage-ledger.md'));
+  assert.ok(roadmap.includes('#1687 translator/manual'));
+});
+
+if (failed > 0) {
+  console.log(`\nFailed: ${failed}`);
+  process.exit(1);
+}
+
+console.log(`\nPassed: ${passed}`);
+