sdd-forge 0.1.0-alpha.29 → 0.1.0-alpha.31

package/README.md

@@ -104,11 +104,10 @@ That's it — `docs/` and `README.md` are generated.
 | `changelog` | Generate change log from specs/ |
 | `agents` | Update AGENTS.md |
 
-### Project Management
+### Other
 
 | Command | Description |
 |---|---|
-| `default` | Set the default project |
 | `presets` | List available presets |
 | `help` | Show command list |
 
@@ -178,9 +177,10 @@ Add project-specific templates and data sources:
 <!-- {{data: docs.chapters("Chapter|Summary")}} -->
 | Chapter | Summary |
 | --- | --- |
-| [01. Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter introduces `sdd-forge`, a CLI tool that automates documentation generation from source code analysis and… |
-| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | This chapter documents all 20 CLI commands available in sdd-forge, covering project setup, documentation generation, … |
-| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | This chapter covers the configuration files that sdd-forge reads to tailor its behavior to your project, including th… |
+| [01. Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter introduces sdd-forge, a CLI tool for Spec-Driven Development that automates technical documentation gene… |
+| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | sdd-forge provides 20+ commands organized into four namespaces (`docs`, `spec`, `flow`, and standalone commands) thro… |
+| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge is configured primarily through `.sdd-forge/config.json`, which controls output language, project type, doc… |
+| [04. Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | This chapter describes the internal architecture of sdd-forge, covering its three-layer directory structure (`src/` →… |
 <!-- {{/data}} -->
 
 ## License

package/docs/cli_commands.md

@@ -3,7 +3,7 @@
 ## Description
 
 <!-- {{text: Write a 1-2 sentence overview of this chapter. Include the total number of commands and subcommand structure.}} -->
-This chapter documents all 20 CLI commands available in sdd-forge, covering project setup, documentation generation, spec management, and SDD workflow automation. Commands are routed through a three-layer dispatch architecture: the top-level entry point (`sdd-forge.js`) delegates to one of five dispatchers (`docs`, `spec`, `flow`, `presets-cmd`, `help`), which in turn load the appropriate implementation module.
+sdd-forge provides 20+ commands organized into four namespaces (`docs`, `spec`, `flow`, and standalone commands) through a three-level dispatch architecture. The CLI entry point (`sdd-forge`) routes to namespace dispatchers, which in turn delegate to individual command implementations under `commands/` directories.
 <!-- {{/text}} -->
 
 ## Content
@@ -11,311 +11,249 @@ This chapter documents all 20 CLI commands available in sdd-forge, covering proj
 ### Command List
 
 <!-- {{text[mode=deep]: List all commands in table format. Include command name, description, and key options. Extract comprehensively from command definitions and routing in the source code.}} -->
-| Command | Dispatcher | Description | Key Options |
-|---|---|---|---|
-| `help` | `help.js` | Display all available commands with descriptions | — |
-| `setup` | `docs` | Interactive project registration and config generation | `--name`, `--path`, `--type`, `--agent`, `--lang`, `--dry-run` |
-| `upgrade` | `docs` | Upgrade template-derived skill files to the current sdd-forge version | `--dry-run` |
-| `default [name]` | `docs` | List registered projects or set the default project | `[name]` positional arg |
-| `build` | `docs` | Run the full documentation pipeline: scan → enrich → init → data → text → readme → agents → [translate] | `--agent`, `--force`, `--verbose`, `--dry-run` |
-| `init` | `docs` | Initialize `docs/` from preset templates | `--force`, `--dry-run` |
-| `forge` | `docs` | Iteratively improve docs using AI based on a prompt and spec | `--prompt`, `--spec`, `--max-runs`, `--mode`, `--agent`, `--dry-run` |
-| `review` | `docs` | Run quality checks against the review checklist | — |
-| `changelog` | `docs` | Generate `change_log.md` from `specs/` directories | — |
-| `agents` | `docs` | Update `AGENTS.md` with SDD and project sections | `--sdd`, `--project`, `--dry-run` |
-| `readme` | `docs` | Generate `README.md` from docs content | `--dry-run` |
-| `translate` | `docs` | Translate default-language docs to configured non-default languages via AI | `--lang`, `--force`, `--dry-run` |
-| `scan` | `docs` | Analyse source code and write `.sdd-forge/output/analysis.json` | — |
-| `enrich` | `docs` | Enrich `analysis.json` entries with AI-generated roles, summaries, and chapter classifications | `--agent` |
-| `data` | `docs` | Resolve all `{{data}}` directives in `docs/` files | `--dry-run` |
-| `text` | `docs` | Resolve all `{{text}}` directives in `docs/` files using an AI agent | `--agent`, `--dry-run` |
-| `spec` | `spec` | Create a numbered feature branch and initialise `specs/NNN-slug/spec.md` | `--title`, `--base`, `--no-branch`, `--worktree`, `--allow-dirty`, `--dry-run` |
-| `gate` | `spec` | Validate a spec file for unresolved items before (or after) implementation | `--spec`, `--phase` |
-| `flow` | `flow` (direct) | Automate the full SDD flow: spec init → gate → forge | `--request`, `--title`, `--spec`, `--agent`, `--max-runs`, `--forge-mode`, `--no-branch`, `--worktree`, `--dry-run` |
-| `presets list` | `presets-cmd` (direct) | Display the preset inheritance tree | — |
+| Command | Description | Key Options |
+|---|---|---|
+| `sdd-forge help` | Display all available commands grouped by section | — |
+| `sdd-forge setup` | Interactive project setup wizard; generates `.sdd-forge/config.json` | `--name`, `--path`, `--type`, `--purpose`, `--tone`, `--agent`, `--lang`, `--dry-run` |
+| `sdd-forge upgrade` | Upgrade template-derived files (skills, etc.) to match installed version | `--dry-run` |
+| `sdd-forge presets list` | Display the preset inheritance tree | — |
+| `sdd-forge docs build` | Run the full documentation pipeline (scan→enrich→init→data→text→readme→agents→translate) | `--agent`, `--force`, `--dry-run`, `--verbose` |
+| `sdd-forge docs scan` | Scan source code and generate `analysis.json` | — |
+| `sdd-forge docs enrich` | AI-enrich analysis entries with summary, detail, chapter, and role metadata | `--agent`, `--dry-run`, `--stdout` |
+| `sdd-forge docs init` | Initialize chapter files from preset templates | `--force`, `--dry-run` |
+| `sdd-forge docs data` | Resolve `{{data}}` directives in chapter files | `--dry-run` |
+| `sdd-forge docs text` | AI-fill `{{text}}` directives in chapter files | `--dry-run` |
+| `sdd-forge docs readme` | Auto-generate `README.md` from chapter files and templates | `--dry-run`, `--lang`, `--output` |
+| `sdd-forge docs forge` | Iteratively improve docs via AI agent and review cycles | `--prompt`, `--prompt-file`, `--spec`, `--max-runs`, `--review-cmd`, `--mode`, `--dry-run`, `--verbose` |
+| `sdd-forge docs review` | Review generated documentation for quality issues | — |
+| `sdd-forge docs translate` | Translate default-language docs to configured non-default languages | `--lang`, `--force`, `--dry-run` |
+| `sdd-forge docs changelog` | Generate changelog from commit history | — |
+| `sdd-forge docs agents` | Update AGENTS.md by resolving directives and AI-refining the PROJECT section | `--dry-run` |
+| `sdd-forge docs snapshot` | Create a snapshot of current documentation state | — |
+| `sdd-forge spec init` | Create a numbered feature branch and spec directory with templates | `--title`, `--base`, `--dry-run`, `--allow-dirty`, `--no-branch`, `--worktree` |
+| `sdd-forge spec gate` | Pre-implementation gate check on spec completeness and guardrail compliance | `--spec`, `--phase`, `--skip-guardrail` |
+| `sdd-forge spec guardrail` | Initialize or update project guardrail rules | Subcommands: `init`, `update`; `--force`, `--dry-run`, `--agent` |
+| `sdd-forge flow start` | Run the full SDD flow (spec init → gate → forge) | `--request`, `--title`, `--spec`, `--agent`, `--max-runs`, `--forge-mode`, `--no-branch`, `--worktree`, `--dry-run` |
+| `sdd-forge flow status` | Display or update SDD flow progress | `--step`, `--status`, `--summary`, `--req`, `--archive` |
+| `sdd-forge flow review` | Run code quality review (draft → final → apply) after implementation | `--dry-run`, `--skip-confirm` |
 <!-- {{/text}} -->
 
 ### Global Options
 
 <!-- {{text[mode=deep]: Describe global options shared by all commands in table format. Extract from argument parsing logic in the source code.}} -->
-The following options are handled by `sdd-forge.js` before any subcommand is dispatched and apply regardless of which command is invoked.
+The following options are recognized at the top level or shared across most subcommands via the common `parseArgs` utility:
 
-| Option | Short | Description |
-|---|---|---|
-| `--project <name>` | — | Select a registered project by name. Sets `SDD_SOURCE_ROOT` and `SDD_WORK_ROOT` environment variables for the duration of the command. |
-| `--version` | `-v`, `-V` | Print the installed sdd-forge package version and exit. |
-| `--help` | `-h` | Display the top-level command list. When passed to an individual command, show that command's own help text. |
+| Option | Description |
+|---|---|
+| `-h`, `--help` | Display help information for the current command or subcommand. Available on all commands. |
+| `-v`, `--version`, `-V` | Print the installed sdd-forge version and exit. Handled at the top-level entry point. |
+| `--dry-run` | Simulate the command without writing any files to disk. Supported by `build`, `init`, `data`, `text`, `readme`, `translate`, `agents`, `forge`, `setup`, `upgrade`, `spec init`, `flow start`, and `flow review`. |
+| `--verbose` | Enable verbose output with detailed progress information. Supported by `build` and `forge`. |
 
-> **Note:** `--project` is silently stripped from `process.argv` before the subcommand arguments are forwarded to the dispatcher, so individual command modules never see it.
+Note: sdd-forge uses a custom `parseArgs` function (in `src/lib/cli.js`) that supports flag normalization (e.g., `--dry-run` → `dryRun`), option aliases (e.g., `-v` → `--verbose`), and default values. Each command declares its own accepted flags and options independently.
 <!-- {{/text}} -->
 
 ### Command Details
 
 <!-- {{text[mode=deep]: Describe each command's usage, options, and examples in detail. Create a #### subsection for each command. Extract from argument definitions and help messages in the source code.}} -->
-#### help
+#### sdd-forge help
 
-Prints all available commands grouped by section (Project, Build, Docs, Scan, Spec, Flow, Info) along with a one-line description for each, sourced from the i18n `ui:help.commands.*` keys. The package version is read from `package.json` at runtime.
+Displays all available commands organized into sections: Project, Docs, Spec, Flow, and Info. Uses ANSI formatting for terminal output. Language is determined by `.sdd-forge/config.json` `lang` setting.
 
 ```
 sdd-forge help
-sdd-forge          # no arguments also shows help
+sdd-forge --help
 sdd-forge -h
 ```
 
-#### setup
+#### sdd-forge setup
 
-Launches an interactive wizard that registers a project, creates `.sdd-forge/config.json`, generates `AGENTS.md`, creates a `CLAUDE.md` symlink, and installs skill files under `.agents/skills/` and `.claude/skills/`. Each step can be supplied non-interactively via CLI flags.
+Interactive wizard that registers a project and generates `.sdd-forge/config.json`. Prompts for project name, source path, output language, architecture type, document style, and default agent. Creates required directories (`.sdd-forge/output`, `docs`, `specs`), sets up `AGENTS.md`, `CLAUDE.md`, and skill templates.
 
 ```
 sdd-forge setup
-sdd-forge setup --name myapp --path /path/to/src --type webapp/cakephp2 --agent claude
+sdd-forge setup --name myapp --path /path/to/src --type webapp/cakephp2
 ```
 
-| Option | Description |
-|---|---|
-| `--name <name>` | Project name |
-| `--path <path>` | Source code directory |
-| `--work-root <path>` | Working root (defaults to source path) |
-| `--type <preset>` | Preset identifier (e.g. `webapp/cakephp2`, `cli/node-cli`) |
-| `--purpose <text>` | Documentation purpose description |
-| `--tone <text>` | Documentation tone |
-| `--agent <name>` | Default AI agent name |
-| `--lang <code>` | Output language code |
-| `--set-default` | Mark this project as the default |
-| `--dry-run` | Show what would be written without writing |
+When all required options (`--name`, `--path`, `--type`, `--purpose`, `--tone`) are provided, the wizard runs non-interactively.
 
-#### upgrade
+#### sdd-forge upgrade
 
-Upgrades template-managed files — specifically the skill `SKILL.md` files under `.agents/skills/` — to match the templates bundled with the currently installed sdd-forge version. Safe to run repeatedly; only overwrites template-derived content and never touches `config.json`.
+Upgrades template-derived files to match the currently installed sdd-forge version. Compares skill templates in `src/templates/skills/` with `.agents/skills/` and overwrites changed files. Converts symlinks to real files if needed. Also checks `config.json` for missing settings and prints configuration hints.
 
 ```
 sdd-forge upgrade
 sdd-forge upgrade --dry-run
 ```
 
-#### default
+#### sdd-forge presets list
 
-Without arguments, lists all registered projects and marks the current default. With a project name, changes the default.
+Displays the preset inheritance tree in a visual tree format. Shows base, architecture, and leaf presets with their labels, aliases, and scan keys. Indicates which architecture layers have templates directories.
 
 ```
-sdd-forge default               # list projects
-sdd-forge default myapp         # set "myapp" as default
-```
-
-#### build
-
-Executes the full documentation generation pipeline in order: `scan → enrich → init → data → text → readme → agents`. If `output.isMultiLang` is `true` in the configuration, a `translate` (or per-language generate) step is appended. Progress is reported via a weighted progress bar.
-
-```
-sdd-forge build
-sdd-forge build --agent claude --force --verbose
-sdd-forge build --dry-run
-```
-
-| Option | Description |
-|---|---|
-| `--agent <name>` | AI agent to use for `enrich` and `text` steps (overrides `config.defaultAgent`) |
-| `--force` | Force re-initialisation of existing docs files |
-| `--verbose` | Show per-step log output |
-| `--dry-run` | Skip all file writes |
-
-#### init
-
-Initialises (or re-initialises) `docs/` from the preset templates. Existing files are skipped unless `--force` is set.
-
-```
-sdd-forge init
-sdd-forge init --force
+sdd-forge presets list
 ```
 
-#### forge
+#### sdd-forge docs build
 
-Iteratively improves `docs/` content by prompting an AI agent with the given `--prompt` and, optionally, a linked spec. Runs up to `--max-runs` iterations until the review passes.
+Runs the full documentation generation pipeline in sequence: `scan` → `enrich` → `init` → `data` → `text` → `readme` → `agents` → `translate` (if multi-language is configured). Displays a progress bar during execution. Steps that require an AI agent (`enrich`, `text`) are skipped if no `defaultAgent` is configured.
 
 ```
-sdd-forge forge --prompt "add enrich command section"
-sdd-forge forge --prompt "describe gate phases" --spec specs/042-gate-docs/spec.md --max-runs 3
+sdd-forge docs build
+sdd-forge docs build --force --verbose
+sdd-forge docs build --dry-run
 ```
 
 | Option | Description |
 |---|---|
-| `--prompt <text>` | Improvement request (required) |
-| `--spec <path>` | Path to the spec file for context |
-| `--max-runs <n>` | Maximum improvement iterations (default: 5) |
-| `--mode <mode>` | `local` \| `assist` \| `agent` |
-| `--agent <name>` | Override the configured default agent |
-| `--dry-run` | Skip writes |
-
-#### review
-
-Runs quality checks against the review checklist (`templates/review-checklist.md`) and reports any issues found in `docs/`. Exits non-zero if the check fails.
-
-```
-sdd-forge review
-```
-
-#### changelog
-
-Reads all `specs/NNN-*/spec.md` files and generates or updates `change_log.md` in the project root.
-
-```
-sdd-forge changelog
-```
+| `--agent` | Override the default agent for AI-powered steps |
+| `--force` | Force regeneration of chapter files even if they exist |
+| `--dry-run` | Simulate the pipeline without writing files |
+| `--verbose` | Show detailed progress output |
 
-#### agents
+#### sdd-forge docs enrich
 
-Updates `AGENTS.md` with the latest SDD section (from the `agents.sdd` data source) and/or the project section (from `agents.project`). Defaults to updating both sections.
+Uses AI to annotate each entry in `analysis.json` with `summary`, `detail`, `chapter`, and `role` metadata. Processes entries in batches based on total line count (default: 3000 lines per batch) or item count (default: 20 items). Supports resume — previously enriched entries are skipped, and progress is saved after each batch.
 
 ```
-sdd-forge agents
-sdd-forge agents --sdd            # update SDD section only
-sdd-forge agents --project        # update project section only
-sdd-forge agents --dry-run
+sdd-forge docs enrich
+sdd-forge docs enrich --dry-run --stdout
 ```
 
-#### readme
+#### sdd-forge docs readme
 
-Generates `README.md` in the project root from the docs content and preset README template.
+Generates `README.md` from preset templates using bottom-up template resolution. Resolves `{{data}}` and `{{text}}` directives, strips block directives, and normalizes formatting. Supports multi-language output by switching `docsDir` to language-specific directories.
 
 ```
-sdd-forge readme
-sdd-forge readme --dry-run
+sdd-forge docs readme
+sdd-forge docs readme --lang ja --output docs/ja/README.md
+sdd-forge docs readme --dry-run
 ```
 
-#### translate
+#### sdd-forge docs forge
 
-Translates the default-language `docs/` files into every non-default language configured in `output.languages`. Re-translates a file only when its source has a newer `mtime` than the existing translation, unless `--force` is set.
+Iteratively improves documentation through AI agent and review cycles. Operates in three modes: `local` (default), `assist`, and `agent`. Pre-populates `{{data}}` placeholders and `{{text}}` directives from analysis before running the AI. Supports spec-based file targeting via keyword matching.
 
 ```
-sdd-forge translate
-sdd-forge translate --lang ja --force
-sdd-forge translate --dry-run
+sdd-forge docs forge --prompt "improve API documentation"
+sdd-forge docs forge --spec specs/001-feature/spec.md --mode agent
+sdd-forge docs forge --max-runs 5 --review-cmd "sdd-forge docs review"
 ```
 
 | Option | Description |
 |---|---|
-| `--lang <code>` | Translate into this language only |
-| `--force` | Re-translate all files regardless of mtime |
-| `--dry-run` | Show what would be translated without writing |
+| `--prompt` | Improvement prompt for the AI agent |
+| `--prompt-file` | Read prompt from a file |
+| `--spec` | Path to spec file for scoped file targeting |
+| `--max-runs` | Maximum iteration rounds (default: 3) |
+| `--review-cmd` | Review command to run after each round (default: `sdd-forge docs review`) |
+| `--mode` | Agent mode: `local`, `assist`, or `agent` |
 
-#### scan
+#### sdd-forge docs translate
 
-Parses the source code under the configured `sourcePath` and writes structured analysis data to `.sdd-forge/output/analysis.json`.
+Translates default-language documentation to configured non-default languages using AI. Compares `mtime` of source and target files for differential translation. Respects `documentStyle.tone` settings for language-appropriate style (e.g., です/ます for Japanese polite tone).
 
 ```
-sdd-forge scan
+sdd-forge docs translate
+sdd-forge docs translate --lang ja --force
+sdd-forge docs translate --dry-run
 ```
 
-#### enrich
+#### sdd-forge docs agents
 
-Reads `analysis.json` and uses an AI agent to annotate each entry with a `role`, `summary`, `detail`, and chapter classification. The enriched result is written back to `analysis.json`.
+Updates `AGENTS.md` by resolving `{{data: agents.sdd}}` and `{{data: agents.project}}` directives. The PROJECT section is refined by AI using generated docs, `package.json` scripts, and the SDD section as context.
 
 ```
-sdd-forge enrich --agent claude
+sdd-forge docs agents
+sdd-forge docs agents --dry-run
 ```
 
-#### data
+#### sdd-forge spec init
 
-Resolves all `{{data: …}}` directives in `docs/` files in place, replacing directive blocks with generated Markdown. Skips `{{text}}` blocks without re-processing them.
+Creates a numbered feature branch and spec directory with `spec.md` and `qa.md` templates. Supports three modes: default (creates a git branch), `--worktree` (creates an isolated git worktree), and `--no-branch` (spec files only). Automatically detects the next available sequence number from existing specs and branches.
 
 ```
-sdd-forge data
-sdd-forge data --dry-run
+sdd-forge spec init --title "contact-form"
+sdd-forge spec init --title "login-feature" --base development --worktree
+sdd-forge spec init --title "quick-fix" --no-branch --allow-dirty
 ```
 
-#### text
+#### sdd-forge spec gate
 
-Calls an AI agent for each `{{text: …}}` directive found in `docs/` files and inserts the generated text. Only directives with no existing body (or with a stale body when `--force` is used) are processed.
+Pre-implementation gate check that verifies spec completeness. Detects unresolved tokens (`TBD`, `TODO`, `FIXME`, `NEEDS CLARIFICATION`), unchecked tasks, missing required sections (`Clarifications`, `Open Questions`, `User Confirmation`, `Acceptance Criteria`), and unapproved user confirmation checkboxes. Optionally runs AI-powered guardrail compliance checking.
 
 ```
-sdd-forge text --agent claude
-sdd-forge text --agent claude --dry-run
+sdd-forge spec gate --spec specs/001-feature/spec.md
+sdd-forge spec gate --spec specs/001-feature/spec.md --phase post
+sdd-forge spec gate --spec specs/001-feature/spec.md --skip-guardrail
 ```
 
-#### spec
+| Option | Description |
+|---|---|
+| `--spec` | Path to spec.md file (required) |
+| `--phase` | `pre` (default) or `post` — pre phase skips Status/Acceptance Criteria unchecked items |
+| `--skip-guardrail` | Skip guardrail AI compliance check |
+
+#### sdd-forge spec guardrail
 
-Creates a numbered feature branch (`feature/NNN-slug`) and scaffolds `specs/NNN-slug/spec.md` and `specs/NNN-slug/qa.md`. Supports three branching strategies: branch (default), worktree, or spec-only.
+Manages project guardrail rules (immutable principles for spec compliance). The `init` subcommand generates `guardrail.md` from preset templates with language fallback. The `update` subcommand uses AI to propose additional project-specific articles based on `analysis.json`.
 
 ```
-sdd-forge spec --title "contact-form"
-sdd-forge spec --title "contact-form" --worktree
-sdd-forge spec --title "contact-form" --no-branch
-sdd-forge spec --title "contact-form" --dry-run
+sdd-forge spec guardrail init
+sdd-forge spec guardrail init --force --dry-run
+sdd-forge spec guardrail update --agent claude
 ```
 
-| Option | Description |
-|---|---|
-| `--title <text>` | Feature name — used for branch/directory slug (required) |
-| `--base <branch>` | Base branch (defaults to current HEAD) |
-| `--no-branch` | Create spec files only, no branch |
-| `--worktree` | Create an isolated git worktree under `.sdd-forge/worktree/` |
-| `--allow-dirty` | Skip the working-tree cleanliness check |
-| `--dry-run` | Print what would be created without writing |
+#### sdd-forge flow start
 
-#### gate
-
-Validates a `spec.md` file for completeness before (`--phase pre`, default) or after (`--phase post`) implementation. Checks for unresolved tokens (`TBD`, `TODO`, `FIXME`, `[NEEDS CLARIFICATION]`), unchecked task items, required sections (`## Clarifications`, `## Open Questions`, `## User Confirmation`, `## Acceptance Criteria`), and the `- [x] User approved this spec` approval marker.
+Runs the complete SDD flow: spec init → gate check → forge. Requires `--request` to describe the feature or fix. Automatically creates a spec, inserts the request text, runs gate validation, saves flow state to `flow.json`, and launches the forge process.
 
 ```
-sdd-forge gate --spec specs/042-contact-form/spec.md
-sdd-forge gate --spec specs/042-contact-form/spec.md --phase post
+sdd-forge flow start --request "add login feature"
+sdd-forge flow start --request "fix pagination bug" --forge-mode agent --max-runs 5
+sdd-forge flow start --request "refactor auth" --worktree
 ```
 
-| Option | Description |
-|---|---|
-| `--spec <path>` | Path to the spec file (required) |
-| `--phase pre\|post` | Validation phase; `pre` skips task-item checks in Acceptance Criteria sections |
+Gate failure exits with code 2 and displays unresolved items. If user confirmation is missing, specific instructions are shown.
 
-#### flow
+#### sdd-forge flow status
 
-Automates the complete SDD flow: creates a spec (if `--spec` is not given), runs `gate`, and — on gate success — runs `forge`. Exits with code `2` and prints `NEEDS_INPUT` when gate fails, listing up to eight blocking issues.
+Displays or updates SDD flow progress stored in `.sdd-forge/flow.json`. Without options, shows spec path, branch info, step progress (with ✓/>/- icons), and requirements checklist. Supports step updates, requirement management, and flow archival.
 
 ```
-sdd-forge flow --request "Add pagination to the user list"
-sdd-forge flow --request "Fix CSV export encoding" --spec specs/040-csv-fix/spec.md
-sdd-forge flow --request "Refactor auth module" --worktree --agent claude --max-runs 3
+sdd-forge flow status
+sdd-forge flow status --step gate --status done
+sdd-forge flow status --summary '["implement auth", "add tests", "update docs"]'
+sdd-forge flow status --req 0 --status done
+sdd-forge flow status --archive
 ```
 
-| Option | Description |
-|---|---|
-| `--request <text>` | The user's change request (required) |
-| `--title <text>` | Spec title slug (derived from `--request` if omitted) |
-| `--spec <path>` | Use an existing spec instead of creating one |
-| `--agent <name>` | AI agent to pass to `forge` |
-| `--max-runs <n>` | Maximum `forge` iterations (default: 5) |
-| `--forge-mode <mode>` | `local` \| `assist` \| `agent` (default: `local`) |
-| `--no-branch` | Create spec without a new branch |
-| `--worktree` | Create an isolated git worktree |
-| `--dry-run` | Skip writes in spec-init and forge steps |
-
-#### presets list
+#### sdd-forge flow review
 
-Displays the full preset inheritance tree, showing arch-level nodes and their leaf presets together with aliases and configured scan categories.
+Post-implementation code quality review with three phases: draft (generate improvement proposals), final (AI validation of each proposal as APPROVED/REJECTED), and apply. Extracts review targets from spec `## Scope` section or falls back to full `git diff` against the base branch. Generates `review.md` in the spec directory with checkbox-formatted results.
 
 ```
-sdd-forge presets list
-sdd-forge presets          # also shows the list
+sdd-forge flow review
+sdd-forge flow review --dry-run
+sdd-forge flow review --skip-confirm
 ```
 <!-- {{/text}} -->
 
 ### Exit Codes and Output
 
 <!-- {{text[mode=deep]: Define exit codes and describe stdout/stderr conventions in table format. Extract from process.exit() calls and output patterns in the source code.}} -->
-| Exit Code | Meaning | Typical Source |
+| Exit Code | Meaning | Used By |
 |---|---|---|
-| `0` | Success | Normal completion of any command |
-| `1` | General error | Unknown subcommand, missing required argument, file not found, AI agent failure, gate error thrown as exception |
-| `2` | Gate check failed (blocking) | `flow` command when `gate` exits non-zero |
-
-**stdout conventions**
-
-Informational progress messages, generated Markdown previews (dry-run), and final success summaries are written to `stdout`. The `build` command uses a weighted progress bar (via `createProgress()`) that prints step labels and optionally verbose per-step logs when `--verbose` is set. Commands that produce structured output (e.g. `default` listing projects, `presets list` showing the tree) write their formatted text directly to `stdout`.
+| `0` | Success | All commands on successful completion |
+| `1` | General error | Unknown subcommands, missing required options, missing config, runtime errors, build pipeline failures |
+| `2` | Gate failure | `flow start` when `spec gate` check fails (unresolved items or missing user confirmation) |
 
-**stderr conventions**
+**stdout/stderr conventions:**
 
-Error messages — including unknown command notices, missing `--spec` warnings, gate failure reason lists, and pipeline step errors — are written to `stderr` via `console.error()`. The `flow` command forwards both `stdout` and `stderr` from its child processes (`spec init`, `gate`, `forge`) so that all output remains visible to the caller.
-
-**dry-run output**
+| Stream | Content |
+|---|---|
+| `stdout` | Primary command output: generated content (`--dry-run` previews), status displays (`flow status`), spec file paths (`spec init`), tree displays (`presets list`), and help text |
+| `stderr` | Progress indicators, step labels (e.g., `[draft] Generating proposals...`), warning messages (prefixed with `WARN:`), error messages (prefixed with `ERROR:`), and build pipeline progress bars |
 
-When `--dry-run` is active, commands print `[dry-run]`-prefixed lines describing each write operation that would occur, then exit `0` without modifying the filesystem.
+Commands that support `--dry-run` write the would-be output to `stdout` while logging dry-run notices to `stderr`. The `forge` command uses `stderr` for progress tickers (dots printed at regular intervals during agent calls) and verbose agent output when `--verbose` is enabled. The `build` command uses a structured progress bar on `stderr` that tracks each pipeline step with weighted progress values.
 <!-- {{/text}} -->