@entelligentsia/forgecli 0.21.0 → 1.0.3

package/dist/forge-payload/init/phases/phase-1-collect.md

@@ -0,0 +1,138 @@
+# Phase 1 — Collect
+
+**Deliverable:** `.forge/config.json` with all required fields.
+
+Set `$FORGE_ROOT` to the forge plugin directory (the parent of this file's
+parent directory — the folder containing `meta/` and `init/`).
+
+---
+
+## Pre-flight — Knowledge Base Folder
+
+Before Phase 1 begins, ask the user where to create the knowledge base folder:
+
+```
+Forge will create a folder for architecture docs, sprints, bugs, and features.
+Default name: engineering/
+
+Does "engineering" conflict with an existing folder in this project? [n/Y]
+If yes, enter your preferred name (e.g. ai-docs, .forge-kb, docs/ai): ___
+```
+
+- If the user accepts the default (types `n` or presses Enter): no config write needed.
+  `paths.engineering` defaults to `"engineering"` in the schema.
+- If the user provides a custom name: write it immediately:
+  ```sh
+  node "$FORGE_ROOT/tools/manage-config.cjs" set paths.engineering "{chosen_name}"
+  ```
+  Note: folder name must not contain spaces.
+
+After this question (and any config write), resolve `KB_PATH` for use in all
+subsequent phases:
+
+```sh
+KB_PATH=$(node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}")
+```
+
+---
+
+## Steps (follow in order)
+
+### Step 1 — Render phase header
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --phase 1 4 "Collect" north
+```
+
+### Step 2 — Discovery
+
+Read each discovery prompt file below, then analyse the project codebase for
+that topic. Summarise your structured findings for each topic before writing
+anything to disk.
+
+| Prompt | File |
+|--------|------|
+| Stack | `$FORGE_ROOT/init/discovery/discover-stack.md` |
+| Processes | `$FORGE_ROOT/init/discovery/discover-processes.md` |
+| Database | `$FORGE_ROOT/init/discovery/discover-database.md` |
+| Routing | `$FORGE_ROOT/init/discovery/discover-routing.md` |
+| Testing | `$FORGE_ROOT/init/discovery/discover-testing.md` |
+
+Complete all 5 discovery reads before proceeding to Step 3.
+
+### Step 3 — Write config.json
+
+Using your discovery findings, write `.forge/config.json` with this structure:
+
+```json
+{
+  "version": "1",
+  "project": { "name": "<project name>", "prefix": "<UPPERCASE_ABBREV>" },
+  "stack": { "primary": [...], "test": "<framework>", "build": "<tool>", "lint": "<tool>" },
+  "commands": { "test": "<test cmd>", "build": "<build cmd>", "lint": "<lint cmd>" },
+  "paths": {
+    "engineering": "engineering",
+    "store": ".forge/store",
+    "workflows": ".forge/workflows",
+    "commands": ".claude/commands/<prefix-lowercased>",
+    "templates": ".forge/templates"
+  }
+}
+```
+
+`<prefix-lowercased>` = the `project.prefix` value you chose, lowercased. For example, if prefix is `HELLO`, write `".claude/commands/hello"`.
+
+Write using:
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" set <key> <value>
+```
+Or write `.forge/config.json` directly as valid JSON.
+
+Write `mode` as `"full"` unconditionally:
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" set mode "full"
+```
+
+### Step 4 — Self-check
+
+Read back `.forge/config.json` and confirm all 8 required keys are present
+and non-empty: `version`, `project.name`, `project.prefix`, `stack`,
+`commands`, `paths.engineering`, `paths.store`, `paths.workflows`.
+
+If any key is missing or empty, fix it now before proceeding.
+
+### Step 5 — Marketplace Skills
+
+Read `$FORGE_ROOT/meta/skill-recommendations.md` for the full mapping.
+
+Using the stack discovered above, look up matching skills from the recommendation
+mapping. For each match:
+
+1. Run `node "$FORGE_ROOT/tools/list-skills.js"` to get all currently installed skill names.
+2. Split matching skills into two buckets: Already installed / Not yet installed.
+3. Group not-yet-installed matches by confidence: High, Medium, Low.
+4. Present to the user for optional installation.
+5. Write `"installedSkills"` to `.forge/config.json` as the union of installed skills.
+6. Track skipped skills for the Report.
+
+**If the user skips or installs none:** proceed without blocking.
+
+Write `.forge/init-progress.json`:
+```json
+{ "lastPhase": 1, "timestamp": "<current ISO timestamp>" }
+```
+
+---
+
+## Verify Phase 1
+
+After writing `init-progress.json`, verify the deliverable:
+
+```sh
+node "$FORGE_ROOT/tools/verify-phase.cjs" --phase 1
+```
+
+- **Exit 0:** Phase 1 complete. Proceed to Phase 2.
+- **Exit 1:** Read the JSON output to identify missing fields. Fix them and
+  re-run verify once. If it still fails, halt and surface the JSON error to
+  the user.

package/dist/forge-payload/init/phases/phase-2-discover.md

@@ -0,0 +1,127 @@
+# Phase 2 — Discover
+
+**Deliverable:** 7 KB architecture docs + 3 index files + `project-context.json` + calibration baseline.
+
+Set `$FORGE_ROOT` and resolve `$KB_PATH` from `.forge/config.json`:
+
+```sh
+KB_PATH=$(node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}")
+```
+
+---
+
+## Phase gate — verify Phase 1 foundation
+
+Before starting any work, verify Phase 1 completed successfully:
+
+```sh
+node "$FORGE_ROOT/tools/verify-phase.cjs" --phase 1
+```
+
+If this exits 1, halt and surface the missing fields. Phase 2 cannot proceed
+without a valid `.forge/config.json`.
+
+---
+
+## Steps (follow in order)
+
+### Step 1 — Render phase header
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --phase 2 4 "Discover" oracle
+```
+
+### Step 2 — Scaffold directories
+
+Create the directory structure (fast Bash operations):
+
+```sh
+mkdir -p "{KB_PATH}/architecture" "{KB_PATH}/business-domain" \
+         "{KB_PATH}/sprints" "{KB_PATH}/bugs" "{KB_PATH}/tools" \
+         ".forge/store/sprints" ".forge/store/tasks" \
+         ".forge/store/bugs" ".forge/store/events"
+touch "{KB_PATH}/sprints/.gitkeep" "{KB_PATH}/bugs/.gitkeep" \
+      ".forge/store/sprints/.gitkeep" ".forge/store/tasks/.gitkeep" \
+      ".forge/store/bugs/.gitkeep" ".forge/store/events/.gitkeep"
+```
+
+### Step 3 — Generate KB documents
+
+Read `$FORGE_ROOT/init/generation/generate-kb-doc.md` once (the per-subagent rulebook).
+
+Generate all 7 knowledge-base documents. For each document, analyse the
+project codebase for that topic and write to its output path. After writing
+each document, read it back and verify the confidence header is present
+(`<!-- AUTO-GENERATED — confidence: NN% -->`).
+
+| Document | Output path | Focus |
+|----------|-------------|-------|
+| stack.md | `{KB_PATH}/architecture/stack.md` | Languages, frameworks, runtime, versions |
+| processes.md | `{KB_PATH}/architecture/processes.md` | Services, build/deploy topology |
+| database.md | `{KB_PATH}/architecture/database.md` | Entities, relationships, field types |
+| routing.md | `{KB_PATH}/architecture/routing.md` | API surface, route groups, auth strategy |
+| deployment.md | `{KB_PATH}/architecture/deployment.md` | Environments, CI/CD, infra targets |
+| entity-model.md | `{KB_PATH}/business-domain/entity-model.md` | Full entity inventory with fields |
+| stack-checklist.md | `{KB_PATH}/stack-checklist.md` | Review checklist items from stack + testing |
+
+You may spawn all 7 as parallel subagents in a single Agent tool message for speed.
+Wait for all 7 to return. Retry any that returned FAILED: once.
+Any still failing after one retry: halt and surface the id list.
+
+### Step 4 — Create index files (sequential)
+
+After all leaf docs are written:
+
+1. **`{KB_PATH}/architecture/INDEX.md`** — list and link to the 5 architecture docs
+2. **`{KB_PATH}/business-domain/INDEX.md`** — list and link to entity-model.md
+3. **`{KB_PATH}/MASTER_INDEX.md`** — scaffold linking both INDEX files; include
+   `## Domain Entities` section listing discovered entities (one per line)
+
+Generate these sequentially — each builds on what's already on disk.
+
+### Step 5 — Construct project-context.json
+
+After all KB docs and MASTER_INDEX are written, construct `.forge/project-context.json`
+inline (do NOT spawn a subagent for this step).
+
+Using the `x-placeholder` annotations from
+`$FORGE_ROOT/schemas/project-context.schema.json` as a guide, map discovered
+facts to schema fields. Required fields: `project.name`, `project.prefix`
+(must be non-empty strings). All array fields must be arrays.
+
+Write the JSON to `.forge/project-context.json`.
+
+**Structural validation failure halts Phase 2** with a descriptive error:
+```
+× Phase 2 validation failed: project.name is missing or empty.
+```
+
+### Step 6 — Write calibration baseline
+
+After `project-context.json` is written, compute and write `calibrationBaseline`
+into `.forge/config.json`:
+
+1. Read `$FORGE_ROOT/.claude-plugin/plugin.json` → `version`
+2. Hash `{KB_PATH}/MASTER_INDEX.md` (strip blank lines + `<!--` lines, SHA-256)
+3. List done sprint IDs from `.forge/store/sprints/`
+4. Merge into config: `calibrationBaseline: { lastCalibrated, version, masterIndexHash, sprintsCovered }`
+
+Write `.forge/init-progress.json`:
+```json
+{ "lastPhase": 2, "timestamp": "<current ISO timestamp>" }
+```
+
+---
+
+## Verify Phase 2
+
+After writing `init-progress.json`, verify the deliverable:
+
+```sh
+node "$FORGE_ROOT/tools/verify-phase.cjs" --phase 2 --kb-path "$KB_PATH"
+```
+
+- **Exit 0:** Phase 2 complete. Proceed to Phase 3.
+- **Exit 1:** Read the JSON output to identify missing documents. Fix them and
+  re-run verify once. If it still fails, halt and surface the JSON error to
+  the user.

package/dist/forge-payload/init/phases/phase-3-materialize.md

@@ -0,0 +1,113 @@
+# Phase 3 — Materialize
+
+**Deliverable:** `.forge/{personas,skills,workflows,templates}` fully populated.
+
+This phase is deterministic and requires no LLM calls.
+
+Set `$FORGE_ROOT` and resolve `$KB_PATH`:
+
+```sh
+KB_PATH=$(node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}")
+```
+
+---
+
+## Phase gate — verify Phase 1 foundation
+
+Before starting any work, verify the Phase 1 foundation:
+
+```sh
+node "$FORGE_ROOT/tools/verify-phase.cjs" --phase 1 --foundation-only
+```
+
+If this exits 1, halt. `project.name` and `project.prefix` are required by
+`substitute-placeholders.cjs`. Missing them causes a hard failure.
+
+---
+
+## Steps (follow in order)
+
+### Step 1 — Render phase header
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --phase 3 4 "Materialize" ember
+```
+
+### Step 2 — Build project brief (first pass)
+
+```sh
+node "$FORGE_ROOT/tools/build-init-context.cjs" \
+  --config    .forge/config.json \
+  --personas  .forge/personas \
+  --templates .forge/templates \
+  --kb        "$KB_PATH" \
+  --out       .forge/init-context.md \
+  --json-out  .forge/init-context.json
+```
+
+The script prints `〇 Brief written — N personas, M templates, K architecture docs` on success.
+If it exits non-zero, halt and surface the error.
+
+Note: `.forge/personas/` and `.forge/templates/` are empty at this point —
+the brief will have stub entries. The full content is produced in Step 3 below.
+
+### Step 3 — Substitute placeholders (base-pack materialisation)
+
+```sh
+node "$FORGE_ROOT/tools/substitute-placeholders.cjs" \
+  --forge-root "$FORGE_ROOT" \
+  --base-pack  "$FORGE_ROOT/init/base-pack" \
+  --config     .forge/config.json \
+  --context    .forge/project-context.json \
+  --out        .
+```
+
+Output directories (managed by the tool's `SUBDIR_OUTPUT_MAP`):
+- `base-pack/commands/`  → `.claude/commands/<prefix-lowercased>/`
+- `base-pack/personas/`  → `.forge/personas/`
+- `base-pack/skills/`    → `.forge/skills/`
+- `base-pack/workflows/` → `.forge/workflows/`
+- `base-pack/templates/` → `.forge/templates/`
+
+If `project-context.json` is absent or missing required keys, halt Phase 3:
+```
+× Phase 3 aborted: project-context.json is missing or incomplete.
+  Ensure Phase 2 (Discover) completed successfully and try again.
+```
+
+### Step 4 — build-overlay.cjs smoke test
+
+```sh
+node "$FORGE_ROOT/tools/build-overlay.cjs" --task INIT-SMOKE-TEST --format json 2>&1
+```
+
+**Expected:** exit 1 with "task not found" error (store not yet seeded). This
+is the passing result — it confirms the binary is functional.
+
+Emit a warning when exit code is non-zero (expected):
+```
+⚠ build-overlay smoke-test: task INIT-SMOKE-TEST not found in store (expected — store not yet seeded). Overlay binary is functional.
+```
+
+Phase 3 does NOT halt on this smoke test — result is informational.
+
+Write `.forge/init-progress.json`:
+```json
+{ "lastPhase": 3, "timestamp": "<current ISO timestamp>" }
+```
+
+---
+
+## Verify Phase 3
+
+After writing `init-progress.json`, verify the deliverable:
+
+```sh
+node "$FORGE_ROOT/tools/verify-phase.cjs" --phase 3
+```
+
+- **Exit 0:** Phase 3 complete. Proceed to Phase 4.
+- **Exit 1:** Read the JSON output. This usually means `substitute-placeholders.cjs`
+  ran against an incomplete config. Fix `.forge/config.json` and run
+  `/forge:rebuild`, or delete `.forge/init-progress.json` and restart.
+  **This is a hard failure — do not continue with partial Phase 3.**

package/dist/forge-payload/init/phases/phase-4-register.md

@@ -0,0 +1,159 @@
+# Phase 4 — Register
+
+**Deliverable:** Versioning, manifest, caches, store entries, agent linking — fully registered.
+
+This phase is deterministic and requires no LLM calls. Execute all 11 steps in order.
+
+Set `$FORGE_ROOT` and resolve `$KB_PATH`:
+
+```sh
+KB_PATH=$(node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}")
+```
+
+---
+
+## Steps (follow in order)
+
+### Step 1 — Render phase header
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --phase 4 4 "Register" forge
+```
+
+### Step 2 — Tools registration
+
+Read `$FORGE_ROOT/init/generation/generate-tools.md` and follow it.
+
+**Input**: `.forge/config.json`
+**Output**: `paths.forgeRoot` written to `.forge/config.json`, schema copies to `.forge/schemas/`
+
+### Step 3 — Enhancement substrate (FR-007)
+
+Materialize the substrate for post-init hooks:
+
+```sh
+mkdir -p .forge/enhancements/
+cp "$FORGE_ROOT/schemas/project-overlay.schema.json" .forge/schemas/
+```
+
+### Step 4 — structure-versions.json
+
+```sh
+node "$FORGE_ROOT/tools/manage-versions.cjs" init
+```
+
+### Step 5 — generation-manifest.json
+
+```sh
+node "$FORGE_ROOT/tools/generation-manifest.cjs" record-all
+```
+
+### Step 6 — persona-pack.json
+
+```sh
+node "$FORGE_ROOT/tools/build-persona-pack.cjs" \
+  --out .forge/cache/persona-pack.json
+```
+
+### Step 7 — context-pack.md / context-pack.json
+
+```sh
+node "$FORGE_ROOT/tools/build-context-pack.cjs" \
+  --arch-dir "$KB_PATH/architecture" \
+  --out-md .forge/cache/context-pack.md \
+  --out-json .forge/cache/context-pack.json
+```
+
+### Step 8 — init-context.json / init-context.md (final rebuild)
+
+```sh
+node "$FORGE_ROOT/tools/build-init-context.cjs" \
+  --config    .forge/config.json \
+  --personas  .forge/personas \
+  --templates .forge/templates \
+  --kb        "$KB_PATH" \
+  --out       .forge/init-context.md \
+  --json-out  .forge/init-context.json
+```
+
+### Step 9 — Store seed
+
+```sh
+node "$FORGE_ROOT/tools/seed-store.cjs"
+```
+
+### Step 10 — Update-check cache
+
+```sh
+node -e "
+const fs = require('fs');
+const pluginPkg = JSON.parse(fs.readFileSync('$FORGE_ROOT/.claude-plugin/plugin.json', 'utf8'));
+const cache = {
+  lastChecked: new Date().toISOString(),
+  installedVersion: pluginPkg.version,
+  latestVersion: pluginPkg.version,
+  upToDate: true
+};
+fs.mkdirSync('.forge', { recursive: true });
+fs.writeFileSync('.forge/update-check-cache.json', JSON.stringify(cache, null, 2) + '\n', 'utf8');
+console.log('ノ update-check-cache.json written');
+"
+```
+
+### Step 11 — Tomoshibi (refresh-kb-links)
+
+Use the Skill tool:
+```
+skill: "forge:refresh-kb-links"
+```
+
+Fallback if unavailable:
+```
+△ Run /forge:refresh-kb-links to wire KB links into your agent instruction files.
+```
+
+### Step 12 — Git hygiene — gitignore transient store paths
+
+1. Check whether `.gitignore` exists at project root:
+   ```sh
+   ls .gitignore 2>/dev/null
+   ```
+   If absent, skip this step.
+
+2. If `.gitignore` exists, check whether `.forge/store/events/` is already
+   ignored (any line containing `.forge/store/events/`, `.forge/store/events`,
+   `.forge/store/`, or `.forge/`).
+   - Found: emit `〇 .forge/store/events/ already gitignored — skipped.`
+
+3. If not already ignored, unconditionally append:
+   ```
+   # Forge — transient agent event logs (one file per phase, do not commit)
+   .forge/store/events/
+   ```
+   Emit `〇 Appended .forge/store/events/ to .gitignore.`
+
+### Step 13 — Agent instruction file linking
+
+Check whether any agent instruction file exists at the project root:
+```sh
+ls CLAUDE.md AGENTS.md CLAUDE.local.md .cursorrules 2>/dev/null
+```
+
+If NONE exists, prompt:
+```
+No agent instruction file found. Create a minimal CLAUDE.md with Forge KB links? [Y/n]
+```
+
+If Y (default), create `CLAUDE.md` with:
+- Project name header
+- Links to `{KB_PATH}/MASTER_INDEX.md`, `{KB_PATH}/architecture/INDEX.md`,
+  `{KB_PATH}/business-domain/INDEX.md`
+- Canonical Forge workflow table
+- Footer: `Generated by /forge:init. Run /forge:refresh-kb-links to update.`
+
+If one already exists: skip. Do NOT modify existing files.
+
+Delete `.forge/init-progress.json` — init is complete:
+```sh
+rm -f .forge/init-progress.json
+```

package/dist/forge-payload/integrity.json

@@ -1,38 +1,35 @@
 {
-  "version": "0.51.4",
-  "generated": "2026-05-26",
+  "version": "1.0.3",
+  "generated": "2026-05-28",
   "note": "Tamper-evident only. Authoritative source: /forge:update from remote.",
   "files": {
-    "commands/add-pipeline.md": "402c1deb6f19ad99561b48548ad89e3e1f625b827dce633eb84317556c0a1a4a",
-    "commands/add-task.md": "b2640c4b3c8c4fb9d4a82633d8c4d8fcd13bd63d4d6deb2c5c6a2008508de770",
+    "commands/add-pipeline.md": "529a2fc01be49815efa2cf1147528827ff1bfc12ce2ac8663b5a3a9781f8682e",
+    "commands/add-task.md": "ce3d66fc38e7e0a7592705c559425c6e122f25280b838b631ad44e514bd64e04",
     "commands/ask.md": "df15f0aa68c93d65bfef05adb514c377bfc65617cafcd79534eb9b4149302657",
-    "commands/calibrate.md": "c764e735c9212eaf785d3d0afaf926f536fef099421b2b1bde7a4b1e3114d443",
-    "commands/config.md": "67251316b806d706bb77f063128e29995c6b4abaf554f4d5558bd97a1a6cfcfe",
-    "commands/enhance.md": "4bbfc05cf85c862c49883bc36f1272f87cd49c8cbe00f9196e76d542e6eaa720",
-    "commands/health.md": "31fdc6e01529b0ee8cfea4a4937e140bacec78f273260d5406108f8be1bf7aea",
-    "commands/init.md": "3c0522294c692e8fbb75f925370caee66f54b23d7dd3a692bedcd69f95718b28",
-    "commands/materialize.md": "195292c9e98f50773c1b0c84f9bbc42438c4c8c989a84bd98092f6692799d6d6",
-    "commands/migrate.md": "b226f10a6f202bfd4a840314f34d503da34a077abbf1dff8d2b40f864474a76b",
-    "commands/quiz-agent.md": "ed261a5c8ac7cd3a1d7c8b372c9bf099bba9a4f9dc0a41cb5c80f22b57a133a1",
-    "commands/regenerate.md": "7c14f87b1bb178dd98ebdf0efafb86792c2b8b079bc5052d02a7e618165ec525",
-    "commands/remove.md": "de8802ee8ad5db4c4f3d0f526eb8735ab7de1a4b8ad307355d11dac5e1e04fc6",
+    "commands/check-agent.md": "f92121cb150d4cf601654e25c28d0c13389039518d05433f1040d727054b127e",
+    "commands/config.md": "e67185f98cf0b045890398083991b9d48f32bf0d53bafda1eaca3ce0337ce49c",
+    "commands/enhance.md": "d28f6414119e84973809d32900bb7245b51f565aed86112bc7a994bc6941b547",
+    "commands/health.md": "29c3e5f9808d996f53a432c4b3aff1c3346d7a40fff54518d8ea2ac2c6ba9d12",
+    "commands/init.md": "cf7a70d55f718304820c310465071d3eea9d14a43131623f46b686499f630d4d",
+    "commands/rebuild.md": "e6d1e0bc29fd21c4c9109d8f40045b782207dfa6db2d98a9bf8c7254a80f09c6",
+    "commands/remove.md": "0ca5ec94d52959afaadd74910bd2c81c9872b71c9cc1ce8b89e5af69c06b304f",
+    "commands/repair.md": "22e21614eee31ee630ead3f587b0b948b8c537e54ecef3b65e7d819c55c0ebd4",
     "commands/report-bug.md": "af8a54bf8887b35e5c880898dd45783f6c2e80d3dc031d6479a6be613ac43053",
-    "commands/store-query.md": "28925bd257ceb6645254628abf0e76524481460382192ea00081b17310b88fed",
-    "commands/store-repair.md": "9317be65deb400953b8642b4d353d5583d3b032546c0b8f73d6c3a9b3445ebdd",
-    "commands/update-tools.md": "768c0d7ec07a17055c3d4b1b31370812f4292e03b1496723ba36f8caf596a609",
-    "commands/update.md": "a7317f919e79cab165ab05b477f0f6a919ea12b159ddd6c06bec103cf85c4337",
+    "commands/search.md": "befc4ba9f3146e7599308b35b95ec315e16895c0c18c9c2bab7549619d79bf1c",
+    "commands/status.md": "2fa82a0b11d493918781aec6d95c39411f84fa923662ff3152b6de0cc830d755",
+    "commands/update.md": "a7eac4362a927eae708ee3844ef8d920f3166d1eafde36323d2dd92789fbdec9",
     "agents/store-query-validator.md": "f4c3573edcf6e28809515705362df611806a805c5269404fb17e31433cf3a81c",
-    "agents/tomoshibi.md": "0112604af0856235d7f028683dbfa3f4af63355cb2dd79d26592e983a6ecec8b",
-    "hooks/check-update.cjs": "e66a03eeca609c7426ba7ab8502d41a10b4d740861a6f9728e8ca1e49db8c86a",
+    "agents/tomoshibi.md": "0c1032df80dfc25a4f482b1276965b5318754d95ccde9f24820846d564e49a27",
+    "hooks/check-update.cjs": "9607cc0c51bedcbc123f5ea1d7a492916f29ee1f838846eec64776d5df70bbea",
     "hooks/forge-permissions.cjs": "8de18fe7e6c9ee1751926275a37f4bb68a5a53090d366d2aa44157c106e7857e",
-    "hooks/post-init.cjs": "c82bc76e846708a471acfbbc6839f341be843a3fb8d711e3a0f2733aa3da9b3d",
-    "hooks/post-sprint.cjs": "21099458fcde372f0f40895447ea76318de88d2a857d764f8fbbd0adab3ad74a",
-    "hooks/triage-error.cjs": "f33e4fd67168c437d55d059f67cf893f1d11b59df4c712153a1dfd7d9bb55930",
+    "hooks/post-init.cjs": "b05d65e7192d126733995989998a0b480604e0cc152887e6d7d0807fba3cf70d",
+    "hooks/post-sprint.cjs": "28ddbd2c49d8b746c35d23a90b02362bc684d188159536a971b2d650bb85f3a9",
+    "hooks/triage-error.cjs": "e47fcb81fd0f99b8ecc449b38765cdc6929bde2461b5f1727d26bc31f76bfcfa",
     "hooks/validate-write.cjs": "3ec7bbbb2cc19f22c78da5a9e7b5031066f4b669c76a10c9f8a92a1a48fcea0a",
     "schemas/transitions/bug.json": "27b17da42d1cebffbd4f61ab3dcd432a0017aa71997d548ed80d22c2fc3fad6a",
     "schemas/transitions/sprint.json": "2e0a629396e687b0ca88e1814ac3e35d84533a5d55b25237ab67feddce3c9deb",
     "schemas/transitions/task.json": "4c71849747baa0d585756e57c56325ff6219c078178374e60815dff91e25e3e7",
-    "schemas/enum-catalog.json": "cf6cb391ef4d6ec846f598c65e7e192cc66e017ef88805e14760a61f7893be7e",
+    "schemas/enum-catalog.json": "93dc3d1656d9d638c8eaecc14ce66554b63149a4779869e6536cf0e620e5b37b",
     "tools/verify-integrity.cjs": "3ec3c970dd3d7c3001f8f373bcc40556803eadd2fc2afafb14f1c232cba4cc3f"
   }
 }

package/dist/forge-payload/meta/fragments/tool-discipline.md

@@ -0,0 +1,41 @@
+## Forge Tool Discipline
+
+All forge_* tools wrap local .cjs scripts via direct exec — deterministic, no LLM,
+no agent loop. Use them for all Forge-managed data — never bypass with god tools.
+
+### Data boundaries — off-limits to `read`, `cat`, `bash`, `grep`
+
+These paths contain Forge-managed data. Never access them with generic tools.
+
+| Path | Owned by | Use instead |
+|------|----------|-------------|
+| `.forge/store/**` | Store | `forge_store`, `forge_store_query` |
+| `{paths.engineering}/**/` task/bug/sprint dirs | Artifacts | `forge_artifact read` (covers all 15 artifact types) |
+| `{paths.engineering}/**/INDEX.md` | KB | `forge_store_query` or `forge_collate` |
+| `{paths.engineering}/MASTER_INDEX.md` | KB | `forge_store_query` or `forge_collate` |
+
+`{paths.engineering}` is the project's KB folder name from `.forge/config.json`
+(default: `engineering`). Never hardcode it.
+
+Source files (`.py`, `.ts`, `.js`, etc.), persona `.md`, workflow `.md`, and
+project config outside `.forge/store/` are fine to `read`/`grep` directly.
+
+### Tool routing
+
+- **Store CRUD:** call `forge_store` (named tool). Canonical write is 2-positional:
+  `{command:"write", args:["<entity>","<json>"]}`. The id lives INSIDE the json
+  (e.g. `{"sprintId":"X-S01","title":"...","status":"planning","taskIds":[],"createdAt":"..."}`).
+  DO NOT pass id as a separate arg — `["sprint","X-S01","<json>"]` (3-arg) FAILS.
+- Before writing any record, call `forge_store_template` for the canonical shape and
+  `forge_store_describe` for required fields, status enums, and FK constraints.
+- Use `forge_store_query` (nlp/query/schema) for lookups instead of grepping `.forge/store/`.
+- Use `forge_collate` to refresh the KB; `forge_validate_store` for integrity checks;
+  `forge_config` for project config reads/writes.
+- Use `forge_artifact` to read/write/list phase artifacts (PLAN.md, PROGRESS.md, *-SUMMARY.json).
+  Never construct artifact paths manually — the tool resolves them from entity IDs.
+- Use `forge_verify_apply` after applying edits to confirm changes landed on disk.
+  If `unchanged` is non-empty, re-apply those edits.
+- Never `bash node "$FORGE_ROOT/tools/store-cli.cjs" ...` — use the named MCP tool instead.
+  The tool is schema-validated and shorter.
+- Workflow text saying `forge_store write sprint '<json>'` means: call the MCP tool
+  `forge_store` with that 2-positional shape. Not a shell command.

package/dist/forge-payload/meta/templates/meta-retro.md

@@ -0,0 +1,28 @@
+# Meta-Template: Sprint Retrospective
+
+## Purpose
+
+Defines the structure of the sprint retrospective document — metrics,
+learnings, and improvements.
+
+## Sections
+
+### Required
+- **Sprint Summary** — tasks completed, failed, carried over
+- **Metrics** — plan iterations, code review iterations, time per task
+- **What Went Well** — patterns that worked
+- **What to Improve** — friction points, recurring issues
+- **Knowledge Base Updates** — what was confirmed, added, or removed
+- **Stack Checklist Changes** — items added or pruned
+
+### Optional
+- **Workflow Improvements** — proposed edits to workflow files
+- **Bug Pattern Analysis** — recurring root cause categories
+- **Merge Conflicts** — if parallel mode, what conflicted and why
+- **Recommendations for Next Sprint** — scope, focus, mode
+
+## Generation Instructions
+- Reference the project's sprint artifact paths for data gathering
+- Reference the project's domain docs and stack checklist
+- Include the project's workflow file paths for proposed edits
+- Reference the project's specific tech debt areas