docs: reconcile the phantom per-intent reverse-engineering record folder

[iuryeng]

Summary

Removes a phantom per-intent <record>/inception/reverse-engineering/ folder that three surfaces still advertise but nothing ever writes, and documents where reverse-engineering output actually lives (the space-level per-repo CodeKB). This is the documentation drift behind the confusion in #632 — the empty per-intent folder tells users the artifacts belong there, while the engine deliberately writes them to aidlc/spaces/<space>/codekb/<repo>/.

Not marked Closes #632: whether the space-level placement itself should change is a design call for maintainers — this PR only reconciles the documented tree with the implemented one.

Changes

The engine treats reverse-engineering exclusively as a codekb stage — KNOWN_CODEKB_STAGES in aidlc-orchestrate.ts and aidlc-state.ts, and the stage frontmatter declares outputs: aidlc/spaces/<active-space>/codekb/<repo>/. Three surfaces still said otherwise:

• core/aidlc-common/stages/initialization/workspace-scaffold.md — the Step 3 ensure-exists list scaffolded an empty reverse-engineering/ under <record>/inception/. Removed, with a short note explaining the deliberate absence (so it doesn't get "fixed" back).

• core/tools/data/scaffold/inception/reverse-engineering/.gitkeep — the matching empty skeleton dir in the scaffold data. Removed.

• docs/guide/14-artifacts-reference.md — the record tree listed reverse-engineering/ (conditional: brownfield) and the guide never mentioned codekb at all. Removed the tree line, annotated the stage-artifact table row with the real location, and added a "The 9 reverse-engineering deliverables are not in the record dir" paragraph mirroring the existing "Team knowledge is not in the record dir" one. It states the semantics as implemented: one store per repo that each brownfield rerun overwrites (last write wins — the condition is "Always rerun for freshness" and no short-circuit exists), the record dir receiving only the stage's own memory.md diary on demand, and codekb writes carrying the codekb > <repo> > <name> audit breadcrumb.

• tests/harness/fixtures.ts — the withReArtifacts option documented itself as copying into inception/reverse-engineering/ while the code seeds codekb. Same drift class, one comment line.

No engine code changes and no command or flag changes, but the shipped dist/ trees do change (installed stage prose, plus an installed skeleton directory that goes away), so this ships as 2.5.14 with a CHANGELOG entry and the README badge.

User experience

Before: a brownfield user finds an empty intents/<intent>/inception/reverse-engineering/ folder in their record tree (and in the artifacts guide) while the actual artifacts appear in codekb/<repo>/ — which reads as a bug (#632). After: the scaffold pre-creates only folders that stages actually write, and both the scaffold prose and the user guide say where the nine deliverables live, that each brownfield rerun overwrites that shared store rather than snapshotting it per intent, and that the one thing landing in the record dir is the stage's own memory.md diary (so the folder can still appear there, diary-only, and that is now documented rather than surprising).

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Test Plan

• bun scripts/package.ts + bun scripts/package.ts --check → green for all 5 harnesses (the scaffold skeleton and stage prose ship in every dist).
• bun run typecheck and bun run lint → clean.
• t68 (version/CHANGELOG/badge sync at 2.5.14), t182 (codekb placement), t239 (documentation parity), t134 and gen-coverage-registry → 63 tests, 0 failures. t72 and t183 are SDK-tier and assert on write paths rather than prose, which this change does not touch.
• Grepped core/, docs/ and tests/ to confirm no production code writes to or reads from <record>/inception/reverse-engineering/ for the deliverables; the remaining references are the two new sentences documenting the stage diary, plus the withReArtifacts fixture option whose comment this PR now corrects.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[apackeer]

Reviewed against the engine at the PR head (a580a3d) plus a full local gate run. The substance of this PR is right and verified: the phantom folder removal is correct, and nothing in production code reads or writes the removed surfaces. Two wording fixes are needed in the new prose before this is accurate, though - details below.

Verified correct

• The engine treats reverse-engineering exclusively as a codekb stage: KNOWN_CODEKB_STAGES contains only reverse-engineering in core/tools/aidlc-state.ts:104, core/tools/aidlc-orchestrate.ts:934, and core/tools/aidlc-sensor.ts:254, and the stage frontmatter declares the codekb output path (core/aidlc-common/stages/inception/reverse-engineering.md:36).
• Intent birth never copies the scaffold skeleton: ensureWorkspaceDirs creates phase-level dirs only (core/tools/aidlc-utility.ts:3414-3424), and the birth handler explicitly documents that it "never re-copies the data/scaffold tree" (core/tools/aidlc-utility.ts:3627). Removing the .gitkeep breaks nothing - the only fixture that seeds RE artifacts already seeds codekb (tests/harness/fixtures.ts:565).
• The audit breadcrumb claim is real: codekb > <repo> > <name> at core/hooks/aidlc-audit-logger.ts:123.
• After this PR, no per-intent reverse-engineering/ reference remains anywhere in core/, docs/, harness/, or dist/ (swept all of them).

Should fix: two overclaims in the new prose

1. "Output is not in the record dir" / "never to the intent record" is too strong - the stage diary lands there every run.

The stage's Learn ritual writes <record>/inception/reverse-engineering/memory.md on every execution: the stage file mandates it (reverse-engineering.md:165, and line 187: "The memory.md file stays in the artefact directory as part of the stage's permanent record"), and the engine's memory_path has no codekb carve-out - memoryPathFor unconditionally resolves <record>/<phase>/<slug>/memory.md into every run-stage directive (core/tools/aidlc-orchestrate.ts:627-630, wired at 1330). The tests already encode this exact distinction: t72's anti-scatter check filters by the 9 artifact stems precisely because "the RE stage's own Learn ritual legitimately writes its stage diary memory.md into <record>/<phase>/<stage>/" (tests/integration/t72-stage-reverse-engineering.test.ts:98-102); t183 mirrors it.

So after a brownfield run, users will see intents/<intent>/inception/reverse-engineering/ reappear, diary-shaped - and the guide paragraph plus the workspace-scaffold Step 3 note would then read as contradicted, recreating the confusion this PR fixes. Suggested fix: scope both claims to the nine deliverables ("the 9 reverse-engineering artifacts live in the space-level codekb; the record dir holds only the stage's memory.md diary, created on demand"). No need to re-add the folder to any tree listing - it materializes lazily.

2. "Reuse ... instead of regenerating it per intent" misstates the semantics - the stage reruns and overwrites.

The stage condition is "Always rerun for freshness" (reverse-engineering.md:5), the timestamp artifact is a rerun trigger, not a skip mechanism (line 121), and there is no freshness short-circuit anywhere in the stage or the orchestrator. Each applicable brownfield intent reruns the scan and overwrites the shared nine files, last-writer-wins - which is exactly the behavior reported in #632. The guide should state this honestly: one shared per-repo store, refreshed (overwritten) by each brownfield run, so intents always see the newest scan rather than a per-intent snapshot.

Judgment call: version bump

The PR body offers to add one; I'd take that offer. This changes shipped dist/ trees (the stage prose users install, plus removing an installed skeleton dir), and the empty-folder removal is the user-visible fix for the #632 confusion - that leans "user-visible" rather than "pure doc sweep" under the changelog policy. Maintainer call.

Nit

• tests/harness/fixtures.ts:499 comment still says "Copy reverse-engineering artifacts into inception/reverse-engineering/" while the code seeds codekb (line 565) - the same drift class this PR fixes; one-line comment fix if you want to fold it in. (Pre-existing, and the PR body already flags this fixture as deliberately untouched, so fine to leave for a follow-up.)

Out of scope but worth a follow-up issue: after this PR the entire core/tools/data/scaffold/ tree is consumed by nothing (birth never copies it; only the packager ships it), and README.md:280 still advertises "data/scaffold/ templates".

Local gates (at the PR head)

• bun scripts/package.ts --check: green for all 5 harnesses.
• smoke + unit: 174 files, 0 failures.
• integration: 103 files, 1 red - t238-user-stories-mob.sdk, a live-agent flake (the mob support prompt paraphrased a rule path instead of citing it literally; zero overlap with this diff), green on solo re-run. t72-stage-reverse-engineering and t183-codekb-placement-reverify both passed.

[iuryeng]

Both overclaims were real and are fixed, the bump is in, and I folded the nit. New head is 59e942e5, rebased onto v2 (257b43a3).

1. "never to the intent record" — scoped to the nine deliverables

You are right, and this is the more damaging of the two: the claim would have been falsified by the first brownfield run. I re-read the surfaces you named — the stage mandates the diary at <record>/<phase>/<stage>/memory.md and calls it part of the stage's permanent record, and memoryPathFor builds that path unconditionally, with no codekb carve-out — so the folder does come back, diary-shaped, and my paragraph would then have been the thing contradicting reality.

Both places now scope the claim and name the diary explicitly. The guide paragraph is retitled "The 9 reverse-engineering deliverables are not in the record dir" and says the record dir does get the stage's own memory.md, created on demand, so an inception/reverse-engineering/ directory can appear there holding the diary and nothing else. The workspace-scaffold Step 3 note says the same and adds why it is still absent from the ensure-exists list: the scaffold does not pre-create it, the stage creates it when it runs. No tree listing re-adds the folder — as you say, it materializes lazily.

2. "reuse instead of regenerating" — replaced with the real semantics

Also correct, and this one mattered beyond wording: it is exactly the behavior reported in #632, so describing it as reuse would have documented away the bug the issue is about. Checked the three points — condition is "Always rerun for freshness", the timestamp artifact describes itself as the staleness marker that triggers a rerun, and there is no freshness short-circuit in the stage or the orchestrator. The guide now reads:

It is not a snapshot: the stage condition is "Always rerun for freshness", so every applicable brownfield intent reruns the scan and overwrites those nine files, last write wins […] Intents therefore read the newest scan of the repo, not the one taken when their own record dir was created.

The stage-artifact table row and the scaffold note carry the same "overwritten by each brownfield rerun" phrasing, so the three surfaces agree.

3. Version bump — taken

Shipped as 2.5.14: aidlc-version.ts, README badge, and a CHANGELOG entry whose upgrade note tells users to re-copy dist/<harness>/ and that an empty inception/reverse-engineering/ left in an existing record can be deleted. Your reasoning is the one I'd apply too — installed prose changes and an installed directory disappears, which is user-visible however small.

4. Nit — folded in

withReArtifacts now documents what the code does (seeds the space-level per-repo codekb store, not the intent record). It is one comment, it is the same drift class this PR exists to fix, and leaving it would have been odd.

Follow-up you flagged as out of scope

Filed as #656 rather than widened into this PR: core/tools/data/scaffold/ is 26 empty directories that nothing consumes (birth creates phase dirs directly and the handler says outright that it never re-copies the tree), yet the packager ships all of them into every dist and installed project, and README.md:294 still calls them "templates". That is a delete-or-wire-up decision plus a README correction, so it deserves its own review rather than riding along here.

Gates at 59e942e5

bun scripts/package.ts --check green on all five harnesses; bun run typecheck and bun run lint clean; t68 (now pinning 2.5.14), t182, t239, t134 and gen-coverage-registry → 63 tests, 0 failures. I did not run the SDK tier locally — t72 and t183 assert on write paths rather than prose, and this diff touches neither, so your run of them at the previous head still holds.

[apackeer]

Round 2, reviewed at the new head (59e942e) against the engine plus a fresh local gate run. All four round-1 items are genuinely fixed - verified against the code, not just read:

Round-1 items: all verified fixed

• Diary scoping: the guide paragraph now scopes the claim to the nine deliverables and names the memory.md diary landing on demand (docs/guide/14-artifacts-reference.md:74-89), and the workspace-scaffold Step 3 note says the same (core/aidlc-common/stages/initialization/workspace-scaffold.md:66-72). Both match the stage's Learn ritual (reverse-engineering.md:164-165, :187) and the unconditional memoryPathFor (core/tools/aidlc-orchestrate.ts:627-629).
• Rerun-and-overwrite semantics: the guide paragraph, the stage-artifact table row, and the scaffold note now agree with the frontmatter condition and the timestamp artifact's self-description (reverse-engineering.md:5, :121).
• Version bump: 2.5.14 + badge + CHANGELOG entry; t68 green.
• Fixtures comment: now matches the code (tests/harness/fixtures.ts:498-500 vs the codekb seed at :566-570).

I also re-verified the audit-breadcrumb sentence in the new prose: the codekb arm of the path gate is real (core/hooks/aidlc-audit-logger.ts:75-79) and the shard lands under the active intent's record audit/ dir (core/tools/aidlc-lib.ts:1899-1903), so "the per-intent trail still records what changed" holds. Filing the scaffold-tree removal as #656 instead of widening this PR was the right call.

Gates at 59e942e: bun scripts/package.ts --check green on all five harnesses; typecheck and lint clean; targeted t68/t182/t239/t134/gen-coverage 63/63; full smoke+unit tier 177/177 files. (GitHub shows no checks because the fork workflow run sits at action_required; the local runs above cover what the v2 gate runs.)

Two wording fixes before approve, both in CHANGELOG.md

1. [P2] The entry describes a runtime change that never existed. CHANGELOG.md:6 says "The workspace skeleton no longer pre-creates an inception/reverse-engineering/ folder in every intent record", and the upgrade note says an empty directory "left in an existing intent record can be deleted". But nothing at runtime ever created that folder in an intent record on v2:

• Initialization stages never execute as run-stage directives; the orchestrator hard-errors on any attempt (core/tools/aidlc-orchestrate.ts:2526, checked at :3343-3345). The Step 3 ensure-exists list in workspace-scaffold.md is prose the deterministic path never enacts.
• Intent birth calls ensureWorkspaceDirs, which creates phase-level dirs only (core/tools/aidlc-utility.ts:3416-3424) and "never re-copies the data/scaffold tree" (:3628); the old --init copy that did consume data/scaffold/ is gone (:3471-3474).
• The shipped shell contains no intents skeleton at all (dist/claude/aidlc/ holds only spaces/default/memory).

So the folder could only appear via a pre-shell-era install, or via an agent conductor literally enacting the old Step 3 prose. The fix this PR makes is real and worth shipping: it removes stale packaged metadata (the dead data/scaffold/ skeleton dir) and corrects the prose and docs that advertised the wrong location. The CHANGELOG entry should say that, rather than describing a change to what intent creation does. Suggested reframe for the summary sentence: "The shipped workspace scaffold data and the Workspace Scaffold stage prose no longer advertise a per-intent inception/reverse-engineering/ folder that nothing writes; the guides now describe where Reverse Engineering output actually lands." The upgrade note's "can be deleted" sentence is fine if scoped to installs that predate the shipped shell.

2. [P3] CHANGELOG.md:9 says "Stage 0.3 Workspace Scaffold"; it is stage 0.1 (harness/claude/skills/aidlc/SKILL.md:172, docs/reference/04-stages/initialization.md:37). 0.3 is State Initialization. One word.

Optional, since you are touching the file

docs/guide/14-artifacts-reference.md:139 (the generic lifecycle step "writes it to the appropriate subdirectory of the intent's record dir") predates this PR and already coexists with the team-knowledge and code exceptions, so it is not something this PR introduced. But a short parenthetical there, e.g. "(or, for the reverse-engineering stage, the space-level codekb store)", would close the loop while you are in the file.

One logistics note: 2.5.14 is also claimed by two other open PRs (#661, #613), so whichever merges later re-bumps per the changelog policy; nothing for you to do now beyond being unsurprised if a rebase asks for a renumber.

With the two CHANGELOG fixes in, this is an approve from me.

[iuryeng]

Thank you for the second pass — and for tracing the runtime path yourself rather than taking the entry at its word. Both items are fixed at 56f8083f.

Before changing the text I re-walked your three anchors, because the reframe only holds if the runtime claim is genuinely absent:

• Initialization stages cannot be enacted as run-stage: SINGLE_INIT_ERROR (core/tools/aidlc-orchestrate.ts:2525-2526) with the guard at :3343-3345 refusing any node.phase === "initialization".
• ensureWorkspaceDirs (core/tools/aidlc-utility.ts:3416-3428) creates the record dir, the five phase dirs, verification/, and the space-level knowledge/ — no stage-level subdirectory anywhere, and its own comment says it never re-copies data/scaffold/ (:3626-3630, matching the --init removal note at :3471-3474).
• The shipped shell really is only active-space + spaces/default/memory/ (dist/claude/aidlc/) — no intents skeleton.

So you are right: the folder could only come from a pre-shell-era install or from an agent literally enacting the old Step 3 prose, and the entry was describing a change to intent creation that never happened. That was my prose overreaching again, in the same direction as round 1 — I appreciate you catching it before it shipped rather than after.

1. [P2] Changelog entry reframed

I took your suggested summary sentence nearly verbatim, since it says exactly what the diff does:

The shipped workspace scaffold data and the Workspace Scaffold stage prose no longer advertise a per-intent inception/reverse-engineering/ folder that nothing writes; the guides now describe where Reverse Engineering output actually lands.

The upgrade note now scopes the deletion advice — "on installs that predate the shipped shell, an empty inception/reverse-engineering/ directory left in an existing intent record can be deleted" — since that is the only way an empty one exists. The bullets are otherwise untouched apart from item 2 below.

2. [P3] Stage number

Fixed: 0.1 Workspace Scaffold. Confirmed against both surfaces you cited (harness/claude/skills/aidlc/SKILL.md:172, docs/reference/04-stages/initialization.md:37) plus the phase table in the very file this PR edits (docs/guide/14-artifacts-reference.md:150), which already had it right — the changelog was the only place saying 0.3.

3. Optional item — taken

docs/guide/14-artifacts-reference.md:139 now reads "… the appropriate subdirectory of the intent's record dir (with the space-level exceptions noted above: Reverse Engineering writes to the per-repo codekb store, team knowledge to knowledge/)". I named both exceptions rather than only the reverse-engineering one, so the generic step points at the two carve-outs the document already explains instead of creating a third account of them. Happy to narrow it to the reverse-engineering half if you would rather keep the step generic.

Gates at 56f8083f

bun scripts/package.ts --check green on all five harnesses (unchanged — this round touches only CHANGELOG.md and docs/, neither of which is packaged); bun run check clean across the three tsconfigs and biome (539 files); t68 7/7 plus your targeted set t182/t239/t134/gen-coverage — 63/63 assertions total, the same number you saw. git merge-tree against the current v2 tip (207db2ea) is conflict-free, and origin/v2 is still at 2.5.11, so 2.5.14 remains free; if #661 or #613 land first I will rebase and renumber per the changelog policy. Same caveat as yours on CI: the fork's runs still sit at action_required, so this is a local Windows run, not the v2 gate.

The diff this round is three lines: the summary sentence, the stage number, and the optional parenthetical.

[apackeer]

Approving. Round 3 verified at 56f8083f, which is a clean fast-forward from the round-2 head I verified (59e942e5), touching exactly the two files from my last comment.

Both blockers are fixed, plus the optional nit:

• [P2] Changelog reframe: the summary now attributes the change to the shipped scaffold data and the stage prose ("no longer advertise a per-intent inception/reverse-engineering/ folder that nothing writes") instead of claiming intent creation changed, and the upgrade note is correctly scoped to installs that predate the shipped shell. Matches the runtime reality we both traced (SINGLE_INIT_ERROR at core/tools/aidlc-orchestrate.ts:2525-2526 + the initialization guard, and ensureWorkspaceDirs creating phase dirs only).
• [P3] Stage number: bullet now reads "Stage 0.1 Workspace Scaffold", matching the registry (harness/claude/skills/aidlc/SKILL.md:172).
• Optional guide nit taken: the lifecycle "Created" step in docs/guide/14-artifacts-reference.md:139 now carries the space-level-exceptions parenthetical, so it no longer reads as contradicting the codekb paragraph above it.

Re-verified at this head: t68-version-changelog-sync 7/7 green, bun scripts/package.ts --check green across all harness trees, and no test or prose pins the old wording.

One mechanical item before merge, not a review blocker: v2 has moved to 2.5.17 since this branch was cut, so the branch is currently conflicting and the 2.5.14 slot is taken. Per the changelog policy this needs a rebase onto v2 plus a re-bump of core/tools/aidlc-version.ts, the README badge, and the ## [2.5.14] heading to the next free patch number (regenerate dist afterwards so --check stays green). Happy to re-confirm after the rebase.

Thanks for the careful fixes across all three rounds - each one was verified against the engine rather than just reworded, and the entry now describes exactly what the diff does.

[iuryeng]

Thanks for the approve. Mechanical item done: rebased onto v2 38bf086b (2.5.17) and re-bumped. New head: 8d28de1d, MERGEABLE again.

Slot: 2.5.26. Reading each open PR's actual AIDLC_VERSION diff rather than its title (several titles lag their own bump), 2.5.18–2.5.24 are already claimed by #669, #671, #672, #673, #674, #675 and #676. #644 — also mine — claims 2.5.25, rebased a few minutes ago, so 2.5.26 is the first free slot after it.

On merge order between my two branches: #644 = 2.5.25 and #645 = 2.5.26 are sequential on purpose. Merging #644 first keeps both trivial — #645 then needs at most a heading reposition. In the reverse order #644 lands below the latest heading and needs a re-bump past 2.5.26 for t68 to pass, so it's the more expensive direction. Happy to swap the two numbers if you'd rather merge this one first.

What the re-bump touched: core/tools/aidlc-version.ts plus the five dist copies, the README badge, and the ## [2.5.14] heading → ## [2.5.26], which also moved above the 2.5.17 block. Same judgment call as on #644: I moved the heading's date 2026-07-25 → 2026-07-29, because the file is reverse-chronological and a 07-25 entry sitting above a 07-29 one would break that (#667 dates by authoring day too — merged 07-30 UTC, dated 07-29). Say the word and I'll put 07-25 back. The commit subject of the middle commit also still said 2.5.14; it now says 2.5.26.

Everything you verified is unchanged. Comparing this PR's own diff before (257b43a3..56f8083f) and after (38bf086b..8d28de1d): identical file set, and exactly 8 files' patches differ — CHANGELOG.md, README.md, core/tools/aidlc-version.ts and the 5 dist version files. Every other file's patch hashes the same. Inside CHANGELOG.md the 2.5.26 block body is byte-identical to the 2.5.14 block you approved, heading line aside — the reframed summary, the pre-shell-scoped upgrade note, and "Stage 0.1 Workspace Scaffold" all carried through the rebase untouched.

Gates at 8d28de1d:

• bun scripts/package.ts --check → green on all five dists. I resolved the five dist version-file conflicts by hand during the rebase, and the drift guard confirms they match what the packager generates byte for byte, so no regeneration was needed.
• bun run check → clean (typecheck across all 3 tsconfigs; biome 541 files, no fixes).
• t68 + t182-codekb-placement + t239-documentation-parity + t134-mechanism-honesty + gen-coverage-registry → 63 tests / 1233 assertions / 0 failures, the same 63 as the round-2 run.
• merge-tree against v2 → clean.

CI still has never run on any head here either — the fork's runs sit in action_required pending a maintainer's "Approve and run".

[iuryeng]

#644 merged, so this branch hit exactly the trivial reposition I flagged as the cheap direction. Rebased onto v2 2dabae2c (2.5.25). New head: 54a9f2fc, MERGEABLE.

Nothing changed but the block's position: 2.5.26 is still free and still correct above v2's 2.5.25, so the version file and the README badge are byte-identical to the head you approved, and the ## [2.5.26] block — heading line included — is byte-identical too. It just sits above the 2.5.25 entry now instead of the 2.5.17 one.

The seven files this PR touches are unchanged from 8d28de1d: core/aidlc-common/stages/initialization/workspace-scaffold.md, core/tools/data/scaffold/inception/reverse-engineering/.gitkeep, docs/guide/14-artifacts-reference.md, tests/harness/fixtures.ts, plus CHANGELOG.md / README.md / core/tools/aidlc-version.ts.

Gates at 54a9f2fc:

• bun scripts/package.ts --check → green on all five dists.
• bun run check → clean (typecheck across all 3 tsconfigs; biome 543 files).
• t68 + t182-codekb-placement + t239-documentation-parity + t134-mechanism-honesty + gen-coverage-registry → 63 tests / 1239 assertions / 0 failures.
• merge-tree against v2 → clean.