@entelligentsia/forgecli 0.15.0 → 0.19.0

package/dist/forge-payload/meta/workflows/meta-quiz-agent.md

@@ -23,6 +23,8 @@ refactor, a deployment, or a migration step).
 The quiz is short — 5–7 questions drawn directly from the project's own architecture
 and process docs. Vague answers fail. Pass requires specific, factual responses.
 
+<!-- No Iron Laws section: quiz-agent is a utility workflow that makes no store writes and enforces no output contract. Knowledge-check only. It is invoked inline by other workflows, not dispatched as a task phase by the orchestrator. -->
+
 ## Algorithm
 
 ```
@@ -57,6 +59,7 @@ beginning the task.
 
 ---
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template (quiz-agent: no token-reporting or event-emission — inline helper workflow) -->
 ## Generation Instructions
 
 ### Overview
@@ -95,7 +98,7 @@ List the architecture and business-domain docs that cover the question topics.
 Use the actual paths as generated (e.g. `{KB_PATH}/architecture/stack.md`).
 Include `{KB_PATH}/stack-checklist.md` always.
 
-### File structure
+## Template Output Format
 
 ```markdown
 # 🍵 Workflow: Quiz Agent — {Project Name}

package/dist/forge-payload/meta/workflows/meta-retrospective.md

@@ -18,6 +18,13 @@ deps:
 
 Close a sprint by reviewing learnings, updating the knowledge base, and improving workflows.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## Iron Laws
+
+- Never mutate JSON records during retrospective; the store is the source of truth and retrospective flows downstream from it. Retrospective operations read store data and write markdown views only.
+- Read `.forge/personas/architect.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
 ## Algorithm
 
 ```
@@ -49,6 +56,7 @@ Close a sprint by reviewing learnings, updating the knowledge base, and improvin
      going forward)
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/architect.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.

package/dist/forge-payload/meta/workflows/meta-review-implementation.md

@@ -26,6 +26,7 @@ deps:
 
 The Supervisor reviews the Engineer's implementation for correctness, quality, and compliance with the approved plan.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Evaluate the code against the approved PLAN.md and the original task prompt. Do not accept "it works" as a substitute for "it is correct and maintainable."
@@ -34,15 +35,7 @@ The Supervisor reviews the Engineer's implementation for correctness, quality, a
 
 ## Store-Write Verification
 
-Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
-non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
-
-1. Parse the structured error (names the offending field + schema file).
-2. Correct the JSON to satisfy the schema.
-3. Retry. Repeat up to 3 times.
-4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
-
-Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -68,7 +61,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Verify test evidence in PROGRESS.md is authentic and complete
 
 3. Verdict:
-   - Write CODE_REVIEW.md using the format:
+   - Write the code review via forge_artifact:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"code-review", content:"<markdown>" })`
+     Use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: provide numbered, actionable items
      - If Approved: provide any advisory notes
@@ -83,7 +78,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
 6. Emit Summary Sidecar:
-   - Write `REVIEW-IMPL-SUMMARY.json` to the record's directory with the following shape:
+   - Write the review summary via forge_artifact:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"review-impl-summary", content:"<JSON>" })`
+     The JSON shape:
      ```json
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -94,18 +91,13 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      }
      ```
    - Call (task mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} code_review \
-       engineering/sprints/{sprint}/{task}/REVIEW-IMPL-SUMMARY.json
-     ```
+     `forge_store({ command:"set-summary", entity:"task", id:"{taskId}", phase:"code_review" })`
      Or (bug mode):
-     ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} code_review \
-       engineering/bugs/{bugDir}/REVIEW-IMPL-SUMMARY.json
-     ```
+     `forge_store({ command:"set-bug-summary", entity:"bug", id:"{bugId}", phase:"code_review" })`
    - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `review_implementation.md` must follow the strict "Algorithm" block format.

package/dist/forge-payload/meta/workflows/meta-review-plan.md

@@ -22,6 +22,7 @@ deps:
 
 # 🌿 Meta-Workflow: Review Plan
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Evaluate the plan against what the task actually requires, not against what the plan claims to deliver. Plans routinely understate complexity, omit edge cases, or skip security steps. Your job is adversarial review, not approval.
@@ -30,15 +31,7 @@ deps:
 
 ## Store-Write Verification
 
-Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
-non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
-
-1. Parse the structured error (names the offending field + schema file).
-2. Correct the JSON to satisfy the schema.
-3. Retry. Repeat up to 3 times.
-4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
-
-Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -61,7 +54,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Identify missing edge cases or failure modes
 
 3. Verdict:
-   - Write PLAN_REVIEW.md using the format:
+   - Write the plan review via forge_artifact: forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"plan-review", content:"<markdown>" })
+     Use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: provide numbered, actionable items
      - If Approved: provide any advisory notes
@@ -77,7 +71,8 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
 5. Emit Summary Sidecar:
-   - Write `REVIEW-PLAN-SUMMARY.json` to the record's directory with the following shape:
+   - Write the review-plan summary via forge_artifact: forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"review-plan-summary", content:"<JSON>" })
+     The JSON must have the following shape:
      ```json
      {
        "objective":   "<one sentence — what this review assessed>",
@@ -89,18 +84,17 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      ```
    - Call (task mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-summary {taskId} review_plan \
-       engineering/sprints/{sprint}/{task}/REVIEW-PLAN-SUMMARY.json
+     forge_store({ command:"set-summary", entity:"task", id:"{record_id}", phase:"review_plan" })
      ```
      Or (bug mode):
      ```
-     node "$FORGE_ROOT/tools/store-cli.cjs" set-bug-summary {bugId} review_plan \
-       engineering/bugs/{bugDir}/REVIEW-PLAN-SUMMARY.json
+     forge_store({ command:"set-bug-summary", entity:"bug", id:"{record_id}", phase:"review_plan" })
      ```
    - If the set-summary call exits non-zero, fix the sidecar JSON and retry. Do not proceed without a valid summary.
 ```
 
-## Generation Notes
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
 
 - Enforce `**Verdict:** [Approved | Revision Required]` format exactly — orchestrator branches on this.
 - **Markers (required by `/forge:run-task` kickoff shim):** Generated workflow MUST include the "Iron Laws" section, the "Store-Write Verification" section, the literal `forge_store` token, and the `.forge/personas/supervisor.md` persona path. Missing any → kickoff shim refuses to dispatch.

package/dist/forge-payload/meta/workflows/meta-review-sprint-completion.md

@@ -18,6 +18,8 @@ deps:
 
 Verify that all tasks in a sprint have been completed, committed, and validated before closing the sprint.
 
+<!-- No Iron Laws section: review-sprint-completion is a read-only verification workflow. No store writes; no entity state transitions (status update in step 4 is the only write — it matches the standard store-I/O law applied by the generated workflow). Intentional omission per N-CM-5 audit. -->
+
 ## Algorithm
 
 ```
@@ -50,6 +52,7 @@ Verify that all tasks in a sprint have been completed, committed, and validated
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/architect.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.

package/dist/forge-payload/meta/workflows/meta-sprint-intake.md

@@ -18,6 +18,13 @@ deps:
 
 Capture sprint requirements via a structured interview and document them for planning.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
+## Iron Laws
+
+- Capture requirements accurately; do not editorialize or pre-select options on the user's behalf. The product manager documents what the user says, not what the agent thinks is best.
+- Read `.forge/personas/product-manager.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store I/O via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
 ## Algorithm
 
 ```
@@ -53,6 +60,7 @@ Capture sprint requirements via a structured interview and document them for pla
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/product-manager.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.

package/dist/forge-payload/meta/workflows/meta-sprint-plan.md

@@ -72,6 +72,7 @@ Break sprint requirements into a set of estimated tasks with a dependency graph.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance (sprint-plan uses verbatim Anti-Pattern Guard pattern — orchestrator-special case) -->
 ## Anti-Pattern Guard
 
 The generated workflow MUST include the following section verbatim, placed immediately
@@ -87,6 +88,9 @@ after the Purpose heading and before the Algorithm block:
   stop. Return to step 1 of the Algorithm and proceed from there.
 ```
 
+<!-- See _fragments/store-write-verification.md — NOTE: this file uses an intentionally expanded
+     Store-Write Verification variant that explains what counts as a store write in the sprint-plan
+     context (includes direct Write/Edit tool calls). Canonical fragment is reference only. -->
 ## Store-Write Verification
 
 Every write to the Forge store MUST succeed before the agent proceeds to the next
@@ -117,6 +121,7 @@ payload, and all error messages in the escalation.
 **Do NOT** set `FORGE_SKIP_WRITE_VALIDATION=1` to bypass a schema error. That
 environment variable is reserved for emergency operator repair only.
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/architect.md` as its first step (before any other tool use). This replaces the former inline `## Persona` section. The persona identity line (emoji, name, tagline) should be printed to stdout after reading the file.

package/dist/forge-payload/meta/workflows/meta-update-implementation.md

@@ -26,6 +26,7 @@ deps:
 
 Update the implementation of a task based on a "Revision Required" verdict from a review phase.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Address every "Revision Required" item from the review artifact at the correct code location; do not paper over them with comments. If a finding is wrong, escalate rather than ignore.
@@ -34,15 +35,7 @@ Update the implementation of a task based on a "Revision Required" verdict from
 
 ## Store-Write Verification
 
-Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
-non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
-
-1. Parse the structured error (names the offending field + schema file).
-2. Correct the JSON to satisfy the schema.
-3. Retry. Repeat up to 3 times.
-4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
-
-Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -66,6 +59,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `update_implementation.md` must follow the strict "Algorithm" block format.

package/dist/forge-payload/meta/workflows/meta-update-plan.md

@@ -26,6 +26,7 @@ deps:
 
 Update the implementation plan of a task based on a "Revision Required" verdict from the plan review phase.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Address every numbered finding in the review artifact. Do not silently drop items; if a finding is wrong, note the reason in the revised plan rather than ignoring it.
@@ -34,15 +35,7 @@ Update the implementation plan of a task based on a "Revision Required" verdict
 
 ## Store-Write Verification
 
-Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
-non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
-
-1. Parse the structured error (names the offending field + schema file).
-2. Correct the JSON to satisfy the schema.
-3. Retry. Repeat up to 3 times.
-4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
-
-Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -66,6 +59,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **Do NOT emit a phase event yourself.** The orchestrator (or kickoff handler) owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `update_plan.md` must follow the strict "Algorithm" block format.

package/dist/forge-payload/meta/workflows/meta-validate.md

@@ -26,6 +26,7 @@ deps:
 
 The Supervisor performs a final validation of the implementation against the acceptance criteria and the technical spec.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Validate against the acceptance criteria as written; do not soften, expand, or reinterpret them. The validator's job is to catch what the implementer optimistically considered "done".
@@ -34,15 +35,7 @@ The Supervisor performs a final validation of the implementation against the acc
 
 ## Store-Write Verification
 
-Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
-non-zero or the `PreToolUse` write-boundary hook blocks the call (exit 2):
-
-1. Parse the structured error (names the offending field + schema file).
-2. Correct the JSON to satisfy the schema.
-3. Retry. Repeat up to 3 times.
-4. After 3 failures, halt and escalate with original payload, corrected payload, and all error messages.
-
-Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+<!-- See _fragments/store-write-verification.md for the canonical block content -->
 
 ## Algorithm
 
@@ -68,7 +61,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - When re-running the test suite, use the **resolved test command** from `commands.test` in `.forge/config.json` (i.e. `` `${commands.test}` ``, e.g. `.venv/bin/python -m pytest`). Template placeholder: {{TEST_COMMAND}}. Do NOT invoke bare `python` / `python3` — the project interpreter is rarely on `$PATH`.
 
 3. Verdict:
-   - Write VALIDATION_REPORT.md using the format:
+   - Write the validation report via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"validation-report", content:"<markdown>" })`
+     The markdown content must use the format:
      **Verdict:** [Approved | Revision Required]
      - If Revision Required: list the failed criteria and required fixes
      - If Approved: confirm the task is validated
@@ -78,7 +73,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - **Do NOT emit a phase event yourself.** The orchestrator owns event emission — it composes the canonical event from runtime telemetry (model, provider, tokens, wall times) plus the SUMMARY you write in the next step. Subagents that call `store-cli emit` for phase events hallucinate runtime facts (see Plan 11 / Slice 2). Write the SUMMARY and return.
 
 5. Emit Summary Sidecar:
-   - Write `VALIDATION-SUMMARY.json` to the task directory with the following shape:
+   - Write the validation summary via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"validation-summary", content:"<JSON>" })`
+     The JSON content must have the following shape:
      ```json
      {
        "objective":   "<one sentence — what acceptance criteria were validated>",
@@ -99,6 +96,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 ## Friction Emit
 Emit `type:friction` `{workflow:validate, persona:qa-engineer, issue}` per `_fragments/friction-emit.md`.
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `validate_task.md` must follow the strict "Algorithm" block format.

package/dist/forge-payload/schemas/structure-manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.46.1",
-  "generatedAt": "2026-05-22T02:09:22.016Z",
+  "version": "0.51.1",
+  "generatedAt": "2026-05-23T07:58:11.586Z",
   "generatedByTool": "build-manifest.cjs",
   "namespaces": {
     "personas": {
@@ -100,14 +100,18 @@
         "event-emission-schema.md",
         "finalize.md",
         "friction-emit.md",
+        "generation-instructions.md",
+        "iron-laws.md",
         "progress-reporting.md",
-        "store-cli-verbs.md"
+        "store-cli-verbs.md",
+        "store-write-verification.md"
       ]
     },
     "schemas": {
       "logicalKey": "schemas",
       "dir": ".forge/schemas",
       "files": [
+        "_defs/phaseSummary.schema.json",
         "bug.schema.json",
         "collation-state.schema.json",
         "config.schema.json",
@@ -369,9 +373,7 @@
         ]
       },
       "architect_sprint_intake": {
-        "personas": [
-          ".forge/personas/product-manager.md"
-        ],
+        "personas": [],
         "skills": [
           ".forge/skills/architect-skills.md",
           ".forge/skills/generic-skills.md"

package/dist/forge-payload/tools/build-context-pack.cjs

@@ -20,6 +20,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { ensureDir } = require('./lib/fsutil.cjs');
 
 const PACK_LINE_LIMIT = 400;
 
@@ -220,8 +221,8 @@ function buildContextPack({ archDir, existingPackPath }) {
 // ── Atomic write ─────────────────────────────────────────────────────────────
 
 function writeContextPack(pack, outMd, outJson) {
-  fs.mkdirSync(path.dirname(outMd), { recursive: true });
-  fs.mkdirSync(path.dirname(outJson), { recursive: true });
+  ensureDir(path.dirname(outMd));
+  ensureDir(path.dirname(outJson));
 
   // Write markdown
   const tmpMd = outMd + '.tmp';

package/dist/forge-payload/tools/friction-emit.cjs

@@ -24,6 +24,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { ensureDir } = require('./lib/fsutil.cjs');
 
 const REQUIRED = ['workflow', 'persona', 'issue'];
 const OPTIONAL = ['subkind', 'evidence'];
@@ -99,7 +100,7 @@ function main(argv) {
   }
 
   const cacheDir = path.join(process.cwd(), '.forge', 'cache');
-  fs.mkdirSync(cacheDir, { recursive: true });
+  ensureDir(cacheDir);
   const target = path.join(cacheDir, `FRICTION-${args.workflow}.jsonl`);
   fs.appendFileSync(target, `${JSON.stringify(record)}\n`, 'utf8');
   process.stdout.write(`${target}\n`);

package/dist/forge-payload/tools/lib/frontmatter.cjs

@@ -0,0 +1,62 @@
+'use strict';
+// lib/frontmatter.cjs — canonical YAML frontmatter extractor.
+//
+// CRLF POSTURE (canonical, enforced by test suite):
+//   Normalize to LF on read. All \r characters are stripped before processing.
+//   Output (both frontmatter and body) always uses LF-only line endings,
+//   regardless of the source line ending style (LF / CRLF / CR-only / mixed).
+//
+//   Rationale: plugin template files are distributed and consumed across
+//   platforms; LF is the canonical line ending for the forge plugin. Two prior
+//   divergent implementations (build-base-pack.cjs and substitute-placeholders.cjs)
+//   differed in CRLF handling — this module resolves them to a single behavior.
+//
+//   To preserve CRLF on write, the caller must re-introduce \r\n explicitly;
+//   this module does not offer a write path.
+//
+// API:
+//   extractFrontmatter(content: string) → { frontmatter: string|null, body: string }
+//
+//   - frontmatter: the YAML block including both opening and closing ---
+//     delimiters, normalized to LF. null if no valid frontmatter found.
+//   - body: the content after the closing --- delimiter, normalized to LF.
+//     If no frontmatter found, body is the full input (LF-normalized).
+//
+// Opening --- MUST appear at column 0 (no leading whitespace).
+
+/**
+ * Extract YAML frontmatter from content.
+ *
+ * @param {string} content - Raw file content (any line ending style).
+ * @returns {{ frontmatter: string|null, body: string }}
+ */
+function extractFrontmatter(content) {
+  // Normalize all line endings to LF before any processing.
+  // This handles CRLF (\r\n), CR-only (\r), and mixed inputs uniformly.
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  // Opening --- must be at column 0, immediately followed by \n.
+  if (!normalized.startsWith('---\n') && normalized !== '---') {
+    return { frontmatter: null, body: normalized };
+  }
+
+  const lines = normalized.split('\n');
+
+  // Find the closing --- delimiter (must be on its own line, exact match).
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      const frontmatterLines = lines.slice(0, i + 1);
+      const bodyLines = lines.slice(i + 1);
+
+      const frontmatter = frontmatterLines.join('\n') + '\n';
+      const body = bodyLines.join('\n');
+
+      return { frontmatter, body };
+    }
+  }
+
+  // No closing --- found — malformed frontmatter; return full normalized content as body.
+  return { frontmatter: null, body: normalized };
+}
+
+module.exports = { extractFrontmatter };

package/dist/forge-payload/tools/lib/fsutil.cjs

@@ -0,0 +1,61 @@
+'use strict';
+// lib/fsutil.cjs — filesystem utility helpers.
+//
+// DECISION (FORGE-S25-T07, closes T-5):
+//   Extracted from four inline mkdirSync sites across forge plugin tools:
+//   - tools/build-base-pack.cjs (private ensureDir function + 6 call sites)
+//   - tools/friction-emit.cjs (inline fs.mkdirSync)
+//   - tools/build-context-pack.cjs (2x inline fs.mkdirSync)
+//   - tools/build-manifest.cjs (inline fs.mkdirSync)
+//
+// API:
+//   ensureDir(dirPath: string) → void
+//     Creates the directory recursively if it does not exist. Idempotent.
+//
+//   isFile(filePath: string) → boolean
+//     Returns true if the path exists and is a regular file. Never throws.
+//
+//   isDirectory(dirPath: string) → boolean
+//     Returns true if the path exists and is a directory. Never throws.
+
+const fs = require('node:fs');
+
+/**
+ * Create a directory (and all intermediate parents) if it does not exist.
+ * Safe to call on an existing directory — no-op in that case.
+ *
+ * @param {string} dirPath - Absolute or relative directory path.
+ */
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Check whether a path exists and is a regular file.
+ *
+ * @param {string} filePath - Path to test.
+ * @returns {boolean}
+ */
+function isFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Check whether a path exists and is a directory.
+ *
+ * @param {string} dirPath - Path to test.
+ * @returns {boolean}
+ */
+function isDirectory(dirPath) {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { ensureDir, isFile, isDirectory };

package/dist/forge-payload/tools/lib/json-io.cjs

@@ -0,0 +1,43 @@
+'use strict';
+// lib/json-io.cjs — shared JSON read/write primitives.
+//
+// Extracted from FSImpl._readJson / FSImpl._writeJson in tools/store.cjs so
+// any tool or hook can reuse them without taking a dependency on the full
+// store facade.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Read and parse a JSON file.
+ *
+ * @param {string} filePath - absolute or cwd-relative path to the JSON file
+ * @returns {object|null} parsed object, or null if the file does not exist
+ * @throws {SyntaxError} if the file exists but contains invalid JSON (fail-fast)
+ */
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+/**
+ * Write an object to a JSON file with 2-space indentation and a trailing
+ * newline. Creates all parent directories as needed.
+ *
+ * Mirrors FSImpl._writeJson contract exactly so consumers can swap in this
+ * function without behavioural change.
+ *
+ * @param {string} filePath - absolute or cwd-relative path for the output file
+ * @param {object} data     - value to serialise
+ * @returns {object} the same `data` object that was written
+ */
+function writeJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  return data;
+}
+
+module.exports = { readJson, writeJson };