Skip to content

v0.4.3 — Root L0-L3 Index & Docs That Catch Themselves Up: Hierarchical Knowledge Index, Single-Source Doc Inventory, Upgrade Back-Fill & Conditional Plan Diagrams

Choose a tag to compare

View all tags
@benwu95 benwu95 released this 03 Jul 09:52
0.4.3
9d3a8ff

Prospec v0.4.3

0.4.2 turned prospec upgrade into a command that catches a project up on config. v0.4.3
does the same for the knowledge and docs layer. Two pillars: the AI-Knowledge entry point
graduates from a buried ai-knowledge/_index.md to the project root <base_dir>/index.md,
making the L0-L3 layered loading model real; and every init-created doc becomes traceable
through a single source of truth that prospec upgrade now back-fills — so an
already-initialized project can finally obtain a doc a newer version introduced, with no CLI
path to it before. Rounding it out: an in-project Prospec README scaffolded at init, and a
conditional User Story Flow diagram in /prospec-plan.

157 files changed · +3,159 / −1,078 · 5 merged PRs (#49, #51, #52, #53, #54) · closes #46, #47, #48, #50

✨ Headline features

The AI-Knowledge index moves to the project root — L0-L3 layered loading (PR #49)

The entry point graduates from ai-knowledge/_index.md to <base_dir>/index.md, establishing
the L0-L3 architecture (L0 = entry configs, L1 = root index + core conventions, L2 = module
READMEs + on-demand conventions + feature specs, L3 = source). A centralized CORE_CONVENTIONS
registry in src/types/conventions.ts (superseding canonical-docs.ts) splits core vs
load-on-demand conventions via filterConventions and always drops the legacy _index.md;
_diagram-conventions.md + _glossary.md join the core set and seed at prospec init. Every
index emitter (init / knowledge init / knowledge generate / knowledge update) now renders
through one shared _index-auto-block.hbs partial + buildIndexTemplateContext, so render
contexts cannot drift — fixing a fresh init that wrote a broken root index (unsubstituted
base_dir). readIndex takes the resolved baseDir so the read side reads exactly what the
writers emit. REQ-KNOW-034/035 + REQ-AGNT-029 graduated. (PR #49)

Every init-created doc is traceable — single-source INIT_DOC_REGISTRY + upgrade docs inventory (PR #51)

The upgrade flow used to drift: the skill's hardcoded scan list had already lost _glossary.md,
and nothing created docs a newer version introduced. A single-source INIT_DOC_REGISTRY
(root-discriminated base/knowledge) now drives both the canonical and user-managed
convention-doc lists via a shared asKnowledgeInitDoc projection — no doc declared twice.
prospec upgrade gains a read-only Docs inventory: section marking every init-created doc
present/MISSING at its actual location (honoring a relocated knowledge.base_path), and
/prospec-upgrade consumes that inventory as its ONLY scan scope. Bidirectional init⇄registry
set-equality + per-template renderability contracts turn a future parallel-list drift red
instead of silently reopening the bug. US-015/016, REQ-TYPES-038 / REQ-SETUP-022 /
REQ-TESTS-036 graduated. (PR #51)

prospec upgrade now back-fills missing init docs directly (PR #53)

Because prospec init refuses to run once .prospec.yaml exists, an already-initialized project
had no CLI path to obtain a newly-added init doc — upgrade only reported them MISSING.
Creating one is a pure deterministic template render, so routing it through an LLM skill was
unnecessary. A shared src/lib/init-docs.ts (buildInitDocContexts / renderInitDoc /
resolveInitDocLocation) now backs both init.service (greenfield output byte-identical) and
upgrade.service.createMissingDocs, which renders + writes each MISSING registry doc —
skip-if-exists, per-doc best-effort, interactive and --no-interactive/CI. It never
overwrites an existing doc; index.md is written as a baseline (its real module table / legacy
_index.md migration stays the skill's job). Verified live: upgrade back-filled this repo's own
previously-missing prospec/README.md. US-017, REQ-SETUP-024 / REQ-LIB-023 /
REQ-SERVICES-061 (+ more) graduated. (PR #53)

An in-project Prospec README, scaffolded at init (PR #52)

prospec init now scaffolds a short {base_dir}/README.md so other developers of an adopting
project can understand what the prospec/ directory (and Prospec) is without cloning this
repo. Content is condensed from the root README's three-piece model (Skills / AI Knowledge /
CLI) and ends with a pointer to the full docs. It's a standalone base entry in
INIT_DOC_REGISTRY, so both init-create and the upgrade docs inventory derive from it with no
new write/inventory logic; an existing README.md is preserved byte-for-byte.
REQ-SETUP-023 graduated. (PR #52)

/prospec-plan emits a conditional User Story Flow diagram (PR #54)

plan.md gains a new Section 5 Mermaid User Story Flow diagram, gated on an any-of structural
signal set (≥2 branching decision points / ≥3 state transitions or multiple terminal states /
cross-module·cross-actor ordering) and skipped for linear stories — complementary to the
existing technical Call Chain. Template-content only, no runtime logic: it reuses
_diagram-conventions.md, is excluded from the 120-line standard cap, and keeps the
_diagram-conventions.md read out of Startup Loading (cache stability, mirroring the Context7
pattern). 4 mutation-verified contract assertions guard it. REQ-TEMPLATES-125 graduated. (PR #54)

Smaller fixes

  • knowledge-loading-rules extracted into a reusable partial shared by 10+ skill templates
    with root-resolvable L2 paths; the upgrade skill's Index Migration step copies curated Modules
    rows verbatim and forbids rebuilding via knowledge update (which blanks curated columns).
    _playbook.md deliberately stays load-on-demand (never core) per feedback-promotion
    governance. (PR #49)
  • Corrected a stale INIT_DOC_REGISTRY count (7 → 8) in REQ-TYPES-038 / REQ-TESTS-036. (PR #53)
  • The verify:skills status-lifecycle skill-count assertion synced 10 → 9 after PR #51's
    upgrade-skill rewrite intentionally dropped its enumerated reference — the assertion had been
    left stale, turning the hygiene check red on the release commit. (9d3a8ff)

🔁 Dogfood

All five changes ran through prospec's own SDD lifecycle on this repo. The hierarchical-index
change (implement-hierarchical-index) went story → … → archive, then a three-reviewer
adversarial audit whose two criticals — a broken init root-index render and data-loss
migration advice — were fixed on-branch. The doc-coverage, upgrade-back-fill, and
plan-diagram changes each reached verify Grade S; the in-project-README change was
review-clean (0 critical / 0 major). REQs graduated into specs/features/project-setup.md and
sdd-workflow, with module Knowledge synced.

🧪 Quality & tests

  • 1,840 tests passing (77 files) — up from 0.4.2's 1,779, climbing across the release:
    1,791 (index) → 1,821 (doc-coverage) → 1,824 (README) → 1,836 (back-fill) → 1,840 (plan
    diagram). (One e2e test, prospec --help, can hit a 5 s timeout under full-suite load but
    passes in isolation (~260 ms) — flaky, not a regression.)
  • Coverage ~96.6% lines; prospec check drift engine 8/8, 0 fail / 0 warn;
    verify:skills 28/28; typecheck + lint clean.
  • New coverage for filterConventions + dynamic base_dir + the legacy _index.md no-touch
    contract, the single-source INIT_DOC_REGISTRY set-equality guards, the shared init-docs.ts
    renderer (100%), and the plan-diagram contract assertions.

📊 Compared to v0.4.2

v0.4.2 v0.4.3
AI-Knowledge entry point ai-knowledge/_index.md root <base_dir>/index.md (L0-L3 layered)
Index rendering across emitters per-emitter contexts (drift-prone) single shared auto-block partial
Init-doc coverage hardcoded skill list (drifted; _glossary missed) single-source INIT_DOC_REGISTRY inventory
Missing init doc on an initialized project no CLI path (init refuses) prospec upgrade back-fills (skip-if-exists)
In-project onboarding doc none {base_dir}/README.md at init
/prospec-plan output prose + Call Chain + conditional User Story Flow diagram
Tests 1,779 1,840
Verify grade S / A S across changes

⬆️ Upgrade notes

Re-install globally (pnpm add -g @benwu95/prospec, or your installer of choice) and run
prospec upgrade in each project. On top of 0.4.2's config-nudge fill + comment-safe writes,
upgrade now reports a Docs inventory and back-fills any MISSING init-created doc directly —
including the new <base_dir>/README.md and the root index.md baseline — skip-if-exists
and non-destructive to the curated trust zone (CONSTITUTION.md / _conventions.md and your
index.md content stay yours). The AI-Knowledge entry point is now the root
<base_dir>/index.md; if you referenced ai-knowledge/_index.md, switch to it.
/prospec-upgrade then enriches the created docs and migrates drifted formats with per-file
consent.

Merged PRs

  • #49 Promote the AI-Knowledge index to root <base_dir>/index.md (hierarchical L0-L3 index)
  • #51 Cover every init-created doc via a single-source docs inventory
  • #52 Scaffold an in-project Prospec README at init
  • #53 Back-fill missing init docs on prospec upgrade
  • #54 Conditional User Story Flow diagram for /prospec-plan
Assets 2
Loading