feat(aidd-context): refresh cook recipes and enforce heading hierarchy

README.md

@@ -207,7 +207,7 @@ flowchart TD
     class PR done;
 ```
 
-> 🍳 **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.
+> 🍳 **How-to sheets** → bundled recipes for [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
 
@@ -293,7 +293,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. |

cli/biome.json

@@ -1,10 +1,10 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.7/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.5/schema.json",
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "preset": "recommended"
     }
   },
   "formatter": {

docs/CATALOG.md

@@ -30,7 +30,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

@@ -35,6 +35,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,12 @@ 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) | - |
 | `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) | `Manage project recipes/how-to sheets by listing, creating, updating, researching, applying, or validating a recipe. Use for recipe, cook, /cook, list, new, update, research, apply, validate.` |
 

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,6 +1,6 @@
 ---
 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: Manage project recipes/how-to sheets by listing, creating, updating, researching, applying, or validating a recipe. Use for recipe, cook, /cook, list, new, update, research, apply, validate.
 argument-hint: recipe
 ---
 
@@ -16,8 +16,11 @@ Maintains recipe how-to sheets. Project recipes live in `aidd_docs/recipes/`; bu
 | 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                |
+| 05  | `validate` | Check recipe structure, evidence, and technical usability    | recipe or `all`       |
 
-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.
+Validation entry points: `cook validate <recipe>` and `cook validate all`.
+
+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, and `validate` to check one or all recipes without changing them. 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.
 
 ## References

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

@@ -4,7 +4,7 @@ Create or update one project recipe at `aidd_docs/recipes/<slug>.md`, scaffolded
 
 ## Input
 
-The recipe topic. Ask for any missing field (description, steps, verify, related) before writing.
+The recipe topic. Infer description, steps, and verification from the request and research; ask only for a missing decision that changes the recipe's outcome or scope.
 
 ## Output
 
@@ -19,12 +19,14 @@ The recipe file at `aidd_docs/recipes/<slug>.md`, filled from the template.
    - 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.
    - 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.
+5. **Scaffold.** Scaffold from [recipe-template.md](../assets/recipe-template.md) when needed, applying [recipe-contract.md](../references/recipe-contract.md) to every section while preserving verified commands, examples, limits, screenshots, and evidence and deleting narrative repetition.
 6. **Fill.** Fill every placeholder. Never maintain a separate recipe index; `list` reads the files directly.
+7. **Validate.** Run `validate` (05), fix every deterministic or semantic finding, and rerun both checks until they 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.
+- `aidd_docs/recipes/<slug>.md` exists and passes the recipe contract.
+- `validate` passes after the write; no validation finding is silently waived.
 - 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.

plugins/aidd-context/skills/12-cook/actions/03-research.md

@@ -19,14 +19,15 @@ Every presented item is confirmed to exist, with its latest state and official l
 ## Process
 
 1. **Refine.** Fill [research-goal-checklist.md](../assets/research-goal-checklist.md) with the user until the target is precise: outcome, level, scope, grouping. Resolve and read the recipe with [recipe-locations.md](../references/recipe-locations.md) when it exists. Run `list` when it is unnamed.
-2. **Fan out.** Spawn one agent per angle in [research-playbook.md](../references/research-playbook.md) via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources.
+2. **Scout.** Cover every angle in [research-playbook.md](../references/research-playbook.md). The caller or orchestrator may isolate or parallelize independent angles; this action never requires a particular delegation mechanism. Return candidates with sources.
 3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear [research-checklist.md](../assets/research-checklist.md): gaps filled, unknowns surfaced, claims corroborated.
-4. **Verify.** Spawn one agent per surviving candidate via the `Task` tool to confirm it exists, capture its official link, and record its latest state (version or date). Drop any candidate that cannot be confirmed against an official source.
+4. **Verify.** Apply the playbook's candidate checks. Drop anything that cannot be confirmed against an official source.
 5. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, each item carrying its official link, then state a recommendation and why.
 6. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe.
 
 ## Test
 
 - The output has an alternatives table with pros and cons, a coverage-gaps list, and a counter-intuitive wins list, plus an explicit recommendation, and nothing is written to disk.
 - Every presented item carries an official link and was confirmed to exist; unverifiable candidates are dropped.
+- Every candidate clears the playbook's evidence and transferability criteria.
 - The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`.

plugins/aidd-context/skills/12-cook/actions/05-validate.md

@@ -0,0 +1,50 @@
+# 05 - Validate recipes
+
+Check one recipe or every available recipe without changing files.
+
+```text
+cook validate <recipe>
+cook validate all
+```
+
+```md
+@../references/recipe-locations.md
+@../references/recipe-contract.md
+```
+
+## Input
+
+A recipe named by number from the latest `list`, slug, title, or path; or `all` for every project and bundled recipe.
+
+## Output
+
+On success:
+
+```text
+PASS: <n> recipe(s) validated.
+Checks: deterministic and semantic; unavailable parsers: <languages or none>.
+```
+
+On failure:
+
+```md
+| File | Line | Rule | Fix |
+| --- | ---: | --- | --- |
+| <path> | <line> | <rule> | <specific correction> |
+```
+
+Validation is read-only. Never repair, reformat, or rewrite a recipe during this action.
+
+## Process
+
+1. **Resolve.** Resolve one recipe with `@../references/recipe-locations.md`, or keep `all` as the full project-plus-bundled scope.
+2. **Check structure.** Run `node <skill-directory>/scripts/validate-recipe.mjs <resolved-path>` or `node <skill-directory>/scripts/validate-recipe.mjs --all`. Preserve its exit code and findings.
+3. **Check semantics.** Apply the Writing, Steps, and Evidence rules from `@../references/recipe-contract.md`; record one line-specific finding per violated rule. For non-JSON snippets, use available native YAML, TOML, and shell parsers and record which languages could not be checked mechanically.
+4. **Report.** Merge deterministic and semantic findings into the output table, or print the two success lines. An unavailable optional parser is disclosed but does not fail an otherwise valid recipe. Do not suppress a finding because it requires editorial judgment.
+
+## Test
+
+- One valid recipe and `all` return PASS without changing tracked files.
+- A structural failure returns the validator table with file, line, rule, fix, and a non-zero exit code.
+- A semantic failure appears in the same table even when the deterministic script passes.
+- JSON is parsed mechanically; YAML, TOML, and shell use available tools, and unavailable parsers appear in the success summary or a relevant failure.

plugins/aidd-context/skills/12-cook/assets/recipe-template.md

@@ -1,50 +1,17 @@
-# <Recipe title>
+# <!-- Recipe title -->
 
-<One sentence describing what this recipe gets the reader.>
+<!-- Write one plain sentence naming the observable outcome. -->
 
-## Why
+<!-- Add a table of contents only when the finished recipe has at least 10 steps. -->
 
-<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.>
+## Steps to <!-- outcome -->
 
-## Steps to <the outcome the reader achieves>
+### 1) <!-- emoji + action title -->
 
-### 🟢 Beginner
-
-#### 1) <emoji> <First step title>
-
-<One benefit-focused line of what and why, in prose.>
-
-1. <where it is, then install it from its URL>
-2. <how to invoke it — its real command or slash>
-
-```bash
-$ <command the reader runs>
-<the useful output it prints, trimmed to what matters>
-```
-
-### 🟡 Intermediate
-
-#### 2) <emoji> <Next step title>
-
-<Benefit-focused what and why, in prose.>
-
-1. <action>
-2. <action>
-
-```<lang>
-<a config or snippet the reader can copy>
-```
-
-### 🔴 Expert
-
-#### 3) <emoji> <Last step title — until the goal is reached>
-
-<Benefit-focused what and why, in prose.>
-
-1. <action>
-
-![<what this screenshot or video shows>](<path-or-url>)
+<!-- Start with one benefit or risk sentence. -->
+<!-- Add numbered actions only when the technique has multiple actions. -->
+<!-- Add a typed, copyable command/config/output, a concrete table, or an operational image. -->
 
 ## Verify
 
-- <Optional. An observable check that proves it worked: a command, a UI state, a file that now exists.>
+<!-- Add an observable command output, UI state, or file check; omit only when none exists. -->