@entelligentsia/forgecli 1.0.21 → 1.0.36

package/dist/forge-payload/hooks/lib/plugin-detection.cjs

@@ -0,0 +1,106 @@
+'use strict';
+// hooks/lib/plugin-detection.cjs — extracted from check-update.js (H-2a, FORGE-S25-T14)
+//
+// Provides Forge plugin distribution detection and installation scanning.
+// Extracted to improve testability — each function can be imported and
+// tested independently without requiring the full check-update module.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Distribution detection — derived from plugin path at runtime.
+// The cache path encodes the marketplace name, making this more reliable than
+// reading fields from plugin.json (which may be stale after a switch).
+function detectDistribution(root) {
+  return root.includes('/cache/skillforge/forge/') || root.includes('/marketplaces/skillforge/forge/')
+    ? 'forge@skillforge' : 'forge@forge';
+}
+
+// Check if forge plugin is enabled in settings files.
+// Returns true if no explicit disable found, false if disabled.
+function isPluginEnabled(pluginPath, scope, homeDir, cwd) {
+  try {
+    // Check user settings: ~/.claude/settings.json
+    const userSettingsPath = path.join(homeDir, '.claude', 'settings.json');
+    if (fs.existsSync(userSettingsPath)) {
+      const userSettings = JSON.parse(fs.readFileSync(userSettingsPath, 'utf8'));
+      if (userSettings.disablePlugin === true) return false;
+      // Check for per-plugin disable (if supported in future)
+      if (userSettings.plugins && userSettings.plugins.forge === false) return false;
+    }
+
+    // Check project settings: ./.claude/settings.local.json
+    const projectSettingsPath = path.join(cwd, '.claude', 'settings.local.json');
+    if (fs.existsSync(projectSettingsPath)) {
+      const projectSettings = JSON.parse(fs.readFileSync(projectSettingsPath, 'utf8'));
+      if (projectSettings.disablePlugin === true) return false;
+      if (projectSettings.plugins && projectSettings.plugins.forge === false) return false;
+    }
+
+    return true; // Default: enabled
+  } catch (e) {
+    return true; // Non-fatal — assume enabled if cannot read settings
+  }
+}
+
+// Scans all known plugin locations to detect multiple Forge installations.
+// Returns array of installation records with version, distribution, scope, enabled status.
+// Optional parameters for dependency injection (testing).
+function scanPluginInstallations(options) {
+  const installations = [];
+  const homeDir = (options && options.homeDir) || os.homedir();
+  const cwd = (options && options.cwd) || process.cwd();
+
+  // Candidate paths — user scope (global) and project scope (local)
+  // Also scan skillforge subdirectory variant (skillforge/forge/forge)
+  const basePaths = [
+    path.join(homeDir, '.claude', 'plugins'),
+    path.join(cwd, '.claude', 'plugins'),
+  ];
+  const variants = ['cache', 'marketplaces'];
+  const pluginNames = ['forge/forge', 'skillforge/forge/forge'];
+
+  const candidates = [];
+  for (const basePath of basePaths) {
+    for (const variant of variants) {
+      for (const pluginName of pluginNames) {
+        candidates.push(path.join(basePath, variant, pluginName));
+      }
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const pluginJsonPath = path.join(candidate, '.claude-plugin', 'plugin.json');
+      if (!fs.existsSync(pluginJsonPath)) continue;
+
+      const manifest = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+      // Determine scope: user-scope paths start with homeDir/.claude, project-scope start with cwd/.claude
+      // Use cwd-relative check first to avoid false positives when cwd is subdir of homeDir
+      const isProjectScope = candidate.startsWith(path.join(cwd, '.claude'));
+      const isUserScope = candidate.startsWith(path.join(homeDir, '.claude'));
+      const scope = isProjectScope ? 'project' : (isUserScope ? 'user' : 'unknown');
+      const enabled = isPluginEnabled(candidate, scope, homeDir, cwd);
+
+      // Avoid duplicates — skip if same path already recorded
+      if (installations.some(i => i.path === candidate)) continue;
+
+      installations.push({
+        path: candidate,
+        version: manifest.version || 'unknown',
+        distribution: detectDistribution(candidate),
+        scope: scope,
+        enabled: enabled,
+      });
+    } catch (e) {
+      // Non-fatal — skip broken installations silently
+    }
+  }
+
+  return installations;
+}
+
+module.exports = { detectDistribution, isPluginEnabled, scanPluginInstallations };

package/dist/forge-payload/hooks/lib/update-msg.cjs

@@ -0,0 +1,23 @@
+'use strict';
+// hooks/lib/update-msg.cjs — extracted from check-update.js (H-2c, FORGE-S25-T14)
+//
+// Provides update message construction and emission.
+// Extracted to improve testability — buildUpdateMsg and emit can be tested
+// without executing the full check-update session logic.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+function buildUpdateMsg(remoteVersion, local) {
+  return remoteVersion && remoteVersion !== local
+    ? `Forge ${remoteVersion} available (you have ${local}). Run /forge:update to review changes and update.`
+    : '';
+}
+
+function emit(forgeCtx, updateMsg) {
+  if (!forgeCtx && !updateMsg) return;
+  const combined = [forgeCtx, updateMsg].filter(Boolean).join(' ');
+  const escaped = combined.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ');
+  process.stdout.write(`{"additionalContext":"${escaped}"}\n`);
+}
+
+module.exports = { buildUpdateMsg, emit };

package/dist/forge-payload/hooks/lib/update-url.cjs

@@ -0,0 +1,46 @@
+'use strict';
+// hooks/lib/update-url.cjs — extracted from check-update.js (H-2b, FORGE-S25-T14)
+//
+// Provides update-check URL resolution and validation.
+// Reads process.env.CLAUDE_PLUGIN_ROOT directly (option b from plan) so
+// the module is self-contained — no pluginRoot argument needed at call sites.
+//
+// Uses only Node.js built-ins — no npm dependencies required.
+
+const fs = require('fs');
+const path = require('path');
+
+// Determine the correct update-check URL for this distribution.
+// Each distribution's plugin.json carries its own updateUrl pointing at the
+// branch it was installed from (main for forge@forge, release for forge@skillforge),
+// so we read it directly — no hardcoded per-distribution URLs needed.
+const FALLBACK_UPDATE_URL = 'https://raw.githubusercontent.com/Entelligentsia/forge/main/forge/.claude-plugin/plugin.json';
+
+const ALLOWED_DOMAINS = ['raw.githubusercontent.com'];
+
+function validateUpdateUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const hostname = parsed.hostname.toLowerCase();
+    if (!ALLOWED_DOMAINS.some(d => hostname === d || hostname.endsWith('.' + d))) {
+      process.stderr.write(`forge-update: rejected update URL with disallowed domain '${hostname}', falling back\n`);
+      return FALLBACK_UPDATE_URL;
+    }
+    return url;
+  } catch {
+    return FALLBACK_UPDATE_URL;
+  }
+}
+
+// Reads updateUrl from the installed plugin.json.
+// Uses process.env.CLAUDE_PLUGIN_ROOT (option b) with a fallback of '' so
+// the function is self-contained. Falls back to FALLBACK_UPDATE_URL on any error.
+function getUpdateUrl() {
+  try {
+    const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || '';
+    const manifest = JSON.parse(fs.readFileSync(path.join(pluginRoot, '.claude-plugin', 'plugin.json'), 'utf8'));
+    return validateUpdateUrl(manifest.updateUrl || FALLBACK_UPDATE_URL);
+  } catch { return FALLBACK_UPDATE_URL; }
+}
+
+module.exports = { FALLBACK_UPDATE_URL, ALLOWED_DOMAINS, validateUpdateUrl, getUpdateUrl };

package/dist/forge-payload/hooks/lib/write-registry.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Write-boundary registry: maps Forge-owned filesystem path patterns to the
+// schema (and kind) that the write-boundary hook enforces on Write/Edit/
+// MultiEdit. FIRST match wins, so order matters — place more specific
+// patterns before their generalizations (sidecar before event).
+//
+// Patterns are anchored to absolute-path suffixes so they match whether the
+// tool invocation used an absolute or project-relative path. Every pattern
+// assumes the Forge store lives at `.forge/store/` (the installed default).
+//
+// If NO pattern matches a write, the hook is a no-op: Forge does not validate
+// non-Forge-owned files. The registry is an allowlist of paths we claim, not
+// a denylist of paths we reject.
+
+const REGISTRY = [
+  // Core store entities — flat files under .forge/store/{kind}s/<id>.json
+  { pattern: /(?:^|\/)\.forge\/store\/features\/[^/]+\.json$/,             schema: 'feature.schema.json',         kind: 'feature' },
+  { pattern: /(?:^|\/)\.forge\/store\/sprints\/[^/]+\.json$/,              schema: 'sprint.schema.json',          kind: 'sprint' },
+  { pattern: /(?:^|\/)\.forge\/store\/tasks\/[^/]+\.json$/,                schema: 'task.schema.json',            kind: 'task' },
+  { pattern: /(?:^|\/)\.forge\/store\/bugs\/[^/]+\.json$/,                 schema: 'bug.schema.json',             kind: 'bug' },
+
+  // Event sidecars — prefixed with `_` and suffixed with `_usage.json`.
+  // Must come BEFORE the general event pattern so the leading `_` file is
+  // classified as a sidecar, not an event with a malformed id.
+  { pattern: /(?:^|\/)\.forge\/store\/events\/[^/]+\/_[^/]+_usage\.json$/, schema: 'event-sidecar.schema.json',   kind: 'event-sidecar' },
+
+  // Canonical events — any other .json under events/<bucket>/ that does NOT
+  // start with an underscore. (Ghost events are not written through Write/Edit
+  // tools, so we don't special-case them here.)
+  { pattern: /(?:^|\/)\.forge\/store\/events\/[^/]+\/[^_/][^/]*\.json$/,   schema: 'event.schema.json',           kind: 'event' },
+
+  // Collation watermark
+  { pattern: /(?:^|\/)\.forge\/store\/COLLATION_STATE\.json$/,             schema: 'collation-state.schema.json', kind: 'collation-state' },
+
+  // Progress log — line-oriented, not JSON. The hook's parser splits newly
+  // appended lines and validates each as a pipe-delimited progress entry.
+  { pattern: /(?:^|\/)\.forge\/store\/events\/[^/]+\/progress\.log$/,      schema: 'progress-entry.schema.json',  kind: 'progress-line', format: 'line-pipe-delimited' },
+];
+
+function matchRegistry(absPath) {
+  if (!absPath || typeof absPath !== 'string') return null;
+  for (const entry of REGISTRY) {
+    if (entry.pattern.test(absPath)) return entry;
+  }
+  return null;
+}
+
+// REGISTRY is intentionally not exported — it is a private implementation detail
+// of this module. Callers use matchRegistry() for lookups. Exporting REGISTRY
+// would expose internal pattern structures to external consumers and create
+// coupling that makes future pattern changes harder. (H-3, FORGE-S25-T14)
+module.exports = { matchRegistry };

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

@@ -0,0 +1,32 @@
+# Discovery: Database
+
+## Purpose
+
+Detect the project's data model: entities, relationships, field types,
+and migration patterns.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| Django: `models.py` files | ORM models, fields, relationships |
+| Rails: `app/models/*.rb` | ActiveRecord models |
+| Prisma: `schema.prisma` | Prisma schema |
+| TypeORM: `*.entity.ts` | TypeORM entities |
+| Sequelize: `models/*.js` | Sequelize models |
+| Go: `*_model.go` | Go struct definitions |
+| SQL: `migrations/` / `schema.sql` | Raw schema |
+| MongoDB: Mongoose schemas | Document models |
+
+## Tools
+
+Use Grep to find model/entity definitions, Read to parse them.
+
+## Output
+
+Structured report:
+- Entity inventory (name, field count, key relationships)
+- Database type (PostgreSQL, MySQL, MongoDB, SQLite, etc.)
+- ORM/query layer in use
+- Migration framework and directory
+- Seed data presence

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

@@ -0,0 +1,31 @@
+# Discovery: Processes
+
+## Purpose
+
+Detect the project's service topology, build tools, and deployment configuration.
+
+## Scan Targets
+
+| File | What It Reveals |
+|------|----------------|
+| `docker-compose.yml` | Service topology, dependencies, ports |
+| `Procfile` | Process types (web, worker, etc.) |
+| `ecosystem.config.js` | PM2 process management |
+| `systemd/*.service` | System service definitions |
+| `.github/workflows/*.yml` | CI/CD pipeline |
+| `.gitlab-ci.yml` | CI/CD pipeline |
+| `Jenkinsfile` | CI/CD pipeline |
+| `vercel.json` / `netlify.toml` | Deployment platform |
+
+## Tools
+
+Use Glob to find these files, Read to parse them.
+
+## Output
+
+Structured report:
+- Services and their roles (web, worker, database, cache, etc.)
+- Build command(s)
+- Deploy command(s) or platform
+- CI/CD pipeline structure
+- Environment variables referenced (names only, not values)

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

@@ -0,0 +1,31 @@
+# Discovery: Routing
+
+## Purpose
+
+Detect the project's API surface, authentication strategy, and middleware.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| Django: `urls.py`, `views.py` | URL patterns, view functions/classes |
+| Express: `router.get/post/...` | Route definitions |
+| Rails: `routes.rb` | Route definitions |
+| FastAPI: `@app.get/post` | Endpoint decorators |
+| Go: `http.HandleFunc` / mux | Route handlers |
+| Auth decorators/middleware | `@login_required`, `authenticate`, `IsAuthenticated` |
+| API docs: `openapi.yaml` / `swagger.json` | API specification |
+
+## Tools
+
+Use Grep to find route definitions and auth patterns, Read to parse them.
+
+## Output
+
+Structured report:
+- Route count (approximate)
+- Auth strategy (decorator-based, middleware, JWT, session, etc.)
+- Public vs protected route ratio
+- URL namespace structure
+- API versioning (if any)
+- Middleware chain

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.