feat(aidd-context): refresh cook recipes and validate practical guides

README.md

@@ -236,7 +236,7 @@ Start with a functional need or User Story, then track it as an issue or ticket
 before planning. Shipping follows the project's own delivery process. Capture a
 learning only when it is durable enough to improve the next feature.
 
-> 🍳 **More flows** → bundled recipes: [start a project](plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md), [ship a feature](plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md), and more.
+> 🍳 **More flows** → bundled recipes: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md).
 
 ## 🧩 Plugins
 
@@ -338,7 +338,7 @@ Full catalog → [`CATALOG.md`](docs/CATALOG.md).
 
 | | |
 | --- | --- |
-| 🍳 **Recipes** | Bundled how-to sheets: [start a project](plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md), [ship a feature](plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md), [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md). Project recipes created by cook live in `aidd_docs/recipes/`. |
+| 🍳 **Recipes** | Bundled how-to sheets: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. |
 | 🏛️ **[Architecture](docs/ARCHITECTURE.md)** | How the framework composes: plugins, skills, hooks, agents. |
 | 🧩 **[Create a plugin](docs/CREATE_PLUGIN.md)** | Build and publish your own. |
 | 🛒 **[Marketplace](docs/MARKETPLACE.md)** | Install scopes, versioning, LLM tiers. |

aidd_docs/tasks/2026_10/2026_10_01_cook-pr-cleanup/review.md

@@ -0,0 +1,41 @@
+# Review: Cook recipe authoring cleanup
+
+- **Verdict**: approve
+- **Diff**: `ff28a45c...HEAD`
+- **Axes run**: code, functional, relevancy
+- **Date**: 2026_10_01
+- **Findings**: 0 critical, 0 warning, 0 minor
+
+## Phases
+
+### Phase 1: Recipe authoring
+
+- [x] Restore the original English Markdown scaffold with optional sections: `plugins/aidd-context/skills/12-cook/assets/recipe-template.md:1`.
+- [x] Keep nine concise contract principles without duplicated scaffolding: `plugins/aidd-context/skills/12-cook/references/recipe-contract.md:3`.
+- [x] Preserve standalone routes, repair routing, action tests, and catalog consistency: `plugins/aidd-context/skills/12-cook/SKILL.md:9`, `plugins/aidd-context/skills/12-cook/actions/02-upsert.md:28`, `plugins/aidd-context/skills/12-cook/actions/05-validate.md:22`.
+
+### Phase 2: Reliable validation
+
+- [x] Accept useful Markdown variants while reporting broken structure, examples, and links: `scripts/__tests__/validate-recipe.test.js:139`.
+- [x] Read and inspect the same file descriptor, close it, and report read failures: `plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs:39`.
+- [x] Run through symlinked entry points without executing on library import: `plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs:504`, `scripts/__tests__/validate-recipe.test.js:391`.
+- [x] Remove punctuation-based description false positives and keep the RTK recipe correction scoped to step 19: `scripts/__tests__/validate-recipe.test.js:208`, `plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md:383`.
+
+## Findings
+
+None.
+
+## Verification
+
+| Metric | Value |
+| --- | --- |
+| Verified | 7/7 cleanup criteria |
+| Files checked | Nine staged cleanup files; independent checker reviewed code, behavior, and relevance |
+| Unchecked | None within the bounded cleanup review |
+| Unplanned | None |
+| Checker execution | 27 guarded validator tests passed; bundled validation returned `PASS: 3 recipe(s) validated.` |
+| Main execution | Global pre-commit passed: 576 script tests, 140 CLI architecture tests, typecheck, lint, manifests, paths, and links |
+| Snippet syntax | 4 JSON, 2 YAML, 8 TOML, and 9 shell examples parsed successfully |
+| Distribution execution | Fresh Codex flat and Claude marketplace builds each returned the exact three-recipe PASS output |
+| CI follow-up | The character-based heading parser and LF/CRLF template assertion were independently approved after the first remote run exposed those gaps |
+| Limits | CodeQL and native Windows remain to be confirmed on the follow-up commit after push; interactive client workflows were not executed |

docs/CATALOG.md

@@ -32,7 +32,7 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex
 | `09-mermaid`           | Generate Mermaid diagrams via a plan-validate workflow                        | `01-mermaid`                                                                                             |
 | `10-learn`             | Capture learnings, conventions, and decisions into memory, decisions, rules   | `01-gather`, `02-assess`, `03-write`, `04-sync`                                                          |
 | `11-explore`           | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill`                                                                                  |
-| `12-cook`              | Manage project and bundled recipes: list, create/update, research, or apply one | `01-list`, `02-upsert`, `03-research`, `04-apply`                                                        |
+| `12-cook`              | Manage and validate technical project or bundled recipes                       | `01-list`, `02-upsert`, `03-research`, `04-apply`, `05-validate`                                         |
 
 ## 💻 aidd-dev
 

lefthook.yml

@@ -53,6 +53,13 @@ pre-commit:
             exit 1
           fi
         done
+    recipe-validity:
+      run: |
+        if ! command -v node >/dev/null 2>&1; then
+          echo "❌ node not available; cannot validate recipes"
+          exit 1
+        fi
+        node plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs --all
     check-skill-argument-hints:
       glob: "plugins/*/skills/**"
       run: |

plugins/aidd-context/CATALOG.md

@@ -207,11 +207,13 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [02-upsert.md](skills/12-cook/actions/02-upsert.md) | - |
 | `actions` | [03-research.md](skills/12-cook/actions/03-research.md) | - |
 | `actions` | [04-apply.md](skills/12-cook/actions/04-apply.md) | - |
+| `actions` | [05-validate.md](skills/12-cook/actions/05-validate.md) | - |
 | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - |
 | `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - |
 | `assets` | [research-goal-checklist.md](skills/12-cook/assets/research-goal-checklist.md) | - |
+| `assets` | [validation-report-template.md](skills/12-cook/assets/validation-report-template.md) | - |
 | `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - |
 | `references` | [recipe-locations.md](skills/12-cook/references/recipe-locations.md) | - |
 | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - |
-| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage project recipes/how-to sheets by listing, creating, updating, researching, or applying a recipe. Use for recipe, cook, /cook, list, new, update, research, apply.` |
+| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manages project recipes and practical guides. Use when the user wants to find a recipe, document a technique, research improvements, follow an existing guide, or check that its steps are usable.` |
 

plugins/aidd-context/README.md

@@ -21,7 +21,7 @@ Covers project bootstrap, the project memory bank, generation of context artifac
 | [1.4]      | [mermaid](skills/09-mermaid/SKILL.md)                 | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow.                                                         |
 | [1.5]      | [learn](skills/10-learn/SKILL.md)                     | Capture durable learnings from the conversation or git history, score each, and route the worthwhile ones to memory, a decision record, a rule, or a new skill. |
 | [1.6]      | [explore](skills/11-explore/SKILL.md)                 | Survey the project across three axes (tooling, context, codebase), then drill into one axis and point to the best-matching item for a goal.                      |
-| [1.7]      | [cook](skills/12-cook/SKILL.md)                       | Maintain project recipes in `aidd_docs/recipes/` and bundled recipes shipped with the skill: list, research, create/update, or apply one.                    |
+| [1.7]      | [cook](skills/12-cook/SKILL.md)                       | Maintain project and bundled recipes: list, research, create/update, apply, or validate one or all.                                                        |
 
 ## Onboarding
 

plugins/aidd-context/skills/12-cook/SKILL.md

@@ -1,31 +1,51 @@
 ---
 name: 12-cook
-description: Manage project recipes/how-to sheets by listing, creating, updating, researching, or applying a recipe. Use for recipe, cook, /cook, list, new, update, research, apply.
+description: Manages project recipes and practical guides. Use when the user wants to find a recipe, document a technique, research improvements, follow an existing guide, or check that its steps are usable.
 argument-hint: recipe
 ---
 
 # Cook
 
-Maintains recipe how-to sheets. Project recipes live in `aidd_docs/recipes/`; bundled recipes ship inside this skill under `assets/recipes/`.
+```mermaid
+flowchart LR
+    unnamed([unnamed recipe]) --> list
+    named-new([new recipe]) --> research
+    named-update([update recipe]) --> research
+    named-research([research topic]) --> research
+    named-apply([apply recipe]) --> apply
+    named-validate([validate recipe or all]) --> validate
+    list -->|list only| listed([listed])
+    list -->|create, update, or reselect for research| research
+    list -->|select or reselect to apply| apply
+    list -->|resume dedup| upsert
+    list -->|reselect to validate| validate
+    research -->|unnamed or stale number| list
+    research -->|standalone research| researched([researched])
+    research -->|create, update, or selected insights| upsert
+    upsert -->|new or substantial, missing verified results| research
+    upsert -->|new, before dedup| list
+    upsert -->|written| validate
+    validate -->|stale number| list
+    validate -->|standalone, pass| validated([validated])
+    validate -->|standalone, findings| findings([findings])
+    validate -->|upsert, pass| saved([saved])
+    validate -->|upsert, findings: repair at Scaffold| upsert
+    apply -->|unnamed or stale number| list
+    apply -->|report only or chosen steps complete| reported([reported])
+```
 
 ## Actions
 
-| #   | Action     | Role                                                         | Input                 |
-| --- | ---------- | ----------------------------------------------------------- | --------------------- |
-| 01  | `list`     | List every recipe as a table                                | none                  |
-| 02  | `upsert`   | Create or update one recipe from the template               | recipe topic + fields |
-| 03  | `research` | Survey modern alternatives, gaps, and counter-intuitive wins | recipe or topic      |
-| 04  | `apply`    | Execute a recipe on the project as a confirmed todo list    | recipe                |
+Run the flow above. Read only the next action file.
 
-Run `list` to survey project and bundled recipes, `research` to gather insights, `upsert` to author one, `apply` to run an existing one against the project. Always run `research` before authoring or substantially updating a recipe — never draft from memory alone. Run `list` first when the user names no recipe.
-Before running an action, read its file in `actions/`, not only the table or assets.
+| Action | Does |
+| --- | --- |
+| list | list project and bundled recipes |
+| research | research one recipe or topic |
+| upsert | create or update one recipe |
+| apply | apply one existing recipe |
+| validate | validate one or all recipes |
 
-## References
+## Transversal rules
 
-- `references/recipe-locations.md`: where project and bundled recipes live, how resolution works, and when writes target each home.
-- `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it.
-
-## Assets
-
-- `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses.
-- `assets/recipes/`: bundled recipes shipped with this skill.
+- Never maintain a separate recipe index.

plugins/aidd-context/skills/12-cook/actions/01-list.md

@@ -4,25 +4,29 @@ List project recipes and bundled recipes as one table.
 
 ## Output
 
+A numbered table of project and bundled recipes, or `No recipes yet.`
+
 ```md
 | # | Recipe | Source | Description |
 | ---: | --- | --- | --- |
 | <n> | [<title>](<path>) | project \| bundled | <description> |
 ```
 
-One row per recipe file, sorted by source then file name, numbered from 1 after sorting. If both homes are absent or empty: `No recipes yet.`
-
 ## Process
 
-1. **Read.** Read every recipe in both homes of [recipe-locations.md](../references/recipe-locations.md), excluding `README.md`.
+1. **Read.** Read every recipe in both homes of [recipe-locations.md](../references/recipe-locations.md).
+   - Exclude `README.md`.
 2. **Title.** Pull the H1 title and the one-sentence description right below it.
-3. **Shadow.** Mark a project row active and its bundled twin shadowed when both share a slug.
-4. **Number.** Sort, then assign contiguous numbers from 1 to N.
-5. **Render.** Render the table above.
+3. **Shadow.** Mark matching-slug project rows active and their bundled twins shadowed.
+4. **Number.** Sort by source then file name and assign contiguous numbers from 1 to N.
+5. **Render.** Render one row per recipe file using the table above.
+   - If both homes are absent or empty, return `No recipes yet.` without an error.
 
 ## Test
 
-- One row per project and bundled recipe file, each with number, title, source, and description.
-- A project recipe with the same slug as a bundled recipe is marked active and overrides the bundled copy.
-- Numbers are contiguous, start at 1, and match the displayed sort order.
-- Absent/empty project and bundled homes → `No recipes yet`, no error.
+| Case | Pass |
+| --- | --- |
+| Project and bundled recipe files | Each file has one row with number, title, source, and description |
+| Matching project and bundled slugs | The project copy is active and the bundled copy is shadowed |
+| Numbered rows | Numbers are contiguous from 1 and follow source then file name order |
+| Both homes absent or empty | `No recipes yet.` is returned without an error |

plugins/aidd-context/skills/12-cook/actions/02-upsert.md

@@ -1,30 +1,41 @@
 # 02 - Upsert recipe
 
-Create or update one project recipe at `aidd_docs/recipes/<slug>.md`, scaffolded from the recipe template and following the recipe contract.
+Create or update one recipe from verified research.
 
 ## Input
 
-The recipe topic. Ask for any missing field (description, steps, verify, related) before writing.
+The recipe topic and any verified results from `research`.
 
 ## Output
 
 The recipe file at `aidd_docs/recipes/<slug>.md`, filled from the template.
 
 ## Process
 
-1. **Research.** For a new recipe or any substantial update, run `research` (03) on the topic and draft only from its verified results, never from memory.
+1. **Evidence.** Use verified research results for a new recipe or any substantial update.
+   - Never draft those changes from memory.
 2. **Slug.** Derive a kebab-case `<slug>` from the topic.
 3. **Resolve.** Resolve existing recipes with [recipe-locations.md](../references/recipe-locations.md).
    - The project recipe exists: update `aidd_docs/recipes/<slug>.md` in place.
-   - Only a bundled recipe exists: ask whether to copy it into `aidd_docs/recipes/<slug>.md` or edit the bundled one. Edit a bundled recipe only when the user asks for that framework-source change.
-4. **Dedup.** For a new recipe, run `list` and rate each near match in an overlap table `| Existing recipe | Source | Shared scope | Overlap |`, where `Overlap` is none, partial, or high.
+   - If only a bundled recipe exists, ask whether to copy it into `aidd_docs/recipes/<slug>.md` or edit the bundled one.
+   - Edit a bundled recipe only on an explicit framework-source change request.
+4. **Ask.** Ask only for a missing decision that changes the recipe's outcome or scope.
+5. **Dedup.** Compare a new recipe with each near match in the current recipe list using `| Existing recipe | Source | Shared scope | Overlap |`.
+   - Compare before scaffolding.
+   - Use none, partial, or high for `Overlap`.
    - On any `high`, recommend updating that recipe instead and ask update-or-create before scaffolding.
-5. **Scaffold.** Scaffold from [recipe-template.md](../assets/recipe-template.md) when needed, applying [recipe-contract.md](../references/recipe-contract.md) to every section.
-6. **Fill.** Fill every placeholder. Never maintain a separate recipe index; `list` reads the files directly.
+6. **Scaffold.** Use [recipe-template.md](../assets/recipe-template.md) when needed and apply [recipe-contract.md](../references/recipe-contract.md).
+   - Preserve verified useful content on updates.
+7. **Fill.** Fill every placeholder and save the recipe.
+   - On validation findings, resume at Scaffold and Fill, reusing verified research until both checks pass.
 
 ## Test
 
-- A new or substantially-updated recipe is drafted from `research` results, not from memory.
-- `aidd_docs/recipes/<slug>.md` exists and follows the recipe contract: opens with a one-sentence description (no Goal label, no table), each step a `#### N)` emoji heading with a real example, no `<...>` placeholder left.
-- A bundled recipe is never overwritten unless the user explicitly asks to change a bundled/framework recipe.
-- A new recipe that highly overlaps an existing project or bundled recipe triggers an update-or-create prompt before scaffolding.
+| Case | Pass |
+| --- | --- |
+| New or substantially updated recipe | The draft uses verified research results rather than memory |
+| Project recipe written | `aidd_docs/recipes/<slug>.md` exists and passes the recipe contract |
+| Update or validation repair | Verified useful content and research results are preserved |
+| Validation after writing | Both checks pass and no finding is silently waived |
+| Bundled recipe selected | It is overwritten only on an explicit bundled/framework change request |
+| High overlap with an existing recipe | An update-or-create prompt precedes scaffolding |