2.10.0 — Knowledge Freshness: source digests, earlier sync, stricter Spec landing

Prospec 2.10.0

2.10.0 is a feature and correctness release that judges Knowledge freshness by source content, moves Knowledge sync before review, and rejects empty MODIFIED Spec blocks before archive. Synced Skills require CLI 2.10.0 or later. Existing modules need a reviewed source_digest stamp after upgrading; Knowledge without one is stale.

210 files changed · +4,705 / −1,088 · 5 merged PRs (#410, #413, #414, #416, #417) + 3 direct maintenance commits

---

✨ Headline features

Source-content Knowledge freshness (PRs #416, #417)

Knowledge freshness now compares each module's current source digest with the source_digest recorded by prospec knowledge verify. Same-day follow-up changes and merged older branches no longer pass merely because of commit dates; unchanged source survives history rewrites without becoming stale.

• Review, then stamp: prospec knowledge verify <module> records source_digest beside last_verified. Missing, outdated or unavailable digests never count as fresh. Shallow clones are judged by content rather than skipped; unavailable commit-time metadata stays null.
• Let Git record the work tree: temporary index copies compute the content Git would record, making equivalent unstaged, staged and committed content agree. Generated-artifact exclusions retain their declared project-relative scope. Prospec's recording uses temporary index/object storage; Git clean filters and configured hook.<name> hooks can still execute.
• Share one freshness decision: drift checks, lifecycle routing, Knowledge sync gates and MCP health consume the same digest result.

Knowledge sync before the final evidence snapshot (PR #414)

The standard route is now implement → knowledge-update → review → verify → archive. Complete Knowledge edits before the final test record and review baseline so later documentation sync does not immediately stale that evidence. If source or Knowledge changes afterward, refresh the affected evidence.

Proven backfill prepares Knowledge after promote and before verify; it retains its lighter route without plan/tasks. Routing, station handoffs and bilingual public workflow diagrams follow the updated order.

🐛 Bug fixes

• An empty MODIFIED Spec block could reach archive and leave convergence pending. Landing-fidelity checks now fail a present **Spec:** block that parses empty, and spec sync refuses it before writing the target Spec. Diagnostics identify the block boundary; genuinely absent Spec labels keep their separate preservation behavior (#413).
• Untracked outputs could repeatedly stale evidence without explaining how to inspect the inputs. Proven input-digest mismatches now explain that tracked and non-ignored files count, show how to list untracked inputs, and point to the repository's actual exclude file, including linked worktrees and submodules. Exclusion remains a developer decision (#410).
• Filesystem guesses could disagree with what Git would record. Temporary-index recording replaces the prior existence inference, handles racy entries conservatively, and attributes recording failures without treating an unavailable digest as fresh (#417).

🔧 CI maintenance

Windows smoke coverage now includes the source-digest and module-digest suites alongside the existing test-runner checks. The Windows smoke job remains in its observation window with continue-on-error; it is not a claim that every Windows test is required and green. Drift-workflow guidance now distinguishes content freshness from commit-time reporting.

🔁 Dogfood

All five shipping changes are archived: one Grade S and four Grade A. They used standard planning, implementation, review and verification, with Knowledge sync moving ahead of review in this release; design was not applicable. 3 ADDED and 33 MODIFIED requirement updates graduated, with Knowledge synced across types, lib, services, cli, templates and tests.

The archived limits remain explicit. Four Grade A changes retain late-captured acceptance baselines, so their scenario adjudication is limited despite independent requirement checks. The temporary-index change also carries accepted review follow-ups, including the cost of project-wide Git recording and missing lazy-spawn coverage; clean filters and configured hooks are disclosed execution boundaries. The release-maintenance commit updates the CLI floor, generated probes, bilingual upgrade guidance, website metadata and social preview.

🧪 Quality & tests

• 8,785/8,789 tests passing, 4 skipped, 0 failed (329/329 files) on macOS with Node.js 24.20.0 and Vitest 4.0.18: 186 more passing tests and 9 more files than 2.9.0. Coverage includes source-digest freshness, temporary-index recording, empty Spec blocks, stale-input hints and Knowledge-before-review routing.
• 97.85% line coverage (14,049/14,357 lines); statements 96.49%, branches 91.21%, functions 98.88%.
• prospec check --strict: 22/22 checks executed, 21 PASS, 1 WARN, 0 FAIL, 0 skipped. The existing knowledge-size pressure warning reports 47 findings; all 6/6 modules have matching source digests, and no token budget was raised.
• TypeScript typecheck, ESLint and build pass. All 151/151 generated artifacts are current, factual counts match the fresh coverage JSON, and post-commit knowledge:check confirms 2/2 source-touched modules (types, tests). The built bundle reports 2.10.0; 34/34 deployed Skills and 2/2 entry configs require CLI 2.10.0.
• After the final README correction, release-document and version contracts pass 1,647/1,647 tests across 3/3 files. Independent review covered 48/48 release-maintenance files and cross-checked the release narrative against all five archive summaries; its stale-floor documentation finding was corrected.

📊 Compared to 2.9.0

Comparison	2.9.0	2.10.0
Knowledge freshness	Commit-date comparison	Source-content digest comparison
Missing source digest	Not required	Stale until reviewed and stamped
Standard Knowledge sync	After verify	Before review and the final evidence snapshot
Shallow-clone Knowledge health	Skipped	Content judged; commit-time fields may be null
Empty MODIFIED Spec block	Could survive until convergence	FAIL in landing checks; refused by spec sync
Synced Skills' minimum CLI	2.9.0	2.10.0
Passing tests on macOS	8,599	8,785

⬆️ Upgrade notes

1. Re-run the macOS/Linux install.sh or Windows install.ps1 installer, which fetches the latest release, or pin ./install.sh 2.10.0. Update the binary before prospec upgrade: refreshed Skills require CLI 2.10.0 or later. Then run prospec upgrade and the prospec-upgrade Skill to refresh project guidance.
2. Review each module README against its source, then run prospec knowledge verify <module> to record the new digest. Legacy entries without source_digest are stale and can block Knowledge sync for affected changes. No manual config-key edit is required, but this reviewed re-stamping is required for existing modules.
3. Complete Knowledge updates before recording the final tests and review baseline. Follow prospec status when resuming an existing change; refresh evidence after any subsequent input edits.
4. Freshness computation may record the whole project through temporary Git indexes and execute project clean filters or configured hook.<name> hooks. Account for those commands and the recording cost in repositories that use them.
5. Run prospec status and prospec check --strict. See the upgrade guide (繁體中文) for migration details.