@entelligentsia/forgecli 1.0.25 → 1.0.40

package/dist/forge-payload/init/discovery/discover-stack.md

@@ -0,0 +1,33 @@
+# Discovery: Stack
+
+## Purpose
+
+Detect the project's programming languages, frameworks, versions, and runtime.
+
+## Scan Targets
+
+| File | What It Reveals |
+|------|----------------|
+| `package.json` | Node.js, npm dependencies, scripts |
+| `requirements.txt` / `Pipfile` / `pyproject.toml` | Python, pip dependencies |
+| `go.mod` | Go, module dependencies |
+| `Cargo.toml` | Rust, crate dependencies |
+| `Gemfile` | Ruby, gem dependencies |
+| `Dockerfile` | Runtime, base image, build steps |
+| `Makefile` | Build commands, task aliases |
+| `*.sln` / `*.csproj` | .NET, C# |
+
+## Tools
+
+Use Glob to find these files, Read to parse them.
+
+## Output
+
+Structured report:
+- Primary language(s)
+- Framework(s) with versions
+- Frontend framework (if any)
+- Database (if detectable from dependencies)
+- Task queue (if any)
+- Containerisation (if any)
+- Runtime version constraints

package/dist/forge-payload/init/discovery/discover-testing.md

@@ -0,0 +1,34 @@
+# Discovery: Testing
+
+## Purpose
+
+Detect the project's test framework, test commands, build commands,
+and lint configuration.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| `test/` / `tests/` / `__tests__/` / `*_test.go` | Test directory structure |
+| `jest.config.*` / `vitest.config.*` | JS test framework config |
+| `pytest.ini` / `setup.cfg` / `pyproject.toml [tool.pytest]` | Python test config |
+| `package.json scripts.test` | Test command |
+| `.eslintrc*` / `ruff.toml` / `.golangci.yml` | Lint configuration |
+| `.github/workflows/*.yml` | CI test/build/lint commands |
+| `coverage/` / `.coveragerc` / `lcov.info` | Coverage configuration |
+
+## Tools
+
+Use Glob to find config files, Read to parse them. Use Bash to verify
+commands work (e.g., `npm test --help` or `pytest --co -q | head`).
+
+## Output
+
+Structured report:
+- Test framework(s) and version
+- Test command (exact command to run tests)
+- Build command (exact command to build)
+- Lint command (exact command to lint)
+- Syntax check command per language
+- Coverage tooling (if any)
+- Approximate test count

package/dist/forge-payload/init/generation/generate-commands.md

@@ -0,0 +1,171 @@
+# Generation: Commands
+
+## Purpose
+
+Generate standalone slash commands in `.claude/commands/forge/` that serve as
+entry points to the generated workflows. The namespace is FIXED to `forge`
+(CLI-first redesign): every project gets the same `/forge:*` surface, matching
+what the `4ge` bootstrap vendors. Project-prefix namespaces (`/acme:*`,
+`/ember:*`) are retired — they existed to avoid collisions with the Forge
+*plugin's* own commands, moot now that the plugin mechanism is retired.
+
+## Inputs
+
+- Generated workflows (from Phase 5) — their exact filenames and paths
+- `.forge/config.json` — paths (project prefix no longer affects the command namespace)
+
+## Outputs
+
+`.claude/commands/forge/` with the fixed-namespace commands:
+- `new-sprint.md` → `/forge:new-sprint`
+- `plan.md` → `/forge:plan {TASK_ID}`
+- `review-plan.md` → `/forge:review-plan {TASK_ID}`
+- `implement.md` → `/forge:implement {TASK_ID}`
+- `review-code.md` → `/forge:review-code {TASK_ID}`
+- `fix-bug.md` → `/forge:fix-bug {BUG_ID}`
+- `plan-sprint.md` → `/forge:plan-sprint`
+- `run-task.md` → `/forge:run-task {TASK_ID}`
+- `run-sprint.md` → `/forge:run-sprint {SPRINT_ID} [--parallel]`
+- `collate.md` → `/forge:collate [SPRINT_ID]`
+- `retro.md` → `/forge:retro {SPRINT_ID}`
+- `approve.md` → `/forge:approve {TASK_ID}`
+- `commit.md` → `/forge:commit {TASK_ID}`
+- `check-agent.md` → `/forge:check-agent $ARGUMENTS`
+- `enhance.md` → `/forge:enhance $ARGUMENTS`
+- `validate.md` → `/forge:validate {TASK_ID}`
+
+## Instructions
+
+**Scope boundary:** Only ever read, write, or delete files in the explicit output list above (16 files).
+Never touch any other file in `.claude/commands/` — custom commands, project-specific
+wrappers, and unrecognised files must be left completely untouched.
+
+**Pre-generation check (idempotency):** For each command file listed above, before writing:
+1. Check first whether the file exists at the **flat path** `.claude/commands/{filename}.md`
+   (old non-namespaced location). If it does, treat it as non-conformant — overwrite into
+   the namespaced path and log: `Replaced flat command (now namespaced): <filename>`.
+2. If the file does not exist at either path — write it fresh to the namespaced path.
+3. If the file exists at the namespaced path `.claude/commands/forge/{filename}.md` — read it
+   and extract the workflow path it references (the `.forge/workflows/` path).
+   - If it does NOT reference `.forge/workflows/` — overwrite and log: `Replaced stale command: <filename>`.
+   - If it references `.forge/workflows/` but that workflow file **does not exist on disk** — overwrite and log: `Replaced command pointing to missing workflow: <filename>`.
+   - If it references `.forge/workflows/` and the workflow file exists — check whether the file matches the template format. If it is missing `effort:` frontmatter, contains `model:` frontmatter, contains a MASTER_INDEX read line, or uses old workflow naming (`engineer_*`, `supervisor_*`) — overwrite and log: `Replaced non-conformant command: <filename>`.
+   - **wfl: dispatch rung (scoped to three filenames only):** If the filename is one of `run-task.md`, `run-sprint.md`, or `fix-bug.md` — and the file body contains `Read .forge/workflows/` — it is non-conformant (it should use `wfl:` dispatch instead). Overwrite it with the `workflow('wfl:run-task'|'wfl:run-sprint'|'wfl:fix-bug', $ARGUMENTS)` body and log: `Replaced non-conformant command: <filename>`. Do NOT apply this rung to any other command — the other 13 commands legitimately use `Read .forge/workflows/` and must not be flagged.
+   - If it matches the template format and the workflow exists — skip it (already up to date).
+
+This ensures any workflow that has been renamed or replaced causes its command wrapper to be regenerated rather than silently left pointing at a missing file.
+
+Each command file MUST follow this exact template — no variations, no additions:
+
+```markdown
+---
+description: {{description}}
+effort: {{effort}}
+---
+Read `.forge/workflows/{{workflow}}.md` and follow it exactly.
+{{argument_line}}
+<!-- AUTO-GENERATED by /forge:init -->
+```
+
+Where:
+- `{{description}}` — from the descriptions table below (fixed, not model-generated)
+- `{{effort}}` — from the effort table below (fixed mapping, not model choice)
+- `{{workflow}}` — the exact filename of the generated workflow (no path prefix, no `engineer_`/`supervisor_` role prefix)
+- `{{argument_line}}` — one of: `Task ID: $ARGUMENTS`, `Sprint ID: $ARGUMENTS`, `Bug ID: $ARGUMENTS`, or `Arguments: $ARGUMENTS`
+
+**Do NOT deviate from this template.** Specifically:
+- Do NOT include a `Read {KB_PATH}/MASTER_INDEX.md` line. The workflow loads MASTER_INDEX as its first step — pre-loading it gives the model enough context to rationalise skipping the workflow entirely and doing the work inline. Workflow first, always.
+- Do NOT include `model:` frontmatter (use `effort:` instead — model-agnostic).
+- Do NOT add numbered step lists, explanations, or any content beyond the template.
+- Do NOT add a `Also read` line for any file — the workflow controls all context loading.
+
+**Per-command descriptions** (fixed, not model-generated):
+
+| Command | description |
+|---|---|
+| `plan.md` | Design and document the implementation plan for a task |
+| `review-plan.md` | Architectural review of a task implementation plan |
+| `implement.md` | Execute the approved implementation plan for a task |
+| `review-code.md` | Code quality review of a completed task implementation |
+| `fix-bug.md` | Triage, diagnose, and fix a bug |
+| `approve.md` | Final architect approval gate for a completed task |
+| `commit.md` | Stage and commit completed task artifacts |
+| `run-task.md` | Orchestrate the full plan→implement→review→approve pipeline for a task |
+| `run-sprint.md` | Execute all tasks in a sprint (sequential or parallel) |
+| `new-sprint.md` | Elicit and structure requirements for a new sprint |
+| `plan-sprint.md` | Decompose sprint requirements into tasks with dependencies |
+| `collate.md` | Regenerate KB documents from the JSON store |
+| `retro.md` | Produce sprint retrospective and lessons-learned document |
+| `check-agent.md` | Verify an agent has read and understood the project KB before high-stakes tasks |
+| `enhance.md` | Progressive project-specific enrichment of structural elements |
+| `validate.md` | Validate that a task implementation satisfies acceptance criteria |
+
+**Effort levels** — use `effort:` frontmatter (capability request, model-agnostic):
+
+| Command | effort | Rationale |
+|---|---|---|
+| `review-plan.md` | `max` | Architectural gate — needs deepest reasoning |
+| `review-code.md` | `max` | Quality gate — needs deepest reasoning |
+| `approve.md` | `max` | Final approval gate |
+| `plan.md` | `high` | Design work with broad codebase context |
+| `implement.md` | `high` | Non-trivial code generation |
+| `fix-bug.md` | `high` | Diagnosis + fix |
+| `plan-sprint.md` | `high` | Decomposition and dependency analysis |
+| `run-task.md` | `high` | Full task orchestration |
+| `run-sprint.md` | `high` | Multi-task orchestration |
+| `new-sprint.md` | `high` | Structured requirements elicitation |
+| `retro.md` | `medium` | Reflection and summary |
+| `collate.md` | `low` | Mechanical markdown regeneration |
+| `commit.md` | `low` | Staging and committing completed work |
+| `check-agent.md` | `medium` | Short factual quiz — moderate reasoning, no deep codebase traversal |
+| `enhance.md` | `high` | Enhancement agent — broad structural enrichment |
+| `validate.md` | `max` | Validation gate — needs deepest reasoning |
+
+Do **not** include `model:` frontmatter — that directive pins a specific model and is
+not appropriate for user command files.
+
+After writing each command file, record it in the generation manifest:
+```sh
+node "$FORGE_ROOT/tools/generation-manifest.cjs" record {paths.commands}/forge/{filename}.md
+```
+
+(`FORGE_ROOT` is available from the parent init flow; tool invocations use `$FORGE_ROOT/tools/` throughout.)
+
+## Post-generation: flat-file cleanup
+
+After all 16 command files have been written and recorded, scan for pre-v0.13.0
+flat command files that were never namespaced. These are the **13 known flat filenames**:
+
+```
+new-sprint.md  plan-sprint.md  run-task.md   run-sprint.md  plan.md
+review-plan.md    implement.md    review-code.md fix-bug.md     approve.md
+commit.md         collate.md      retro.md
+```
+
+Check for each at `.claude/commands/{filename}.md` (the flat path, NOT the namespaced
+subdirectory).
+
+**Logic:**
+
+- If **none** of the 13 files exist at the flat path — skip silently. No prompt.
+
+- If **one or more** exist, display the list:
+  ```
+  Found pre-v0.13.0 flat command files that are no longer used:
+    .claude/commands/plan.md
+    .claude/commands/implement.md
+    ... (list each found file)
+
+  These have been replaced by namespaced commands under .claude/commands/forge/.
+  Remove them now? (yes / skip)
+  ```
+
+  - **On `yes`:** Delete each found file. For each deletion, print:
+    `Removed: .claude/commands/{filename}.md`
+    When done: `Flat command cleanup complete.`
+
+  - **On `skip`:** Print:
+    `Skipped. Remember to delete these files manually to avoid command name collisions.`
+
+**Do NOT delete any file that is not in the 13-filename list above.** Custom commands,
+project-specific wrappers, and unrecognised files are strictly off-limits.

package/dist/forge-payload/init/generation/generate-kb-doc.md

@@ -0,0 +1,60 @@
+# Knowledge Base Doc Generation — Per-Subagent Instructions
+
+You are generating **ONE** knowledge base document. You have been given:
+
+1. A **discovery context** — the raw findings from Phase 1 discovery scans,
+   passed inline in your prompt
+2. A **doc spec** — which file to write and what it should contain
+3. A **project brief** (`.forge/init-context.md`) — for names and paths
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file** at the path specified in your doc spec.
+
+2. **Confidence header** — every generated doc must open with:
+   ```
+   <!-- AUTO-GENERATED by /forge:init — confidence: N% -->
+   ```
+   Set N% based on how much evidence the discovery context provided:
+   - 90–100%: directly observed in code/config
+   - 70–89%: inferred from conventions or partial evidence
+   - below 70%: limited evidence, many `[?]` markers expected
+
+3. **Uncertainty markers** — any fact not directly observed in the discovery
+   context must be marked with `[?]`. Do not invent values.
+
+4. **Entity names** — use entity names exactly as they appear in the brief's
+   `## Domain Entities` section. Do not rename or abbreviate.
+
+5. **Scope discipline** — generate only what the doc spec prescribes.
+   Do not add sections not listed in the spec. Do not cross-reference
+   other KB docs that do not yet exist.
+
+6. **`architecture/INDEX.md` and `business-domain/INDEX.md`** — if your
+   assigned doc is an INDEX file, link only to docs that exist on disk at
+   the time you write. Do not anticipate files that may not have been written.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back the written file
+2. Confirm the confidence header is present on the first line
+3. Confirm no `{placeholder}` tokens remain
+4. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record "{output_path}"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+5. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-persona.md

@@ -0,0 +1,73 @@
+# Persona Generation — Per-Subagent Instructions
+
+You are generating **ONE** persona file. You have been given two inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, command values, and installed-skill wiring
+2. A **meta-persona source** — the role definition and Generation Instructions
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these two sources before writing anything:
+
+- `$FORGE_ROOT/meta/personas/{meta}` — the meta-persona for your assigned role
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/personas/{role}.md`
+
+2. **Opening line** — the first non-blank line must be the persona's symbol
+   (emoji from the meta-persona's `## Symbol` section) followed by a brief
+   first-person announcement in this exact format:
+   ```
+   {symbol} **{Project} {Role Name}** — {quiet first-person voice, present-tense}
+   ```
+   Do not use `symbol:` YAML frontmatter. The symbol must appear as the first
+   non-blank line of the file.
+
+3. **Project substitution** — replace every `{Project}` placeholder with the
+   project name from the brief's `## Commands` / `## Paths` header line.
+   All entity names, architecture doc names, persona names, and command values
+   MUST come from the brief. Do not invent values.
+
+4. **Stack wiring** — substitute actual commands from the brief's `## Commands`
+   section wherever the meta-persona references test/build/lint/syntax-check.
+
+5. **Skill invocation wiring** — read `## Installed Skill Wiring` from the
+   brief. For each skill that maps to this persona's role, add an explicit
+   YOU MUST directive. Follow the wiring pattern in the meta-persona's
+   Generation Instructions exactly.
+
+6. **Follow Generation Instructions** — each meta-persona has a
+   `## Generation Instructions` section (or equivalent). Follow it fully.
+   Do not add sections, steps, or notes beyond what it prescribes.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/personas/{role}.md`
+2. Confirm the **first non-blank line** starts with the persona's symbol emoji
+3. Confirm **no unsubstituted `{Project}` placeholders** remain
+4. Confirm **no literal `{TEST_COMMAND}`, `{BUILD_COMMAND}`, `{SYNTAX_CHECK}`,
+   or `{LINT_COMMAND}`** remain
+5. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/personas/{role}.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+6. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-skill.md

@@ -0,0 +1,66 @@
+# Skill Generation — Per-Subagent Instructions
+
+You are generating **ONE** skill file. You have been given two inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, command values, and installed-skill wiring
+2. A **meta-skill source** — the role's universal capability set and Generation Instructions
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these two sources before writing anything:
+
+- `$FORGE_ROOT/meta/skills/{meta}` — the meta-skill for your assigned role
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/skills/{role}-skills.md`
+
+2. **Project interpolation** — replace every generic placeholder with the
+   project's actual tools, libraries, paths, and conventions from the brief.
+   All entity names, stack names, and command values MUST come from the brief.
+   Do not invent values.
+
+3. **Stack specificity** — replace abstract references (e.g. "your test runner",
+   "your ORM") with the actual tools discovered for this project. Substitute
+   actual command values from the brief's `## Commands` section.
+
+4. **Installed skill integration** — read `## Installed Skill Wiring` from the
+   brief. For each skill that maps to this role, add an explicit reference
+   explaining how the persona should combine the marketplace skill with this
+   project-specific skill set.
+
+5. **Follow Generation Instructions** — each meta-skill has a
+   `## Generation Instructions` section. Follow it fully. Do not add sections,
+   steps, or notes beyond what it prescribes.
+
+6. **No free-form additions** — produce only the sections the meta-skill defines.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/skills/{role}-skills.md`
+2. Confirm **no unsubstituted placeholders** remain
+3. Confirm **no abstract project references** remain (e.g. "your framework",
+   "your ORM" — these must be replaced with the actual project values)
+4. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/skills/{role}-skills.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+5. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-template.md

@@ -0,0 +1,60 @@
+# Template Generation — Per-Subagent Instructions
+
+You are generating **ONE** template file. You have been given two inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, command values, and entity names
+2. A **meta-template source** — the document structure and Generation Instructions
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these two sources before writing anything:
+
+- `$FORGE_ROOT/meta/templates/{meta}` — the meta-template for your assigned document
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/templates/{filename}.md`
+
+2. **Stack-specific sections** — add framework-specific subsections based on the
+   stack information in the brief. Use the detected languages and frameworks to
+   decide which optional sections to include.
+
+3. **Project substitution** — replace all `{Project}`, `{PREFIX}`, entity name
+   placeholders, and ID format examples with actual values from the brief.
+   All entity names and command values MUST come from the brief. Do not invent.
+
+4. **Test output formats** — reference the project's actual test runner output
+   format in any template sections that involve test results.
+
+5. **Follow Generation Instructions** — each meta-template has a
+   `## Generation Instructions` section. Follow it fully. Do not add sections
+   or notes beyond what it prescribes.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/templates/{filename}.md`
+2. Confirm **no unsubstituted placeholders** remain (no literal `{Project}`,
+   `{PREFIX}`, `{TEST_COMMAND}`, etc.)
+3. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/templates/{filename}.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+4. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-tools.md

@@ -0,0 +1,133 @@
+# Generation: Tools
+
+## Purpose
+
+Vendor the plugin tools closure and validation schemas into the project so
+generated workflows can invoke tools via `node .forge/tools/<tool>.cjs` from
+the project root without resolving `$FORGE_ROOT` at runtime.
+
+Store validation schemas are loaded at runtime from `.forge/schemas/`
+(project-installed), `forge/schemas/` (in-tree fallback), or
+`$FORGE_ROOT/schemas/` (plugin-installed fallback). During init, schemas
+are copied to `.forge/schemas/` so that validation works without relying
+on fallback paths.
+
+## Inputs
+
+- `.forge/config.json` — target paths
+
+## Outputs
+
+- `.forge/tools/` — vendored plugin tools closure
+- `.forge/tools/.forge-tools-version` — version marker for `/forge:health` staleness check
+- `.forge/schemas/` — JSON Schema copies from the installed plugin
+
+## Instructions
+
+Read `.forge/config.json` for:
+- `paths.store` (default: `.forge/store`)
+
+### Step 1 — Copy validation schemas
+
+Copy all JSON Schema files from the installed plugin to the project:
+
+```sh
+mkdir -p .forge/schemas
+cp "$FORGE_ROOT/schemas/"*.schema.json .forge/schemas/
+```
+
+This ensures `store-cli.cjs` and `validate-store.cjs` can validate records
+using the full schema (not the minimal fallback) even when the project is
+not inside the Forge source tree.
+
+### Step 2 — Vendor plugin tools
+
+Copy the plugin tools closure into the project's `.forge/tools/` so that
+generated artifacts can invoke `node .forge/tools/<tool>.cjs` from the
+project root without resolving `$FORGE_ROOT`:
+
+Copy BOTH `.cjs` and `.js` files. Some tools require `.js` helpers at load
+time — e.g. `store-cli.cjs` does a top-level `require('./lib/validate.js')`
+and `collate.cjs` requires `./lib/result.js` — so a `.cjs`-only copy leaves
+`store-cli.cjs` dead-on-arrival and breaks KB collation. `-maxdepth 1`
+excludes the `__tests__/` subtree without copying any `*.test.*` files.
+
+```sh
+mkdir -p .forge/tools/lib
+
+# Copy top-level tool files (.cjs and .js — e.g. list-skills.js)
+find "$FORGE_ROOT/tools" -maxdepth 1 -type f \( -name '*.cjs' -o -name '*.js' \) \
+  -exec cp {} .forge/tools/ \;
+
+# Copy lib/ helper files (.cjs and .js — e.g. result.js, validate.js)
+find "$FORGE_ROOT/tools/lib" -maxdepth 1 -type f \( -name '*.cjs' -o -name '*.js' \) \
+  -exec cp {} .forge/tools/lib/ \;
+```
+
+After copying, record each vendored file in the generation manifest so that
+`/forge:health` can detect modifications or stale copies:
+
+```sh
+for f in $(find .forge/tools .forge/tools/lib -maxdepth 1 -type f \( -name '*.cjs' -o -name '*.js' \)); do
+  node "$FORGE_ROOT/tools/generation-manifest.cjs" record "$f"
+done
+```
+
+### Step 2b — Write version marker
+
+After the tool copy loop, write the version marker so `/forge:health` can
+detect whether the vendored tools are stale relative to the active plugin:
+
+```sh
+ACTIVE_VERSION=$(node -e "console.log(require('$FORGE_ROOT/.claude-plugin/plugin.json').version)")
+node -e "
+const fs = require('fs');
+fs.writeFileSync('.forge/tools/.forge-tools-version', JSON.stringify({ version: '${ACTIVE_VERSION}' }) + '\n');
+"
+```
+
+### Step 3 — Verify
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+```
+
+If it exits non-zero, report the error. Do not proceed to Phase 9 until this passes.
+
+### Step 4 — Register the Forge root
+
+Write the project-relative Forge root into config. In the CLI-first vendored
+world the `.forge/` directory IS the Forge root (tools, schemas, hooks, init,
+meta are all vendored there) — NEVER write an absolute path (plugin cache,
+npm global payload, …): absolute paths break on version upgrades, nvm/node
+switches, and machine moves.
+
+```sh
+node .forge/tools/manage-config.cjs set paths.forgeRoot '".forge"'
+```
+
+### Step 5 — Record hashes
+
+Record all generated artifacts in the generation manifest so health checks
+can detect later modifications:
+
+```sh
+for f in .forge/schemas/*.schema.json; do
+  node "$FORGE_ROOT/tools/generation-manifest.cjs" record "$f"
+done
+node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/config.json
+```
+
+## Notes
+
+- `/forge:update` automatically refreshes schemas and re-vendors tools as part
+  of its normal flow — run it after upgrades to pick up any changed tools or
+  schema updates from the new version.
+- Generated workflow files invoke tools using the vendored project-relative path:
+  ```
+  node .forge/tools/<tool>.cjs
+  ```
+  This works from the project root without resolving `$FORGE_ROOT` at runtime.
+- `paths.forgeRef` in config records the plugin version the project was generated
+  against. `forge-preflight.cjs` uses it to resolve the plugin root via cache
+  lookup when runtime telemetry requires the original plugin path.