@1aboveio/skills 0.19.3 → 0.20.1

package/skills/engineering/resolve-issues/SKILL.md

@@ -1,168 +0,0 @@
----
-name: resolve-issues
-description: "Slash/explicit-only (/resolve-issues). Drive GitHub issues (single or epic) to merge-ready PRs: implement → e2e → independent review on a different model ∥ CI → fix, looped until PASS; epics assemble one PR per shippable component. Orchestrates implement-and-pr, e2e-test, ensure-coverage, review-pr, smoke. Do not auto-select — only on explicit user/orchestrator invoke. NOT one implement+PR alone, review alone, rush-issues, or release work (rush-release or resolve-release)."
-disable-model-invocation: true
-dependencies:
-  - implement-and-pr
-  - e2e-test
-  - ensure-coverage
-  - review-pr
-  - smoke
----
-
-# Resolve issues (produce → review ∥ CI → fix, looped)
-
-Drive GitHub issues to **merge-ready PR(s)**. You orchestrate: schedule spawns, run the loop, enforce the guarantees below. One issue or an epic is the same pipeline — normalize the input to a `units[]` list (a plain issue is one unit, an epic one per sub-issue) and loop over it.
-
-At intake, classify every unit as `implementation`, `external-verification`,
-`human-decision`, or `prerequisite` with `scripts/unit-kind.mjs`. The same intake
-classifies evidence/authorization lifecycle semantics from declared scope and changed
-surfaces, deny-by-default; classified implementation work must carry a valid
-`evidenceLifecycleContract` before `spawn-contract` admits it. Only confirmed
-`implementation` units enter the produce/review/CI/delivery loop; other kinds retain
-their own completion protocols and remain separate in progress reporting.
-
-## The four guarantees (everything here serves one of these)
-
-A step that serves none of these does not belong in this skill — see [The removal path](#the-removal-path-keep-this-skill-small). Each guarantee's incident record: [references/why.md](references/why.md#the-four-guarantees).
-
-1. **Real tests, honestly green.** Never skip, guard, weaken, or `.only` a test to pass; never mock a first-party internal seam or intercept first-party routes in a journey; assertions against 404/empty/error pages are defects. A missing precondition is the test's *arrange* step — **seed it**. Un-sandboxable/flaky → quarantine lane (runs, non-blocking, `Unverified`); obsolete → delete. Diff-discipline: gate the net `merge-base...HEAD` diff; pre-existing issues are notes.
-2. **An independent review that actually ran.** Fresh context **and** a different model than the one that wrote the diff. The reviewer loads `review-pr` and returns its proof artifacts — a prose review-shaped answer does not count.
-3. **The loop exits on a fresh verdict on the current authorization boundary, never on a claim.** "I addressed the findings" is not a terminal state. A unit review PASS is terminal for that unit branch and becomes preserved **preliminary evidence**; notes inside it become `deferrals[]`, never another unit round. Component delivery is authorized separately: progressively assemble those passed unit heads, freeze one complete clean candidate, then run one terminal exact-head integrated review + CI + smoke whose `authorizationBoundary` is the component HEAD. Any movement after that terminal PASS requires a typed `reopenReason: ci-red|head-rewritten|contract-revised|integration-finding|external-review`, a changed matching `ci|head|contract|integration` boundary, and a fresh freeze + terminal authorization. (`external-review` is the epic-876 shape: independent PASS, then a non-self `CHANGES_REQUESTED` naming a real AC gap — not a note-chase; boundary kind is still `head`.) A bar the orchestrator may raise after the fact is not a bar.
-4. **Merging requires a recorded human authorization, and only ever targets the integration branch.** The authorization is `mergeShippable` on the run manifest, and the *only* thing that sets it is a human answering pre-flight — the recommended `autonomous` level turns it on, `supervised` leaves it off, and an explicit field wins over either. With it, an [independently-shippable component](references/deliverables.md#deliverables-the-shippable-component-not-the-whole-epic) merges into `targetBranch` (e.g. `dev`) at its full bar; without it the loop hands components back merge-ready with evidence and merges nothing. Never to production, which stays `resolve-release`'s with its own authorization.
-
-   **Two different things are called "the default" around this field, and conflating them is how the guarantee gets read backwards.** What pre-flight *recommends* to a human who is present is `autonomous` (authorization on). What an *unset* field resolves to, on a manifest nobody was ever asked about, is `supervised` (authorization off) — the fail-safe, because a recommendation may change what a human is offered but must never change what silence already meant. This guarantee rests on the second: no recorded answer, no merge.
-
-## How to invoke me
-
-**Main loop only — never nested in a subagent. All spawns at depth 1, launched by you — and you coordinate, never implement**, single-issue runs included. Why both halves matter: [references/why.md](references/why.md#main-loop-only-and-the-spawn-contract). Be a **thin scheduler**: every heavy step runs in a spawn that returns a compact, schema'd result (verdict + `file:line` pointers + PR ref, never a transcript); durable state lives in the [run manifest](references/run-state.md). **Waiting is not a foreground activity either** — an enqueued PR is watched by one launch of [`watch-delivery.mjs`](scripts/watch-delivery.mjs), not a poll loop that spends a turn per check.
-
-**The leaf-spawn contract (every spawn, both steps).** A spawned agent does not inherit your loaded skills — everything it must know has to be *in the spawn*, and each clause fails **silently** when omitted. So **render it, don't compose it: [`run-state.mjs spawn-contract <slug> <unit> --kind producer|fix|review`](scripts/run-state.mjs)** fills every clause from state and prints a block to paste (exit 4 = state is missing a clause; fix the state). A composed contract is written once per run and then repeated — measured, it decays rather than being re-derived, which is how gate flags go missing. All five clauses in full: [references/spawn-contract.md](references/spawn-contract.md). → [why](references/why.md#the-spawn-contract-is-rendered-not-composed)
-
-**(e) Pass the working directory** is the clause worth restating here: the *unit's own* `units[].workspacePath`, never the orchestrator's checkout. A spawn inherits *your* cwd otherwise, so an unset one quietly writes into the tree you are coordinating from — the workspace is recorded, reported, and doing nothing. Every code-writing spawn, every round; and a fix round gets the **same** path its producer used, so it resumes rather than reinstalls.
-
-**A spawn that dies mid-flight leaves a partial, and the partial beats a clean slate** — point the replacement at the same path so it resumes. But a partial is **never** proof: `status: in-progress` counts exactly as missing for every gate, and the response is a re-spawn, not an exit.
-
-**Fan-out (opt-in, Workflow harness):** only read-only/advisory stages — prior-art and independent review — via `workflows/`; everything that writes code or hits a human gate stays in the main loop ([references/fan-out.md](references/fan-out.md)). An epic's *implementers* run as plain depth-1 spawns regardless, concurrently up to the in-flight cap, each in its own unit's workspace.
-
-## Pre-flight (once, before intake — never mid-run)
-
-**Before creating or resuming a run, use [`run-state.mjs init|resume`](scripts/run-state.mjs).** That shared lifecycle boundary runs `engineering-runtime`'s read-only coherence verifier first; an incoherent, unavailable or malformed verdict fails closed with findings and a pinned repair recipe, and never runs the repair itself.
-
-**Then read [references/pre-flight.md](references/pre-flight.md) and run its seven steps (0–6)** — it owns the procedure and every non-negotiable in it. Four rules decide whether the rest of the run means anything, so they are named here too:
-
-- **Both model slots are filled individually by the human**, each as an operating point (a model *and* its banked effort), with alternates shown. **`reviewer ≠ implementer`** is hard — it is what makes guarantee 2 an independent review rather than a second opinion from the same blind spots.
-- **Probe, never assume, the merge path** — `deliveryMode`, `queueProvider`, and above all **`enqueueTrigger`**: on a repo that auto-merges once conditions hold, *posting the review verdict as an approval **is** the merge*. Ask [`run-state.mjs approval-gate <slug> [componentId]`](scripts/run-state.mjs) before any verdict reaches GitHub. → [why](references/why.md#the-enqueue-trigger)
-- **`autonomy` is filled as `autonomous` by default** (subsumes `mergeShippable`; guarantee 4). It is **not** a pre-flight question — stated in the summary; a human may override to `supervised`. Ask the manifest what it resolved to — `run-state.mjs autonomy <slug>` — never re-derive it from prose. No level lifts the design gate, the breaker's `descope`, or its round ceiling.
-- **No silent fallback:** read back the model every spawn actually ran on and record it per unit. A reviewer read-back ≠ the confirmed review model means the verdict does not count.
-
-## Routing (read this first)
-
-**This file is an index, and must stay one** — a truncated skill silently becomes a shorter skill and nothing warns you. The doctrine lives in `references/`, one file per phase.
-
-| Phase | Read | The rule you must not miss |
-|---|---|---|
-| Know the bar any step must serve | [references/guarantees.md](references/guarantees.md) | The four guarantees in full. |
-| **Once, before intake** — pre-flight | [references/pre-flight.md](references/pre-flight.md) | Seven steps, **once**, before intake, never mid-run. |
-| Turn issues into scheduled units | [references/intake.md](references/intake.md) | A prerequisite artifact is **not a unit**; schedule against [interference](references/interference.md), not dependency order alone. |
-| Decide what runs next | [references/interference.md](references/interference.md) | **`runnable <slug>` is the scheduler — ask it at every milestone** and spawn what it names. The bar is *pushed*, never *merged*; `inFlightCap` is 4 on every repo. |
-| Run a unit: produce → review ∥ CI → fix | [references/loop.md](references/loop.md) | **Review on a different model than the implementer**, same breath as CI, **same HEAD**. A PASS is preliminary component evidence — **record it with typed `reviewSubject` + `authorizationBoundary`, then feed `record-component-candidate`. The log is append-only: a legacy-shape round can never become component evidence.** |
-| Deliver a merge-ready component | [references/deliverables.md](references/deliverables.md) | One PR per **independently-shippable component** — an epic is not one PR. |
-| Enqueue, watch, route a dequeue | [references/delivery.md](references/delivery.md) | A watch observes a **progression**, not a state. Never hand-roll a watcher. |
-| Preserve terminal facts while coherence blocks a transition | [references/terminal-evidence-journal.md](references/terminal-evidence-journal.md) | Journal append is evidence only; reconciliation revalidates coherence and live facts before one state transition. |
-| Persist / resume run state | [references/run-state.md](references/run-state.md) | Durable state lives in the manifest, not your context. |
-| Reconcile superseded unit PRs, then finalize | [references/finalization.md](references/finalization.md) | Run the pre-finalization `reconcile-contained-unit-prs` operation `next` emits for delivered combined components. **`finalize <slug>` remains the sole completion transition** — fails closed on dispositions, live ancestry/GitHub state, branch restoration and cleanup, then renders the handoff. |
-
-**`references/why.md` is not on this list, and never is.** It is the archive — the incident behind each rule — read when you **edit** this skill, never while running it. The `→ [why]` citations are provenance, not steps: every rule you need is stated where the rule is.
-
-
-The four guarantees, the spawn contract, the step map and the definition of done
-stay on this page: a reader who takes nothing else from this skill should still
-take those.
-
-## The four guarantees (everything here serves one of these)
-
-A step that serves none of these does not belong in this skill ([the removal path](#the-removal-path-keep-this-skill-small)). Each bar in full — what it refuses, what satisfies it, the state that records it — is [references/guarantees.md](references/guarantees.md); each one's incident record is [references/why.md](references/why.md#the-four-guarantees).
-
-1. **Real tests, honestly green.** Never skip, guard, weaken or `.only` a test to pass; never mock a first-party internal seam or intercept first-party routes in a journey; an assertion against a 404/empty/error page is a defect.
-2. **An independent review that actually ran.** Fresh context **and** a different model than the one that wrote the diff, loading `review-pr` and returning its proof artifacts.
-3. **The loop exits on a fresh verdict on the current authorization boundary, never on a claim.** "I addressed the findings" is not a terminal state, and a bar the orchestrator may raise after the fact is not a bar.
-4. **Merging requires a recorded human authorization** (`mergeShippable`, set only by a human answering pre-flight) **and only ever targets the integration branch** — never production, which is `resolve-release`'s. An **unset** field resolves to `supervised`: no recorded answer, no merge.
-
-## How to invoke me
-
-**Main loop only — never nested in a subagent. All spawns at depth 1, launched by you — and you coordinate, never implement**, single-issue runs included. Be a **thin scheduler**: every heavy step runs in a spawn returning a compact schema'd result (verdict + `file:line` + PR ref, never a transcript), durable state lives in the [run manifest](references/run-state.md), and **waiting is not foreground work** — an enqueued PR gets one launch of [`watch-delivery.mjs`](scripts/watch-delivery.mjs), never a poll loop.
-
-**The leaf-spawn contract (every spawn, both steps).** A spawned agent inherits none of your loaded skills, and each clause fails **silently** when omitted. **Render it, don't compose it — [`run-state.mjs spawn-contract <slug> <unit> --kind producer|fix|review`](scripts/run-state.mjs) fills every clause from state and prints a block to paste** (exit 4 = state is missing a clause; fix the state): a composed contract decays across a run. Each clause in full, with its failure mode: [references/spawn-contract.md](references/spawn-contract.md).
-
-- **(a) Read the skill** — `<skillsRoot>/<skill>/SKILL.md`, **absolute**, resolved at [pre-flight](references/pre-flight.md) step 0.
-- **(b) Name the proof** — an artifact the next step verifies; output without it did not run the skill.
-- **(c) Use the harness's own agent primitive** — one whose result returns *into this session as a value*. A launch with no result channel back (detached job, background CLI, queued task) does not qualify.
-- **(d) Pass the model *and* its effort** — `models.<slot>` + `models.<slot>Effort` (absent = `high`). A slot is an operating point, not a model.
-- **(e) Pass the working directory** — the **unit's own** `units[].workspacePath`, never yours; unset, the spawn inherits *your* cwd and writes into the tree you coordinate from. Every code-writing spawn, every round — and a fix round gets the **same** path its producer used.
-
-**A spawn that dies mid-flight leaves a partial, and the partial beats a clean slate** — point the replacement at the same path. But a partial is **never** proof: `status: in-progress` counts as missing for every gate.
-
-**Fan-out (opt-in, Workflow harness):** read-only/advisory stages only — prior-art and independent review — via `workflows/`; anything that writes code or hits a human gate stays in the main loop ([references/fan-out.md](references/fan-out.md)). An epic's *implementers* are plain depth-1 spawns either way, concurrent up to the in-flight cap, each in its own unit's workspace.
-
-## Pre-flight (once, before intake — never mid-run)
-
-**Before creating or resuming a run, use [`run-state.mjs init|resume`](scripts/run-state.mjs).** That lifecycle boundary runs `engineering-runtime`'s read-only Workflow coherence verifier first: an incoherent, unavailable or malformed verdict fails closed with structured findings and a generated repair recipe it never executes. Inspection commands stay available for diagnosis.
-
-Read [references/pre-flight.md](references/pre-flight.md) and run its seven steps (0-6) — **once**, before intake, never mid-run. One neutral question batch through [`scripts/preflight-questions.mjs`](scripts/preflight-questions.mjs); invoke only the calls it plans; record the completed patch atomically (a cancelled gate records nothing). The non-negotiables it elaborates rather than replaces:
-
-- **Models** — the **implementer** is asked with alternates shown; the **reviewer is filled from the ranking, never asked**, and stated in the gate. **Reviewer ≠ implementer** is hard; a slot is an **operating point** (model + banked `models.<slot>Effort`). **No silent fallback:** read back the model each spawn ran on (`units[].implementationModel` when it differs) — a reviewer read-back ≠ the confirmed model voids the verdict for guarantee 2.
-- **Everything else is probed or filled, never assumed mid-run** — `targetBranch` from fetched remote heads; `deliveryMode` + `queueProvider` + `enqueueTrigger` from [`detect-delivery-mode.mjs`](scripts/detect-delivery-mode.mjs), UNKNOWN being a human ask; `autonomy` **filled** as `autonomous` by [`preflight-questions.mjs`](scripts/preflight-questions.mjs) (stated, overridable to `supervised`), subsuming `mergeShippable`, lifting neither the design gate nor the breaker's `descope` or ceiling. Where a repo auto-merges on its conditions, **posting the verdict as an approval *is* the merge** — ask [`run-state.mjs approval-gate <slug> [componentId]`](scripts/run-state.mjs) first.
-- **Design first** — pre-flight **skims for units that already owe a design and hands them back** before anything else is settled.
-
-An outer orchestrator that already ran an equivalent gate → inherit, don't re-prompt.
-
-## The loop (per unit)
-
-Loop each unit through these three steps until the review passes — all three in [references/loop.md](references/loop.md).
-
-| Step | What it does | Ends when |
-|---|---|---|
-| 1 — Produce | One spawn: implement + e2e + gates + PR | A PR exists carrying its Review Contract |
-| 2 — Review ∥ CI | Independent review on a **different model**, same breath as CI, same HEAD | A verdict lands: PASS / NEEDS_CHANGES / FAIL / BLOCKED |
-| 3 — Fix, then loop | Address the verdict, then re-review the delta | The review PASSes — preserve it and update the component candidate |
-
-## Promotion / release lane
-
-A unit PR based on a production branch is a **promotion**, not a feature PR: fast-forward required (review-pr § Promotion PRs), gate on the promoted SHA's already-green PR-lane result, and read-only smoke (under a read-only production profile, `prod-preview`/`prod-active`) against a 0%-traffic candidate before any traffic shifts. Full releases belong to `resolve-release`.
-
-## Definition of done (handoff)
-
-**Run the operations emitted by `run-state.mjs next <slug>`.** For a delivered combined component with distinct published unit PRs, `next` first emits `reconcile-contained-unit-prs`: it freshly fetches `origin/<targetBranch>`, verifies the live combined PR at its recorded merge SHA, compares every live unit PR exact head with the component's recorded reviewed-unit evidence, and closes only open heads proved contained in the fresh target. Drift, missing ancestry, or unreadable state leaves that unit PR open and blocks finalization; terminal unit PRs are recorded no-ops.
-
-**Then run `run-state.mjs finalize <slug>`.** This remains the only completion transition. It independently fetches the target again, proves every delivered merge SHA is an ancestor, verifies issue and PR terminal states live, restores `originalBranch`, and applies the fail-closed workspace reap — refusing on any unresolved unit, stale GitHub state, missing ancestry, or preserved unpublished work. On success it writes immutable `finalization` evidence and prints the canonical handoff from that validated state.
-
-**Do not retype that handoff or replace it with a prose completion claim.** `run-state.mjs progress <slug>` is the standing progress report, never a completion gate; [the profiler](references/postmortem.md) is an explicitly invoked, non-blocking diagnostic that authorizes nothing.
-
-Three rules the generated handoff exists to enforce:
-
-- **A component whose members are `merge-ready` owes one terminal `components[].delivery.outcome`** — `merged` with a verified component `mergedSha`, or `handed-back` with the blocking condition. Member units derive dispositions through `deliveryRef`; a member with neither canonical nor legacy evidence is reported **undelivered, never done**.
-- **Merge only what `mergeShippable` authorizes, and only into `targetBranch`.** Never promote to production — that is `resolve-release` with its own authorization.
-- **Reap the workspaces last**, through `finalize`, after every unit branch is pushed — removing them first destroys what was never published. **Never `--force` a worktree removal and never delete one by hand**: preserved unpublished work blocks finalization and stays on disk, and a forced removal is the one action in this loop that destroys work no gate can recover. On a `worktree` run the **orchestrator's own checkout is removed separately, after the reap**, and only once the finalization record exists.
-
-What the handoff reports per unit, and how to read the round profile: [references/finalization.md](references/finalization.md).
-
-## The removal path (keep this skill small)
-
-This skill accretes, so every new gate/artifact/validator must name the incident it would have caught in the same commit and in [references/why.md](references/why.md). Recommend retirement only from a configurable durable cross-run window of readable executions with zero unique findings and zero rejections; one clean run is never enough, and `not run`, `skipped`, or `unreadable` breaks the streak. Fingerprint findings by stable `class + locator`, keep value separate from raw volume, and leave every retirement decision to the human. Process weight is a regression ([regression checklist](references/regression-checklist.md)). → [why](references/why.md#the-removal-path) Editing this skill? Run the sandbox self-test first: [references/sandboxed-testing.md](references/sandboxed-testing.md).
-
-## Reference Map
-
-**`run-state.mjs guide [what you are trying to do]`** — 29 routed answers, each naming the reference
-that owns it and the script that runs it. `guide` with no query lists them all; `--json` for a
-machine-readable answer. It needs no run and no manifest.
-
-```
-run-state.mjs guide reap          # -> references/interference.md, scripts/workspaces.mjs
-run-state.mjs guide breaker       # -> references/breaker.md, run-state.mjs diagnose-breaker
-```
-
-This table used to live here, at 24 rows and 3.6KB of a file that is loaded into **every** run
-whether the table is consulted or not — and it is consulted one row at a time, when you already
-know what you are doing next. That is a query, not doctrine. The [phase routing](#routing-read-this-first)
-above stayed, because it is read once at the start and is what makes a truncated read survivable.

package/skills/engineering/resolve-issues/agents/openai.yaml

@@ -1,9 +0,0 @@
-interface:
-  display_name: "Resolve Issues"
-  short_description: "Slash/explicit-only orchestrator: issues/epic → merge-ready PR(s)"
-
-policy:
-  # Codex counterpart to SKILL.md disable-model-invocation: true
-  # (Claude Code / Pi). Keeps $resolve-issues / explicit invoke; blocks
-  # description-based auto-selection.
-  allow_implicit_invocation: false