feat(aidd-context): rebuild project-memory as three actions, verified on both hosts

aidd_docs/tasks/2026_07/2026_07_13_project-memory-rebuild/headless-runs.md

@@ -0,0 +1,43 @@
+# Headless runs
+
+Both hosts served this branch, synced with `scripts/dev-sync.sh aidd-context` (v2.3.2). Before the sync, both caches held 2.2.0 and its five old actions, so an unsynced run would have tested the released skill and passed for the wrong reason.
+
+Every claim below was read off disk, never off the model's report.
+
+## Claude, existing repo with code and no memory
+
+Picked `claude`. Detected `core`, `api` (`express` + `src/routes/`), `database` (`pg` + `src/db.js`).
+
+- 9 memory files, all flat in `aidd_docs/memory/`. No subfolder.
+- `CLAUDE.md` had no `## Memory Management`. The section was appended, the block filled with all 9 files.
+- The hand-written line in `CLAUDE.md` survived.
+- `AGENTS.md` was never created. Only the picked tool was touched.
+
+The review fanned out to one `aidd-dev:checker` per file and earned its keep: it found that `pg` is declared but imported nowhere, and that `src/db.js` is required by no caller. The first draft's architecture diagram had drawn `Routes → Db → Postgres`, three edges that do not exist in the code. The reviewers, none of whom wrote the file they read, caught what the writer could not see.
+
+## Claude, a repo whose memory was already nested
+
+The fixture carried `memory/core/project-brief.md` and `memory/internal/architecture.md`, the client bug.
+
+Scan stopped at the confirmation gate, as designed, so nothing was written. What it said before stopping is the proof the destinations table fired:
+
+> `core/` is a template-selection folder, not a path. This is a misplaced generated file. Its flat home `aidd_docs/memory/project-brief.md` does not exist, so nothing is loading it today.
+
+It planned to write the flat file, carry the nested file's content into it, leave the orphan in place, and report it. That matches the decision: prevent and surface, never auto-remediate.
+
+## Codex, hand-written `AGENTS.md` carrying no block
+
+Picked `codex`. Same fixture shape as the Claude run.
+
+- 9 memory files, all flat.
+- `AGENTS.md` had no block at all. The action inserted the section and the block, then the script filled it.
+- The hand-written line survived.
+- `CLAUDE.md` was never created.
+- The script was called as `update_memory.js codex`, so the picked-tool argument reached it.
+
+Codex spawned nine independent reviewers of its own.
+
+## What stays unproven
+
+- **The no-subagent fallback never ran.** Both hosts have subagents, so `review-protocol.md`'s degrade path is untested. It is defensive code, not verified behavior. Do not report it as working.
+- **The interactive contract is untested.** Every run pre-answered the tool pick and the capability confirmation in the prompt. The blocking ask itself was exercised only once, in the nested-drift run, where scan correctly refused to proceed.

aidd_docs/tasks/2026_07/2026_07_13_project-memory-rebuild/phase-1.md

@@ -0,0 +1,69 @@
+---
+status: done
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Router and scan
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+plugins/aidd-context/skills/02-project-memory/
+├── SKILL.md                              ✏️ router: mermaid scan->generate->sync, 3-action table, rules, ref/asset lists
+├── actions/
+│   └── 01-scan.md                        ✅ detect tools + capabilities, user picks tools, confirms capabilities
+└── references/
+    ├── tools.md                          ✅ tool | detected-when | context-file (merges detection signals + the AI map)
+    └── capability-signals.md             ✏️ keep the table, strip prose to one-line intents
+```
+
+## Tasks to do
+
+### `1)` Rewrite SKILL.md as a router
+
+> The always-on description and the smallest body that routes.
+
+1. Frontmatter: `name`, a `description` under ~45 tokens naming the journey not the mechanism, `argument-hint: scan | generate | sync`.
+2. Body: a linear mermaid `scan --> generate --> sync`, then a 3-row action table (verb, one-line does).
+3. Carry the load-bearing line: run in order, read the action's file in `actions/` before running it.
+4. Keep the transversal Memory rules and Action rules, one idea per line, no semicolons.
+5. Carry no reference or asset list: the actions point at them with `@`, and onboard proves the list is pure duplication.
+
+### `2)` Write actions/01-scan.md
+
+> Detect, ask, confirm. Read only, one prompt.
+
+1. Detect the tools present per `references/tools.md` (detected-when column).
+2. Show the detected tools, let the user pick one or several, wait for the pick, never default to all.
+3. Detect the capabilities per `references/capability-signals.md`, each with its repo evidence.
+4. Show each capability with evidence, let the user confirm, add, or drop, block on the answer.
+5. Output: the confirmed tool set and confirmed capability set, rendered nowhere.
+
+### `3)` Write references/tools.md
+
+> One table keyed by tool, serving scan and sync.
+
+1. Columns: tool, detected-when (its own dir or a file only it reads), context-file (where the block lives).
+2. Rows: claude, codex, cursor, opencode, copilot, matching the current mapping paths.
+3. A note: a shared `AGENTS.md` is a wiring target, never a detection signal.
+
+### `4)` Trim references/capability-signals.md
+
+> Keep the capability/definition/evidence/folder table, cut the surrounding prose to intents.
+
+1. Reduce the two prose paragraphs to the load-bearing rules only (a capability holds on a concrete fact, no inferred domain, every fire shown with evidence).
+2. Leave the table and the template folders untouched.
+
+## Test acceptance criteria
+
+<!-- Each criterion is an observable behavior, not a command. -->
+
+| Task | Acceptance criteria                                                                     |
+| ---- | --------------------------------------------------------------------------------------- |
+| 1    | SKILL.md holds a mermaid, a 3-row table, the read-the-action-file line, and a sub-45-token description. |
+| 2    | scan detects tools, offers a multi-pick, and confirms capabilities with evidence, rendering no memory. |
+| 3    | tools.md maps every listed tool to a detected-when signal and a context-file path.       |
+| 4    | capability-signals.md keeps its table and carries no prose beyond the holding rules.      |

aidd_docs/tasks/2026_07/2026_07_13_project-memory-rebuild/phase-2.md

@@ -0,0 +1,60 @@
+---
+status: done
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Generate with forced paths
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+plugins/aidd-context/skills/02-project-memory/
+├── actions/
+│   └── 02-generate.md                    ✅ scaffold aidd_docs/, fill memory to forced flat paths, review
+└── references/
+    ├── memory-destinations.md            ✅ template path -> exact flat output path
+    └── review-protocol.md                ✅ independent checker fan-out, fresh-context degrade
+```
+
+## Tasks to do
+
+### `1)` Write actions/02-generate.md
+
+> One action: scaffold, fill, review. Small file, each step one line pointing at a ref.
+
+1. Scaffold: create `aidd_docs/` with its three docs and `memory/{internal,external}` from `@../assets/`, preserving user edits.
+2. Select: take `core/` plus each confirmed capability's folder from scan.
+3. Fill: for each template, write to its forced path in `references/memory-destinations.md`, capturing the macro and non-derivable facts, never repeating a fact, pointing to code over a copy.
+4. Enforce: every core file lands flat in `aidd_docs/memory/`, never under `core/`, `internal/`, or any subfolder.
+5. Review: run `references/review-protocol.md`, apply confirmed fixes.
+6. Output: the memory bank, flat, plus the review report.
+
+### `2)` Write references/memory-destinations.md
+
+> The table that kills the nesting bug. Data, not inference.
+
+1. One row per template: source `templates/memory/<folder>/<file>.md`, destination `aidd_docs/memory/<file>.md`.
+2. State the invariant: the template folder is a capability gate only, never part of the output path.
+3. State that `internal/` and `external/` hold user notes, never a generated core file.
+
+### `3)` Write references/review-protocol.md
+
+> Independent review that works, with a stated fallback.
+
+1. Fan out one `aidd-dev:checker` subagent per memory file (or per small group), each verifying cross-file consistency, duplication, and accuracy against the code.
+2. Collect findings, apply the safe confirmed fixes, flag the rest for a human.
+3. Degrade: where the host cannot spawn subagents, run a single fresh-context review pass over all files, and say so in the report.
+
+## Test acceptance criteria
+
+<!-- Each criterion is an observable behavior, not a command. -->
+
+| Task | Acceptance criteria                                                                        |
+| ---- | ------------------------------------------------------------------------------------------ |
+| 1    | generate scaffolds the docs, fills the selected templates, and ends with a review, in one action file. |
+| 2    | memory-destinations.md maps every template to a flat `aidd_docs/memory/<file>.md` path with no subfolder. |
+| 3    | review-protocol.md fans out to independent checkers and names the fresh-context fallback.   |
+| 4    | A generate run writes every core file flat, none under `core/` or `internal/`.              |

aidd_docs/tasks/2026_07/2026_07_13_project-memory-rebuild/phase-3.md

@@ -0,0 +1,64 @@
+---
+status: done
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Sync that adapts
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+plugins/aidd-context/
+├── hooks/
+│   └── update_memory.js                  ✏️ accept an optional picked-tool list, fill only those; no-arg keeps fill-all-present
+└── skills/02-project-memory/
+    ├── actions/
+    │   └── 03-sync.md                    ✅ create the context file when missing, upsert the block, run the fill script
+    └── references/
+        └── memory-block.md               ✏️ keep the upsert cases, add the create-when-missing case for a picked tool
+```
+
+## Tasks to do
+
+### `1)` Write actions/03-sync.md
+
+> The wiring. Owns the context file end to end.
+
+1. For each tool picked in scan, resolve its context-file path per `references/tools.md`.
+2. Create the file when missing: copy `@../assets/AGENTS.md`, set the tool's title, per `references/memory-block.md`.
+3. Upsert the empty `<aidd_project_memory>` block into every picked tool's file.
+4. Run the fill script `hooks/update_memory.js`, passing the picked tools, to fill each block with the memory-file references.
+5. Guard: on a non-zero exit, print the error and stop, telling the user to check that `aidd_docs/memory/` holds a `.md` file and that `node` is available.
+6. Output: each picked tool's context file, present, wired, and filled.
+
+### `2)` Make update_memory.js respect the picked tools
+
+> Fill only what the user chose, without breaking the auto hook.
+
+1. Accept an optional tool list (CLI args), map each to its context file, fill only those.
+2. No argument: keep today's behavior, fill every target file already present.
+3. Keep the hook wiring unchanged, the hook calls it with no argument.
+4. Never insert a block: a file without `<aidd_project_memory>` is skipped, both no-arg and with-args. Block insertion stays the sync action's job.
+
+### `3)` Update references/memory-block.md
+
+> Add the create case, keep the rest.
+
+1. Keep the existing upsert cases (absent, no section, section-no-block, block-present).
+2. State that a tool picked in scan whose context file does not exist gets the file created from the template, not skipped.
+3. Note that the fill script only fills an existing block: it creates neither the file nor the block, so both are the action's job before the script runs.
+4. State the boundary: a blockless existing file (e.g. a hand-written `AGENTS.md`) is only given a block when its tool is picked; the auto hook never inserts one.
+
+## Test acceptance criteria
+
+<!-- Each criterion is an observable behavior, not a command. -->
+
+| Task | Acceptance criteria                                                                        |
+| ---- | ------------------------------------------------------------------------------------------ |
+| 1    | sync creates a missing context file for a picked tool, upserts the block, and runs the fill script. |
+| 2    | Passing only claude fills `CLAUDE.md` and leaves a pre-existing `AGENTS.md` block untouched; no-arg fills all present. |
+| 3    | memory-block.md documents the create-when-missing case and the script's update-only limit.   |
+| 4    | A non-zero script exit stops with a message, never a silent partial sync.                     |

aidd_docs/tasks/2026_07/2026_07_13_project-memory-rebuild/phase-4.md

@@ -0,0 +1,65 @@
+---
+status: done
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Instruction: Cutover and headless verify
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+plugins/aidd-context/skills/02-project-memory/
+├── SKILL.md                              ✏️ ref and asset lists point at the new files only
+├── actions/
+│   ├── 01-init-context-file.md           ❌ absorbed into 03-sync
+│   ├── 02-scaffold-docs.md               ❌ absorbed into 02-generate
+│   ├── 03-generate-memory.md             ❌ replaced by 02-generate
+│   ├── 04-review-memory.md               ❌ absorbed into 02-generate
+│   └── 05-sync-memory.md                 ❌ replaced by 03-sync
+└── references/
+    └── mapping-ai-context-file.md        ❌ merged into tools.md
+```
+
+## Tasks to do
+
+### `1)` Remove the superseded files
+
+> Delete only what the new three actions fully absorb.
+
+1. Delete the five old action files.
+2. Delete `references/mapping-ai-context-file.md`, its content now in `tools.md`.
+3. Grep the skill for any dangling `@` reference to a deleted file, fix or remove it.
+
+### `2)` Verify the skill is internally whole
+
+> No broken link, no orphaned rule.
+
+1. Run the repo link checker, expect zero broken links.
+2. Confirm every action file is reachable from SKILL.md and reads only refs that exist.
+3. Confirm no runtime instruction lives only in an authoring contract (the onboard lesson).
+
+### `3)` Headless sweep on both hosts
+
+> Prove it runs, not just that it reads.
+
+1. Build fixtures: an existing repo with a stack and no memory, a repo whose tool wrote memory into `internal/`, and one for Codex whose `AGENTS.md` carries no block.
+2. Sync this checkout into both tools' caches with `scripts/dev-sync.sh`, so the run tests the branch and not the released version.
+3. Run `02-project-memory` headless on Claude across the fixtures, capture each output.
+4. Run the same on Codex, capture its output.
+5. Assert on disk, never on the report: core files flat, the picked tool's block filled, an unpicked tool's file untouched.
+6. Record which review path ran. Both hosts have subagents today, so the no-subagent fallback stays unexercised and must not be reported as verified.
+
+## Test acceptance criteria
+
+<!-- Each criterion is an observable behavior, not a command. -->
+
+| Task | Acceptance criteria                                                                        |
+| ---- | ------------------------------------------------------------------------------------------ |
+| 1    | The five old actions and `mapping-ai-context-file.md` are gone, no reference dangles.       |
+| 2    | The link checker reports zero broken links across the skill.                                |
+| 3    | Claude and Codex both run the three-action flow end to end, each output naming scan, generate, and sync. |
+| 4    | Disk shows core memory flat, the picked tool's block filled, and an unpicked tool's file untouched. |
+| 5    | The review ran with reviewers that did not write what they read, and the report names them. |

aidd_docs/tasks/2026_07/2026_07_13_project-memory-rebuild/plan.md

@@ -0,0 +1,42 @@
+---
+objective: "02-project-memory is a three-action skill (scan, generate, sync) on the onboard anatomy, writing every core memory file flat and wiring the block into each chosen tool's context file, created when missing."
+status: implemented
+---
+
+<!-- Fill or omit these sections; never add, rename, or reorder one. -->
+
+# Plan: Rebuild 02-project-memory on the onboard anatomy
+
+## Overview
+
+| Field      | Value                                                                                  |
+| ---------- | -------------------------------------------------------------------------------------- |
+| **Goal**   | Collapse the five-action memory skill to three, token-lean, with forced flat paths and an independent review. |
+| **Source** | Brainstorm this session, grounded in the onboard rebuild and the current skill's files. |
+
+## Phases
+
+| #   | Phase                       | File                         |
+| --- | --------------------------- | ---------------------------- |
+| 1   | Router and scan             | [`phase-1.md`](./phase-1.md) |
+| 2   | Generate with forced paths  | [`phase-2.md`](./phase-2.md) |
+| 3   | Sync that adapts            | [`phase-3.md`](./phase-3.md) |
+| 4   | Cutover and headless verify | [`phase-4.md`](./phase-4.md) |
+
+## Decisions
+
+<!-- Architecture-magnitude only, one you'd regret reversing. Omit if none qualify. -->
+
+| Decision                                                                 | Why                                                                                              |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| Three actions `scan → generate → sync`, linear, each idempotent          | Five actions were four trivial ones and a pipeline; onboard proved small SKILL.md plus small actions. |
+| `sync` owns the tool context file: creates it when missing, then fills   | The user's "project-memory adapts" — no separate init skill; the config file's absence is not a veto once the tool is picked. |
+| A forced template-to-path table, flat destinations only                  | Codex and Copilot nested core files into `core/` or `internal/`, demoting them out of the always-loaded tier. Make the path data, not inference. |
+| Review is a fan-out to independent `aidd-dev:checker` subagents          | The user requires an independent review that works, not a self-check.                            |
+| Review degrades to a fresh-context pass where the host has no subagents  | Same portability lesson as onboard's orphaned rule: a runtime capability the host lacks must have a stated fallback. |
+| Merge tool detection and the context-file map into one `tools.md`        | Both are keyed by tool; one table inside the skill is DRY. Duplication with onboard stays, tables independent. |
+| Memory templates under `assets/templates/` are untouched                 | They are user-facing content; telegraphing them degrades what the reader reads.                  |
+| `update_memory.js` takes an optional picked-tool list, no-arg unchanged  | sync must fill only the tools the user picked; the same script also runs as an auto hook with no such context, so the tool list is optional and absence keeps today's fill-all-present behavior. |
+| `skill-authoring.md` stays untouched on this branch                      | Same standing constraint as the onboard rework; the authoring contract is a separate ticket.     |
+| Nesting is prevented and surfaced, never auto-remediated                | A file already nested by an older run is the user's file now. Generate writes the flat one, reports the orphan, and deletes nothing. Silently moving a file the user may have edited is worse than the drift. |
+| The Codex review self-pass is accepted, not treated as a defect         | `codex exec` headless spawns no real subagents, so the review degrades to one honest self-pass and says so. Claude fans out real independent checkers. The skill behaves as designed on both; the asymmetry is a platform limit, accepted by the user. |