@aperant/framework 0.16.0 → 0.19.0

package/dist/plugin/skills/apt-produce/SKILL.md

@@ -0,0 +1,606 @@
+---
+name: apt:produce
+description: "Outer loop (M1+M2) — freeze an outcome as an immutable setpoint, project a crash-safe roadmap from the append-only event log, one wake tick per invocation, gate `done` behind a cross-family oracle + a held-out blind probe."
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: x-produce
+when_to_use: "You have ONE outcome to drive over time and want a frozen acceptance setpoint plus a crash-safe, event-sourced roadmap that a host wake-beat re-reads from disk one tick at a time — no daemon, no in-skill polling loop. M2 unlocks `done` behind a two-gate adjudication: the visible oracle (verify-proof `approved` + an independent cross-family evidence-quality judge) AND a held-out blind cross-family probe must both pass; otherwise the milestone stays open and a reward-hacking canary logs the gap."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: self-managed
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:produce \"<outcome>\"  |  apt:produce --tick --run-id <id>"
+gates: []
+---
+
+# /apt:produce — Outer loop (M1 + M2 + M3 + M4 + M5 + M6)
+
+You take **one outcome** and stand up the minimum viable outer loop: a **frozen
+acceptance setpoint** written once and never mutated, and an **event-sourced
+roadmap** projected from the existing append-only substrate. The long run is a
+**host wake-beat** — one tick per invocation. No daemon. No in-skill polling
+loop.
+
+This skill is **one-tick-per-invocation** (ID-05). It MUST NOT enter a polling
+loop. The recurring beat is delivered externally — by Claude Code's
+`CronCreate` on cron-capable hosts, or by the user re-invoking
+`/apt:produce --tick --run-id <id>` on non-cron hosts. Each wake invocation does
+exactly one tick, then exits.
+
+**Scope.** M1 freezes the setpoint, seeds + projects the roadmap crash-safely,
+and re-reads from disk on each wake tick. **M2** unlocks `done` behind a
+two-gate adjudication — an independent cross-family evidence-quality oracle over
+verify-proof's captured evidence AND a held-out blind cross-family probe the
+implementer never sees. **M3** adds closed-loop convergence: an
+acceptance-criteria ledger whose open count **V** must strictly decrease across
+shipped milestones (the Lyapunov property), with an anti-windup guard that
+rejects any un-sanctioned increase. **M4** is the anti-degradation layer: the
+loop is a **saga** (plan→execute→verify→review→ship) where each phase declares a
+**FORWARD compensator** (a failed verify **ships a revert** + reopens + re-plans;
+you NEVER roll back a merged PR), a **verification-TTL** re-verifies a rotating
+sample of OLD done milestones against HEAD **each tick** and flags regressions,
+and **provider-diverse review** is a RULE (reviewer family ≠ implementer). **M5**
+is the **WSJF/WIP scheduler**: the wake tick now advances the highest-leverage
+READY milestone under a WIP budget — ranked by `WSJF = cost-of-delay / job-size`
+(regression > blocking > open-value > priority), dependency-aware (a milestone
+whose deps aren't `done` is `blocked`, a cycle is surfaced, never a silent idle),
+and M4-regression-aware (a regressed `done` milestone re-enters the ready queue).
+**M6** is the **Claim Envelope**: a durable, bounded, expiring way to CAPTURE a
+review-lesson as a first-class claim and CONSUME it as a concrete AC / subtask /
+proof-obligation DELTA — never a lesson-text context paste. It is interop, not a
+4th store (a fold + a per-record content file on the SAME substrate), it
+generalizes past `lesson` as a data-driven profile registry, and expiry + HEAD
+re-validation keep the corrective loop from corroding. The outer loop is now
+**feature-complete** (M1–M6). See §5 (done-adjudication) + §6 (cross-family
+dispatch) + §7 (probe-blindness) + §8 (Lyapunov monotone progress) + §9 (saga +
+forward compensators) + §10 (provider-diverse review) + §11 (verification-TTL) +
+§12 (WSJF/WIP scheduler) + §13 (Claim Envelope).
+
+---
+
+## Your environment
+
+- **Working directory:** the project root (or any worktree — the run dir
+  resolves to the shared main repo).
+- **apt-tools path:** `node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs`
+  (or `node packages/framework/bin/apt-tools.mjs` when developing the framework).
+- **Run artifacts:** `.aperant/produce/<run-id>/setpoint.json` (frozen,
+  immutable) + `.aperant/produce/<run-id>/roadmap.json` (a DERIVED cache,
+  regenerable from the log — never the authority).
+- **Events:** every mutation appends one line to `.aperant/events/{today}.jsonl`
+  — `produce.run.started` + `produce.setpoint.frozen` at start,
+  `produce.roadmap.milestone_added` / `produce.roadmap.milestone_status_changed`
+  on roadmap edits, `produce.tick` on each wake beat. M2 adds the oracle/probe
+  forensic trail: `produce.milestone.implemented`, `produce.probe.frozen`
+  (hash + author family only — NEVER probe content), `produce.probe.run`
+  (result/family/head_sha only), `produce.oracle.judged`, `produce.oracle.verdict`,
+  `produce.oracle.probe_gap`. M3 adds the Lyapunov acceptance-criteria ledger:
+  `produce.criteria.declared` / `produce.criteria.closed` / `produce.scope.changed`.
+  M4 adds the saga + verification-TTL trail: `produce.saga.phase_entered` /
+  `produce.saga.phase_completed` / `produce.saga.compensated` /
+  `produce.saga.reviewed` / `produce.ttl.reverified` /
+  `produce.ttl.regression_detected` (the saga-phase ops enforce a closed
+  `plan|execute|verify|review|ship` vocabulary; no op carries probe/review
+  content). M5 adds `produce.schedule.computed` (emitted once per `tick` — the
+  scheduler's recorded pick; content-blind: `picked` ids + `wip_limit` only, never
+  folded by the roadmap projection). Schema-gated (`event-schema.mjs`) so a
+  malformed event is rejected fail-closed.
+- **CLI surface:** `apt-tools produce <start|add-milestone|set-milestone-status|status|tick>`
+  (M1) + `<record-implementer|resolve-probe-family|oracle prepare|oracle record|probe freeze|probe record|probe sweep|canary>`
+  (M2) + `<declare-criteria|progress>` (M3) +
+  `<saga enter|saga complete|saga compensate|saga review|saga resolve-reviewer|saga status|ttl select|ttl reverify>`
+  (M4) + `<schedule>` (M5 — the WSJF/WIP ranking + WIP-limited pick; `add-milestone`
+  gains OPTIONAL `--depends-on`/`--priority`/`--size`). The subcommands do the
+  deterministic work — DO NOT re-implement the projection, the setpoint freeze, the
+  probe hash, the gate, the ledger fold, the compensator table, the TTL rotation,
+  or the WSJF math in your prompt.
+- **Probe artifacts:** `.aperant/produce/<run-id>/probes/<milestone>.json` (the
+  frozen blind-probe set — immutable, hash-stamped; its CONTENT is blind to the
+  event log + roadmap projection).
+
+---
+
+## §1. First invocation — freeze the setpoint + seed the roadmap
+
+Given one outcome string:
+
+1. **Freeze the setpoint.** Run:
+
+   ```bash
+   apt-tools produce start . --outcome "<outcome>"
+   ```
+
+   This writes an immutable `setpoint.json` (hash-stamped, exclusive-create) and
+   returns `{ run_id, setpoint_hash, setpoint_path }`. **Record the `run_id`** —
+   every later invocation needs it. Re-running `start` with `--run-id <id>` is
+   idempotent-reuse: it returns the byte-identical setpoint, never an overwrite
+   (ID-02). The setpoint is the fixed external reference — it cannot drift.
+
+2. **Seed milestones.** For each milestone the outcome decomposes into:
+
+   ```bash
+   apt-tools produce add-milestone . --run-id <id> --title "<milestone title>"
+   ```
+
+   Each append lands a `produce.roadmap.milestone_added` event and refreshes the
+   derived roadmap projection. Milestones seed at status `planned`.
+
+3. **Reschedule the first wake tick** — see §3.
+
+---
+
+## §2. Wake beat — one tick
+
+On each wake beat run exactly ONE tick and then exit:
+
+```bash
+apt-tools produce tick . --run-id <id>
+```
+
+The `tick` subcommand does exactly one of the following, once, then returns:
+
+- re-projects the roadmap from the append-only event log (ID-01 — no in-memory
+  authority, re-read from disk every time);
+- folds the M5 WSJF/WIP **schedule** (dependency-aware, regression-aware) under
+  the resolved WIP budget (`--wip N` → config `produce.wip` → default 1);
+- appends a `produce.tick` event + ONE `produce.schedule.computed`;
+- computes `next_action` from the schedule (§12): `continue_milestone` for an
+  in-progress one (unconditional), else `start_milestone` for the **top WSJF ready
+  pick under the WIP budget**, else `idle` (carrying the schedule's reason);
+- returns `{ run_id, roadmap, next_action, schedule, next_tick_hint }`.
+
+Act on `next_action` (advance the named milestone via `set-milestone-status`, or
+dispatch its work), then **reschedule** per §3 and **exit**. You may also mark a
+milestone `in_progress` when you begin it:
+
+```bash
+apt-tools produce set-milestone-status . --run-id <id> --milestone <mid> --status in_progress
+```
+
+---
+
+## §3. Reschedule — the host beat (two branches)
+
+The recurring beat is the HOST's, never yours. Pick the branch for your host:
+
+- **Cron-capable host (Claude Code).** Refresh the `CronCreate` entry's
+  next-fire timestamp so the next tick fires automatically (CronCreate is
+  idempotent on the same payload). This mirrors `apt-watch-ci` §3 step 4. The
+  cron payload's invocation form is `/apt:produce --tick --run-id <id>`.
+
+- **Non-cron host.** Print the honest manual line and stop — do NOT register a
+  cron the host cannot honor, and do NOT fake a scheduler (the framework would
+  be lying). This mirrors `apt-watch-ci` §8:
+
+  ```
+  Next tick: run `apt-tools produce tick . --run-id <id>` again when you return.
+  ```
+
+---
+
+## §4. Single-execution-mode contract (the most easily-broken invariant)
+
+- One tick = one invocation. Do NOT wrap the §2 tick in a polling loop.
+- Do NOT sleep and then re-invoke yourself inside a single session.
+- The recurring beat is delivered by host cron OR by the user re-invoking the
+  skill manually. The loop's value comes from the host scheduler — it does not
+  impersonate one.
+
+If you find yourself wanting to add "and then wait N minutes and run again",
+STOP. The skill is finished after one tick. Exit.
+
+---
+
+## §5. Done-adjudication (M2) — the Showrunner never self-attests "done" (ID-03)
+
+The Showrunner is planner + prosecutor, **never** the judge. `done` is reachable
+ONLY through recorded external evidence + a blind cross-family probe — the skill
+physically cannot let the Showrunner's prose mark a milestone done. A milestone
+flips to `done` ONLY when the **visible gate** AND the **blind gate** both pass;
+otherwise it stays open and a reward-hacking canary logs the gap.
+
+When a milestone's implementation is claimed done, walk these steps IN ORDER:
+
+1. **Record who implemented it** (the cross-family disjointness anchor, ID-M2-02):
+
+   ```bash
+   apt-tools produce record-implementer . --run-id <id> --milestone <mid> --implementer-family <fam>
+   ```
+
+   `<fam>` is one of `claude | codex | gemini` (the family that did the work).
+   Every later cross-family check reads this recorded fact; if it is absent,
+   adjudication is impossible (fail-closed).
+
+2. **Resolve a probe/oracle family DISJOINT from the implementer** (§6):
+
+   ```bash
+   apt-tools produce resolve-probe-family . --run-id <id> --milestone <mid> [--host-family <fam>]
+   ```
+
+   Returns a `probe_family` ≠ the implementer family plus a LIVE-resolved model
+   (never a hardcoded id) + a `transport_hint`. `available:false` when no
+   disjoint family exists (a single-family setup cannot satisfy the rule by
+   design — it CANNOT reach done).
+
+3. **Author 10–20 behavioral probes in that disjoint family + freeze them**
+   (probe-blindness, §7):
+
+   ```bash
+   apt-tools produce probe freeze . --run-id <id> --milestone <mid> --probe-file <path> --author-family <probe_family>
+   ```
+
+   The probe set is immutable (a second freeze returns the byte-identical set)
+   and its CONTENT never enters the event log or the roadmap projection.
+
+4. **Run the cross-family evidence-quality oracle over verify-proof's
+   `verification.json` + record it:**
+
+   ```bash
+   apt-tools produce oracle prepare . --run-id <id> --milestone <mid> --verdict-path <path/to/verification.json>
+   ```
+
+   `prepare` extracts the v2 verdict (must be EXACTLY `approved`) + the tests[]
+   evidence into a judge payload. Dispatch that payload to the disjoint family
+   (§6) for a pass/fail evidence-quality judgement, then record it:
+
+   ```bash
+   apt-tools produce oracle record . --run-id <id> --milestone <mid> --verdict <pass|fail> --oracle-family <probe_family>
+   ```
+
+   `record` is REFUSED when `oracle_family` equals the implementer family.
+
+5. **Run the frozen blind probe against HEAD in the disjoint family + record the
+   result** (result/family/head-sha only — never content):
+
+   ```bash
+   apt-tools produce probe record . --run-id <id> --milestone <mid> --result <pass|fail> --probe-family <probe_family> --head-sha <sha>
+   ```
+
+6. **Adjudicate `done`:**
+
+   ```bash
+   apt-tools produce set-milestone-status . --run-id <id> --milestone <mid> --status done --verdict-path <path/to/verification.json>
+   ```
+
+   Accepted (flips to `done` + appends `produce.oracle.verdict{done}`) ONLY when
+   the **visible gate** (verify-proof `approved` AND a recorded cross-family
+   oracle pass) AND the **blind gate** (a recorded cross-family probe pass + a
+   cross-family frozen probe set) both pass. A visible-pass + blind-fail is
+   REFUSED — the milestone stays open and a `produce.oracle.probe_gap` canary
+   event is logged (the reward-hacking near-miss).
+
+**Canary + rotating blind re-probe:**
+
+```bash
+apt-tools produce canary . --run-id <id>       # green-on-visible MINUS green-on-blind + per-milestone breakdown
+apt-tools produce probe sweep . --run-id <id> --sample N   # deterministic rotating sample of already-done milestones to blind-re-probe against HEAD
+```
+
+`produce probe sweep` selects already-`done` milestones (fewest / oldest
+last-probe-run first) so a milestone that silently regressed after done is
+caught; re-run the blind probe (steps 3+5) against those, and a fresh failure is
+a real regression.
+
+---
+
+## §6. Cross-family dispatch recipe — REUSE the apt-spar mechanism (ID-M2-01)
+
+M2 does NOT invent a second cross-family path. The probe/oracle family + model
+resolve through the SAME primitives `apt:spar` uses — provider is an OUTPUT,
+Aperant holds ZERO model ids:
+
+- `apt-tools produce resolve-probe-family` picks a family DISJOINT from the
+  implementer (the one new rule) using the apt-spar §3 partner-map shape, and
+  delegates model resolution to `spar-resolve-partner` /
+  `resolveCodexSparModel` — for `codex` it reads the model LIVE from
+  `~/.codex/config.toml`; `claude` / `gemini` self-resolve (`model: null`).
+- Dispatch the oracle-judge + probe-run to the resolved family via the
+  **transport ladder** (MCP tool → plugin shim → raw CLI), following the
+  returned `transport_hint.recommended_walk` (codex prefers the self-resolving
+  plugin/CLI rungs — see `apt:spar` §3). NEVER name a model id yourself; NEVER
+  hardcode one in a prompt (the `produce-no-hardcoded-models.guard` test fails
+  CI on any `gpt-*` / `claude-*` / `gemini-*` / `grok-*` / `glm-*` literal in a
+  produce module or this SKILL).
+
+## §7. Probe-blindness — the invariant you must never break
+
+The held-out probe set is what makes the blind gate meaningful. The probe
+CONTENT lives ONLY in the frozen `probes/<milestone>.json` file; the event log +
+roadmap projection carry ONLY the probe-set hash + families. **NEVER paste probe
+content into any Showrunner or implementer context** — not into a plan, a prompt,
+a commit, or a chat message. A Showrunner re-anchoring from disk each tick
+physically cannot see the probe questions (the projection folds
+`produce.roadmap.*` ONLY); do not defeat that by hand. Author the probes in the
+disjoint family, freeze them, and reference them only by running them
+cross-family.
+
+---
+
+## §8. Lyapunov monotone progress (M3) — V must strictly decrease
+
+M3 adds the closed-loop convergence measure: **V = open acceptance criteria**
+(declared − closed), folded from the append-only log on every read. The run
+converges when V reaches 0. Two guarantees, enforced at two different times.
+
+1. **Declare a milestone's acceptance criteria at seed time — BEFORE it ships:**
+
+   ```bash
+   apt-tools produce declare-criteria . --run-id <id> --milestone <mid> --criterion "<text>"
+   ```
+
+   Each declaration opens one criterion bound to the milestone (V += 1). Declare
+   a milestone's criteria while defining/seeding it (§1) so they land in the
+   baseline scope-definition window — before the run has closed anything.
+
+2. **Monotone-decrease is enforced at WRITE time (the anti-windup guard).** Once
+   the run has begun closing criteria (it is **in descent**), a `declare-criteria`
+   that would raise V is **REJECTED fail-closed** — the criterion is not added —
+   unless it carries the scope-change escape hatch:
+
+   ```bash
+   apt-tools produce declare-criteria . --run-id <id> --milestone <mid> --criterion "<text>" --scope-change "<why the outcome genuinely grew>"
+   ```
+
+   `--scope-change "<reason>"` is the **ONLY** sanctioned way V may rise after
+   descent — it appends a `produce.scope.changed` event immediately before the new
+   criterion, so every post-descent increase carries its own logged justification
+   on the trail. There is NO permanent unlock: the flag justifies exactly the
+   criteria declared in that one call. Honest scope growth is allowed; it is
+   ALWAYS audited.
+
+3. **Criteria close as a CONSEQUENCE of a milestone shipping.** When a milestone
+   flips to `done` (the §5 two-gate), its still-open criteria auto-close, so V
+   strictly decreases. A milestone with zero declared criteria closes zero
+   (byte-identical to M2).
+
+4. **Monotone-progress is REPORTED at READ time:**
+
+   ```bash
+   apt-tools produce progress . --run-id <id>
+   ```
+
+   `progress` re-reads the ledger from disk every invocation (no in-memory
+   authority) and returns `{ v_open_now, v_series:[{milestone_id, v_before,
+   v_after, delta, decreased}], strictly_decreasing, lyapunov_ok,
+   lyapunov_violations[], scope_changes[] }`. The V-series must be **strictly
+   decreasing** across shipped milestones. A milestone that shipped without
+   closing any criterion (`delta === 0`) is a soft **stall**
+   (`strictly_decreasing: false`), not a hard failure. A `produce.criteria.declared`
+   that raised V after descent WITHOUT an accompanying `produce.scope.changed` is
+   a hard **Lyapunov violation** (`lyapunov_ok: false`). `progress` FLAGS these —
+   it never rejects (the rejection is the write-time guard in step 2); a
+   scope-changed increase is audited, NOT a hard violation.
+
+---
+
+## §9. Saga + forward compensators (M4) — ship a revert, never roll back a merged PR
+
+M4 models the loop as a **saga**: `plan → execute → verify → review → ship`. Each
+phase transition is recorded; each phase declares a **FORWARD compensator** that
+recovers the run WITHOUT a destructive rollback. Record the transitions as you
+drive a milestone:
+
+```bash
+apt-tools produce saga enter    . --run-id <id> --milestone <mid> --phase <plan|execute|verify|review|ship>
+apt-tools produce saga complete . --run-id <id> --milestone <mid> --phase <plan|execute|verify|review|ship>
+apt-tools produce saga status   . --run-id <id>
+```
+
+When a phase FAILS, fire its compensator:
+
+```bash
+apt-tools produce saga compensate . --run-id <id> --milestone <mid> --phase <p> --reason "<why it failed>"
+```
+
+The **load-bearing rule (ID-10 / ID-M4-02):** EVERY compensator is FORWARD —
+`rolls_back_merged_pr: false` on every phase. `plan`/`execute` (pre-merge) reopen
++ re-plan without a revert; `verify`/`review`/`ship` are `revert_reopen_replan` —
+they **ship a revert** (a new forward commit/branch) + reopen the task + re-plan.
+**You NEVER roll back a merged PR** — you cannot un-merge history other agents or
+humans already built on. The CLI RECORDS the forward-compensator descriptor; it
+does NOT execute the revert / reopen / re-plan (that is the dispatch layer's job)
+and it NEVER mutates the roadmap milestone status (the saga fold is SEPARATE from
+the roadmap projection — blindness preserved).
+
+## §10. Provider-diverse review (M4) — reviewer family ≠ implementer (ID-08)
+
+The saga's REVIEW phase reviewer must be a provider family DISJOINT from the
+implementer's — a same-family reviewer rubber-stamps its own family's work. This
+REUSES the SAME `resolveProbeFamily` M2 uses on the probe/oracle path (no second
+cross-family mechanism; provider is an OUTPUT; the model resolves LIVE, never a
+hardcoded id):
+
+```bash
+apt-tools produce saga resolve-reviewer . --run-id <id> --milestone <mid> [--host-family <fam>] [--available-families a,b,c]
+```
+
+Returns a `reviewer_family` DISJOINT from the recorded implementer + a
+LIVE-resolved model + a `transport_hint`; `available:false` when no disjoint
+family exists (single-family setup — the review-diversity rule cannot be
+satisfied by design). Dispatch the review to that family via the same **transport
+ladder** as §6, then record the verdict:
+
+```bash
+apt-tools produce saga review . --run-id <id> --milestone <mid> --verdict <pass|fail> --reviewer-family <reviewer_family>
+```
+
+`saga review` is REFUSED fail-closed when `reviewer_family` equals the recorded
+implementer family (or when no implementer family is recorded, ID-M2-02) — the
+review-path analog of `oracle record`.
+
+## §11. Verification-TTL (M4) — re-verify OLD done milestones against HEAD each tick
+
+Verification is not permanent: a milestone marked `done` at HEAD-sha `A` can
+silently regress as HEAD advances to `B`. **Each tick**, re-verify a rotating
+sample of OLD done milestones against the current HEAD. Pass the current HEAD sha
+on the tick to surface the sample (additive — a tick WITHOUT `--head-sha` is
+byte-identical to M1/M2/M3, still one tick, no loop):
+
+```bash
+apt-tools produce tick . --run-id <id> --head-sha <sha>   # surfaces the additive ttl_reverify sample
+apt-tools produce ttl select . --run-id <id> --head-sha <sha> [--sample N]
+```
+
+`ttl select` REUSES the M2 rotating-sample primitive and returns a deterministic
+sample of already-`done` milestones **STALE** against HEAD — a milestone last
+re-verified against the current HEAD is EXCLUDED as fresh. Re-run the frozen blind
+probe (§5 steps 3+5) against each, then record the re-verify result cross-family:
+
+```bash
+apt-tools produce ttl reverify . --run-id <id> --milestone <mid> --result <pass|fail> --probe-family <fam> --head-sha <sha>
+```
+
+`ttl reverify` REUSES the M2 cross-family guard (a same-family re-verify is
+refused). A `pass` refreshes verification against the new HEAD. A **`fail`** flags
+the milestone — it appends `produce.ttl.regression_detected` AND **fires the
+FORWARD compensator** (`saga compensate --phase verify` → `revert_reopen_replan`:
+ship a revert + reopen + re-plan, never a merged-PR rollback). The re-verify RUN +
+the revert-ship/reopen/re-plan EXECUTION is the dispatch layer's job; the CLI
+records + computes.
+
+---
+
+## §12. WSJF/WIP scheduler (M5) — what to advance next, under budget
+
+M5 replaces the naive "first planned" tick heuristic with a deterministic
+**WSJF** (Weighted Shortest Job First) ranking of the READY milestones + a
+**WIP-limited pick**. Ask the scheduler what to advance next:
+
+```bash
+apt-tools produce schedule . --run-id <id> [--wip N]
+```
+
+Read-only (emits nothing — mirrors `status`/`progress`/`canary`). It returns
+`{ wip_limit, wip_in_use, wip_available, ready_queue[], blocked[], in_progress[],
+pick[], reason, cycle }`.
+
+**The formula (fixed integer weights — deterministic, no LLM):**
+
+```
+WSJF(m) = CostOfDelay(m) / JobSize(m)
+  CostOfDelay(m) = 5·regression_flag(m)   // W_REGRESS — user-facing breakage, most urgent
+                 + 3·blocking_count(m)     // W_BLOCK   — # milestones depending on m
+                 + 2·open_criteria(m)      // W_VALUE   — M3 open criteria bound to m
+                 + priority(m)             // optional declared --priority (default 0)
+  JobSize(m)     = declared_size(m) > 0 ? declared_size(m) : max(open_criteria(m), 1)
+```
+
+`open_criteria` deliberately appears in BOTH the value term of CoD and (as the
+fallback) in JobSize — standard WSJF (prefer small, high-value jobs); a declared
+`--size` decouples them. `ready_queue` is sorted **WSJF desc → roadmap first-seen
+order → milestone_id** — a total, stable order, so two folds of the same log are
+byte-identical.
+
+**Ready-set membership + WIP budget:**
+
+- A `planned` milestone is READY iff every `depends_on` id resolves to a roadmap
+  milestone with status `done` (an unknown dep fails closed = unmet); otherwise it
+  is in `blocked` with `blocked_by` = the not-done deps. A dependency **cycle**
+  among not-done milestones surfaces `reason: "dependency_cycle_detected"` + the
+  offending `cycle` — never a silent idle.
+- A `done` milestone with an **unresolved M4 regression** (§11) re-enters the ready
+  queue tagged `regressed: true` with the `W_REGRESS=5` weight — the loop defends
+  what it shipped. A subsequent `ttl reverify --result pass` resolves it.
+- The WIP cap resolves `--wip N` → `.aperant/config.json :: produce.wip` →
+  default **1**. `wip_available = max(0, wip_limit − in_progress_count)`; `pick` is
+  the top `wip_available` of `ready_queue`. WIP-saturated → empty `pick`,
+  `reason: "wip_saturated"`. WIP counts roadmap `in_progress` status ONLY (a
+  regressed `done` candidate is not counted as in_progress).
+
+Declare a milestone's dependencies / priority / size at seed time (additive on the
+existing `milestone_added` event — an M1-style add is byte-identical):
+
+```bash
+apt-tools produce add-milestone . --run-id <id> --title "<t>" [--depends-on a,b] [--priority <int>] [--size <positive int>]
+```
+
+**Scheduler-driven tick.** The §2 `tick` folds this schedule and sets
+`next_action` to the scheduler's pick (top WSJF ready under the WIP budget), still
+one tick per invocation. The `pick` is **advisory scheduling input** — the M5 CLI
+does NOT dispatch plan→execute→verify→review→ship of the picked milestone (that
+closed-loop dispatch is out of scope; the scheduler tells the loop *what* to
+advance next). A **token/cost budget** is deferred — the substrate records no cost
+data; WIP is the honest, substrate-native budget.
+
+---
+
+## §13. Claim Envelope (M6) — capture a lesson, consume it as a plan delta
+
+M6 turns "we learned this once" into "every future plan in this family is
+pre-corrected." A **Claim Envelope** is a durable, provider-neutral, bounded,
+expiring claim (the `lesson` profile is the only one shipped). Four subcommands
+drive its lifecycle:
+
+```bash
+apt-tools produce claim declare . --run-id <id> --profile lesson --claim-file <path> [--claim-id <id>]
+apt-tools produce claim list    . --run-id <id>
+apt-tools produce claim expire  . --run-id <id> --claim-id <id> [--reason "<r>"]
+apt-tools produce claim consume . --run-id <id> [--milestone <mid>]
+```
+
+- **`declare`** VALIDATES the envelope (the `lesson` profile requires
+  `provenance` + a non-empty `preconditions` trigger + a **bounded** `scope`
+  (`global !== true`) + an `expiry` (`expires_at` OR `revalidate_against_head`) +
+  a `negative_evidence` field + a non-empty `resolution_verifier`), then FREEZES
+  it once to `claims/<claim-id>.json` (exclusive-create, immutable) and logs
+  `produce.claim.declared` carrying the **content_hash only** — the claim content
+  NEVER touches the event log. A global/unbounded scope, an empty precondition,
+  or a missing expiry is REJECTED fail-closed with a reason.
+- **`list`** re-projects the claim ledger (`declared − expired`) folded from the
+  append-only log. The `produce.claim.*` ops are a SEPARATE fold — they NEVER
+  enter the roadmap projection the Showrunner re-reads each tick.
+- **`expire`** logs `produce.claim.expired`; the claim leaves the active set.
+- **`consume`** emits a STRUCTURED delta
+  `{claim_id, targets:[{kind: acceptance_criterion|subtask|proof_obligation, requirement, ref?}]}`
+  derived FROM the claim's `resolution_verifier`.
+
+**Consumption is a DELTA, never a context paste (the M6 invariant).** "Consuming
+a lesson" means applying a concrete AC / subtask / proof-obligation requirement to
+a plan — it does NOT mean pasting the lesson's prose (`provenance` /
+`negative_evidence` / body) into the planner's context. Pasting lesson text
+re-introduces the context-rot the loop is trying to escape and is FORBIDDEN. The
+consume output is a projection DOWN to `{claim_id, targets}` and carries none of
+the envelope's non-delta fields.
+
+**Anti-corrosion (expiry + HEAD re-validation).** A stale lesson that no longer
+matches HEAD silently degrades every future plan. `consume` SKIPS (never applies)
+a claim that is time-expired, whose `revalidate_against_head` check no longer
+matches the working tree, or whose precondition does not match — surfacing each
+under `skipped[]` with a reason. The HEAD check is a DETERMINISTIC path-exists /
+grep, never an LLM judgment.
+
+**Bounded critic (anti-windup).** A lesson fires only behind a matching
+precondition and a bounded scope, and consumption emits ONE delta per claim — one
+incident fixes ITS task, it never ratchets a global always-on policy.
+
+**Interop, not a 4th store; generalizes as data.** The claim ledger is a fold +
+a per-record content file on the SAME `.aperant/produce/<run-id>/` substrate M1/M2
+already use — no new DB, no schema, no migration, and it touches none of the 3
+adjudication engines (verify-proof / oracle / review). Generalization past
+`lesson` is a data-driven **profile registry** (`CLAIM_PROFILES`): adding a second
+profile is one map entry, not a code fork. The outer loop is now
+**feature-complete** (M1–M6).
+
+---
+
+## Notes for the orchestrator
+
+- **After editing this SKILL** (or any shipped `apt-*/SKILL.md`), re-run
+  `apt-tools init . --<runtime>` (e.g. `apt-tools init . --solo --claude`, and
+  once per other installed runtime) — or `/apt:update` — so each runtime's
+  `apt-file-manifest.json` + `apt-skill-version` headers stay in sync.
+
+- The event log is the authority; `roadmap.json` is a derived cache, always
+  regenerable by folding the log. A corrupt/stale cache is repaired by the next
+  `status`/`tick` re-fold — never trust it as the source of truth (ID-01).
+- Concurrent `add-milestone` writers are crash-safe by construction: the
+  mutation is a pure O_APPEND to the shared log (atomic under PIPE_BUF), and the
+  cache is a fold-under-lock single-writer regenerate — no lost updates.
+- M1 introduces no new secret material, no daemon, and no new per-mode
+  persistence: it is framework filesystem substrate, cross-mode by construction.

package/dist/plugin/skills/apt-quick/SKILL.md

@@ -29,7 +29,7 @@ Execute a small task quickly without full pipeline overhead. For small fixes, do
 - **Working directory:** The project root (where you were invoked) UNLESS an active task has a task-level worktree (see below).
 - **Constitution:** Read `AGENTS.md` in the project root if it exists
 - **State directory:** `.aperant/quick/{task-id}/`
-- **Task-level worktree isolation:** Use the `worktree_path` the router passed in skill context (router path) OR that §1a parsed from `task create`'s envelope (direct path) — this is the worktree `task create` literally just provisioned for this task. When present, run all editing Bash commands with `cd {worktree_path} &&` prefix so the fix lands on the task branch. `apt-tools` calls still take the project root as `<project-dir>` so they coordinate through the main repo's shared `.aperant/`. The quick task's `.aperant/quick/{task-id}/` directory lives in the main repo, not the worktree. (Last-resort fallback only: if neither source supplied a `worktree_path` but `.aperant/state.json` has an active task with one, you may use that.)
+- **Task-level worktree isolation:** Use the `worktree_path` the router passed in skill context (router path) OR that §1a parsed from `task ensure`'s envelope (direct path) — this is the worktree `task ensure` literally just provisioned for this task. When present, run all editing Bash commands with `cd {worktree_path} &&` prefix so the fix lands on the task branch. `apt-tools` calls still take the project root as `<project-dir>` so they coordinate through the main repo's shared `.aperant/`. The quick task's `.aperant/quick/{task-id}/` directory lives in the main repo, not the worktree. (Last-resort fallback only: if neither source supplied a `worktree_path` but `.aperant/state.json` has an active task with one, you may use that.)
 </your_environment>
 
 <state_files>
@@ -54,35 +54,27 @@ Extract the task description from `$ARGUMENTS`.
 
 ### 1a. Resolve canonical task id (idempotent)
 
-QUICK now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile. The body owns idempotency because `apt-tools task create` does NOT guard against existing ids (see spec §3 R8).
+QUICK now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile. Idempotency is owned by the deterministic allocator `apt-tools task ensure --intent create-new` (NOT raw `task create`) — re-running returns the SAME task + worktree (`reused: true`), so the old `task get` guard dance is gone.
 
 Two invocation paths converge here:
 
-- **Router path** (`/apt` → `/apt:quick`): the router has already called `task create` and injected `task_id` into your skill context.
-- **Direct path** (`/apt:quick foo`): no `task_id` in context — you create one now.
-
-Sequence:
+- **Router path** (`/apt` → `/apt:quick`): the router has already run `task ensure --intent create-new` and injected `task_id` (+ `worktree_path`) into your skill context. Re-affirm idempotently with the same id:
+  ```bash
+  apt-tools task ensure . --description "$ARGUMENTS" --intent create-new --track QUICK --id {task_id}
+  ```
+  The `--id {task_id}` makes ensure resolve to the EXACT record the router just provisioned (`reused: true`) — no second task, no second worktree.
 
-1. **If `task_id` is present in skill context** (router path):
-   ```bash
-   apt-tools task get . --id {task_id}
-   ```
-   - If exit 0 AND the returned record has `track === "QUICK"` → reuse, skip the create call.
-   - Else (record missing OR wrong track) → call:
-     ```bash
-     apt-tools task create . --description "$ARGUMENTS" --track QUICK --id {task_id}
-     ```
-     Parse `task_id` from the returned envelope (it will match the id you passed).
+- **Direct path** (`/apt:quick foo`): no `task_id` in context — allocate now:
+  ```bash
+  apt-tools task ensure . --description "$ARGUMENTS" --intent create-new --track QUICK
+  ```
+  ensure is keyed on the normalized description + scope, so a retry returns the SAME canonical `{slug}_YY-MM-DD` `task_id`.
 
-2. **If no `task_id` in skill context** (direct path):
-   ```bash
-   apt-tools task create . --description "$ARGUMENTS" --track QUICK
-   ```
-   Parse the generated `task_id` from the envelope — it will be the canonical `{slug}_YY-MM-DD` shape.
+Parse `task_id` from the returned envelope.
 
 The task id is now canonical (no more `quick-YYYYMMDD-*` invention). `QuickTaskSchema` accepts both the canonical `{slug}_YY-MM-DD` form and the legacy `quick-YYYYMMDD-{slug}` form for back-compat with already-shipped task records on disk.
 
-**Worktree isolation (both paths).** `task create` provisions a worktree when `task_isolation.worktree_per_task` is enabled (track-agnostic — QUICK gets one too). Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the `task create` envelope (direct path); on the router path the orchestrator already passed `worktree_path` into your skill context — use that. When a `worktree` block is present, print the banner and run all subsequent editing Bash commands with `cd {worktree_path} &&`:
+**Worktree isolation (both paths).** `task ensure --intent create-new` provisions a worktree when `task_isolation.worktree_per_task` is enabled (track-agnostic — QUICK gets one too). Parse `worktree.worktree_path`, `worktree.branch`, and `worktree.base_branch` from the `task ensure` envelope (direct path); on the router path the orchestrator already passed `worktree_path` into your skill context — use that. When a `worktree` block is present, print the banner and run all subsequent editing Bash commands with `cd {worktree_path} &&`:
 
 ```
 [APT] Working in isolated worktree: {worktree_path}