v0.4.2 — Upgrade That Catches You Up: Config Nudges, Comment-Safe Writes & Git-Tracked Scans

Prospec v0.4.2

0.4.0 and 0.4.1 built the version-upgrade path and made re-running commands no-clobber —
but prospec upgrade on a project that predates a feature still just bumped the version
number. It didn't help the project actually catch up: optional config fields a newer init would
have offered stayed missing, writeConfig silently destroyed your .prospec.yaml comments
while its own docs claimed otherwise, and the deterministic raw-scan.md was left stale against
the new scanner. v0.4.2 turns upgrade into a command that catches a project up — it detects
and interactively fills missing curated config fields, preserves your comments, and refreshes the
scan — then retires the long-dead prospec steering command and ships a public landing
page.

96 files changed · +2,786 / −1,698 · 2 merged PRs (#44, #45) · new GitHub Pages landing page (EN + 繁體中文)

---

✨ Headline features

prospec upgrade now catches a project up — config-field nudges + interactive fill (PR #45)

A curated UPGRADE_NUDGE_RULES registry detects optional .prospec.yaml fields a pre-feature
project never set (first rule: artifact_language) and reports them. It is deliberately
curated, not "every absent field" — fields with sensible defaults (base_dir, knowledge) or
that hard-error when missing (agents) are excluded. On an interactive TTY, upgrade prompts to
fill each nudge just like prospec init; --no-interactive (and any non-TTY stdin) forces
report-only, so the /prospec-upgrade Skill and CI never block. (PR #45)

Config writes preserve your comments and formatting (PR #45)

writeConfig used to rebuild the YAML tree (doc.createNode), silently destroying user
comments while its JSDoc claimed it preserved them. A new mergeIntoDocument reconciles in
place — mutating only changed scalars, recursing into maps, deleting removed keys — so
prospec upgrade (which only bumps version) keeps every comment and formatting choice intact.
(PR #45)

Generated artifacts stay aligned to the new version (PR #45)

After agent sync, upgrade best-effort regenerates the deterministic raw-scan.md (the only
ai-knowledge/ write — never a curated doc) so the project snapshot matches the new scanner; it
is non-fatal if it can't. And raw-scan now scans git-tracked files only: scanDir
intersects its glob with git ls-files, so gitignored directories the static ignore list misses
no longer leak into the scan — falling back to the full glob when there is no git work tree. Used
by knowledge init --raw-scan-only, the archive refresh, and upgrade. (9652e53, 79f0611)

The deprecated prospec steering command is gone (PR #44)

steering was superseded by prospec knowledge init and had become dead code — a staler
parallel scan (manifest-only tech detection, unconditional module-map.yaml overwrite) that no
live code imported. v0.4.2 deletes the command, its formatter, service, and the
architecture.md.hbs template, moves module-readme.hbs under templates/knowledge/, and
repoints every module-map prerequisite hint to prospec knowledge init. REQ-SETUP-008/009/010

• US-004 are retired; architecture.md generation and the self-referential per-module paths
  writeback are intentionally dropped — their content is already covered by raw-scan.md /
  _index.md / module READMEs (+ module-map.yaml for the layers). (PR #44)

A public landing page — benwu95.github.io/prospec (EN + 繁體中文)

A GitHub Pages landing page (served from docs/) now introduces Prospec as "spec-driven
development that audits itself", with a client-side i18n layer (i18n.js) offering English
(default on first visit) and Traditional Chinese. The README's Project Structure tree was folded
into Quickstart and corrected to reflect the full quickstart bootstrap (synced
.claude/skills/*, raw-scan.md, module READMEs, a filled _index.md) — not just init.
(6957239, eca71b8, 75912f1, 634f546)

Smaller fixes

• 8 skill templates ended with a trailing blank line that propagated into every generated
  SKILL.md — normalized to one trailing newline, with a contract test guarding it. (e4bfba7)
• Canonical agent order unified to claude, codex, copilot, antigravity across the zod enum
  error, AGENT_CONFIGS, and AGENT_DIRS (zero drift — generated files depend on the agent set,
  not its order). (0959efc)
• Corrected a stale prospec archive hint in the feature-map / product MCP resources.
  (a2c835e)

---

🔁 Dogfood

Both core changes ran through prospec's own SDD lifecycle
(story → plan → tasks → implement → review → verify → archive) on this repo. The
upgrade-config-nudges change reached 0-critical adversarial review and verify Grade S —
REQ-SETUP-019/020/021 + REQ-LIB-022 graduated into specs/features/project-setup.md and
REQ-AGNT-028 into agent-integration.md, with module Knowledge synced. The steering removal
reached verify Grade A, retiring REQ-SETUP-008/009/010 + US-004 and reconciling a
pre-existing services-count inconsistency (module-map 13 / README 14 / _index 15) to the true
execute()-services count of 14.

🧪 Quality & tests

• The suite is 1,779 tests passing (74 files) — a net dip from 0.4.1's 1,786 because removing
  steering deleted its test files (1,786 → 1,748), which the upgrade work then brought back up
  (1,748 → 1,779).
• Coverage ~97% lines; prospec check drift engine 8/8 checks, 0 fail; typecheck + lint
  clean.
• New coverage for the config-nudge registry, interactive fill, the comment-preserving
  mergeIntoDocument, the git-tracked scan intersection, and the skill-template
  trailing-newline contract.

---

📊 Compared to v0.4.1

	v0.4.1	v0.4.2
prospec upgrade on a pre-feature project	bumps version only	detects + interactively fills missing curated .prospec.yaml fields
writeConfig user comments	destroyed on rewrite	preserved (in-place merge)
upgrade & raw-scan.md	left stale	refreshed to the new scanner
raw-scan file set	full glob (gitignored leaks)	git-tracked files only (glob fallback)
prospec steering	deprecated dead command	removed
Landing page	none	GitHub Pages site (EN + 繁中)
Tests	1,786	1,779 (−steering tests)
Verify grade	S	S (upgrade) / A (steering removal)

---

⬆️ Upgrade notes

Re-install globally (pnpm add -g @benwu95/prospec, or your installer of choice) and run
prospec upgrade in each project: on an interactive terminal it now offers to fill any
missing curated config field (e.g. artifact_language), preserves your .prospec.yaml
comments, re-syncs agents, and refreshes raw-scan.md — all non-destructive to the curated
trust zone (CONSTITUTION.md / _conventions.md / _index.md stay skip-if-exists). In CI or
with --no-interactive it stays report-only. If you scripted around prospec steering,
switch to prospec knowledge init (or knowledge init --raw-scan-only for just the scan).

---

Merged PRs

• #45 Improve prospec upgrade: config nudges, interactive fill, comment-safe writes, git-tracked raw-scan
• #44 refactor: remove deprecated prospec steering command