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

package/README.md

@@ -8,21 +8,46 @@
 
 > **Alpha:** This tool is currently in alpha. APIs, command structure, and configuration formats may change without notice. Not recommended for production use.
 
-**A CLI tool that automatically generates and maintains project documentation using source code analysis + AI.**
+**A CLI tool that generates documentation from programmatic source code analysis — based on facts, not AI guesswork.**
 
-Statically analyzes your codebase and combines templates with AI to auto-generate `docs/`.
-The Spec-Driven Development (SDD) workflow also automates documentation updates when adding features or making changes.
+Mechanical gate checks and structured templates guarantee the reproducibility and accuracy that AI alone cannot deliver.
+The Spec-Driven Development (SDD) workflow keeps your documentation in sync as features are added or changed.
+
+## Why sdd-forge?
+
+Most AI documentation tools let AI "read" your code and write docs.
+sdd-forge is different.
+
+- **Programmatic analysis** — A static analyzer parses controllers, models, routes, and configs instead of asking AI to read them. No hallucinations, no missed files
+- **Facts vs. generation** — `{{data}}` directives inject facts extracted mechanically from source code. `{{text}}` directives hold AI-generated explanations. What is trustworthy and what is inferred is structurally clear
+- **Mechanical gate checks** — Spec completeness is verified by program logic, not AI judgment. A quality gate you can rely on
+- **Structural stability** — Directives define what goes where. AI cannot rearrange paragraphs or alter the document structure
 
 ## Features
 
-- **Zero dependencies** — Runs on Node.js 18+ only. No npm packages required
-- **Automatic source analysis** — Statically analyzes controllers, models, routes, and config files to extract structural data
-- **AI document generation** — AI automatically expands `{{text}}` directives in templates
-- **Template inheritance** — Four-layer inheritance (base → arch → preset → project-local) for full customization
-- **SDD workflow** — Manage the development cycle of spec → gate → implement → forge → review via commands
-- **Multi-language support** — Auto-generate documentation in multiple languages using translate/generate modes
-- **AI agent integration** — Supports Claude Code (skills) and Codex CLI
-- **Multi-preset** — Supports Node.js CLI / CakePHP2 / Laravel / Symfony
+### Analyze
+
+`scan` statically analyzes source code and produces `analysis.json`. A program — not AI — reads the structure.
+
+- Parses controllers, models, routes, and config files to extract structural data
+- `enrich` lets AI survey the whole picture and annotate each entry with role, summary, and chapter classification
+- Preset system adapts to various frameworks and project structures
+
+### Generate
+
+`{{data}}` injects facts, `{{text}}` injects AI explanations, both into templates. A single `build` command produces `docs/` and `README.md`.
+
+- Template inheritance — 4-layer override: base → arch → preset → project-local
+- Multi-language — translate / generate modes for automatic localization
+- Zero dependencies — runs on Node.js 18+ only, no npm packages required
+
+### Enforce
+
+`gate` mechanically validates specs, `review` checks document quality. The SDD workflow keeps documentation fresh.
+
+- gate — detects unresolved items and missing approvals programmatically. Implementation blocked until PASS
+- review — AI checks alignment between docs and source code
+- AI agent integration — Claude Code (skills) and Codex CLI supported
 
 ## Quick Start
 
@@ -39,44 +64,44 @@ yarn global add <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
 </pre>
 
-### Setup & Document Generation
+### Setup & Generate
 
 <pre>
 # 1. Register your project (interactive wizard)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
 
-# 2. Generate all documentation (scan → init → data → text → readme → agents → translate)
+# 2. Generate all documentation (scan → enrich → init → data → text → readme → agents → translate)
 <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
 </pre>
 
-This will generate `docs/` and `README.md` in one step.
+That's it — `docs/` and `README.md` are generated.
 
 ## Commands
 
-### Document Generation
+### Documentation Generation
 
 | Command | Description |
 |---|---|
-| `setup` | Register project + generate config file |
-| `build` | Run the full document generation pipeline |
+| `setup` | Register project + generate config |
+| `build` | Run the full documentation pipeline |
 | `scan` | Analyze source code → `analysis.json` |
 | `init` | Initialize `docs/` from templates |
-| `data` | Resolve `{{data}}` directives with analyzed data |
+| `data` | Resolve `{{data}}` directives with analysis data |
 | `text` | Resolve `{{text}}` directives with AI |
-| `readme` | Auto-generate `README.md` from `docs/` |
-| `forge` | Iteratively improve documentation with AI |
-| `review` | Check documentation quality |
-| `translate` | Translate to other languages (from default language) |
-| `upgrade` | Update preset templates to the latest version |
+| `readme` | Generate `README.md` from `docs/` |
+| `forge` | Iteratively improve docs with AI |
+| `review` | Check document quality |
+| `translate` | Translate docs (default language → others) |
+| `upgrade` | Update preset templates to latest version |
 
 ### SDD Workflow
 
 | Command | Description |
 |---|---|
-| `spec` | Create a spec document + feature branch |
+| `spec` | Create spec + feature branch |
 | `gate` | Pre-implementation spec check |
 | `flow` | Run the SDD workflow automatically |
-| `changelog` | Generate change history from specs/ |
+| `changelog` | Generate change log from specs/ |
 | `agents` | Update AGENTS.md |
 
 ### Project Management
@@ -89,74 +114,73 @@ This will generate `docs/` and `README.md` in one step.
 
 ## SDD Workflow
 
-Feature development and change flow:
+Feature development flow:
 
 ```
-  spec          Create a spec (feature branch + spec.md)
+  spec          Create spec (feature branch + spec.md)
     ↓
-  gate          Spec gate check (PASS when no unresolved issues)
+  gate          Spec gate check ← verified by program (not AI)
     ↓
-  implement     Write code after gate PASS
+  implement     Code after gate PASS
     ↓
-  forge         Auto-update documentation
+  forge         AI updates documentation
     ↓
-  review        Quality check (repeat until PASS)
+  review        AI quality check (repeat until PASS)
 ```
 
 ### AI Agent Integration
 
 #### Claude Code
 
-Run the SDD workflow using skills:
+Run SDD workflows via skills:
 
 ```
-/sdd-flow-start   — Start spec creation → gate → implementation
-/sdd-flow-close   — Finish with forge → review → commit → merge
+/sdd-flow-start   — create spec → gate → start implementation
+/sdd-flow-close   — forge → review → commit → merge
 ```
 
 #### Codex CLI
 
-Run the workflow from prompts:
+Run workflows from the `$` prompt:
 
 ```
-$sdd-flow-start   — Start spec creation → gate → implementation
-$sdd-flow-close   — Finish with forge → review → commit → merge
+$sdd-flow-start   — create spec → gate → start implementation
+$sdd-flow-close   — forge → review → commit → merge
 ```
 
 ## Configuration
 
-Running `sdd-forge setup` generates `.sdd-forge/config.json`.
+`sdd-forge setup` generates `.sdd-forge/config.json`:
 
 ```jsonc
 {
-  "type": "cli/node-cli",     // Project type (preset selection)
-  "lang": "en",               // Documentation language
+  "type": "cli/node-cli",     // project type (preset selection)
+  "lang": "en",               // documentation language
   "defaultAgent": "claude",   // AI agent
-  "providers": { ... }        // Agent configuration
+  "providers": { ... }        // agent settings
 }
 ```
 
 ### Customization
 
-You can add project-specific templates and data sources:
+Add project-specific templates and data sources:
 
 ```
 .sdd-forge/
 ├── templates/{lang}/
-│   ├── docs/      ← Chapter templates / README overrides
+│   ├── docs/      ← chapter template & README overrides
 │   └── specs/     ← spec.md / qa.md templates
-└── data/          ← Custom data source modules
+└── data/          ← custom data source modules
 ```
 
 ## Documentation
 
-<!-- {{data: docs.chapters("Chapter|Overview")}} -->
-| Chapter | Overview |
+<!-- {{data: docs.chapters("Chapter|Summary")}} -->
+| Chapter | Summary |
 | --- | --- |
-| [01. System Overview](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) | This chapter describes the overall architecture of sdd-forge — a Node.js CLI tool that automates documentation genera… |
-| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | This chapter covers all 19 subcommands available in `sdd-forge`, organized by their routing layer: documentation comm… |
-| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) |  |
-| [04. Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/04_internal_design.md) |  |
+| [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… |
 <!-- {{/data}} -->
 
 ## License

package/docs/cli_commands.md

@@ -0,0 +1,321 @@
+# 02. CLI Command Reference
+
+## 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.
+<!-- {{/text}} -->
+
+## Content
+
+### 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 | — |
+<!-- {{/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.
+
+| 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. |
+
+> **Note:** `--project` is silently stripped from `process.argv` before the subcommand arguments are forwarded to the dispatcher, so individual command modules never see it.
+<!-- {{/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
+
+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.
+
+```
+sdd-forge help
+sdd-forge          # no arguments also shows help
+sdd-forge -h
+```
+
+#### 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.
+
+```
+sdd-forge setup
+sdd-forge setup --name myapp --path /path/to/src --type webapp/cakephp2 --agent claude
+```
+
+| 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 |
+
+#### 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`.
+
+```
+sdd-forge upgrade
+sdd-forge upgrade --dry-run
+```
+
+#### default
+
+Without arguments, lists all registered projects and marks the current default. With a project name, changes the default.
+
+```
+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
+```
+
+#### forge
+
+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.
+
+```
+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
+```
+
+| 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
+```
+
+#### agents
+
+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.
+
+```
+sdd-forge agents
+sdd-forge agents --sdd            # update SDD section only
+sdd-forge agents --project        # update project section only
+sdd-forge agents --dry-run
+```
+
+#### readme
+
+Generates `README.md` in the project root from the docs content and preset README template.
+
+```
+sdd-forge readme
+sdd-forge readme --dry-run
+```
+
+#### translate
+
+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.
+
+```
+sdd-forge translate
+sdd-forge translate --lang ja --force
+sdd-forge translate --dry-run
+```
+
+| 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 |
+
+#### scan
+
+Parses the source code under the configured `sourcePath` and writes structured analysis data to `.sdd-forge/output/analysis.json`.
+
+```
+sdd-forge scan
+```
+
+#### enrich
+
+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`.
+
+```
+sdd-forge enrich --agent claude
+```
+
+#### data
+
+Resolves all `{{data: …}}` directives in `docs/` files in place, replacing directive blocks with generated Markdown. Skips `{{text}}` blocks without re-processing them.
+
+```
+sdd-forge data
+sdd-forge data --dry-run
+```
+
+#### text
+
+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.
+
+```
+sdd-forge text --agent claude
+sdd-forge text --agent claude --dry-run
+```
+
+#### spec
+
+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.
+
+```
+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
+```
+
+| 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 |
+
+#### 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.
+
+```
+sdd-forge gate --spec specs/042-contact-form/spec.md
+sdd-forge gate --spec specs/042-contact-form/spec.md --phase post
+```
+
+| Option | Description |
+|---|---|
+| `--spec <path>` | Path to the spec file (required) |
+| `--phase pre\|post` | Validation phase; `pre` skips task-item checks in Acceptance Criteria sections |
+
+#### flow
+
+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.
+
+```
+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
+```
+
+| 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
+
+Displays the full preset inheritance tree, showing arch-level nodes and their leaf presets together with aliases and configured scan categories.
+
+```
+sdd-forge presets list
+sdd-forge presets          # also shows the list
+```
+<!-- {{/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 |
+|---|---|---|
+| `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`.
+
+**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**
+
+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.
+<!-- {{/text}} -->