@entelligentsia/forgecli 0.11.3 → 0.19.0

package/dist/forge-payload/meta/workflows/_fragments/iron-laws.md

@@ -0,0 +1,72 @@
+# Fragment: Iron Laws — Structural Template Guide
+
+> **Pattern:** This fragment is a template guide, not a verbatim include.  
+> Each workflow's `## Iron Laws` section is kept inline because the opening law and
+> persona load line are workflow-specific. Use this guide to ensure every `## Iron
+> Laws` section has the required structure.
+>
+> **Distinction from verbatim fragments:** CM-2 (Iron Laws structural duplication)
+> and CM-3 (persona-load line repetition) are closed-as-documented, not
+> closed-as-deduplicated. The prose stays inline; this guide documents the canonical
+> structure so future authors follow the same pattern. See `doc/decisions/meta-fragment-includes.md`.
+
+---
+
+## Required structure
+
+An Iron Laws section MUST contain exactly these three bullets in this order:
+
+```markdown
+## Iron Laws
+
+- {WORKFLOW_SPECIFIC_LAW}
+- Read `.forge/personas/{persona}.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.
+```
+
+### Slot definitions
+
+**`{WORKFLOW_SPECIFIC_LAW}`** — first bullet; unique per workflow. Describes the single most
+important constraint of *this workflow* (e.g., "Commit only the artifacts produced for this
+task", "Approve only when the implementation is consistent with the project's architecture",
+"Follow the plan exactly"). Never generic; never copied from another workflow.
+
+**persona load line** — second bullet; constant prose with `{persona}` replaced by the
+workflow's `deps.personas[0]` value (e.g., `engineer`, `architect`, `supervisor`,
+`product-manager`, `qa-engineer`).
+
+**store-I/O law** — third bullet; verbatim identical across all workflows.
+
+---
+
+## Orchestrator-special case
+
+`meta-fix-bug.md` and `meta-orchestrate.md` have Iron Laws that *defer* to
+`generic-skills.md § Orchestrator Iron Laws` via a prose comment, then add
+workflow-specific supplemental laws. This is intentional and cannot be collapsed
+into the standard three-bullet structure.
+
+---
+
+## Intentional omissions
+
+Some workflows have no `## Iron Laws` section by design:
+
+- `meta-quiz-agent.md` — utility workflow; no store writes; no output contract.
+- `meta-review-sprint-completion.md` — read-only verification; no state transitions.
+
+Intentional omissions are documented with an inline comment before the `## Algorithm`
+heading:
+```html
+<!-- No Iron Laws section: {reason} -->
+```
+
+---
+
+## Byte-budget note
+
+The Iron Laws section (three bullets) contributes approximately 280–320 bytes to a
+workflow file. Byte budgets in `phase-frontmatter.test.cjs` must be set ≥ the actual
+byte count of the file (with ≤ 512 bytes headroom). Lowering budgets after removing
+content is always safe; raising budgets requires written justification in the commit
+body naming the new content added.

package/dist/forge-payload/meta/workflows/_fragments/store-cli-verbs.md

@@ -26,10 +26,20 @@ Notes for subagents:
   natural-language lookup.
 - **`update-status`** is the ONLY supported task/bug status mutation path.
   Do not `write` a task back with a new `status` field; the FSM is enforced
-  by `update-status`.
+  by `update-status`. Syntax requires the field keyword `status` as the third
+  argument — four args total:
+  `node "$FORGE_ROOT/tools/store-cli.cjs" update-status task {taskId} status {value}`
+  The three-arg form `update-status task {taskId} {value}` is WRONG and will
+  error. Always include `status` between the id and the value.
 - **`emit`** appends an event. There is no `append-event` / `add-event`.
 - **`set-summary`** / **`set-bug-summary`** write summary sidecars referenced
   from the entity record. Do not inline summaries into the entity via `write`.
+- **Artifact I/O:** Use `forge_artifact` for ALL phase artifact reads and writes
+  (PLAN.md, PROGRESS.md, *-SUMMARY.json, CODE_REVIEW.md, etc.). Never construct
+  artifact file paths manually — the tool resolves paths from entity IDs and
+  validates JSON summary schemas on write. After writing a summary JSON via
+  `forge_artifact`, link it to the store record via `forge_store set-summary`.
+  Example: `forge_artifact({ command:"write", entity:"task", entityId:"{taskId}", artifact:"progress", content:"..." })`
 - If you need a verb not on this list, run
   `node "$FORGE_ROOT/tools/store-cli.cjs" --help` before improvising.
 - If you supply an unknown verb, entity type, enum value, or field name,

package/dist/forge-payload/meta/workflows/_fragments/store-write-verification.md

@@ -0,0 +1,11 @@
+## 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.

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

@@ -26,6 +26,7 @@ deps:
 
 The Architect gives final sign-off on a completed task after Supervisor approval. This is the last gate before commit.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## Iron Laws
 
 - Approve only when the implementation is consistent with the project's architecture and the deployment posture is understood. Architectural sign-off is not a rubber stamp — it is the last point at which cross-cutting concerns can be caught cheaply.
@@ -34,15 +35,7 @@ The Architect gives final sign-off on a completed task after Supervisor approval
 
 ## 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
 
@@ -67,7 +60,9 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - Assess operational impact (deployment changes, migrations)
 
 3. Sign Off:
-   - Write ARCHITECT_APPROVAL.md containing:
+   - Write the architect approval via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"architect-approval", content:"<markdown>" })`
+     The markdown content must contain:
      - A canonical verdict line for human readers, on its own line, in this exact form:
        ```
        **Verdict:** [Approved | Revision Required]
@@ -84,7 +79,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.
 
 5. Emit Summary Sidecar:
-   - Write `APPROVE-SUMMARY.json` to the record's directory with the following shape:
+   - Write the approve summary via:
+     `forge_artifact({ command:"write", entity:"{entity_kind}", entityId:"{record_id}", artifact:"approve-summary", content:"<JSON>" })`
+     The JSON content must have the following shape:
      ```json
      {
        "objective":   "<one sentence — what this approval covered>",
@@ -107,6 +104,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
    - In bug mode, if the set-bug-summary call exits non-zero, fix the sidecar JSON and retry. Do not return without a valid summary — the downstream commit gate has no other way to read the approval verdict.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `approve_task.md` must follow the strict "Algorithm" block format.

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

@@ -18,12 +18,17 @@ deps:
 
 Regenerate markdown views from the JSON store. This is a deterministic operation — prefer the generated tool, fall back to manual collation.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## 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.
+- Do NOT call `set-summary` or `set-bug-summary` from within collation. The collator writes markdown views and a `WRITEBACK-SUMMARY.json` disk file only. Calling `set-summary` mutates the JSON store and violates Iron Law 1 (the store is the source of truth; collation flows downstream from it, not into it). The orchestrator reads `WRITEBACK-SUMMARY.json` directly — no store write is needed.
 
+<!-- See _fragments/store-write-verification.md — NOTE: this file uses an intentionally modified
+     Store-Write Verification variant: collation typically writes markdown views (not JSON records),
+     so the preamble explains when `forge_store` calls apply. Canonical fragment is reference only. -->
 ## Store-Write Verification
 
 Collation typically writes markdown views, not JSON records. If a remediation
@@ -67,6 +72,16 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
 
 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.
+   - Write `WRITEBACK-SUMMARY.json` to the sprint directory (`engineering/sprints/{sprintId}/`) with the following shape:
+     ```json
+     {
+       "objective":   "<one sentence — what views were regenerated>",
+       "key_changes": ["<up to 6 bullets — which files were written>"],
+       "verdict":     "n/a",
+       "written_at":  "<current ISO 8601 timestamp>"
+     }
+     ```
+     The orchestrator reads this file directly to compose the collation event narrative. Do NOT call `set-summary` to register it — that would mutate the store in violation of Iron Law 1.
    - Invoke Tomoshibi via Skill tool to refresh KB and workflow links in agent
      instruction files:
      ```
@@ -75,6 +90,7 @@ Never set `FORGE_SKIP_WRITE_VALIDATION=1` — operator-only emergency switch.
      ```
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## 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.

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

@@ -26,6 +26,7 @@ deps:
 
 Seal a completed and approved task by committing its artifacts to the VCS and updating the store.
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## 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.
@@ -34,15 +35,7 @@ Seal a completed and approved task by committing its artifacts to the VCS and up
 
 ## 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
 
@@ -83,6 +76,7 @@ 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.
 ```
 
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
 ## Generation Instructions
 
 - **Workflow Structure:** The generated `commit_task.md` must follow the strict "Algorithm" block format.

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

@@ -15,13 +15,17 @@ deps:
 
 # Meta-Workflow: Enhancement Agent
 
+<!-- See _fragments/iron-laws.md for Iron Laws section structure guidance -->
 ## 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.
+- 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.
 - Phase 1 only touches `{{KEY}}` token text; never rewrite persona prose, algorithm steps, or role definitions.
 
+<!-- See _fragments/store-write-verification.md — NOTE: this file uses an intentionally abbreviated
+     Store-Write Verification variant (4-line condensed form for orchestrator-only workflow).
+     Canonical fragment is reference only. -->
 ## Store-Write Verification
 
 Every `forge_store` write MUST succeed before advancing. If `store-cli` exits
@@ -50,6 +54,40 @@ Phases 2 and 3 write proposal artifacts to `.forge/enhancement-proposals/`. This
 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.
 
+### Sub-directory: `.forge/enhancement-proposals/queue/`
+
+FORGE-S24-T07 introduces a project-local **enhancement queue** at
+`.forge/enhancement-proposals/queue/<sprintId>/<taskId>-<ts>.json` — one file per
+per-task curator run (T10). The queue is **append-only**: each curator run writes
+a fresh file (the ISO compact `<ts>` suffix differentiates writes; nothing is
+overwritten). Phase 2 drains the queue at sprint close, dedupes by
+`{op, target_path, sha256(diff_body)}`, and feeds the merged batch into the
+existing recurrence → delete-candidate → compression-gate → judge pipeline.
+The result: **one batched review prompt per sprint, not one per task** (paper
+§3.2.1 grouped reward). The drain is read-only — Phase 2 never deletes queue
+files; operators triage them during retrospective if needed.
+
+**Per-task curator (T10) write contract.** A curator MUST write via
+`forge/tools/queue-drain.cjs` to preserve the append-only invariant:
+
+```sh
+node -e "
+const { appendToQueue } = require('./forge/tools/queue-drain.cjs');
+appendToQueue({
+  queueRoot: '.forge/enhancement-proposals/queue',
+  sprintId:  process.env.FORGE_SPRINT_ID,
+  taskId:    process.env.FORGE_TASK_ID,
+  ts:        new Date().toISOString().replace(/[-:]|\\.\\d{3}/g, ''),
+  proposals: PROPOSALS_ARRAY,
+});
+"
+```
+
+`appendToQueue` throws if the exact file path already exists; curators MUST
+choose a fresh `ts` per run rather than overwriting. The drain is empty-safe:
+if no curator ever wrote (queue dir missing) or no files exist in the sprint
+sub-dir, Phase 2 reports "no proposals" and exits cleanly (AC5).
+
 ## Confidence gating (Phase 1)
 
 A key substitution is **high-confidence** when there is exactly one unambiguous signal source
@@ -191,11 +229,40 @@ Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
    "
    ```
 
-2. **Zero-friction guard**: If the friction event list is empty, print:
+1a. **Drain enhancement queue** (FORGE-S24-T07) — read per-task curator
+   proposals from `.forge/enhancement-proposals/queue/<sprintId>/`, dedupe by
+   `{op, target_path, sha256(diff_body)}`, and produce a `queuedProposals`
+   array that joins the synthesised proposals from step 5. This is what makes
+   the review **batched** rather than per-task (paper §3.2.1):
+
+   ```sh
+   node -e "
+   const { drainQueue } = require('./forge/tools/queue-drain.cjs');
+   const drained = drainQueue({
+     queueRoot: '.forge/enhancement-proposals/queue',
+     sprintId:  process.env.FORGE_SPRINT_ID,
+   });
+   process.stdout.write(JSON.stringify(drained));
+   "
+   ```
+
+   Contract (per `forge/tools/queue-drain.cjs`):
+   - Returns `{ proposals: [...], files: [...], errors: [...] }`. `proposals`
+     is the deduped union of every per-task curator file in the sprint
+     sub-dir. `files` is the lexicographic-sorted list of source paths (used
+     by step 6 to log provenance). `errors` carries any malformed JSON files
+     skipped during read — log them, do not abort.
+   - Empty / missing queue → empty result. The drain never throws on absent
+     queue dir (first-run or no curators registered yet, AC5).
+   - The drain is read-only. Operators are responsible for queue triage
+     after sprint close.
+
+2. **Zero-input guard**: If both the friction event list AND `queuedProposals`
+   are empty, print:
    ```
-   No friction events queued for the active sprint — nothing to enhance.
+   No friction events or queued proposals for the active sprint — nothing to enhance.
    ```
-   and exit Phase 2 immediately (skip steps 3–9; emit the enhancement event with `"notes": "{\"phase\":2,\"frictionCount\":0}"`). Do not create `.forge/enhancement-proposals/` when there are no proposals.
+   and exit Phase 2 immediately (skip steps 3–9; emit the enhancement event with `"notes": "{\"phase\":2,\"frictionCount\":0,\"queuedCount\":0}"`). Do not create `.forge/enhancement-proposals/` when there are no proposals.
 
 3. **Deduplicate** friction events by composite key `workflow + persona + issue`. Keep the most
    recent occurrence of each composite key.
@@ -204,19 +271,276 @@ Invoked by T09 post-sprint hook or manually via `/forge:enhance --phase 2`.
    `retrospective-done`), sorted by completion date. Read its task records from
    `.forge/store/tasks/` filtered by the sprint ID.
 
-5. **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. **Synthesize enrichment proposals** — for each friction event, classify the proposed
+   change into exactly one of three ops (see `forge/schemas/proposal.schema.json`):
+
+   | `op`            | When to use                                                                 |
+   |-----------------|-----------------------------------------------------------------------------|
+   | `insert_skill`  | A new skill / persona / kb_docs reference is needed; target file does not yet carry the guidance. |
+   | `update_skill`  | An existing skill or persona file needs revised guidance — e.g., add a routing pattern reference to `deps.kb_docs`, replace a stale instruction. |
+   | `delete_skill`  | A skill is unused, redundant, or stale (`skill_unused` / `skill_redundant` / `skill_stale` friction subkinds); target file or section should be removed. |
+
+   For each proposal capture **at minimum** the schema-required triplet
+   `{op, target_path, diff_body}` plus optional `rationale` and `sourceFrictionIds`.
+   `sourceFrictionIds` MUST carry the `eventId` of every friction event that
+   contributed to the proposal — the next step depends on it to resolve the
+   originating task for the recurrence scan.
+   For large committed file sets (> 5 files in the sprint), also check whether
+   `engineer-skills.md` or `architect-skills.md` should be updated (`update_skill`).
+   The op classification is the foundation for the downstream judge (T03),
+   delete-candidate detection (T05), compression gate (T06), and queue drain (T07).
+
+   **Merge with queued proposals (T07).** Concatenate the synthesised
+   proposals built in this step with the `queuedProposals` array from
+   step 1a, then dedupe the combined array with the same key the drain
+   uses (`{op, target_path, sha256(diff_body)}`) so a friction-synthesised
+   proposal that happens to be byte-identical to a curator-queued one
+   collapses. Use:
+
+   ```sh
+   node -e "
+   const { dedupeProposals } = require('./forge/tools/queue-drain.cjs');
+   // synthesised = proposals built above from friction events.
+   // queued      = drained.proposals from step 1a.
+   const merged = dedupeProposals(synthesised.concat(queued));
+   process.stdout.write(JSON.stringify(merged));
+   "
+   ```
+
+   The merged array is what feeds steps 5a (recurrence) → 5b (delete
+   candidates) → 5b.5 (compression gate) → 5c (judge) — a single batched
+   pipeline, never one per task (AC4).
+
+5a. **Cross-task replay scoring (recurrence boost)** — before writing the
+   artifact, stamp each proposal with `recurrence_count` and
+   `recurrence_task_ids` so the T03 judge can score "this friction recurred
+   across N tasks" rather than treating every signal as a singleton:
+
+   ```sh
+   node -e "
+   const { annotateProposals } = require('./forge/tools/replay-scoring.cjs');
+   // friction = deduped friction events from step 3, each carrying eventId,
+   //            taskId, subkind, evidence.skillId (orchestrator-stamped).
+   // proposals = array built in step 5.
+   // taskOrder = task IDs of the most-recent sprint sorted by completion
+   //             order — same source as step 4.
+   const annotated = annotateProposals(proposals, friction, taskOrder);
+   process.stdout.write(JSON.stringify(annotated));
+   "
+   ```
+
+   Contract (per `forge/tools/replay-scoring.cjs`):
+   - `recurrence_count` is the number of distinct tasks (origin task + later
+     tasks in `taskOrder`) whose friction events match the proposal's
+     originating `(subkind, evidence.skillId)` pair. Always `>= 1`.
+   - `recurrence_task_ids` is the `taskOrder`-sorted list of those task IDs.
+   - Proposals whose `sourceFrictionIds` cannot be resolved (no matching
+     `eventId` in the friction set, or the resolved event lacks
+     `subkind`/`evidence.skillId`) receive `recurrence_count: 1` and an empty
+     `recurrence_task_ids: []` — neutral signal, not silent failure.
+   - The annotator returns new proposal objects; the input array is not
+     mutated.
+
+5b. **Delete-candidate detection (3-sprint zero-use)** — scan `skill_usage`
+   events across the trailing 3 sprints and emit a `delete_skill` proposal
+   for every skill with zero retrieval AND zero invocation across the
+   window. This is the only mechanism by which the skill repository shrinks:
+
+   ```sh
+   node -e "
+   const { buildDeleteProposals } = require('./forge/tools/delete-candidate-detector.cjs');
+   // skillUsageEvents = all events with type === 'skill_usage' across the
+   //                    sprints in scope (collected via the same Step 1
+   //                    walker, filtered by type instead of friction).
+   // sprintOrder      = sprint IDs sorted by completion order (oldest →
+   //                    newest). The detector takes the trailing windowSize
+   //                    entries.
+   // windowSize       = 3 by default; configurable. Defined as the trailing
+   //                    N sprints of sprintOrder.
+   // targetPathFor    = (skillId) => the on-disk path of the skill file to
+   //                    delete. Workflow chooses the mapping convention.
+   const deletes = buildDeleteProposals({
+     events:        skillUsageEvents,
+     sprintOrder,
+     windowSize:    3,
+     targetPathFor: (skillId) => 'forge/skills/' + skillId + '.md',
+   });
+   process.stdout.write(JSON.stringify(deletes));
+   "
+   ```
+
+   Append the resulting `delete_skill` proposals to the proposal array from
+   step 5/5a before step 6. Each delete proposal already carries
+   `recurrence_count: 1` and `recurrence_task_ids: []` (the annotator from
+   step 5a is for friction-derived proposals; delete candidates come from
+   usage telemetry, not friction, so recurrence is neutral by construction).
+
+5b.5. **Compression gate (reject >20% growth without 3+ frictions)** — a cheap
+   deterministic filter that runs BEFORE the LLM judge (step 5c). Any
+   `update_skill` proposal that would grow the target file by more than 20%
+   (byte-wise, UTF-8) must be backed by at least 3 supporting friction events;
+   otherwise it is rejected here and never reaches the judge. `insert_skill`
+   and `delete_skill` proposals pass through unconditionally — insert growth
+   is handled by the judge's `body_under_2kb` axis and delete only shrinks.
+
+   Why a pre-judge gate? Judging is expensive. Unbounded skill-body growth is
+   the classic SkillOS failure mode — pasting pages of trajectory copy-paste to
+   "patch" a friction. It is cheap to detect deterministically and wasteful to
+   ask the judge to rule on.
+
+   ```sh
+   node -e "
+   const fs = require('node:fs');
+   const path = require('node:path');
+   const { filterProposals } = require('./forge/tools/compression-gate.cjs');
+   // proposals = post-5b array (synthesis + recurrence + delete-candidates).
+   // PROJECT_ROOT resolves the target_path; forge plugin source is the source
+   // of truth for current bodies. The workflow renders the diff via its own
+   // applyProposalDiff helper (left abstract here — the gate is body-agnostic).
+   const projectRoot = process.env.PROJECT_ROOT;
+   const result = filterProposals({
+     proposals,
+     currentBodyFor: (p) => {
+       const abs = path.join(projectRoot, p.target_path);
+       try { return fs.readFileSync(abs, 'utf8'); }
+       catch (e) { return ''; } // insert_skill or missing file → empty
+     },
+     newBodyFor: (p) => applyProposalDiff(currentBodyFor(p), p),
+     // Default supporting count = proposal.sourceFrictionIds.length. Override
+     // if the policy is 'count frictions citing the same skill across the
+     // sprint' rather than 'count citations on the proposal itself'.
+   });
+   const proposalsAfterGate = result.admitted;
+   const compressionRejections = result.rejected; // [{ proposal, ...evaluation }]
+   process.stdout.write(JSON.stringify({ kept: proposalsAfterGate, rejected: compressionRejections }));
+   "
+   ```
+
+   **Logging gate rejections.** Append every rejection from this step to the
+   same `phase2-<timestamp>-rejections.json` sibling that step 5c uses, with
+   the rejection record carrying `{ proposal, admit: false,
+   reason: 'compression_gate_growth_unsupported', growthRatio, currentBytes,
+   newBytes, supportingFrictionCount, threshold, minSupportingFrictions }`.
+   This keeps every drop — gate or judge — traceable in one place.
+
+   Contract (per `forge/tools/compression-gate.cjs`):
+   - `GROWTH_THRESHOLD === 0.20`; comparison is **strict** (`> 0.20`). A
+     proposal at exactly 20% growth admits without friction support.
+   - `MIN_SUPPORTING_FRICTIONS === 3`. Two or fewer citations is not enough.
+   - An update on an empty current body yields `growthRatio: Infinity`; the
+     friction-support rule still applies.
+   - Negative growth (shrink) admits unconditionally.
+   - `filterProposals` partitions the input array preserving order; the
+     output `rejected` array carries the structured evaluation alongside the
+     original proposal.
+
+5c. **LLM-judge gate (Sonnet rubric, drop <3/5)** — score every proposal
+   against the 5-axis rubric and drop low-signal proposals before
+   presentation. The rubric is single-sourced in
+   `forge/tools/judge-proposal.cjs`:
+
+   | Axis (0..5) | What it measures |
+   |---|---|
+   | `specificity` | Names a concrete target_path beyond `forge/skills/*` floor; carries a non-trivial rationale; recurrence trail boosts. |
+   | `when_not_to_use` | Body contains a literal "When NOT to use" section. |
+   | `no_trajectory_copy_paste` | No long verbatim runs or unbroken non-whitespace blocks (>= 400 bytes) that suggest pasted trajectory log. |
+   | `body_under_2kb` | `Buffer.byteLength(diff_body, 'utf8') <= 2048`. |
+   | `cites_friction` | Proposal carries at least one `sourceFrictionIds` entry; multiple citations or recurrence boost the score. |
+
+   For each proposal in the post-5b array, the workflow asks Sonnet to
+   apply the rubric and emit per-axis 0..5 scores; in the absence of an
+   LLM call, the deterministic `scoreProposal(proposal)` helper in
+   `judge-proposal.cjs` is used as both the fallback scorer and the
+   validation contract for Sonnet-produced scores (single source of truth
+   for the rubric definition).
+
+   ```sh
+   node -e "
+   const {
+     scoreProposal,
+     decideJudgement,
+   } = require('./forge/tools/judge-proposal.cjs');
+   // proposals = post-5b array of proposal records.
+   const judged = proposals.map((p) => {
+     const scored   = scoreProposal(p);
+     const decision = decideJudgement(scored);
+     return { proposal: p, ...decision };
+   });
+   const kept    = judged.filter((j) => j.verdict === 'keep').map((j) => j.proposal);
+   const dropped = judged.filter((j) => j.verdict === 'drop');
+   process.stdout.write(JSON.stringify({ kept, dropped }));
+   "
+   ```
+
+   Contract (per `forge/tools/judge-proposal.cjs`):
+   - `scoreProposal(proposal)` returns `{ axes, average }` with `axes`
+     keyed by every entry in `RUBRIC_AXES` and `average` rounded to one
+     decimal place.
+   - `decideJudgement({ axes })` returns
+     `{ verdict, average, axes, reason }`. `verdict === 'drop'` iff
+     `average < 3` (strictly less than); ties at exactly 3.0 keep.
+   - `decideJudgement` fails loud on missing or out-of-range axes — the
+     judge will NOT silently coerce a malformed score sheet into a verdict.
+
+   **Logging dropped proposals (AC3).** Every rejection MUST be persisted
+   for retro review. Replace the proposal array passed to step 6 with the
+   `kept` list, and append the `dropped` list to
+   `$PROJECT_ROOT/.forge/enhancement-proposals/phase2-<timestamp>-rejections.json`
+   as a sibling artifact. Each rejection record carries the original
+   proposal alongside `{ verdict: 'drop', average, axes, reason }`. The
+   markdown summary written in step 6 SHOULD include a "Dropped (N)" line
+   pointing at the rejections file when N > 0.
+
+   **Carry-over caveat** — the rubric is deterministic; Sonnet's role is
+   to add semantic judgement to axes that the heuristic scorer
+   approximates (specificity in particular). When Sonnet is invoked, its
+   per-axis scores MUST be validated against the 0..5 range via the same
+   `validateAxes` invariant `decideJudgement` enforces. Operators
+   investigating an unexpected drop should consult the per-axis trace in
+   `reason`.
+
+   Contract (per `forge/tools/delete-candidate-detector.cjs`):
+   - A skill qualifies for deletion iff it has at least one `skill_usage`
+     event inside the trailing window AND every in-window observation has
+     `retrieved === false` AND `used === false`. Any single `retrieved: true`
+     or `used: true` event disqualifies the skill.
+   - Skills with zero observations in the window are NOT proposed — this
+     case is indistinguishable from a newly-added skill that hasn't been
+     loaded yet, so silence is the safe default.
+   - Each proposal carries `window_size`, `window_sprint_ids`, and a
+     `sourceFrictionIds: []` (delete candidates derive from usage telemetry,
+     not friction).
+
+   **Carry-over caveat** — the trailing-3-sprint window is only meaningful
+   once 3 sprints have actually elapsed since `skill_usage` event emission
+   landed in FORGE-S24-T01 (forge 0.45.1). During the carry-over period the
+   detector still runs over whatever sprintOrder it receives, but the
+   signal is noisier: a skill flagged after only one or two sprints of
+   history may simply be new or temporarily idle. Operators should treat
+   delete proposals from short-history runs as advisory until the full
+   window is populated.
 
 6. **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.
+   Write **two** outputs for each Phase 2 run (using the `kept` list from
+   step 5c — dropped proposals are persisted separately to the
+   `phase2-<timestamp>-rejections.json` sibling described in step 5c):
+
+   - `phase2-<timestamp>.md` — human-readable markdown, one section per proposal,
+     showing op + target_path + a fenced diff block.
+   - `phase2-<timestamp>.json` — machine-readable array of proposal records, each
+     conforming to `forge/schemas/proposal.schema.json` (required keys: `op`,
+     `target_path`, `diff_body`; `op` ∈ {insert_skill, update_skill, delete_skill};
+     optional `recurrence_count` ≥ 1 and `recurrence_task_ids` populated by step 5a).
+
+   **Back-compat on read** — pre-0.45.2 proposal records lack `op`. Downstream
+   consumers MUST route legacy records through
+   `forge/tools/proposal-normalize.cjs:normaliseProposal()` which defaults the
+   missing `op` to `insert_skill` (the only op the prior insert-biased flow
+   could produce). Do NOT silently coerce — call the helper explicitly so the
+   normalisation is auditable.
 
 7. **Present to user**:
    ```
@@ -290,3 +614,14 @@ Invoked by `/forge:enhance --phase 3` (default when no phase given), or delegate
 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`."
+
+<!-- See _fragments/generation-instructions.md for Generation Instructions template -->
+## Generation Instructions
+
+- **Workflow Structure:** This is an `audience: orchestrator-only` workflow (not a subagent-targeted phase workflow). The generated `enhance.md` must follow the strict multi-phase Algorithm block format (Phase 1 / Phase 2 / Phase 3 routing).
+- **Context Isolation:** All proposal application steps that modify `.forge/` structural elements must run in the orchestrator session (full tool access required). Do NOT delegate to a subagent.
+- **Project Specifics:**
+  - Reference the project's `commands.test` and `commands.build` from `.forge/config.json` when verifying stack-command fills in Phase 1.
+  - Reference `forge/tools/queue-drain.cjs`, `forge/tools/replay-scoring.cjs`, `forge/tools/compression-gate.cjs`, `forge/tools/judge-proposal.cjs`, and `forge/tools/delete-candidate-detector.cjs` by their resolved `$FORGE_ROOT` paths.
+- **Token Reporting:** See `_fragments/finalize.md` — wire via `file_ref:`. Enhancement runs are orchestrator-only and may be long-running; token reporting is advisory (no orchestrator composes a phase event for this workflow).
+- **Event Emission:** Emit enhancement events directly via `store-cli emit` (orchestrator-only exception to the "do NOT emit yourself" rule — this workflow IS the orchestrator for enhancement).