@entelligentsia/forgecli 0.11.3 → 0.15.0

package/dist/forge-payload/.base-pack/workflows/enhance.md

@@ -38,6 +38,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
@@ -179,11 +213,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.
@@ -192,19 +255,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**:
    ```

package/dist/forge-payload/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "forge",
-  "version": "0.44.8",
+  "version": "0.46.1",
   "description": "Self-enhancing AI software development lifecycle \u2014 generates project-specific SDLC instances from meta-definitions",
   "license": "MIT",
   "author": {

package/dist/forge-payload/.schemas/event.schema.json

@@ -61,7 +61,9 @@
 
         "bug-triaged", "fix-planned", "fix-review-passed", "fix-review-failed",
         "fix-implemented", "fix-code-review-passed", "fix-code-review-failed",
-        "fix-approved", "bug-committed"
+        "fix-approved", "bug-committed",
+
+        "skill_usage"
       ]
     },
     "workflow": { "type": "string" },
@@ -89,7 +91,13 @@
     "haltedAtTaskId":       { "type": "string" },
     "lastError":            { "type": "string" },
     "waveCount":            { "type": "integer", "minimum": 1 },
-    "maxConcurrency":       { "type": "integer", "minimum": 1 }
+    "maxConcurrency":       { "type": "integer", "minimum": 1 },
+
+    "skillId":                { "type": "string", "minLength": 1 },
+    "retrieved":              { "type": "boolean" },
+    "used":                   { "type": "boolean" },
+    "tool_call_success_rate": { "type": "number", "minimum": 0, "maximum": 1 },
+    "retrieval_score":        { "type": "number", "minimum": 0, "maximum": 1 }
   },
   "additionalProperties": false,
   "allOf": [
@@ -161,6 +169,16 @@
           "lastError":         { "type": "string" }
         }
       }
+    },
+    {
+      "if": { "properties": { "type": { "const": "skill_usage" } }, "required": ["type"] },
+      "then": {
+        "required": [
+          "eventId", "sprintId", "taskId",
+          "skillId", "retrieved", "used",
+          "tool_call_success_rate", "retrieval_score"
+        ]
+      }
     }
   ]
 }

package/dist/forge-payload/.schemas/migrations.json

@@ -1,4 +1,100 @@
 {
+  "0.46.0": {
+    "version": "0.46.1",
+    "date": "2026-05-22",
+    "notes": "build: regenerate base-pack/workflows/enhance.md from meta sources to ship the FORGE-S24 SKILL-CURATION Phase 2 pipeline. The 0.45.1–0.45.7 entries declared `workflows:enhance` in their `regenerate` lists, but the meta→base-pack derivation (node tools/build-base-pack.cjs) was not re-run during the sprint, so the installable workflow stayed at the pre-S24 algorithm and downstream projects migrating to 0.46.0 received a stale workflow that lacked queue-drain (step 1a), recurrence scoring, delete-candidate detection (step 5b), compression gate (step 5b.5), and the LLM-judge step (step 5c). This patch bump regenerates the base-pack copy (init/base-pack/workflows/enhance.md — 280→600 lines, 20 S24 markers landed) and forces a re-copy on any project sitting at 0.46.0 by declaring `workflows:enhance` here. No plugin source change beyond the regenerated workflow file. Additive, non-breaking.",
+    "regenerate": ["workflows:enhance"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.7": {
+    "version": "0.46.0",
+    "date": "2026-05-22",
+    "notes": "chore: FORGE-S24 SKILL-CURATION sprint completion — gated rollout marker (FORGE-S24-T12). No plugin source change in this bump; the seven preceding entries (0.45.1 → 0.45.7) carry the actual SKILL-CURATION machinery: `skill_usage` event variant (T01, 0.45.1), proposal op classification (T02, 0.45.2), recurrence scoring (T04, 0.45.3), delete-candidate detection (T05, 0.45.4), LLM-judge rubric (T03, 0.45.5), compression gate (T06, 0.45.6), and queue-drain (T07, 0.45.7). T12 lands the gated-rollout contract on the forge-cli side via `forgeCli.skillCuration.enabled` (default OFF) — the four forge-cli modules (T08 skill-retriever, T09 skill-usage-tracker, T10 skill-curator-subagent, T11 friction-emit) no-op at entry when the flag is off, so a flag-off run is byte-identical to pre-FORGE-S24 behaviour. This plugin-side minor bump (0.45.7 → 0.46.0) is the convergent terminal marker for the sprint: it signals to operators running `/forge:update` that the full SKILL-CURATION pipeline has shipped end-to-end, and pairs with the forge-cli 0.13.4 → 0.14.0 bump that lands the rollout flag. No regeneration is required (no manifest entry change, no workflow change, no schema change in this bump alone — those landed in 0.45.1–0.45.7). Operators who want to enable the pipeline must (1) upgrade forge-cli to 0.14.0+ AND (2) set `forgeCli.skillCuration.enabled: true` in their project config at `<cwd>/.pi/forge-cli/config.json` (or the env override `FORGE_CLI_SKILL_CURATION_ENABLED=1` for one-shot operator use). Until both conditions hold, the new event variants and friction subkinds remain emitter-silent — the plugin schema continues to accept them on receipt, so a delayed forge-cli upgrade is non-blocking. Additive, non-breaking.",
+    "regenerate": [],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.6": {
+    "version": "0.45.7",
+    "date": "2026-05-22",
+    "notes": "feat: queue drain at sprint close — per-task curator → batched review (FORGE-S24-T07). Adds `forge/tools/queue-drain.cjs` exporting `bodyHash(body)` (sha256 hex digest, UTF-8), `dedupeKey(proposal)` (`<op>|<target_path>|<sha256(diff_body)>` composite), `dedupeProposals(proposals)` (first-seen-wins, no-mutation), `queuePathFor({queueRoot, sprintId, taskId, ts})` (canonical `.forge/enhancement-proposals/queue/<sprintId>/<taskId>-<ts>.json` path), `appendToQueue({queueRoot, sprintId, taskId, ts, proposals})` (writes one file per curator run; throws if path exists — append-only invariant per AC1), and `drainQueue({queueRoot, sprintId})` (returns `{proposals, files, errors}` after deduping the sprint sub-dir; empty-safe when queue missing per AC5; skips malformed JSON and reports them via `errors`; deterministic lexicographic file ordering ⇒ chronological because of the ts suffix). Per-task curators (T10) append proposals to the queue throughout the sprint without collision (AC2 — distinct ts per call); Phase 2 reads the queue once at sprint close, dedupes by `{op, target_path, body-hash}` (AC3), and merges the queued proposals with the friction-synthesised ones, then feeds a SINGLE batched array through recurrence (T04) → delete-candidate detection (T05) → compression gate (T06) → judge (T03) — one prompt per sprint, not one per task (AC4, paper §3.2.1 grouped reward). `meta/workflows/meta-enhance.md` Phase 2 gains step 1a (drain queue) and step-5 merge sub-block; the zero-input guard now checks both friction events AND queued proposals before exiting cleanly with `frictionCount:0,queuedCount:0`. The drain is read-only — Phase 2 never deletes queue files; operators triage them during retrospective. Test-first per Iron Law 2: `queue-drain.test.cjs` (19 cases — exports surface, bodyHash sha256 contract + empty-body digest + collision contract, dedupeKey AC3 composite + field-sensitivity, dedupeProposals dedup + order-preservation + no-mutation + empty + non-array, queuePathFor AC1 canonical layout + input validation x3, appendToQueue AC1 fresh-file write + AC2 no-collision + append-only refusal, drainQueue AC5 empty/missing safety + AC3 multi-file dedup merge + AC4 single-batch output + sprint scoping + input validation x2 + malformed-JSON resilience) landed before the helper. Pure helpers; fs-touching helpers are `appendToQueue` and `drainQueue` only. Full suite 1437/1437 (was 1418; +19). Additive, non-breaking.",
+    "regenerate": ["tools:queue-drain", "workflows:enhance"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.5": {
+    "version": "0.45.6",
+    "date": "2026-05-22",
+    "notes": "feat: compression gate — reject >20% growth without 3+ frictions (FORGE-S24-T06). Adds `forge/tools/compression-gate.cjs` exporting `GROWTH_THRESHOLD` (0.20), `MIN_SUPPORTING_FRICTIONS` (3), `evaluateGrowth({currentBody, newBody}) -> {currentBytes, newBytes, growthRatio}`, `evaluateProposal({proposal, currentBody, newBody, supportingFrictionCount}) -> {admit, reason, growthRatio, currentBytes, newBytes, supportingFrictionCount, threshold, minSupportingFrictions, op}`, and `filterProposals({proposals, currentBodyFor, newBodyFor, supportingFrictionCountFor}) -> {admitted, rejected}`. The gate runs in `meta/workflows/meta-enhance.md` Phase 2 as new step 5b.5 BEFORE the LLM judge (5c) — cheap deterministic filter first. Only `update_skill` proposals are gated; `insert_skill` and `delete_skill` pass through unconditionally (insert bloat is the judge's `body_under_2kb` axis; delete only shrinks). Growth is measured byte-wise via `Buffer.byteLength(body, 'utf8')` on the new body that would land after applying the proposal's diff. Threshold comparison is strict (>0.20) so ties at exactly 20% admit. Default supporting friction count = `proposal.sourceFrictionIds.length`; the caller may override via `supportingFrictionCountFor(proposal)` when the policy is to count frictions citing the same skill across the sprint. Updates on an empty current body yield `growthRatio: Infinity` and the friction-support rule still applies; shrinks (negative growth) admit unconditionally. Rejected proposals are persisted to the same `phase2-<timestamp>-rejections.json` sibling that the T03 judge writes, with reason `compression_gate_growth_unsupported` and the full evaluation record alongside the original proposal — every drop (gate or judge) stays traceable. Closes the unbounded-growth failure mode of SkillOS — pasting pages of trajectory copy-paste to 'patch' a friction now requires real recurrence evidence. Test-first per Iron Law 2: `compression-gate.test.cjs` (25 cases — GROWTH_THRESHOLD/MIN_SUPPORTING_FRICTIONS constants, evaluateGrowth shape, UTF-8 multibyte byte counting, empty-current-body Infinity ratio, AC1 0-friction rejection, AC2 3-friction admission, 2-friction insufficiency, AC5 exact-20% strict admission, under-threshold admission, sourceFrictionIds fallback, shrink admission, AC4 insert_skill/delete_skill pass-through, input validation x5, filterProposals AC6 ordering/partition, empty input, no-mutation invariant, callback contracts, supportingFrictionCountFor override) landed before the helper. Pure module; no fs access; no LLM call. Full suite 1418/1418 (was 1393; +25). Additive, non-breaking.",
+    "regenerate": ["tools:compression-gate", "workflows:enhance"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.4": {
+    "version": "0.45.5",
+    "date": "2026-05-22",
+    "notes": "feat: LLM-judge step in Phase 2 — Sonnet rubric, drop <3/5 (FORGE-S24-T03). Adds `forge/tools/judge-proposal.cjs` exporting `RUBRIC_AXES` (frozen 5-axis tuple: specificity, when_not_to_use, no_trajectory_copy_paste, body_under_2kb, cites_friction), `scoreProposal(proposal) -> { axes, average }` (deterministic per-axis 0..5 scorer), and `decideJudgement({ axes }) -> { verdict, average, axes, reason }` (pure aggregator: verdict === 'drop' iff average < 3, strict; ties at 3.0 keep). The rubric is single-sourced in this helper — Sonnet's role is to apply the same axes and emit scores that the helper then validates and aggregates; in the absence of an LLM call the deterministic scorer is the fallback. `decideJudgement` fails loud on missing or out-of-range axes (RangeError) so a malformed score sheet never silently coerces into a verdict. `meta/workflows/meta-enhance.md` Phase 2 gains step 5c calling `scoreProposal` + `decideJudgement` for every proposal between delete-candidate detection (5b) and artifact write (6); kept proposals continue to step 6, dropped proposals are persisted to a sibling `phase2-<timestamp>-rejections.json` carrying the original proposal alongside `{ verdict, average, axes, reason }` so every rejection is traceable for retro review (AC3). Per-axis heuristics: specificity scores deep paths, named (non-generic) skill files, non-trivial rationales, and recurrence trails; when_not_to_use checks for the literal phrase; no_trajectory_copy_paste flags long verbatim runs or unbroken non-whitespace blocks >= 400 bytes; body_under_2kb gates on `Buffer.byteLength(diff_body,'utf8') <= 2048`; cites_friction rewards `sourceFrictionIds.length` >= 1, boosting for multi-citation and recurrence. Consumes recurrence data from T04 in the specificity and cites_friction axes — proposals that recurred across multiple tasks score higher. Test-first per Iron Law 2: `judge-proposal.test.cjs` (13 cases — rubric-axes shape, 5/5 keep fixture, 1/5 drop fixture, body byte boundary at exactly 2048, zero-citation suppression, phrase-presence binary, AC6 explicit 2.8/5 drop fixture, keep + drop end-to-end decisions, exact-3.0 boundary keeps, missing-axis RangeError, out-of-range RangeError) landed before the helper. Pure module; no fs access; no LLM call. Full suite 1393/1393 (was 1380; +13). Additive, non-breaking.",
+    "regenerate": ["tools:judge-proposal", "workflows:enhance"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.3": {
+    "version": "0.45.4",
+    "date": "2026-05-22",
+    "notes": "feat: delete-candidate detection — 3-sprint zero-use (FORGE-S24-T05). Adds `forge/tools/delete-candidate-detector.cjs` exporting `scanZeroUse({events, sprintOrder, windowSize})` and `buildDeleteProposals({events, sprintOrder, windowSize, targetPathFor})`. The detector scans `skill_usage` events across the trailing `windowSize` (default 3) sprints; any skill with at least one in-window observation AND zero `retrieved` AND zero `used` qualifies as a delete candidate. Skills with zero in-window observations are explicitly NOT proposed — that case is indistinguishable from a newly-added skill that hasn't been loaded yet. `meta/workflows/meta-enhance.md` Phase 2 gains step 5b calling `buildDeleteProposals` between recurrence annotation (step 5a) and artifact write (step 6). Each delete proposal carries `op: 'delete_skill'`, `target_path` resolved via the supplied `targetPathFor(skillId)` callback, a diff body and rationale that name the cold skill and the observed sprints, `sourceFrictionIds: []` (usage-derived, not friction-derived), `window_size`, `window_sprint_ids`, plus neutral `recurrence_count: 1` and `recurrence_task_ids: []` so the proposal shape stays uniform with the rest of the Phase 2 array. Carry-over caveat documented in the workflow: the trailing-3-sprint window only becomes meaningful once 3 sprints have elapsed since `skill_usage` emission landed in T01 (0.45.1); short-history runs produce advisory rather than authoritative deletes. This is the only mechanism by which the skill repository shrinks, completing the three-op classification rollout from T02 (insert/update were already in play). Test-first per Iron Law 2: `delete-candidate-detector.test.cjs` (16 cases — three-sprint zero-use baseline, retrieved=true disqualification, used=true disqualification, trailing-window guard against pre-window usage, default windowSize 3, configurable windowSize, never-observed-in-window suppression, empty events, friction-event filtering, short-history carry-over case, no-mutation invariant, multi-skill output, deterministic ordering, callback contract, plus AC restatement cases) landed before the detector. Pure module; no fs access. Full suite 1380/1380 (was 1364; +16). Additive, non-breaking.",
+    "regenerate": ["tools:delete-candidate-detector", "workflows:enhance"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.2": {
+    "version": "0.45.3",
+    "date": "2026-05-22",
+    "notes": "feat: cross-task replay scoring — recurrence boost (FORGE-S24-T04). Adds `forge/tools/replay-scoring.cjs` exporting `computeRecurrence({events, subkind, skillId, fromTaskId, taskOrder})` and `annotateProposals(proposals, frictionEvents, taskOrder)`. For each Phase 2 enrichment proposal synthesised from a friction event at task `t`, the annotator scans tasks `t+1..N` in the same sprint for friction events matching the same `(subkind, evidence.skillId)` pair and stamps `recurrence_count` (>= 1, includes the origin task) and `recurrence_task_ids` (taskOrder-sorted) onto the proposal. Forward-only scan: earlier tasks before `fromTaskId` are excluded. Proposals without resolvable `sourceFrictionIds` (eventId not in the friction set, or the resolved event lacks subkind/evidence.skillId) receive a neutral `recurrence_count: 1` and empty `recurrence_task_ids: []`. `meta/workflows/meta-enhance.md` Phase 2 gains step 5a calling `annotateProposals` between synthesis (step 5) and artifact write (step 6); the step 5 contract is tightened to require `sourceFrictionIds` to carry every contributing eventId so the recurrence scan can resolve provenance. `forge/schemas/proposal.schema.json` gains optional `recurrence_count` (integer minimum:1) and `recurrence_task_ids` (array of strings) properties — additive only, both fields are optional, `additionalProperties: false` continues to reject unknown keys. Feeds T03 (judge) so specificity scoring can boost frictions that recurred across multiple tasks. Test-first per Iron Law 2: `replay-scoring.test.cjs` (11 cases — AC3 three-task recurrence, single-task baseline, forward-only-direction guard, subkind mismatch rejection, skillId mismatch rejection, intra-task dedup, fromTaskId-outside-taskOrder fallback, missing-evidence guard, full annotateProposals happy path, unresolved-provenance neutral case, no-mutation invariant) landed before the helper. Full suite 1364/1364 (was 1353; +11). Additive, non-breaking.",
+    "regenerate": ["tools:replay-scoring", "schemas:proposal", "workflows:enhance"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.1": {
+    "version": "0.45.2",
+    "date": "2026-05-22",
+    "notes": "feat: Phase 2 proposal op classification (FORGE-S24-T02). Adds `forge/schemas/proposal.schema.json` and `forge/tools/proposal-normalize.cjs`. The new schema enumerates `op` ∈ {insert_skill, update_skill, delete_skill} with required `target_path` + `diff_body`; `additionalProperties: false` rejects unknown fields. `meta/workflows/meta-enhance.md` Phase 2 (steps 5–6) now requires every enrichment proposal to carry this triplet and writes a machine-readable `phase2-<timestamp>.json` alongside the existing markdown artifact. Back-compat: legacy proposals without `op` are normalised to `insert_skill` via `proposal-normalize.cjs:normaliseProposal()` — downstream consumers route through the helper explicitly so normalisation is auditable. Foundation for T03 (judge), T05 (delete-candidate detection), T06 (compression gate), T07 (queue drain). Test-first per Iron Law 2: `proposal-schema.test.cjs` (6 cases including missing-op rejection, unknown-op rejection, additionalProperties:false, and the legacy normalisation contract) landed before the schema. Full suite 1353/1353. Additive, non-breaking.",
+    "regenerate": ["schemas:proposal"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.45.0": {
+    "version": "0.45.1",
+    "date": "2026-05-22",
+    "notes": "feat: event.schema.json — new `skill_usage` event variant (FORGE-S24-T01, plan 08 Phase B). Adds `skill_usage` to the `type` enum and a conditional allOf branch requiring {skillId, retrieved, used, tool_call_success_rate, retrieval_score}. Top-level numeric properties (`tool_call_success_rate`, `retrieval_score`) carry [0,1] declarative bounds; `skillId` is `minLength: 1`. The root `additionalProperties: false` gate continues to reject unknown fields on every variant. Foundation for Sprint S24 SKILL-CURATION: T02 emits, T04 retrieval-score correlation, T05 delete-candidate detection, T08 replay scoring all consume records of this type. No code path change to validate-store.cjs — the existing validateRecord() handles the new allOf branch via the same machinery used for friction / sprint-complete / sprint-halted variants. Additive, non-breaking: existing event records remain valid. Note on target version: TASK_PROMPT requested v0.45.0 but that tag already shipped (snapshot-replay change); bumping to 0.45.1 is the minimum forward step.",
+    "regenerate": ["schemas:event"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.44.10": {
+    "version": "0.45.0",
+    "date": "2026-05-21",
+    "notes": "feat: Approach A — snapshot replay (forge#107). manage-versions gains a new replay subcommand that restores user-enhanced files captured by /forge:enhance Phase 2 snapshots after /forge:regenerate writes fresh base-pack content. Fulfills layer 3 of the composition contract (Working Artifact = base + snapshot + user_enhancements) declared at manage-versions.cjs:13. regenerate.md updated to invoke replay per category (personas, skills, workflows, templates) between subagent generation and manifest record. Overlay semantics: user-enhanced files retain captured content; later snapshots win on collision. Pairs with v0.44.10 (forge#108 archive-path fix) which made layer 2 functional in the first place.",
+    "regenerate": ["commands:regenerate", "tools:manage-versions"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.44.9": {
+    "version": "0.44.10",
+    "date": "2026-05-21",
+    "notes": "fix: manage-versions add-snapshot now archives files correctly when --enhanced-elements paths include the .forge/ prefix (forge#108). Previously, every archive directory has been created empty since basePackVersion 0.43.3 — layer 2 of the composition contract was silently a no-op. Tool now strips a leading .forge/ from each element path before joining; both .forge/-relative (e.g. personas/X.md) and project-root-relative (.forge/personas/X.md) forms accepted. Unblocks forge#107 (Approach A — snapshot replay). Pure tool fix.",
+    "regenerate": ["tools:manage-versions"],
+    "breaking": false,
+    "manual": []
+  },
+  "0.44.8": {
+    "version": "0.44.9",
+    "date": "2026-05-21",
+    "notes": "fix: /forge:regenerate personas + skills silently overwrote manual modifications (forge#106 / FORGE-BUG-037). Pre-write generation-manifest check added to both single-file and full-rebuild paths in commands/regenerate.md, mirroring the workflows + templates pattern. Closes asymmetric modification-detection across the four structural-element categories. Markdown-only fix.",
+    "regenerate": ["commands:regenerate"],
+    "breaking": false,
+    "manual": []
+  },
   "0.44.7": {
     "version": "0.44.8",
     "date": "2026-05-21",

package/dist/forge-payload/.schemas/proposal.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forge/proposal.schema.json",
+  "title": "EnhancementProposal",
+  "description": "A single Phase 2 enrichment proposal emitted by /forge:enhance. Each record carries an op classification (insert/update/delete a skill artifact), the target file path, and a diff body. Foundation for the T03 judge, T05 delete detection, T06 compression gate, and T07 queue drain.",
+  "type": "object",
+  "required": ["op", "target_path", "diff_body"],
+  "properties": {
+    "proposalId":         { "type": "string", "minLength": 1 },
+    "op": {
+      "type": "string",
+      "enum": ["insert_skill", "update_skill", "delete_skill"],
+      "description": "Three-op classification: insert a new skill artifact, update an existing one, or delete an existing one."
+    },
+    "target_path": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repository-relative path to the artifact being inserted, updated, or deleted (e.g. forge/skills/engineer-skills.md)."
+    },
+    "diff_body": {
+      "type": "string",
+      "description": "Unified-diff body or full file body for inserts. For delete_skill this may be empty — the op + target_path is sufficient."
+    },
+    "rationale":          { "type": "string" },
+    "sourceFrictionIds":  { "type": "array", "items": { "type": "string" } },
+    "generated_at":       { "type": "string", "format": "date-time" },
+    "sprintId":           { "type": "string" },
+    "recurrence_count": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "FORGE-S24-T04 — count of distinct tasks within the same sprint that emitted a matching (subkind, evidence.skillId) friction event, including the originating task. Always >= 1."
+    },
+    "recurrence_task_ids": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "FORGE-S24-T04 — taskOrder-sorted list of task IDs that contributed to recurrence_count. Empty when the originating friction event cannot be resolved from sourceFrictionIds."
+    }
+  },
+  "additionalProperties": false
+}