gsdd-cli 0.1.0

package/distilled/README.md

@@ -0,0 +1,169 @@
+# GSDD (Get Shit Done Distilled)
+
+Lightweight Spec-Driven Development (SDD) for AI-assisted engineering.
+
+Distilled from GSD (Get Shit Done): keep rigor and leverage, drop ceremony.
+
+## What This Is
+
+GSDD is a small set of workflow sources plus a CLI (`gsdd`) that:
+- scaffolds a project planning workspace (`.planning/`)
+- generates portable workflow entrypoints as skills (`.agents/skills/gsdd-*/SKILL.md`)
+- optionally generates tool-specific adapters for runtimes that need extra native surfaces (root `AGENTS.md`, Claude skills + plan-command alias + native agents, OpenCode commands + native agents)
+
+## Quick Start
+
+Run in your project root:
+```bash
+npx gsdd-cli init
+```
+
+Optional adapters:
+```bash
+npx gsdd-cli init --tools claude
+npx gsdd-cli init --tools opencode
+npx gsdd-cli init --tools codex
+npx gsdd-cli init --tools agents
+npx gsdd-cli init --tools all
+```
+
+Notes:
+- `gsdd init` always generates open-standard skills at `.agents/skills/gsdd-*`. This is also the primary Codex CLI surface.
+- `--tools claude` also generates native agents at `.claude/agents/gsdd-*.md` and a compatibility plan command alias at `.claude/commands/gsdd-plan.md`.
+- `--tools opencode` also generates native agents at `.opencode/agents/gsdd-*.md`.
+- `--tools codex` generates `.codex/agents/gsdd-plan-checker.toml`; the portable `.agents/skills/gsdd-plan/` surface remains the Codex entry path.
+- Root `AGENTS.md` is only written when explicitly requested (`--tools agents` or `--tools all`).
+
+## The Workflow
+
+```
+gsdd init           -> bootstrap (create .planning/, copy templates, generate skills/adapters)
+/gsdd:new-project   -> .planning/SPEC.md + .planning/ROADMAP.md  (questioning + codebase audit + research)
+/gsdd:plan N        -> phases/N/PLAN.md      (task breakdown + research)
+/gsdd:execute N     -> code changes          (plan execution with quality gates)
+/gsdd:verify N      -> VERIFICATION.md       (goal-backward validation)
+  ... repeat plan/execute/verify per phase ...
+/gsdd:quick         -> .planning/quick/NNN/  (sub-hour task outside phases)
+/gsdd:pause         -> .planning/.continue-here.md  (session checkpoint)
+/gsdd:resume        -> restore context, route to next action
+/gsdd:progress      -> show status, route to next action
+```
+
+## Current Status (updated 2026-03-20)
+
+| Workflow | Status | Notes |
+|----------|--------|-------|
+| `new-project.md` | [OK] Defined, source-audited | Covers greenfield + brownfield + milestone context |
+| `plan.md` | [OK] Defined, source-audited | Portable workflow defines the planner contract and supports independent plan checking through generated native adapters |
+| `execute.md` | [OK] Source-audited | Mandatory read enforcement, auth-gate routing, deviation-rule examples, and substantive summary quality gate |
+| `verify.md` | [OK] Source-audited | 5 gap closures against hardened verifier role contract: grouped-gap guidance, orphan detection, frontmatter enforcement, verification basis emphasis, requirements coverage chain |
+| `audit-milestone.md` | [OK] Defined, source-audited | Aggregates phase verification, cross-phase integration audit, auth protection checks, requirement reconciliation, and orphan detection into `MILESTONE-AUDIT.md` |
+| `quick.md` | [OK] | Quick-work lane for sub-hour tasks outside the phase cycle (D11) |
+| `pause.md` | [OK] Source-audited | Session checkpoint writer with conversational handoff (D12) |
+| `resume.md` | [OK] Source-audited | Session context restorer with priority-ordered routing (D12) |
+| `progress.md` | [OK] Source-audited | Read-only status reporter with 6 named route branches, recent work, between-milestones detection (D12) |
+| `map-codebase.md` | [OK] Defined, source-audited | Standalone codebase mapping/refresh |
+
+Architecture notes:
+- `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
+- Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
+- Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.
+- Phase verification and milestone integration audit are treated as separate concerns.
+- Canonical role contracts use bounded sections, typed output examples, and checklist-driven completion where those structures materially improve downstream reliability.
+
+## Init Workflow Agent Count (by config)
+
+| Mode | Mappers | Researchers | Synthesizer | Total |
+|------|---------|-------------|-------------|-------|
+| Brownfield, first run, research balanced/deep | 4 | 4 | 1 | 9 |
+| Brownfield, first run, research fast | 4 | 4 | 0 (inline) | 8 |
+| Brownfield, subsequent run, research balanced/deep | 0 (maps exist) | 4 | 1 | 5 |
+| Greenfield, research balanced/deep | 0 | 4 | 1 | 5 |
+| Greenfield, research fast | 0 | 4 | 0 (inline) | 4 |
+| Any, no research | 0-4 | 0 | 0 | 0-4 |
+
+Note: `parallelization: false` keeps the same mapper/researcher set but runs them sequentially.
+
+## What Gets Created (Project Output)
+
+```
+.planning/
+  SPEC.md
+  ROADMAP.md
+  config.json
+  templates/           # copied from distilled/templates/
+  phases/              # phase plans and summaries
+  research/            # optional research outputs
+.agents/skills/
+  gsdd-new-project/SKILL.md
+  gsdd-plan/SKILL.md
+  gsdd-execute/SKILL.md
+  gsdd-verify/SKILL.md
+  gsdd-audit-milestone/SKILL.md
+  gsdd-quick/SKILL.md
+  gsdd-pause/SKILL.md
+  gsdd-resume/SKILL.md
+  gsdd-progress/SKILL.md
+  gsdd-map-codebase/SKILL.md
+.claude/agents/
+  gsdd-plan-checker.md      # native-capable checker agent generated from the active plan-checker contract
+.claude/commands/
+  gsdd-plan.md              # compatibility alias to the Claude skill-primary plan entry
+.claude/skills/
+  gsdd-plan/SKILL.md        # Claude-native skill-primary planner -> checker surface
+.opencode/agents/
+  gsdd-plan-checker.md      # native-capable checker agent generated from the active plan-checker contract
+.opencode/commands/
+  gsdd-plan.md              # OpenCode-native specialized planner -> checker command surface
+.codex/agents/
+  gsdd-plan-checker.toml    # Codex-native checker agent (read-only, high reasoning effort)
+.planning/
+  quick/              # quick task directories and LOG.md
+  .continue-here.md   # session checkpoint (created by pause)
+```
+
+## Files In This Framework
+
+```
+distilled/
+  DESIGN.md                # design decisions and rationale (28 decisions, evidence-backed)
+  SKILL.md                 # primary entry point (plain markdown)
+  workflows/
+    new-project.md
+    map-codebase.md
+    plan.md
+    progress.md
+    execute.md
+    verify.md
+    audit-milestone.md
+    quick.md
+    pause.md
+    resume.md
+  templates/
+    spec.md
+    roadmap.md
+    agents.md              # full AGENTS.md template (for tool adapters)
+    agents.block.md        # bounded block payload for root AGENTS.md insertion
+    delegates/               # delegate instruction files (copied to .planning/templates/delegates/)
+      mapper-tech.md
+      mapper-arch.md
+      mapper-quality.md
+      mapper-concerns.md
+      plan-checker.md
+      researcher-stack.md
+      researcher-features.md
+      researcher-architecture.md
+      researcher-pitfalls.md
+      researcher-synthesizer.md
+    research/
+      stack.md
+      features.md
+      architecture.md
+      pitfalls.md
+      summary.md
+    codebase/
+      stack.md
+      architecture.md
+      conventions.md
+      concerns.md
+```

package/distilled/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: GSDD (Spec-Driven Development)
+description: Disciplined, lightweight workflow for AI-assisted development. Spec first, then build, then verify.
+---
+
+<role>
+You are an AI agent following the GSDD workflow. You are a disciplined engineer, not a code generator.
+Your mandate: understand the problem deeply, specify what "done" looks like, implement with precision, and verify with rigor.
+</role>
+
+<principles>
+1. Spec first: do not write code without a written spec that defines "done".
+2. Clean commits: group changes logically following repo conventions. Do not bundle unrelated changes.
+3. Verify everything: verify observable success criteria, not vibes.
+4. Research when unsure: verify current docs and patterns before choosing an approach.
+5. Honest reporting: a clear failure report beats a false pass.
+</principles>
+
+<workflow>
+The loop is:
+
+```
+init -> [plan -> execute -> verify] x N phases -> done
+```
+
+Read only the file for the phase you are in:
+- new-project: `workflows/new-project.md`
+- plan: `workflows/plan.md`
+- execute: `workflows/execute.md`
+- verify: `workflows/verify.md`
+- quick: `workflows/quick.md`
+</workflow>
+
+<governance>
+Mandatory:
+- Read before you write. If `.planning/` exists, read `.planning/SPEC.md`, `.planning/ROADMAP.md`, `.planning/config.json`.
+- Stay in scope. Implement only what the current phase plan describes.
+- Never hallucinate. Confirm paths and APIs from repo or docs before use.
+- Research-first when unfamiliar. Log evidence, then plan.
+- Exists -> Substantive -> Wired gate before claiming done.
+</governance>
+
+<project_structure>
+GSDD uses `.planning/` as the durable workspace:
+
+```
+.planning/
+  SPEC.md
+  ROADMAP.md
+  config.json
+  templates/
+  phases/
+  research/
+```
+</project_structure>
+
+<adapters>
+Recommended: generate adapters with `gsdd`:
+
+```bash
+npx gsdd-cli init
+npx gsdd-cli init --tools claude
+npx gsdd-cli init --tools agents
+```
+
+Behavior:
+- Always: generates open-standard skills at `.agents/skills/gsdd-*/SKILL.md` by embedding `distilled/workflows/*.md`. This is also the primary Codex CLI surface.
+- Optional: generates tool adapters (root `AGENTS.md`, Claude `.claude/skills` + `.claude/commands` alias + `.claude/agents`, OpenCode `.opencode/commands` + `.opencode/agents`).
+- Deprecated compatibility: `--tools codex` does not generate `.codex/AGENTS.md`; Codex CLI should use the default skills directly.
+- Root `AGENTS.md` is only written when explicitly requested (so we do not pollute existing user governance).
+</adapters>
+
+<templates>
+Use templates from `.planning/templates/` (copied from `distilled/templates/`) when producing planning artifacts.
+
+Core:
+- `.planning/templates/spec.md` -> `.planning/SPEC.md`
+- `.planning/templates/roadmap.md` -> `.planning/ROADMAP.md`
+
+Research:
+- `.planning/templates/research/*.md` -> `.planning/research/*.md`
+
+Brownfield codebase mapping:
+- `.planning/templates/codebase/*.md` -> `.planning/codebase/*.md`
+</templates>

package/distilled/templates/agents.block.md

@@ -0,0 +1,90 @@
+## GSDD Governance (Generated)
+
+This block is managed by `gsdd`. Do not edit inside the block directly.
+Edit the source template in the GSDD framework instead.
+
+### What This Project Uses
+- Framework: GSDD (Spec-Driven Development)
+- Planning dir: `.planning/` (specs, roadmaps, plans, research, templates)
+- Lifecycle: `bootstrap (gsdd init) -> new-project -> [plan -> execute -> verify] x N -> audit-milestone` for roadmap work
+- Supporting workflows: quick (sub-hour tasks), map-codebase (codebase analysis), pause/resume (session management), progress (status query)
+
+### Rules You MUST Follow
+
+1. Never Skip The Workflow
+- Roadmap work should follow: plan -> execute -> verify.
+- Direct user requests do NOT need to be forced into a phase or plan unless the user explicitly wants roadmap tracking.
+- Before coding roadmap work: read `.planning/SPEC.md`, `.planning/ROADMAP.md`, and the relevant phase plan if one exists.
+- After coding: verify against the relevant success criteria before claiming done.
+
+2. Read Before You Write
+- If `.planning/` exists, read in order:
+  - `.planning/SPEC.md`
+  - `.planning/ROADMAP.md`
+  - `.planning/config.json`
+  - The relevant phase plan in `.planning/phases/` when the work is roadmap-scoped
+- If `.planning/` does not exist, the project has not been bootstrapped. Run `gsdd init`, then run the new-project workflow (`.agents/skills/gsdd-new-project/SKILL.md`).
+
+3. Stay In Scope (Zero Deviation)
+- Implement ONLY what the approved plan or direct user request specifies.
+- If you notice unrelated improvements, do not implement them. Record them as a TODO for a future phase.
+
+Priority order when instructions conflict:
+- Developer explicit instruction (highest)
+- Current approved plan or direct task scope
+- `.planning/SPEC.md`
+- General best practices (lowest)
+
+4. Version Control Protocol
+- Treat `.planning/config.json` -> `gitProtocol` as advisory guidance, not a mandatory naming template.
+- Follow the existing repo or team git conventions first.
+- Do not mention phase, plan, or task IDs in commit or PR names unless explicitly requested.
+- Tests must pass before committing.
+
+5. Verify Your Own Work (Exists -> Substantive -> Wired)
+Before reporting "done", verify each deliverable:
+- Exists: artifact is present where the plan says it should be
+- Substantive: real content/code, not placeholders or TODOs
+- Wired: connected to the system (imported, called, rendered, tested)
+
+6. Research Before Unfamiliar Domains
+If you are not confident about a domain/library/pattern:
+- Stop and research first (docs + existing code).
+- Do not assume training data is current.
+- Cite sources in `.planning/research/` (or `.internal-research/` for framework work).
+
+7. Never Hallucinate Paths Or APIs
+- Use only file paths you've confirmed exist.
+- Use only APIs verified in docs or source.
+
+8. Adapter Architecture Rule
+- Do not pollute core workflows (`distilled/workflows/*.md`) with vendor-specific syntax.
+- Tool-specific adapters are generated in `bin/` (generators, not converters).
+
+9. Anti-YOLO
+- Do not delete or rewrite code unless explicitly asked.
+- If asked for analysis, answer first; propose changes separately.
+
+### Where The Workflows Live
+- Primary lifecycle:
+  - `.agents/skills/gsdd-new-project/SKILL.md` — project initialization (spec + roadmap)
+  - `.agents/skills/gsdd-plan/SKILL.md` — phase planning with optional independent checking
+  - `.agents/skills/gsdd-execute/SKILL.md` — plan execution with quality gates
+  - `.agents/skills/gsdd-verify/SKILL.md` — phase goal-backward verification
+  - `.agents/skills/gsdd-audit-milestone/SKILL.md` — milestone integration audit
+- Supporting workflows:
+  - `.agents/skills/gsdd-quick/SKILL.md` — sub-hour tasks outside the phase cycle
+  - `.agents/skills/gsdd-map-codebase/SKILL.md` — codebase analysis and refresh
+  - `.agents/skills/gsdd-pause/SKILL.md` — session checkpoint
+  - `.agents/skills/gsdd-resume/SKILL.md` — session context restore and routing
+  - `.agents/skills/gsdd-progress/SKILL.md` — read-only status and next-action routing
+
+### How To Invoke Workflows
+
+How you run these workflows depends on your tool:
+
+- **Claude Code / OpenCode:** Use slash commands — `/gsdd-new-project`, `/gsdd-plan`, `/gsdd-execute`, etc.
+- **Codex CLI:** Use skill references — `$gsdd-new-project`, `$gsdd-plan`, `$gsdd-execute`, etc.
+- **All other tools (Cursor, Copilot, Gemini, any AI agent):** Open the SKILL.md file listed above and follow its instructions. This AGENTS.md governance block keeps the agent aligned with GSDD discipline.
+
+Start with the new-project workflow to produce `.planning/SPEC.md` and `.planning/ROADMAP.md`.

package/distilled/templates/agents.md

@@ -0,0 +1,13 @@
+# AGENTS.md - GSDD Governance
+
+This file is generated by `gsdd` when requested for runtimes that use AGENTS.md governance surfaces.
+It provides the universal governance layer for agents that support the AGENTS.md convention.
+
+See also:
+- Skills (preferred workflow entrypoints): `.agents/skills/gsdd-*/SKILL.md`
+- Planning workspace: `.planning/`
+
+<!-- BEGIN GSDD -->
+{{GSDD_BLOCK}}
+<!-- END GSDD -->
+

package/distilled/templates/auth-matrix.md

@@ -0,0 +1,78 @@
+# Authorization Matrix Template
+
+> OWASP-style authorization matrix for systematic auth verification.
+> Create `.planning/AUTH_MATRIX.md` using this template when your project has multiple user roles or protected resources.
+
+## When to Create This Matrix
+
+Create an authorization matrix when your project has:
+- Multiple user roles (e.g., anonymous, user, admin, owner)
+- Protected resources that vary by role
+- Ownership-scoped data (users can only access their own records)
+- Admin or operator surfaces that must be restricted
+
+Skip this matrix for single-role projects or projects with no auth requirements.
+
+## Matrix Format
+
+Use the OWASP pivot format: rows are resources, columns are roles, cells are permissions.
+
+### Permission Values
+
+| Value | Meaning |
+|-------|---------|
+| ALLOW | Role can perform this action on any matching resource |
+| DENY  | Role must be explicitly rejected (not just "no route") |
+| OWN   | Role can perform this action only on resources they own |
+| N/A   | Action does not apply to this resource |
+
+### Matrix Table
+
+```markdown
+| Resource | Action | anonymous | user | admin |
+|----------|--------|-----------|------|-------|
+| /login   | POST   | ALLOW     | ALLOW| ALLOW |
+| /profile | GET    | DENY      | OWN  | ALLOW |
+| /profile | PUT    | DENY      | OWN  | ALLOW |
+| /users   | GET    | DENY      | DENY | ALLOW |
+| /users   | DELETE | DENY      | DENY | ALLOW |
+| /posts   | GET    | ALLOW     | ALLOW| ALLOW |
+| /posts   | POST   | DENY      | ALLOW| ALLOW |
+| /posts   | DELETE | DENY      | OWN  | ALLOW |
+```
+
+Adapt the table to your project's actual resources, actions, and roles. Add or remove columns as needed.
+
+## Sensitive Surfaces
+
+The following resource categories MUST have matrix coverage when they exist in your project:
+
+- **User-scoped data** (profiles, settings, personal records) — require OWN or DENY
+- **Admin surfaces** (user management, system config, audit logs) — require DENY for non-admin roles
+- **Financial data** (billing, payments, subscriptions) — require explicit DENY or OWN
+- **Destructive actions** (delete, bulk operations, account removal) — require explicit role gates
+- **API keys and credentials** — require DENY for non-owner roles
+
+If a sensitive surface exists in your codebase but is missing from the matrix, the integration checker's narrative auth check (Step 4) will still flag it — Step 4 runs unconditionally regardless of whether this matrix exists. Step 4a only verifies cells that are already in the matrix.
+
+## How the Integration Checker Uses This Matrix
+
+During milestone audits, the integration checker (Step 4a) will:
+
+1. Parse each row of the matrix table(s)
+2. For each cell (resource x role x expected permission):
+   - **ALLOW**: Verify the role can access the resource (no auth gate blocks it)
+   - **DENY**: Verify explicit rejection exists (middleware, guard, or policy denies access)
+   - **OWN**: Verify ownership check is enforced (not just auth, but scoped to the user's records)
+3. Report each cell as:
+   - **VERIFIED**: Implementation matches the matrix expectation
+   - **MISMATCH**: Implementation contradicts the matrix (e.g., DENY expected but no guard found)
+   - **UNTESTED**: Cannot determine from static analysis (e.g., dynamic policy evaluation)
+
+The narrative auth check (Step 4) always runs regardless of whether this matrix exists.
+
+## File Location
+
+Save your project's authorization matrix as `.planning/AUTH_MATRIX.md`.
+
+The integration checker will automatically detect and consume it when present. No configuration needed.

package/distilled/templates/codebase/architecture.md

@@ -0,0 +1,110 @@
+# Codebase Architecture
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- This document is durable intent: boundaries, layering, entrypoints, and change-routing rules.
+- Do NOT write a static directory tree. It rots. Instead: reference a few canonical entrypoints and show "where changes go".
+- Every layer/abstraction must include concrete file paths.
+- Include "where to add new code" rules. This prevents downstream agents from scattering logic across random files.
+</guidelines>
+
+## Pattern Overview
+
+Overall:
+- [Pattern name]
+
+Key characteristics:
+- [Characteristic 1]
+- [Characteristic 2]
+- [Characteristic 3]
+
+## Layers (Boundaries)
+
+Layer: [Layer name]
+- Purpose: [What this layer does]
+- Location: `[path(s)]`
+- Owns: [What it is responsible for]
+- Does NOT own: [Explicit non-responsibilities]
+- Depends on: [What it uses]
+- Used by: [What uses it]
+
+## Entry Points
+
+Entrypoint: [Name]
+- Location: `[path]`
+- Triggers: [What invokes it]
+- Responsibilities: [What it does]
+
+## Data Flow (One Or Two Canonical Flows)
+
+Flow: [Name]
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+State management:
+- [How state is handled]
+
+## Key Abstractions
+
+Abstraction: [Name]
+- Purpose: [What it represents]
+- Examples: `[file paths]`
+- Pattern: [Pattern used]
+
+## Error Handling Strategy
+
+Strategy:
+- [Approach]
+- Examples: `[file paths]`
+
+## Cross-Cutting Concerns
+
+Logging:
+- [Approach] - examples: `[file paths]`
+
+Validation:
+- [Approach] - examples: `[file paths]`
+
+Authentication/Authorization:
+- [Approach] - examples: `[file paths]`
+
+## Change Routing (Where To Add New Code)
+
+When making a change, follow these rules:
+
+| Change type | Add/modify here | Do NOT do this | Example paths |
+|---|---|---|---|
+| New API endpoint / handler | [file or folder pattern] | [anti-pattern] | `[paths]` |
+| New domain capability / business rule | [location] | [anti-pattern] | `[paths]` |
+| New UI page / screen | [location] | [anti-pattern] | `[paths]` |
+| New background job / worker | [location] | [anti-pattern] | `[paths]` |
+| DB schema change / migration | [location] | [anti-pattern] | `[paths]` |
+| New external integration | [location] | [anti-pattern] | `[paths]` |
+| Adding a new module/package | [location] | [anti-pattern] | `[paths]` |
+
+<good_examples>
+Example (good):
+- "New routes live in `src/server/routes/*.ts` and are registered in `src/server/app.ts`. Business rules never go in route handlers; they live in `src/domain/*`. See `src/server/routes/users.ts` and `src/domain/user/createUser.ts`."
+
+Example (bad):
+- "Add routes wherever it makes sense."
+</good_examples>
+
+## Golden Files Per Layer
+
+For each architectural layer, identify the single most-instructive file using inbound import frequency as the signal: the most-imported file in a layer is the most stable and most understood.
+
+| Layer | Golden File | Why |
+|-------|-------------|-----|
+| [Layer name] | `[path/to/file.ts]` | [Why it's the most-imported / most-instructive for this layer] |
+| [Layer name] | `[path/to/file.ts]` | [Why] |
+| [Layer name] | `[path/to/file.ts]` | [Why] |
+
+To find the most-imported file in a layer: grep for imports of each candidate file and count occurrences. The highest count is the golden file.
+
+---
+
+*Architecture analysis: [date]*
+

package/distilled/templates/codebase/concerns.md

@@ -0,0 +1,95 @@
+# Codebase Concerns
+
+**Analysis Date:** [YYYY-MM-DD]
+
+<guidelines>
+- Every concern must include concrete file paths.
+- Be specific with measurements (e.g., "p95 500ms") not adjectives ("slow").
+- Include reproduction steps for bugs, and "safe change" advice for fragile areas.
+- This document is about risk and leverage: what breaks, where, and how to change safely.
+</guidelines>
+
+## Tech Debt
+
+Area/component: [Name]
+- Issue: [What's the shortcut/workaround]
+- Files: `[file paths]`
+- Impact: [What breaks or degrades]
+- Fix approach: [How to address it]
+
+## Known Bugs
+
+Bug: [Description]
+- Symptoms: [What happens]
+- Files: `[file paths]`
+- Trigger: [How to reproduce]
+- Workaround: [If any]
+
+## Security Considerations
+
+Area: [Name]
+- Risk: [What could go wrong]
+- Files: `[file paths]`
+- Current mitigation: [What's in place]
+- Recommendations: [What should be added]
+
+## Performance Bottlenecks
+
+Operation: [Name]
+- Problem: [What is slow]
+- Files: `[file paths]`
+- Measurement: [numbers, if known]
+- Suspected cause: [why]
+- Improvement path: [how]
+
+## Fragile Areas
+
+Component/module: [Name]
+- Files: `[file paths]`
+- Why fragile: [what makes it break easily]
+- Safe modification: [how to change safely]
+- Test coverage: [gaps]
+
+## Dependency Risks
+
+Dependency: [Package/service]
+- Risk: [what is wrong]
+- Impact: [what breaks]
+- Mitigation: [what to do]
+
+## Missing Critical Features (If Any)
+
+Feature gap: [Name]
+- Problem: [what is missing]
+- Blocks: [what can't be done]
+
+## Test Coverage Gaps
+
+Untested area: [Name]
+- What's not tested: [specific functionality]
+- Files: `[file paths]`
+- Risk: [what could break unnoticed]
+- Priority: [High/Medium/Low]
+
+<good_examples>
+Example (good):
+- "Auth refresh tokens are stored unencrypted in `src/auth/tokenStore.ts` and logged in `src/auth/logger.ts` (risk: credential leakage). Fix: remove token logging and encrypt at rest. Repro: enable debug logging and observe tokens in logs."
+- "Checkout endpoint p95 is 1.8s in staging due to N+1 queries in `src/db/orders.ts` (see `getOrdersForUser`). Fix: batch query and add integration test asserting query count."
+</good_examples>
+
+## Downstream Impact Ranking
+
+Rank the top 3 concerns by how much future work they block. Use the Change Routing table in ARCHITECTURE.md as reference: concerns that block multiple change-routing rows rank highest.
+
+| Rank | Concern | Blocks | Severity | Fix effort |
+|------|---------|--------|----------|------------|
+| 1 | [Concern name] | [Which change types from ARCHITECTURE.md this blocks] | critical/moderate/minor | [small/medium/large] |
+| 2 | [Concern name] | [Blocks] | [Severity] | [Effort] |
+| 3 | [Concern name] | [Blocks] | [Severity] | [Effort] |
+
+Ranking heuristic: a concern that blocks 3 change-routing rows ranks above one that blocks 1, even if the latter is more severe in isolation.
+
+---
+
+*Concerns audit: [date]*
+