@entelligentsia/forgecli 0.10.1 → 0.11.2

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

@@ -0,0 +1,89 @@
+---
+requirements:
+  reasoning: Medium
+  context: Low
+  speed: High
+deps:
+  personas: [collator]
+  skills: [collator, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: [MASTER_INDEX.md]
+  config_fields: [paths.engineering]
+---
+
+# 🍃 Meta-Workflow: Collate
+
+## Purpose
+
+Regenerate markdown views from the JSON store. This is a deterministic operation — prefer the generated tool, fall back to manual collation.
+
+## Iron Laws
+
+- Collation is a read-and-rewrite of generated markdown. Do not mutate any JSON record under `.forge/store/`; the store is the source of truth and collation flows downstream from it.
+- Read `.forge/personas/collator.md` first; print the persona identity line (emoji, name, tagline) to stdout before any other tool use.
+- All store reads via `forge_store` (or `node "$FORGE_ROOT/tools/store-cli.cjs"`). Never edit `.forge/store/*.json` directly.
+
+## Store-Write Verification
+
+Collation typically writes markdown views, not JSON records. If a remediation
+step does call `forge_store` and the call 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.
+
+## Algorithm
+
+```
+1. Preferred: Run Plugin Tool
+   - Read `paths.forgeRoot` from `.forge/config.json` as `FORGE_ROOT`
+   - Run: `node "$FORGE_ROOT/tools/collate.cjs" [SPRINT_ID]`
+   - If tool succeeds, proceed to Finalize
+
+2. Fallback: Manual Collation
+   - Read `.forge/config.json` for prefix, paths, project description
+   - Read all sprint/task/bug/event JSONs from `.forge/store/`
+   - Generate MASTER_INDEX.md (sprint registry, task registry, bug registry)
+   - Generate per-sprint TIMESHEET.md (from events)
+   - Generate any other configured views
+
+3. Rebuild context pack:
+   - Rebuild the architecture context pack so orchestrators have a fresh summary
+     after any KB updates (architecture docs may have changed during the sprint):
+     ```
+     FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
+     ENGINEERING=$(node "$FORGE_ROOT/tools/manage-config.cjs" get paths.engineering 2>/dev/null || echo engineering)
+     node "$FORGE_ROOT/tools/build-context-pack.cjs" \
+       --arch-dir "$ENGINEERING/architecture" \
+       --out-md .forge/cache/context-pack.md \
+       --out-json .forge/cache/context-pack.json
+     ```
+   - On exit 1 (architecture directory absent), skip silently.
+
+4. Finalize:
+   - **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.
+   - Invoke Tomoshibi via Skill tool to refresh KB and workflow links in agent
+     instruction files:
+     ```
+     Use the Skill tool:
+       skill: "forge:refresh-kb-links"
+     ```
+```
+
+## Generation Instructions
+
+- **Persona Self-Load:** The generated workflow MUST begin by reading `.forge/personas/collator.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.
+- **Workflow Structure:** The generated `collate.md` must follow the strict "Algorithm" block format.
+- **Context Isolation:** Forbid inline execution of large-scale file generation; use the `Agent` tool for sub-tasks.
+- **Token Reporting:** The generated workflow MUST mandate the following before returning:
+  1. Probe session token usage: invoke `/cost` if the host runtime supports it
+     (Claude Code only); on any other runtime treat as unavailable and proceed.
+     Do NOT shell out to a `cost-cli.cjs` — there is no such tool.
+  2. Parse: `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `estimatedCostUSD`.
+  3. Write the usage sidecar via `node "$FORGE_ROOT/tools/store-cli.cjs" emit {sprintId} '{sidecar-json}' --sidecar`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

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

@@ -0,0 +1,93 @@
+---
+requirements:
+  reasoning: Low
+  context: Low
+  speed: High
+audience: subagent
+phase: commit
+context:
+  architecture: false
+  prior_summaries: none
+  persona: summary
+  master_index: false
+  diff_mode: false
+deps:
+  personas: [engineer]
+  skills: [engineer, generic]
+  templates: [PROGRESS_TEMPLATE]
+  sub_workflows: []
+  kb_docs: []
+  config_fields: [commands.test, paths.engineering]
+---
+
+# 🌱 Meta-Workflow: Commit Task
+
+## Purpose
+
+Seal a completed and approved task by committing its artifacts to the VCS and updating the store.
+
+## Iron Laws
+
+- Commit only the artifacts produced for this task; do not sweep unrelated working-tree changes into the commit. The commit boundary mirrors the task boundary.
+- Read `.forge/personas/engineer.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.
+
+## 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.
+
+## Algorithm
+
+```
+
+0. Pre-flight Gate Check:
+   - Resolve FORGE_ROOT (`node -e "console.log(require('./.forge/config.json').paths.forgeRoot)"`).
+   - **Entity-mode resolution:** read the kickoff arguments. `--task {id}` → `entity_kind = "task"`, `record_id = {id}`. `--bug {id}` → `entity_kind = "bug"`, `record_id = {id}`. All store-cli calls below substitute `{entity_kind}` and `{record_id}` for the literal "task"/{taskId} placeholders.
+   - Run: `node "$FORGE_ROOT/tools/preflight-gate.cjs" --phase commit --{entity_kind} {record_id}`
+   - Exit 1 (gate failed) → print stderr and HALT. Do not proceed; do not attempt to produce the artifact.
+   - Exit 2 (misconfiguration) → print stderr and HALT.
+   - Exit 0 → continue.
+
+1. Load Context:
+   - Read the record manifest (task or bug, per entity_kind).
+   - Read ARCHITECT_APPROVAL.md from the record's artifact directory:
+     - Task mode: `engineering/sprints/{sprint}/{task}/ARCHITECT_APPROVAL.md`
+     - Bug mode:  `engineering/bugs/{bugDir}/ARCHITECT_APPROVAL.md`
+
+2. Staging:
+   - Stage all record-related artifacts and the code changes:
+     - Task mode: PLAN.md, PROGRESS.md, REVIEW files, ARCHITECT_APPROVAL.md, and the implementation diff under the task directory plus modified source files.
+     - Bug mode: BUG_FIX_PLAN.md (Path B only — absent on Path A), TRIAGE.md, PROGRESS.md, REVIEW files, ARCHITECT_APPROVAL.md, the regression test, and the implementation diff.
+   - Verify no unrelated files are staged.
+
+3. Commit:
+   - Create a commit with a message following project conventions.
+   - Include the record ID in the commit message: task ID for task mode, bug ID for bug mode.
+   - Append a `Co-authored-by:` trailer crediting the AI assistant that actually ran the session. Resolve the identity from the host runtime: on Claude Code use `Co-authored-by: Claude <noreply@anthropic.com>`; on pi / Ollama / any other runtime use `Co-authored-by: {modelId} <noreply@{provider}.ai>` derived from the session's `provider` and `modelId` (e.g. `Co-authored-by: glm-5.1:cloud <noreply@ollama.ai>`); if neither is resolvable, omit the trailer rather than guess. Do NOT hardcode `Claude Opus 4.6 <noreply@anthropic.com>` — that literal is rejected as a regression of forge#82 (commits authored under the wrong model).
+   - Let git's configured `user.name` / `user.email` own the commit author; never pass `--author` to override it.
+
+4. Store Finalization:
+   - Transitions:
+     - **Task mode** — `approved → committed` (terminal): `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status committed`
+     - **Bug mode** — `in-progress → fixed` (terminal): `node "$FORGE_ROOT/tools/store-cli.cjs" update-status bug {bugId} status fixed`. This is the ONLY phase in the bug pipeline that writes `bug.status` post-triage (see `meta-fix-bug.md § Iron Laws #2`). Do NOT write `approved` or `verified` — those values are vestigial enum members slated for removal.
+
+5. Finalize:
+   - **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.
+```
+
+## Generation Instructions
+
+- **Workflow Structure:** The generated `commit_task.md` must follow the strict "Algorithm" block format.
+- **Context Isolation:** Forbid inline execution of commit operations; use the `Agent` tool for sub-tasks.
+- **Project Specifics:**
+  - Embed project's commit message conventions.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`.
+- **Event Emission:** Ensure the "complete" event includes the `eventId` passed by the orchestrator.

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

@@ -0,0 +1,286 @@
+---
+requirements:
+  reasoning: High
+  context: High
+  speed: Low
+audience: orchestrator-only
+deps:
+  personas: [engineer]
+  skills: [engineer, generic]
+  templates: []
+  sub_workflows: []
+  kb_docs: []
+  config_fields: [paths.engineering, paths.forgeRoot]
+---
+
+# Meta-Workflow: Enhancement Agent
+
+## Iron Laws
+
+- Orchestrator-only: this workflow runs with full tool access in the orchestrator session. NEVER delegate it to a subagent.
+- Read `.forge/personas/engineer.md` first; print the persona identity line 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.
+- Phase 1 only touches `{{KEY}}` token text; never rewrite persona prose, algorithm steps, or role definitions.
+
+## 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.
+2. Correct the JSON to satisfy the schema.
+3. Retry. Repeat up to 3 times. After 3 failures, halt and escalate.
+
+Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
+
+## Purpose
+
+Autonomously improve the installed `.forge/` structural elements by:
+- **Phase 1** (auto-apply, post-init): Fill any `{{KEY}}` placeholders left unsubstituted during init.
+- **Phase 2** (propose-diffs, post-sprint): Scan sprint artifacts and friction events; propose persona/skill enrichments for user review.
+- **Phase 3** (drift detection, on-demand): Compare full codebase state against structural-element knowledge; propose targeted patches.
+
+This workflow is `audience: orchestrator-only` — it reads store events and proposes writes to
+`.forge/` structural elements. It must run with full tool access. It is never delegated to a
+subagent.
+
+## Note on `.forge/enhancement-proposals/` directory
+
+Phases 2 and 3 write proposal artifacts to `.forge/enhancement-proposals/`. This directory is
+distinct from `.forge/enhancements/` (FR-007, S14 scope). This workflow uses `mkdir -p` before
+writing the first proposal artifact to avoid assuming the directory exists. No conflict with S14.
+
+## Confidence gating (Phase 1)
+
+A key substitution is **high-confidence** when there is exactly one unambiguous signal source
+(e.g., `scripts.test` in `package.json` is the sole candidate for `{{TEST_COMMAND}}`). It is
+**low-confidence** when multiple candidates exist or no signal is found. Only high-confidence
+fills are applied automatically. Low-confidence keys are listed in the Phase 1 report and left
+unsubstituted for the user to fill manually.
+
+## Phase routing
+
+Receive the phase flag from the command invocation:
+
+| Flag | Mode |
+|------|------|
+| `--phase 1` or `--auto` | Auto-apply: placeholder fills only |
+| `--phase 2` | Propose-diffs: sprint artifact + friction scan |
+| `--phase 3` | Drift detection: full codebase vs structural-element comparison |
+
+Default to `--phase 3` if no phase flag is given.
+
+---
+
+## Step 0 — Resolve roots
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+Read `.forge/config.json`. Resolve:
+- `PROJECT_ROOT` = current working directory (absolute).
+- `ENGINEERING_PATH` = `paths.engineering` from config (default `engineering`).
+
+---
+
+## Phase 1 — Auto-apply placeholder fills
+
+### When to run
+
+Invoked by T09 post-init hook (`--auto`) or manually via `/forge:enhance --phase 1`.
+
+### Algorithm
+
+1. **Scan structural elements** for `{{KEY}}` patterns:
+   ```sh
+   grep -r '{{' "$PROJECT_ROOT/.forge/personas/" "$PROJECT_ROOT/.forge/skills/" \
+        "$PROJECT_ROOT/.forge/workflows/" "$PROJECT_ROOT/.forge/templates/" \
+        --include="*.md" -l 2>/dev/null
+   ```
+   Collect each unique `{{KEY}}` token found.
+
+2. **Skip runtime passthrough keys** — keys used at runtime (e.g., `{{TASK_ID}}`, `{{SPRINT_ID}}`,
+   `{{ARGUMENTS}}`) are intentional and must not be substituted. Read
+   `$FORGE_ROOT/tools/substitute-placeholders.cjs` to identify the RUNTIME_PASSTHROUGH_KEYS list.
+   Exclude them from the fill candidates.
+
+3. **Derive values from codebase signals** — for each remaining `{{KEY}}`, attempt to derive a
+   value with high confidence:
+
+   | Key | Signal source |
+   |-----|--------------|
+   | `{{STACK_SUMMARY}}` | `package.json` dependencies field (list top-level frameworks); or dominant file extension survey |
+   | `{{BRANCHING_CONVENTION}}` | `git branch -a` output pattern or `.git/config` |
+   | `{{TEST_COMMAND}}` | `package.json` → `scripts.test` |
+   | `{{BUILD_COMMAND}}` | `package.json` → `scripts.build` |
+   | `{{ENTITY_MODEL}}` | Scan source for ORM model files or type definitions |
+   | `{{KEY_DIRECTORIES}}` | Top-level directory listing (exclude `.git`, `node_modules`, `.forge`) |
+   | `{{IMPACT_CATEGORIES}}` | Derive from project type (web app → UI/API/DB/Infra; library → API/Docs/Tests) |
+
+   Any key without a single unambiguous signal → mark as **low-confidence** (skip auto-fill).
+
+4. **Apply high-confidence fills** — for each high-confidence key, perform in-place substitution
+   in all structural element files that contain the key. Use `substitute-placeholders.cjs` if it
+   supports a targeted single-key mode; otherwise apply the substitution directly with a read/write
+   cycle per file.
+
+   **Minimal modification principle**: Phase 1 only touches `{{KEY}}` token text. It never rewrites
+   persona prose, algorithm steps, or role definitions.
+
+5. **Update `project-context.json`** — write the newly discovered values into
+   `$PROJECT_ROOT/.forge/project-context.json` so that future invocations of
+   `substitute-placeholders.cjs` use the derived values.
+
+6. **Snapshot gate** — if at least one fill was applied:
+   ```sh
+   node "$FORGE_ROOT/tools/manage-versions.cjs" add-snapshot \
+     --source post-init \
+     --enhanced-elements "<comma-separated list of relative .forge/ paths that were modified>"
+   ```
+   If no fills were applied, skip the snapshot call entirely.
+
+7. **Emit enhancement event** to the store:
+   ```sh
+   node "$FORGE_ROOT/tools/store-cli.cjs" emit enhancement '{
+     "eventId": "<ISO timestamp slug>_enhance_phase1",
+     "taskId": "enhancement",
+     "sprintId": "enhancement",
+     "role": "enhancement-agent",
+     "action": "enhancement-completed",
+     "phase": "post-init",
+     "iteration": 1,
+     "notes": "{\"phase\":1,\"fillCount\":<N>,\"snapshotCreated\":<true|false>}"
+   }'
+   ```
+
+8. **Report**:
+   ```
+   ## Phase 1 Enhancement Complete
+
+   Fills applied: N key(s) — {{KEY1}}, {{KEY2}}, ...
+   Uncertain keys (not filled): M — {{KEY3}}, ...  (manual intervention needed)
+   Snapshot: [written as snap-{index}] | [skipped — no fills]
+   ```
+
+---
+
+## Phase 2 — Propose enrichment diffs (post-sprint)
+
+### When to run
+
+Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
+
+### Algorithm
+
+1. **Collect friction events**:
+   ```sh
+   node -e "
+   const fs = require('fs'), path = require('path');
+   const eventsDir = '.forge/store/events';
+   const allFiles = fs.readdirSync(eventsDir, { withFileTypes: true })
+     .flatMap(d => d.isDirectory()
+       ? fs.readdirSync(path.join(eventsDir, d.name)).map(f => path.join(eventsDir, d.name, f))
+       : [path.join(eventsDir, d.name)]
+     )
+     .filter(f => f.endsWith('.json'));
+   const friction = allFiles
+     .map(f => { try { return JSON.parse(fs.readFileSync(f,'utf8')); } catch { return null; } })
+     .filter(e => e && e.type === 'friction');
+   console.log(JSON.stringify(friction));
+   "
+   ```
+
+2. **Deduplicate** friction events by composite key `workflow + persona + issue`. Keep the most
+   recent occurrence of each composite key.
+
+3. **Read most recent completed sprint** from `.forge/store/sprints/` (status `done` or
+   `retrospective-done`), sorted by completion date. Read its task records from
+   `.forge/store/tasks/` filtered by the sprint ID.
+
+4. **Synthesize enrichment proposals** — for each friction event:
+   - Identify which persona or skill file it references.
+   - Propose a targeted addition: e.g., "architect persona lacks routing pattern knowledge —
+     suggest adding `{{KB_PATH}}/routing.md` reference to deps.kb_docs."
+   - For large committed file sets (> 5 files in the sprint), also check whether
+     `engineer-skills.md` or `architect-skills.md` should reference new patterns.
+
+5. **Write proposal artifact**:
+   ```sh
+   mkdir -p "$PROJECT_ROOT/.forge/enhancement-proposals"
+   ```
+   Write to `$PROJECT_ROOT/.forge/enhancement-proposals/phase2-<timestamp>.md`. Format:
+   one section per proposed change, with a fenced diff block showing before/after text.
+
+6. **Present to user**:
+   ```
+   ## Phase 2 Enhancement Proposals
+
+   N change(s) proposed — review: .forge/enhancement-proposals/phase2-<timestamp>.md
+
+   [A] Apply all  [r] Review individually  [n] Skip
+   ```
+
+7. **On approval** — for each approved change:
+   - Apply the edit in-place.
+   - Call `manage-versions.cjs add-snapshot --source post-sprint:<SPRINT_ID> --enhanced-elements <list>`.
+
+8. **Emit enhancement event** (same schema as Phase 1, with `"phase": "post-sprint"`).
+
+9. **Report**: N changes applied, M skipped, snapshot written or skipped.
+
+---
+
+## Phase 3 — Drift detection (on-demand / delegated from calibrate)
+
+### When to run
+
+Invoked by `/forge:enhance --phase 3` (default when no phase given), or delegated by
+`/forge:calibrate` after its Step 4 drift categorization.
+
+### Algorithm
+
+1. **Read codebase state** from `$PROJECT_ROOT/.forge/project-context.json`:
+   key directories, entities, commands, stack summary, test command, build command.
+
+2. **Read all structural elements** from `.forge/personas/`, `.forge/skills/`,
+   `.forge/workflows/`, `.forge/templates/`.
+
+3. **Compare**: for each structural element, verify:
+   - It correctly references known entities and key directories.
+   - It uses valid `{{KB_PATH}}` references (paths that exist in `engineering/`).
+   - Its `deps.kb_docs` list includes docs referenced in its body.
+
+4. **Read friction events** (same collection as Phase 2 Step 1).
+
+5. **Read `calibrationBaseline`** from `$PROJECT_ROOT/.forge/config.json` to understand what
+   was last confirmed correct.
+
+6. **Write drift report**:
+   ```sh
+   mkdir -p "$PROJECT_ROOT/.forge/enhancement-proposals"
+   ```
+   Write to `$PROJECT_ROOT/.forge/enhancement-proposals/phase3-<timestamp>.md`.
+
+7. **Present to user**:
+   ```
+   ## Phase 3 Drift Report
+
+   N discrepancy(ies) found — review: .forge/enhancement-proposals/phase3-<timestamp>.md
+
+   [A] Apply all  [r] Review individually  [n] Skip
+   ```
+
+8. **On approval** — apply changes and call `manage-versions.cjs add-snapshot --source on-demand`.
+
+9. **Emit enhancement event** (`"phase": "on-demand"`).
+
+10. **Report**: N changes applied, snapshot written or skipped.
+
+---
+
+## On error
+
+If any step fails unexpectedly, describe what went wrong and offer:
+
+> "This looks like a Forge bug. Would you like to file a report? Run `/forge:report-bug`."