refactor(aidd-context): dedupe project-memory templates and lighten actions

plugins/aidd-context/CATALOG.md

@@ -82,6 +82,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `-` | [README.md](skills/02-project-memory/README.md) | - |
 | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - |
 | `references` | [mapping-ai-context-file.md](skills/02-project-memory/references/mapping-ai-context-file.md) | - |
+| `references` | [memory-block.md](skills/02-project-memory/references/memory-block.md) | - |
 | `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Initialize or refresh the project memory bank. Use when the user wants to set up or regenerate the project's memory files. Not for updating one memory file after it exists or editing a single rule directly.` |
 
 #### `skills/03-context-generate`

plugins/aidd-context/skills/02-project-memory/SKILL.md

@@ -20,22 +20,27 @@ Bootstraps the project's context layer: the AI context files with a memory block
 
 Run the actions in order, `01 → 05`, and run each action's `## Test` before the next.
 
-## Transversal rules
+## Memory rules
 
-- Capture the macro picture and the non-derivable: decisions, conventions, gotchas, the why. Never restate derivable detail (a full schema, a file tree). Prefer a pointer to the code over a copy.
-- Keep each memory file small. Bullets stay short, code in backticks, no version number in a tech name (`React`, not `React 19`).
-- Memory files document the user's project, never AIDD's own scaffold.
-- Reflect the current state only. Drop an unused section, no empty placeholder survives.
-- Ask the user before including or excluding anything ambiguous. Never decide silently.
-- Write files, never display their content.
+Govern the content of every memory file.
 
-## Loading
+- Capture the macro and the non-derivable: decisions, conventions, gotchas, the why. Never restate a schema or a file tree. Point to the code over a copy.
+- One fact, one file: define it in its home, elsewhere reference it. Naming a shared lib in its own concern is fine.
+- Keep each file small. Short bullets, code in backticks, no version in a tech name (`React`, not `React 19`).
+- Reflect the current state only. Drop an unused section, never leave a placeholder.
 
-The core concerns load always. The `internal/` and `external/` directories are listed for on-demand reading, never auto-loaded.
+## Action rules
+
+Govern how every action runs.
+
+- Read an asset or reference relative to this skill. If one can't be read, stop and say so, never invent.
+- Ask before anything ambiguous. Never default silently.
+- End with a short report of what changed.
 
 ## References
 
 - `references/mapping-ai-context-file.md`: the per-tool context-file path.
+- `references/memory-block.md`: the context-file memory block and its upsert cases.
 - `references/capability-signals.md`: the capabilities, their signals, and the concerns each gates.
 
 ## Assets

plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md

@@ -1,6 +1,6 @@
 # 01 - Init context file
 
-Resolve the target tools, then ensure each tool's AI context file carries the project memory block.
+Ensure each target tool's AI context file carries the project memory block.
 
 ## Input
 
@@ -12,17 +12,9 @@ One context file per confirmed tool, each carrying an empty `<aidd_project_memor
 
 ## Process
 
-1. **Gate.** Read `@../assets/AGENTS.md`. If it cannot be read, stop: the plugin assets are not reachable in this host.
-2. **Detect.** Find the context files already present, using the per-tool paths in `@../references/mapping-ai-context-file.md`. Only those paths qualify. Any other file is user content, off-limits.
-3. **Resolve tools.**
-   - Re-run: every detected context file already carries the block. The confirmed set is the tools present. Skip the prompt.
-   - New: propose the detected tools plus the full list (`@../references/mapping-ai-context-file.md`) and ask which the user uses. Wait for an explicit pick. Never default to all, never infer from filenames.
-4. **Upsert.** For each confirmed tool, resolve its context-file path (`@../references/mapping-ai-context-file.md`) and apply the first matching case:
-   - Absent: copy `@../assets/AGENTS.md`, set the title for that tool.
-   - Present, no `## Memory Management`: append that section from the template.
-   - Present, section but no block: insert an empty `<aidd_project_memory>` block after the `### Project memory` heading.
-   - Block present: leave it, report "already ok".
-5. **Report.** Print a table: tool, file, action taken.
+1. **Detect.** Find the context files already present, by the per-tool paths in `@../references/mapping-ai-context-file.md`. Only those paths qualify; any other file is user content, off-limits.
+2. **Resolve tools.** On a re-run, the tools present are the confirmed set, skip the prompt. Otherwise propose the detected tools plus the full list and ask which the user uses; wait for an explicit pick, never default to all.
+3. **Upsert.** For each confirmed tool, write the memory block into its context file per `@../references/memory-block.md`.
 
 ## Test
 

plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md

@@ -1,6 +1,6 @@
 # 02 - Scaffold docs
 
-Create the `aidd_docs/` structure with its root docs and empty memory subdirectories.
+Create the `aidd_docs/` structure: root docs and empty memory subdirectories.
 
 ## Input
 
@@ -12,10 +12,9 @@ The project root.
 
 ## Process
 
-1. **Docs.** For each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`: write it from the matching `@../assets/` template if absent, or update it in place while preserving the user's customizations.
+1. **Docs.** Write each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md` from its `@../assets/` template if absent, else update in place preserving the user's edits.
 2. **Memory dirs.** Ensure `aidd_docs/memory/internal/` and `aidd_docs/memory/external/` exist, each with a `.gitkeep`.
-3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent, leaving an existing one untouched.
-4. **Report.** Print a table: path, action taken (created, updated, or skipped).
+3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent; leave an existing one.
 
 ## Test
 

plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md

@@ -8,24 +8,15 @@ The `aidd_docs/memory/` directory and the project root.
 
 ## Output
 
-The `core/` memory files plus the folder of each detected capability, filled and written flat to `aidd_docs/memory/`.
+The `core/` memory files plus each detected capability's folder, filled and written flat to `aidd_docs/memory/`.
 
 ## Process
 
-1. **Gate.** Read one template (e.g. `@../assets/templates/memory/core/architecture.md`). If it cannot be read, stop: the templates are unreachable. Never invent content.
-2. **Detect.** Find the project's capabilities (`@../references/capability-signals.md`). A capability holds when a concrete fact in the repo matches its definition, whether or not the fact is in the Evidence column. Never fire on an inferred domain. In a monorepo, scan every workspace, not the root manifest alone.
-3. **Confirm.** Show each detected capability with the concrete evidence behind it and the templates it selects. Ask the user to confirm, add, or drop one. Block on the answer.
-4. **Select.** Take every template in `core/`, plus every template in each confirmed capability's folder (`@../references/capability-signals.md`).
-5. **Reconcile.** If `aidd_docs/memory/` already holds files:
-   - A selected concern with an existing file: update it from current reality, preserving the user's edits.
-   - A selected concern with no file: create it.
-   - An existing file whose capability is no longer detected: leave it, flag it to the user, never delete.
-6. **Fill.** For each selected template, in parallel:
-   - Read its sections.
-   - Capture the macro and non-derivable facts from the project, excluding AIDD's own scaffold. Prefer a pointer to the code over a copy.
-   - Fill the sections. Drop a section with no content. Strip the guidance comment. Never copy a template verbatim, ask the user instead.
-7. **Write.** One output per template, named by the template's basename, flat at `aidd_docs/memory/<basename>`. Never nest, never rename, never consolidate.
-8. **Report.** A table: capability, concern, output file, status (created, updated, kept, or flagged).
+1. **Detect.** Find the project's capabilities (`@../references/capability-signals.md`): a capability holds when a concrete repo fact matches its definition, never an inferred domain. In a monorepo, scan every workspace.
+2. **Confirm.** Show each capability with its evidence and the templates it selects. Ask the user to confirm, add, or drop one. Block on the answer.
+3. **Select.** Take `core/` plus each confirmed capability's folder. On an existing `aidd_docs/memory/`: update a concern from current reality (keep the user's edits), create a missing one, leave-but-flag one whose capability is gone (never delete).
+4. **Fill.** For each template, knowing what earlier ones captured (never repeat a fact, point to its file): capture the macro, non-derivable facts (exclude AIDD's scaffold, point to code over a copy), fill its sections, drop an empty one, strip the guidance comment, never copy verbatim.
+5. **Write.** One file per template, named by its basename, flat in `aidd_docs/memory/`. Never nest, rename, or consolidate.
 
 ## Test
 

plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md

@@ -1,21 +1,22 @@
 # 04 - Review memory
 
-Review every memory file together for cross-file consistency, and fix what is safe.
+Review every memory file together for cross-file consistency and duplication, fixing what is safe.
 
 ## Input
 
 The `aidd_docs/memory/` directory with the generated files.
 
 ## Output
 
-The memory files, corrected in place where needed, and a status table.
+The memory files, corrected in place where safe, and a status report.
 
 ## Process
 
 1. **Read.** Load every `.md` under `aidd_docs/memory/`, recursively.
-2. **Review.** In one pass with all files in context, check consistency and accuracy across them. Fix a safe inconsistency in place. Flag one that needs a human.
-3. **Report.** A table: file, status (clean, fixed with reason, or needs review).
+2. **Review.** In one pass, check cross-file consistency and accuracy. Fix a safe issue in place, flag one that needs a human.
+3. **Deduplicate.** Keep each fact in one file, drop the copies (judge by meaning, not wording). May be handed to an independent checker subagent.
 
 ## Test
 
-- The status table covers every memory file, and each flagged file carries a reason a human can act on.
+- Every memory file is covered by the report, each flagged file with a reason a human can act on.
+- No fact's definition is duplicated across files.

plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md

@@ -12,9 +12,8 @@ Each `<aidd_project_memory>` block lists the generated memory files as reference
 
 ## Process
 
-1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to inject the references.
-2. **Guard.** On a non-zero exit, print the error and stop. Tell the user to confirm `aidd_docs/memory/` holds a `.md` file and that `node` is available.
-3. **Report.** Print how many context files were updated and how many references went into each block, then list the references per file.
+1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to fill each block (the block: `@../references/memory-block.md`).
+2. **Guard.** On a non-zero exit, print the error and stop; tell the user to check that `aidd_docs/memory/` holds a `.md` file and that `node` is available.
 
 ## Test
 

plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md

@@ -4,7 +4,7 @@ The HTTP API surface: its style, the main resources, and the contracts.
 
 ## Style
 
-- <REST, GraphQL, or RPC, the framework, where routes are defined>
+- <Server/RPC surface: REST, GraphQL, or RPC, the framework, where server routes are defined>
 - <Versioning and base path>
 
 ## Resources

plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md

@@ -1,21 +1,17 @@
 # Integration
 
-How this system talks to others: internal communication and external services.
-
-## Internal
-
-- <How services or modules communicate (HTTP, events, gRPC)>
+How this system integrates with external/third-party services.
 
 ## External services
 
 - <Each external service (payments, email, storage), its purpose, integration point>
 
 ```mermaid
 flowchart LR
-    A[TODO: macro communication between this system and its services]
+    A[TODO: macro map of this system and its external services]
 ```
 
 <!--
-Capture: the macro communication map and the external integrations.
-Skip: implementation detail. Keep the diagram macro. Remove this comment when filled.
+Capture: the external integrations and the macro map to them.
+Skip: internal module flow (that lives in architecture). Keep the diagram macro. Remove this comment when filled.
 -->

plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md

@@ -5,12 +5,7 @@ The macro technical shape: the stack, how the pieces fit, and the decisions behi
 ## Stack
 
 - <Language and runtime, the main framework, the one-line why>
-- <Key libraries that shape the codebase, and what each is for>
-
-## Structure
-
-- <The few top-level modules or layers, and each one's responsibility>
-- <Where the entry point lives>
+- <Cross-cutting libraries only; a capability's own library (ORM, test runner) lives in its file>
 
 ## How it fits together
 

plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md

@@ -4,7 +4,7 @@ How the user moves through the app: routing and the page structure.
 
 ## Routing
 
-- <The router and where routes are defined>
+- <Client routing: the router and where client routes are defined>
 - <Public versus protected route handling>
 
 ## Structure

plugins/aidd-context/skills/02-project-memory/references/capability-signals.md

@@ -23,12 +23,3 @@ A capability holds when a concrete fact in the repo matches the capability's **d
 | `cli`        | is run as a command-line tool                          | a `bin` field, or a CLI-parser dependency (commander, yargs, oclif, clap, click)                | cli                         |
 | `data`       | processes data or trains models                        | notebooks, a data-versioning or ML tool, or pipeline and model files                            | data                        |
 | `monorepo`   | hosts several packages in one repo                     | workspaces, or a monorepo tool (Turborepo, Nx, Lerna)                                            | enriches `core/codebase-map` (the Packages section), no folder |
-
-## How the action uses this
-
-- Always generate every template in `core/`.
-- For each capability that holds, generate every template in its folder.
-- Fire a capability on a concrete fact that matches its definition, whether or not the fact is in the Evidence column. Never fire on an inferred domain.
-- A capability with no concrete fact produces no file.
-- A monorepo fills the Packages section of `codebase-map`, it has no folder of its own.
-- In a monorepo, gather facts across every workspace, not the root manifest alone. A capability holds when any one workspace shows it (a React app in `packages/web` means `ui` holds for the project).

plugins/aidd-context/skills/02-project-memory/references/memory-block.md

@@ -0,0 +1,12 @@
+# Memory block
+
+The `<aidd_project_memory>` block is where a tool's AI context file points to the generated memory files. It sits under `## Memory Management` → `### Project memory` (full template: `@../assets/AGENTS.md`).
+
+## Upsert
+
+Apply the first case that matches a tool's context file:
+
+- **Absent:** copy `@../assets/AGENTS.md`, set the tool's title.
+- **No `## Memory Management`:** append that section from the template.
+- **Section but no block:** insert an empty `<aidd_project_memory>` block after `### Project memory`.
+- **Block present:** leave it, report "already ok".