@forgeailab/create-spark 0.1.2 → 0.2.0

package/.claude/skills/mvp-spec/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: mvp-spec
+description: Convert a grilled idea into a single concise MVP specification that an executor can build from. Use when the user says "write the spec", "let's lock the MVP", or after `/mvp-grill` has settled the open questions. Do NOT use if `.ai/product-spec.md` already exists and is current — edit it directly or run `/risk-check` first.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# Skill: mvp-spec
+
+## Goal
+
+Produce `.ai/product-spec.md` — the single source of truth for what the MVP is. Technical enough that Sonnet/Claude Code can execute without guessing, short enough to fit in working memory.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these if they exist:
+
+- `.ai/decision-log.md` (this is the input — do not re-grill)
+- existing `.ai/product-spec.md` (update in place rather than rewrite)
+
+If the decision log is missing the answers needed, stop and tell the user to run `/mvp-grill` first. Do not invent answers.
+
+## Rules
+
+- One spec, one MVP slice. If the user wants v1 and v2, write v1 only.
+- Every section must fit on one screen. If it does not, you are over-specifying.
+- **Non-goals are mandatory.** A spec without a non-goals list always leaks scope.
+- Acceptance criteria must be checkable, not aspirational.
+- Do not pick a stack here — that is `/architecture-cutline`'s job.
+- Do not write tasks here — that is `/mvp-board`'s job.
+
+## Output format
+
+Write `.ai/product-spec.md` with exactly these sections:
+
+```md
+# Product Spec — <name>
+
+## 1. One-sentence product
+<who it is for, what it does, what they get>
+
+## 2. Target user
+<specific persona, not a category>
+
+## 3. Core user journey
+<3–7 numbered steps from open-app to win>
+
+## 4. MVP feature list
+- <feature>: <one-line description>
+(keep this list aggressively short)
+
+## 5. Non-goals
+- <thing we will NOT build for MVP>
+(at least 5 entries; this section is mandatory)
+
+## 6. Data model
+<entities and their key fields, no SQL>
+
+## 7. Screens / pages
+- <route>: <purpose>
+
+## 8. Integrations
+<auth, payments, third-party APIs, or "none">
+
+## 9. Risks
+<technical, product, or scope risks — 3–5 bullets>
+
+## 10. Acceptance criteria
+- [ ] <observable, testable statement>
+(these are what makes MVP "done")
+```
+
+After writing, return a short summary and recommend `/architecture-cutline` next.

package/.claude/skills/new-pack/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: new-pack
+description: Scaffold a new local feature-pack directory under `packs/` with a minimal manifest, empty files and skills directories, and an empty task stub. Prompts for install mode (`copy` or `hybrid`); a `hybrid` pack additionally scaffolds a companion `libs/spark-<name>/` workspace package and writes a `[runtime_package]` block into the new manifest. Use when a needed capability has no v1 pack.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# Skill: new-pack
+
+## Goal
+
+Create a minimal pack skeleton that a human or executor can fill in later. This skill only scaffolds the pack directory (and, in `hybrid` mode, a companion workspace package under `libs/`); it does not implement the integration.
+
+## Recommended model
+
+Sonnet 4.6 or GPT-5 family executor.
+
+## Inputs
+
+Required from the user:
+
+- `<name>` — pack directory name, for example `realtime-supabase`
+- `category=<category>` — one of the v1 category values
+- `mode=<mode>` — install mode, either `copy` or `hybrid`
+
+If any of these values is missing, ask for it before writing files. When asking for `mode`, explain the difference:
+
+- `copy` — pack ships its full runtime logic as files copied into the consumer project. The user owns the code in place. This is the right default for stable framework glue (config files, route handlers, env wiring).
+- `hybrid` — pack ships only thin wiring files and imports its runtime logic from a versioned npm helper package `@forgeailab/spark-<name>` published from `libs/spark-<name>/`. Choose this when the logic is the same across every consumer project and bug fixes should land in one place.
+
+## Valid categories
+
+- `db`
+- `auth`
+- `payments`
+- `email`
+- `ui`
+- `ai`
+- `infra`
+- `testing`
+- `deploy`
+- `analytics`
+- `storage`
+
+## Rules
+
+- Validate that `<name>` is a single directory segment. Reject names containing `/`, `..`, spaces, or shell metacharacters.
+- Validate that `packs/<name>/` does not already exist. If it exists, stop and report the collision.
+- Validate that `category` is exactly one of the allowed categories above.
+- Validate that `mode` is exactly `copy` or `hybrid`.
+- Pack scaffold (both modes) creates only these paths:
+  - `packs/<name>/pack.toml`
+  - `packs/<name>/files/`
+  - `packs/<name>/skills/`
+  - `packs/<name>/tasks.yaml`
+- Additionally in `hybrid` mode, validate that `libs/spark-<name>/` does not already exist, then create the companion workspace package:
+  - `libs/spark-<name>/package.json`
+  - `libs/spark-<name>/tsconfig.json`
+  - `libs/spark-<name>/src/index.ts`
+  - `libs/spark-<name>/test/index.test.ts`
+  - `libs/spark-<name>/README.md`
+- `tasks.yaml` must be an empty stub file.
+- Leave `provides`, `requires`, and `conflicts` empty. Do not guess capability tags.
+- The pack's `[dependencies].runtime` MUST NOT redeclare the helper package — the CLI adds it implicitly from `[runtime_package]`.
+
+## `pack.toml` skeleton — `copy` mode
+
+Write this manifest, replacing `<name>` and `<category>`:
+
+```toml
+name = "<name>"
+version = "0.1.0"
+category = "<category>"
+description = "TODO: describe what this pack adds."
+provides = []
+requires = []
+conflicts = []
+```
+
+## `pack.toml` skeleton — `hybrid` mode
+
+In `hybrid` mode, the manifest gains a `[runtime_package]` table pointing at the companion helper:
+
+```toml
+name = "<name>"
+version = "0.1.0"
+category = "<category>"
+description = "TODO: describe what this pack adds."
+provides = []
+requires = []
+conflicts = []
+
+[runtime_package]
+package = "@forgeailab/spark-<name>"
+version = "^0.1"
+```
+
+## `libs/spark-<name>/` skeleton — `hybrid` mode only
+
+`package.json`:
+
+```json
+{
+  "name": "@forgeailab/spark-<name>",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}
+```
+
+`tsconfig.json`:
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*", "test/**/*"]
+}
+```
+
+`src/index.ts`: empty `export {};` placeholder.
+`test/index.test.ts`: minimal `test('placeholder', () => expect(true).toBe(true));`.
+`README.md`: one-line description plus a "Why is this in libs/ vs packages/?" note (it is a library consumers import from, not internal CLI plumbing).
+
+## Output format
+
+After creating the skeleton, return:
+
+```md
+## New pack scaffolded
+
+- Pack: `<name>`
+- Category: `<category>`
+- Install mode: `<mode>`
+- Created:
+  - `packs/<name>/pack.toml`
+  - `packs/<name>/files/`
+  - `packs/<name>/skills/`
+  - `packs/<name>/tasks.yaml`
+  <!-- hybrid mode only -->
+  - `libs/spark-<name>/package.json`
+  - `libs/spark-<name>/tsconfig.json`
+  - `libs/spark-<name>/src/index.ts`
+  - `libs/spark-<name>/test/index.test.ts`
+  - `libs/spark-<name>/README.md`
+
+Next: fill in `provides`, `requires`, files, tasks, and any pack-shipped skills before installing it.
+In hybrid mode, also implement the runtime helper under `libs/spark-<name>/src/` and re-run `bun install`.
+```

package/.claude/skills/next-task/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: next-task
+description: Pick the next best board task to work on, with the reasoning. Use when the user says "what should I do next?", "what's next?", or after `/sync-board` finishes. Do NOT use to plan a whole batch — that is `/parallel-execution`.
+allowed-tools:
+  - Read
+---
+
+# Skill: next-task
+
+## Goal
+
+Recommend the single next task (or smallest parallel batch) the user should execute now, based on the current state of the board.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5. Picking the next move is a planning call.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+- `.ai/product-spec.md`
+
+Read if available:
+
+- `.ai/architecture.md`
+- `.ai/execution-log.md`
+
+## Rules
+
+Decision order, in priority:
+
+1. **Unblock the core user flow first.** The user's primary action in the spec must work end-to-end before anything else.
+2. **Prefer tasks whose dependencies are satisfied.** A task with unmet `Depends on:` is not eligible.
+3. **Prefer tasks with clear acceptance criteria** over vague ones.
+4. **Batch parallel-safe tasks** only when the user explicitly asked for parallelism.
+5. **Schedule QA after every feature batch**, not at the end of the project.
+6. **Do not pick polish before core works.** Empty states and copy come after the loop is alive.
+
+Only recommend tasks in status `Approved for execution`. If nothing is approved, recommend `/board-review` instead.
+
+## Output format
+
+```md
+## Next recommended
+
+### Task
+- <TASK-ID>: <title>
+
+### Why now
+<one line — usually one of: "unblocks core flow", "prerequisites just landed", "highest-risk path">
+
+### Dependencies satisfied
+- <DEP-ID>: <status> ✓
+
+### Risk
+<low | medium | high — and the specific risk if not low>
+
+### Suggested execution
+Run `/implementation-brief <TASK-ID>`, then `/execute-task <TASK-ID>`.
+
+### Alternative
+<one other reasonable pick + one-line reason, or "none — this is the clear next step">
+```

package/.claude/skills/pack-add/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: pack-add
+description: Safely install feature packs by dry-running `spark add`, showing the plan, waiting for explicit approval, running the real install, and syncing the board. Use when the user asks to add one or more packs.
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Skill: pack-add
+
+## Goal
+
+Install packs through the board-aware workflow: dry-run first, show the plan, get explicit confirmation, install, then sync the board so seeded tasks appear.
+
+## Recommended model
+
+Sonnet 4.6 or GPT-5 family executor.
+
+## Inputs
+
+Read these if present:
+
+- `spark.config.json`
+- `.ai/architecture.md`
+- `.ai/board.md`
+- `.spark/state.json`
+
+The user must provide one or more pack names. If no pack is named, stop and ask for the pack list or recommend `/pack-resolve`.
+
+## Rules
+
+- Always run `spark add <pack...> --dry-run` before any real install.
+- Present the dry-run diff or plan to the user in compact form: packs, dependencies, files, env vars, skills, and board tasks.
+- Wait for explicit confirmation before installing. Accept only clear approval such as "yes", "approved", or "install".
+- If the dry-run fails, stop. Do not attempt the real install.
+- If the user declines or gives an ambiguous answer, stop with no filesystem changes.
+- On approval, run `spark add <pack...>` with the same pack arguments as the dry-run.
+- After a successful install, invoke `/sync-board` so seeded tasks are reflected in `.ai/board.md`.
+- Do not mark any seeded task `Approved for execution` or `Validated`; board-review and review skills own those transitions.
+
+## Workflow
+
+1. Confirm the pack arguments exactly as provided.
+2. Run `spark add <pack...> --dry-run`.
+3. Summarize the plan and ask the user for explicit approval.
+4. If approved, run `spark add <pack...>`.
+5. If install succeeds, run `/sync-board`.
+6. Report the installed packs, changed files summary, and board sync result.
+
+## Output format
+
+Before approval:
+
+- Dry-run command
+- Planned pack order
+- Files/env/skills/tasks summary
+- Confirmation question
+
+After install:
+
+- Install command
+- Result
+- `/sync-board` result
+- Any follow-up tasks or blockers

package/.claude/skills/pack-resolve/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: pack-resolve
+description: Recommend the right scaffold template and concrete feature packs from `.ai/product-spec.md` and `.ai/architecture.md`. Annotates each recommended pack as `copy` or `hybrid` based on whether its manifest declares `[runtime_package]`. Use when the user asks which packs to install, wants a scaffold/preset recommendation, or scope changed after architecture. This skill only plans; it never installs.
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Skill: pack-resolve
+
+## Goal
+
+Recommend a scaffold template and a concrete pack set from the current product spec and architecture. The output should be directly actionable, but this skill must not execute any install.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+
+Read these if present:
+
+- `templates/*/template.toml`
+- `packs/*/pack.toml`
+- `presets/*.toml`
+- `spark.config.json`
+
+If the spec or architecture is missing, stop and tell the user to run `/mvp-spec` and `/architecture-cutline` first.
+
+## Rules
+
+- Do not run `bunx create-spark`, `spark add`, or `spark preset`. This is a planning skill only.
+- Resolve from the registry, not from memory. Pack names must come from `packs/*/pack.toml`; templates must come from `templates/*/template.toml`.
+- Prefer the smallest pack set that satisfies the spec and architecture. Do not install "usual SaaS" packs unless the capability is actually required.
+- Group packs by manifest `category`, and map each pack to the capability tags it provides or satisfies.
+- Annotate each recommended pack as either `copy` or `hybrid`. The classification is derived from the pack's `pack.toml`: presence of a `[runtime_package]` table means `hybrid`; absence means `copy`. Readers must immediately see which packs ship a versioned runtime helper they will import from versus which copy source files into the project.
+- Respect `requires`, `conflicts`, `compatible_scaffolds`, and `requires_runtime` when recommending a set.
+- If a needed capability has no v1 pack, name the gap explicitly and suggest `/new-pack`. Do not invent a pack name or include the missing capability in the command.
+- If the best-fit template has `status = "planned"`, still recommend it as the destination, write `planned, not yet implemented`, suggest `nextjs` as the interim alternative, and make the final command use the executable interim path.
+- If a preset exactly matches the recommended fresh-project pack set, the final command may be `bunx create-spark <name> --template <t> --preset <p>`. Otherwise, or when resolving for an existing project, the final command must be `spark add <pack...>` using only real pack names from the registry.
+- The final answer must end with exactly one fenced `sh` command block and no text after it.
+
+## Capability hints
+
+Use these only as hints; the registry still wins:
+
+- Paid SaaS: `db`, `auth`, `payments`, `email`, `ui-kit`, `deploy-target`.
+- Internal tool: `db`, `auth`, `ui-kit`, optionally `local-runtime`.
+- AI workflow: `ai-sdk`, optional `db`, optional `ui-kit`.
+- Documentation site: `mdx-content` template capability; `astro-starlight` may be the destination but is planned in v1.
+- Realtime/client-first sync: `sync`; if the requested capability is broader than the v1 `sync-zero` pack covers, name the gap.
+
+## Output format
+
+Return these sections:
+
+- `## Scaffold` — recommended template, status, why it fits, and interim alternative if the best fit is planned.
+- `## Packs` — grouped by category. Each bullet must be `<pack-name> (<copy|hybrid>)` followed by `provides:` and the capability tags. Example: `auth-better-auth (hybrid) — provides: auth, session, oauth`.
+- `## Gaps` — missing capabilities and a `/new-pack` suggestion, or `none`.
+- `## Command` — the last section, containing exactly one executable fenced `sh` block.
+
+Do not put any other fenced command block anywhere in the response.

package/.claude/skills/parallel-execution/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: parallel-execution
+description: Decide which board tasks can safely run at the same time and group them into execution batches. Use when the user says "what can run in parallel?", "batch the board", "can I spin up multiple agents?", or after `.ai/board.md` is built. Do NOT use as a license to fan out everything — the output may be one batch.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# Skill: parallel-execution
+
+## Goal
+
+Read the board and produce ordered execution batches where every task inside a batch is safe to run in parallel. Conflicts are detected up front, not at merge time.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5. This is dependency analysis — do not rush it.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+- `.ai/architecture.md`
+
+## Rules
+
+- A batch is parallel-safe only if **no two tasks share**:
+  - the same files (likely-edit lists)
+  - the same database schema migration
+  - the same route or layout
+  - the same shared component
+  - the same migration / config file
+- If two tasks conflict, the later one moves to the next batch.
+- Foundations (schema, routing skeleton, theme tokens) usually go alone in Batch 1.
+- Integration / QA / deployment tasks usually go alone in the last batch.
+- Prefer **fewer, safer batches** over many micro-batches.
+- It is fine for the answer to be "no parallelism — run sequentially."
+
+## Output format
+
+```md
+## Execution batches
+
+### Batch 1 — foundations
+- <TASK-ID>: <title>
+- <TASK-ID>: <title>
+Why parallel-safe: <one line>
+
+### Batch 2 — feature work
+- ...
+
+### Batch 3 — integration / QA
+- ...
+
+## Conflicts detected
+- <TASK-A> ⇄ <TASK-B>: <shared resource>
+
+## Recommended execution mode
+- Sequential: <which tasks>
+- Parallel with worktrees / subagents: <which tasks>
+- Background: <which tasks, if any>
+
+## Notes for the executor
+- <e.g. "DB migration must finish before Batch 2 starts">
+```
+
+After returning the plan, recommend `/execute-task <ID>` for the first batch.

package/.claude/skills/qa-verify/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: qa-verify
+description: Verify the app actually runs and the feature works end-to-end, not just that code compiles. Use after a feature batch lands, before a demo, when the user says "does this actually work?", "run it and check", or before flipping a task to `Validated`. Do NOT use as a substitute for `/code-review` — they cover different failure modes.
+allowed-tools:
+  - Read
+  - Bash
+  - Edit
+---
+
+# Skill: qa-verify
+
+## Goal
+
+Boot the app, click through the real user flow, and confirm the acceptance criteria hold when humans actually use the product. Type-checks and unit tests pass != feature works.
+
+## Recommended model
+
+Sonnet 4.6. This is execution, not judgment.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md` — task(s) being verified
+- `.ai/product-spec.md` — the core user journey
+
+Read if useful:
+
+- `.ai/ux-theme.md` for empty / loading / error patterns
+- `README.md` / `package.json` for the run command
+
+## Rules
+
+- Always run the app. If you cannot launch it, report that explicitly — do not claim verification from reading code.
+- Walk the **core user journey from `product-spec.md`**, not just the changed feature. Regressions in adjacent flows count.
+- Check empty / loading / error / mobile states for every screen touched. MVPs feel broken at the seams, not the happy path.
+- Capture exact commands and outputs so the user can reproduce.
+- Use a real browser or device when relevant (Playwright MCP if available). Curl-ing an API endpoint is not UI verification.
+
+## Workflow
+
+1. Find the run command (project README, `package.json` scripts, or ask).
+2. Boot the app. Note the URL.
+3. Walk the core journey step by step from the spec.
+4. Re-walk the specific feature(s) from the task(s).
+5. Probe empty / loading / error / mobile.
+6. Write the report.
+
+## Output format
+
+```md
+## QA verification — <TASK-ID(s)> / <feature name>
+
+### Boot
+- Command: `<cmd>`
+- Result: app running at <url> | failed (<reason>)
+
+### Core user journey (from spec)
+- [x|✗] Step 1: <description> — <observation>
+- [x|✗] Step 2: ...
+
+### Feature-specific checks
+- [x|✗] <acceptance criterion> — <observation>
+
+### Edge states
+- Empty state: <ok | broken | missing>
+- Loading state: <ok | broken | missing>
+- Error state: <ok | broken | missing>
+- Mobile / narrow viewport: <ok | broken>
+
+### Broken flows discovered
+- <one-line description> — <repro steps>
+
+### Recommended board update
+- <TASK-ID>: review → Validated | review → In progress
+- New tasks to add: <list or none>
+```

package/.claude/skills/risk-check/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: risk-check
+description: Detect whether the project is drifting — scope creep, architecture creep, hidden dependencies, missing tests, unclear tasks, plus stale hybrid-pack helper versions (more than two minor versions behind the latest published). Use every few sessions, when the user says "are we on track?", "is this getting out of hand?", or before a demo. The anti-overthinking and anti-feature-creep skill.
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# Skill: risk-check
+
+## Goal
+
+Be the brake. Compare the current state of the project to the spec and architecture, and call out where reality is drifting. Recommend concrete cuts.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+- `.ai/board.md`
+- `.ai/decision-log.md` if it exists
+- `.spark/state.json` if it exists
+- `packs/*/pack.toml` if pack state exists and the registry is available
+
+Sample reality:
+
+- `git log --oneline -30`
+- top-level directory listing
+- list of dependencies in `package.json` / `pyproject.toml` / equivalent
+
+## Rules
+
+- Compare **what is in the code now** to **what the spec said**. Highlight gaps in both directions: missing must-haves, plus things built that the spec did not ask for.
+- Treat the spec's non-goals list as a checklist of things that should NOT be present in code. Violations are creep, not features.
+- Recommend cuts, not additions. The default fix is "remove or defer," not "build more."
+- Distinguish **drift** (planned scope grew quietly) from **discovery** (new task properly added to the board). Discovery is fine; silent drift is not.
+- For pack-level drift, inspect `.spark/state.json` when present. For each installed pack, determine its provided capabilities from state or from `packs/<name>/pack.toml`; if none of those capabilities are referenced in `.ai/product-spec.md` or `.ai/architecture.md`, flag it as drift.
+- The pack-level drift recommendation is exactly: **review or revert the pack-install commit via git**. Do not suggest a CLI removal command; v1 has no pack uninstall flow.
+- For each installed pack whose manifest declares `[runtime_package]` (hybrid pack), inspect the consumer project's `package.json` (`dependencies` + `devDependencies`) for the named helper. Compare the installed version against the latest published version on the npm registry (use `bun pm view <pkg> version` or `npm view <pkg> version` via Bash). If the installed version is more than two minor versions behind the latest, flag it under "Stale helper". A `file:` specifier counts as "local dev link" and is NOT stale.
+
+## Checklist
+
+- **Scope creep** — features in code that are not in `MVP feature list`, or are in `Non-goals`.
+- **Architecture creep** — services / dependencies / abstractions beyond what `architecture.md` declared.
+- **Pack-level drift** — installed packs whose provided capabilities are not justified by the spec or architecture.
+- **Stale helper** — hybrid packs whose helper package is more than two minor versions behind the latest on npm.
+- **Unclear tasks** — open board tasks without observable acceptance criteria.
+- **Missing tests / verification** — tasks marked `Validated` with no run command or no review.
+- **Hidden dependencies** — packages added not justified by a task or decision.
+- **Stalled tasks** — tasks in `In progress` for more than ~2 sessions with no commits.
+
+## Output format
+
+```md
+## Pack-level drift
+- no drift detected
+- <pack-name>: provides <capability tag(s)>; none are referenced in `.ai/product-spec.md` or `.ai/architecture.md` — **recommend: review or revert the pack-install commit via git**
+
+## Stale helper
+- no stale helpers
+- <pack-name>: helper `<helper-package>` installed at <installed-version>, latest is <latest-version> — **recommend: `bun update <helper-package>`**
+
+## Risk check
+
+### Scope creep
+- <thing built / in progress> — not in spec / in non-goals — **recommend: cut | defer | keep with decision log entry**
+
+### Architecture creep
+- <new service / dep / abstraction> — **recommend: revert | document in architecture.md**
+
+### Unclear tasks
+- <TASK-ID>: criteria are vague — **recommend: rewrite or send to `/board-review`**
+
+### Hidden dependencies
+- <package> added in <commit> — justification: <none | <task>>
+
+### Stalled tasks
+- <TASK-ID>: in progress since <when> — **recommend: split | unblock | drop**
+
+### Summary
+- Drift severity: low | medium | high
+- Suggested next action: <one line>
+```