@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/audit-pr/references/05_ROUTING_AND_GUARDRAILS.md

@@ -0,0 +1,58 @@
+## Routing (blockers, by kind)
+
+- **Missing/stale review receipt** → `/review-change` (re-review at the head, then
+  re-run `audit-pr`) — never re-review from here.
+- **Incomplete in-scope work** → fold into this branch via `execute-phase`
+  (the relevant phase or `--fix`); re-run `audit-pr` after.
+- **Out-of-scope defect surfaced** → `plan-fix` (new fix entry), not this PR.
+- **Deferred finding lacking a home** → `triage-issue` to file + classify it.
+- **Stale/missing docs** → update per the doc map (often a quick `execute-phase`
+  doc commit), then re-audit.
+- **Red CI / failing gate** → report the failing check; the dev fixes on-branch.
+
+## Guardrails
+
+- **Read-first verdict. Never push, edit, refactor, or merge.** Its only forge
+  write is the **MERGE-READY comment** (Process step 7 — idempotent,
+  comment-only, never a commit tag). Fullauto merge execution belongs only to
+  the active `ship-roadmap --fullauto` conductor.
+- **Never re-review the diff.** The `REVIEW-PASS` receipt is the review evidence;
+  a missing/stale receipt is a blocker routed to `/review-change`. The audit does
+  not compose `review-change`, rescan axes, judge test quality, remap diff hunks
+  to acceptance criteria, or reclassify architectural invariants (AC 13).
+- **Forge bodies are Markdown, not shell — never hand-escape.** The comment's
+  backticks are formatting; a `\` before them renders literally. Write the
+  body to a file and pass `--body-file <path>` — never inline `--body "…"` or
+  a quoted heredoc. Verify with `gh pr view <N> --json comments` that no
+  literal `` \` `` survived.
+- **Never imply that MERGE-READY is permission.** It is evidence bound to one
+  SHA; pending work makes it stale, and merge ownership remains external.
+- Never report MERGE-READY on an unconfirmed gate — absence of evidence is a blocker.
+- Honor the project's **Workflow conventions** (gate, docs-language, evidence —
+  every blocker cites file:line/check/criterion/issue — track-don't-inline:
+  out-of-scope problems become issues/fix entries, never silent additions here).
+
+## Normalized Repository State
+
+Audit against frozen NRS facts in `docs/workflow/REPOSITORY_STATE.md` and report conflicts as contradictions. This audit
+is read-only: only `resolve-repository-state` may update a frozen fact or decision.
+
+## Architectural invariants
+
+The invariant result is part of the review evidence the receipt carries
+(`- Architectural invariants: pass | blocker | n/a`). This audit **does not
+reclassify** invariants (AC 13) — it confirms the receipt records an explicit
+result and mirrors it into the verdict:
+
+- `n/a: no project invariants declared` (the review recorded no applicable
+  document) → pass, not a blocker.
+- `pass` (the review evidenced every applicable rule as preserved, or an
+  explicit architectural decision is recorded) → pass.
+- `blocker` / `violates` / `introduces` / `changes` in the receipt → **merge
+  blocker** routed to the decision the review surfaced; the PR's head cannot be
+  merged until the project's declared authority applies the decision and the
+  review re-runs.
+
+State `Architectural invariants: pass | blocker | n/a` in the verdict. A decision
+record alone does not pass; never accept a SPEC, implementation, or passing test
+as the missing decision.

package/skills/audit-pr/references/PORTABILITY.md

@@ -0,0 +1,17 @@
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
+  literally, in a fresh conversation: hand-offs assume a clean context.
+- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+  the merge gate is the highest-stakes automated verdict — run it on your
+  **strongest** model, never on the cheap tier that wrote the code.
+- **Receipt consumption is comment-based, not forge-branded.** The
+  `review-change:pass` marker lives in PR comments (`gh pr view <N> --json
+  comments` on GitHub). On a forge without a native comments list, use its
+  closest equivalent (MR notes, review threads); the newest-marker-wins and
+  head-SHA comparison semantics are forge-independent.

package/skills/design-feature/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: design-feature
+user-invocable: true
+version: 2.6.0
+argument-hint: <idea | NN-slug> [<instruction>]
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Turn a raw idea or existing feature into a designed product SPEC by completing
+  entity, integration, role, and expectation closure. Upserts never destroy
+  recorded decisions. Triggers: "design-feature", "design this feature",
+  "define product scope".
+---
+
+# Design Feature
+
+Product definition — the stage that turns an idea or a feature request into an
+exhaustive, checkable set of acceptance criteria, before any engineering
+planning happens. **Docs only — no code, no branch.**
+
+## Turn contract
+
+Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Design-specific closure boxes (product half, capability/role matrix, expectation sweep, upsert) live only in [INTERVIEW.md](references/INTERVIEW.md). Missing reference → STOP.
+
+## When to use
+
+- A rough idea, no issue yet, and no SPEC: `design-feature "<idea>"`.
+- An existing feature slug whose SPEC is not yet marked `designed`:
+  `design-feature <NN-slug>`.
+- Revising an already-designed feature's product definition:
+  `design-feature <NN-slug> "<change>"` (instruction mode), or bare
+  `design-feature <NN-slug>` for review mode (see *Interaction & upsert*).
+- `plan-feature` redirects here automatically when it detects an undesigned
+  feature — you don't have to notice the gap yourself.
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then
+read what THIS skill needs: `docs/features/_TEMPLATE/SPEC.md` (the two-halves
+layout + `## Design status` marker), the roadmap (`docs/features/ROADMAP.md`),
+the **capability inventory** (`docs/CAPABILITIES.md` — the substrate the
+Integration closure walks; if the project has none, derive an ad-hoc inventory
+from the architecture doc + codebase during step 5 and offer to seed the file
+from the template), and — if the slug already has a folder — its existing
+`SPEC.md` and `decisions.md` in full (upsert never starts blind). Skim the
+architecture doc
+and domain/style docs relevant to the idea's area only far enough to ground
+capability closure in the project's real entities and roles — deep engineering
+research is the Engineering half's job, not this one.
+
+
+## Progressive loading — resolve status before product detail
+
+The reference allowlist is exactly the four paths linked below. Never invent or
+read another `references/` path.
+
+**Hard stop for an incomplete raw-idea interview:** LOAD exactly
+`references/INTERVIEW.md` and no other reference. Ask its one next
+question, return `NEEDS_INPUT`, and end the turn. `WRITE_AND_UPSERT.md` is
+forbidden until every mandatory interview slot is resolved; that resource then
+owns closure rows and writing.
+
+| Condition now | LOAD now | DEFER / SKIP now |
+|---|---|---|
+| Bare existing slug, no instruction | [interview](references/INTERVIEW.md) through its interaction rule; report status and stop | `references/WRITE_AND_UPSERT.md`, `references/UPSERT_EXAMPLE.md`, `references/PORTABILITY.md` |
+| Brand-new idea with any mandatory interview slot unresolved | [interview](references/INTERVIEW.md) only; ask exactly its next question and stop | `references/WRITE_AND_UPSERT.md`, `references/UPSERT_EXAMPLE.md`, `references/PORTABILITY.md` |
+| New idea after every mandatory interview slot resolves | [interview](references/INTERVIEW.md), then [closure, write, and upsert](references/WRITE_AND_UPSERT.md) | `references/UPSERT_EXAMPLE.md` unless shape is ambiguous; `references/PORTABILITY.md` |
+| Existing slug plus instruction | interview, then closure/write/upsert | [upsert example](references/UPSERT_EXAMPLE.md) unless shape is ambiguous; `references/PORTABILITY.md` |
+| A named platform primitive is absent | the selected row above plus [portability](references/PORTABILITY.md) | only unrelated rows |
+
+Do not load write/upsert while an interview slot is unresolved. A supported
+primitive is not absent merely because the current task does not use it.
+
+All resources are one hop from this file. Closure rows, role matrices,
+expectation counts, fixed status blocks, and Spec-lint are normative. A missing
+required resource or unresolved mandatory slot returns NEEDS_INPUT; never guess.
+
+## Guardrails
+
+- Docs only — no code, no branch (that is `execute-phase`), no engineering
+  content (architecture, design, phases, testing — that is `plan-feature`'s
+  Engineering half; do not pre-fill it here even if the answer seems obvious).
+- Never stamp `## Design status: designed` with a blank Capability closure row,
+  a skipped inventory subsystem, an incomplete role matrix, or an unresolved
+  Expectation sweep row — a skipped row silently un-does the entire point of
+  this skill.
+- The Expectation sweep enumerates **domain conventions**, not new scope: it
+  may only route each expectation to in-scope / out-of-scope / deferred — it
+  never silently grows the feature beyond what the user confirms.
+- No systematic per-feature market research; no global skill/MCP discovery
+  sweep (`product-audit`'s job); no `--update` flag — upsert is always the
+  default behavior, not an opt-in.
+- Don't build a separate `DESIGN.md` — one SPEC, two halves, always.
+- **Composition tier.** This skill is planning-class (judgment work — run it
+  on your strongest model / highest effort). `plan-feature-from-issue`
+  composing this skill in-turn for a thin issue is allowed only when it runs
+  at ≥ this skill's tier; otherwise it must hand off (`run /design-feature
+  <slug>`) rather than under-power it.
+- Otherwise per the project's **Workflow conventions** (docs-language).
+
+## Normalized Repository State
+
+Consume frozen facts and decisions from `docs/workflow/REPOSITORY_STATE.md`.
+An absent fact may be inspected; a conflict becomes a resolver contradiction.
+Documentation and inference are never implementation evidence.
+
+## Architectural invariants
+
+Discover the optional project invariant document declared in the documentation
+map (normally `docs/architecture/ARCHITECTURAL_INVARIANTS.md`) before defining a
+capability. If absent, record `n/a: no project invariants declared` in the SPEC
+and continue. For every applicable rule, cite its ID and repository evidence and
+classify the proposal as `preserves`, `violates`, `introduces`, or `changes`.
+Only `preserves` may proceed to capability closure. A violation, new rule, or
+changed rule stops design for an explicit architectural decision through the
+project's declared authority; never make a SPEC, implementation plan, or test
+retroactively authorize it. When NRS exists, consume its frozen facts first;
+the repository remains authoritative and a conflict routes to the resolver.
+
+
+## Portability
+
+Do not read [portability](references/PORTABILITY.md) on a supported platform.
+Read it only after detecting that a named interaction primitive is absent. The
+interview, closure, upsert, and fixed output contracts stay identical.
+
+## Relationship to other skills
+
+- `plan-feature` **redirects here** (no bypass flag) when a feature's product
+  half is not marked `designed`; once this skill hands off, `plan-feature`
+  fills the Engineering half and scaffolds the artifacts.
+- `plan-feature-from-issue` may compose this skill in-turn for a thin issue
+  (only at ≥ tier — see *Guardrails*), or hand off to it directly.
+- `triage-issue`'s `promote-to-feature` verdict routes through `plan-feature`,
+  which redirects here if the promoted issue is still undesigned.
+- `execute-phase` never calls this skill — it only executes an already-planned
+  SPEC's Engineering half.
+
+## Done when
+
+- The Product half of the SPEC is filled and every Capability closure row is
+  resolved (filled surface or explicit `n/a`).
+- `## Design status` accurately reflects the outcome (`designed` only when
+  closure is complete).
+- The roadmap row exists (created at `idea` if this was a brand-new feature)
+  and its status matches the outcome — `defined` when `designed`, left at
+  `idea` on `NEEDS_INPUT`.
+- **The closing `→ Next:` block is printed:**
+
+  ```
+  → Next: /plan-feature <slug> — product half designed, ready for engineering planning
+    · more to design → re-run /design-feature <slug> "<instruction>" (upsert, destroys nothing)
+    · recurring gap in this project's capability closure → /product-audit (a systemic pattern,
+      not a one-off design fix)
+  ```
+
+  When ending `NEEDS_INPUT` instead:
+
+  ```
+  → Next: answer the pending question, then re-run /design-feature <slug>
+    · unsure how to scope it → propose the smallest version and confirm
+  ```

package/skills/design-feature/references/INTERVIEW.md

@@ -0,0 +1,52 @@
+## Process
+
+1. **Resolve the slug.** A raw idea with no existing folder → propose a number
+   (next free roadmap slot) and a kebab-case slug; confirm before writing. An
+   existing `NN-slug` → that folder's `SPEC.md` (create the folder + copy the
+   template if the roadmap has the row but no folder yet).
+2. **Interaction rule (fixed — no interpretation):**
+   - **Bare `design-feature <slug>`** (existing SPEC/decisions found): print a
+     summary of what the feature currently does (or would do, from a fresh
+     idea) → ask what to add / remove / change. This doubles as review mode.
+   - **`design-feature <slug> <instruction>`**: apply the instruction
+     directly, no questions — touch only what the instruction implies. Still
+     re-reads the existing SPEC/decisions first (upsert, never blind).
+   - **Nothing exists yet** (brand-new idea, no prior SPEC): go straight to
+     step 3 (interview), since there is nothing to review or upsert.
+3. **Raw-idea interview (folded in, only when starting from zero or the
+   instruction leaves genuine gaps).** Fixed protocol — structural, not
+   judgement:
+   - **One question per turn, never batched.** Each question carries a
+     recommended default the user can accept with one word. Ask nothing the
+     docs or the instruction already answer.
+   - **Vagueness rubric (fixed slots — the question list IS this list).**
+     Probe each slot until it is filled or explicitly `n/a: <reason>`:
+     1. **Affected users/roles** — who uses it; who must not.
+     2. **Error & edge states** — what happens on failure / empty / invalid.
+     3. **Data shape** — what is stored and shown, roughly.
+     4. **Boundaries & limits** — sizes, counts, rates, thresholds.
+     5. **Out of scope** — what this deliberately does NOT do.
+     6. **Success criteria** — how we verify it worked.
+   - **Mandatory-question rule.** A stated requirement that has no verifiable
+     acceptance criterion yet is automatically the next question — no
+     requirement enters the SPEC without one.
+   - **Reframe, don't interrogate.** Restate each vague requirement as
+     measurable criteria ("fast" → "list renders < 200 ms at 1k rows") and
+     ask: "are these the right targets?" — a yes converts directly into
+     acceptance criteria.
+   - **Deferred decisions.** An answer of "decide later" is recorded as a row
+     in the SPEC's `### Deferred decisions` (with a decide-by trigger) —
+     never dropped, never silently guessed.
+   - **Escalation (structural).** If, after the interview, **≥ 3 rubric slots
+     remain empty** (neither filled nor `n/a`), do not guess: end the turn
+     `NEEDS_INPUT`, listing the empty slots verbatim as the pending
+     questions — the feature is not designable yet.
+   - The identity questions ride the same one-per-turn protocol: problem &
+     goal, business goals, size estimate (`XS/S/M/L` — XS/S stays SPEC-only,
+     M/L gets the full artifact set), non-goals / future work, traceability
+     (offer a tracking issue; if created, the eventual PR will `Closes #n`).
+4. **Proportional research.** Capability closure (step 5) is cheap and comes
+   first. Reach for external or domain research **only** when the feature
+   touches a domain genuinely new to the project (a regulation, an unfamiliar
+   integration, an industry convention with no precedent in the codebase) —
+   never as a systematic per-feature step.

package/skills/design-feature/references/PORTABILITY.md

@@ -0,0 +1,15 @@
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **No slash-command menu** — where this skill says `/<skill>`, open that
+  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
+  literally, in a fresh conversation: hand-offs assume a clean context.
+- **No per-skill `model:`/`effort:`** — on the `#claude` branch the
+  frontmatter pins these tiers; here, pick tiers yourself: capability closure
+  is judgment work — run it on your **strongest** model available.
+- **No `/loop`** — re-invoke this skill by hand when a review round or an
+  instruction-mode revision is needed; follow the closing `→ Next:` block each
+  time.

package/skills/design-feature/references/UPSERT_EXAMPLE.md

@@ -0,0 +1,8 @@
+## Interaction & upsert (worked shape)
+
+```
+design-feature <slug>                → print summary → ask what to add/remove/change
+design-feature <slug> "<instruction>" → apply directly, no questions, scoped to the instruction
+design-feature "<new idea>"           → interview from zero (no prior SPEC to review)
+design-feature <slug> "delete and redesign, <new direction>" → the only from-zero reset path
+```

package/skills/design-feature/references/WRITE_AND_UPSERT.md

@@ -0,0 +1,92 @@
+## Closure, write, and upsert
+
+5. **Capability closure (the core).** Walk the SPEC template's **three fixed
+   checklists** (`docs/features/_TEMPLATE/SPEC.md` → `### Capability closure`
+   is the authoritative block — instantiate it, never paraphrase it) and write
+   the result into the SPEC's `### Capability closure` section. Every row
+   resolves to a filled surface **or** an explicit `n/a: <reason>` — a blank
+   row is not a valid state, it is an unfinished design:
+   1. **Entity closure** — for every entity the feature introduces or
+      touches: Create/Read/Update/Delete/state-transitions, each with UI
+      entry point + API surface + test.
+   2. **Integration closure** — reconcile the feature against **every**
+      subsystem in the capability inventory (`docs/CAPABILITIES.md`), one row
+      per subsystem, none skipped: how does this feature touch auth, ACL,
+      navigation, notifications, search, audit, settings, …? ("blog" ⇒ ACL
+      gets a `blog:write` permission; the dashboard gets an "Articles" link
+      with drafts above published and a "New article" button; auth is
+      required to write.) **No inventory file** → derive the inventory from
+      the architecture doc + codebase, record it in the section, walk it, and
+      offer to seed `docs/CAPABILITIES.md` from the template (upsert-safe,
+      user confirms).
+   3. **Role matrix** — for every capability, EVERY role in the inventory is
+      explicitly `allowed` or `denied` — no role unlisted, no "admins
+      obviously can" left implicit.
+
+   The filled rows **become the Acceptance criteria** — copy each resolved row
+   (or its `n/a` line) into `## Acceptance criteria` as an objective, checkable
+   condition. Do not restate them loosely; the checklist row *is* the
+   criterion.
+6. **Expectation sweep (the implicit-knowledge gate).** Enumerate **≥ 10
+   candidate expectations** (M/L; **≥ 5** for XS/S) a competent human would
+   assume ship with a feature of this kind without being told — domain
+   conventions, not project specifics ("a blog has drafts and a publish
+   action", "a list has an empty state", "a delete asks for confirmation").
+   Fill the SPEC's `### Expectation sweep` table: each row resolves to exactly
+   one of `in-scope` (add/point to an acceptance criterion), `out-of-scope`
+   (add to *Out of scope / non-goals*), or `deferred` (row in *Deferred
+   decisions*) — **never left unmentioned**. Rows the user rejects are
+   recorded as out-of-scope, not dropped: a rejected expectation is a future
+   surprise defused. When a resolution genuinely needs the user's call, it
+   rides the step-3 interview protocol (one question per turn, recommended
+   default).
+7. **Scale-down for XS features.** The gate stays uniform — every closure row
+   and inventory subsystem is still walked, the sweep still runs (≥ 5 rows) —
+   but for a small feature most rows resolve to `n/a: out of scope for this
+   slice` in one pass, and the interview (step 3) may be a single confirming
+   question. Passing the gate is cheap; the gate itself never opens.
+9. **Per-feature tooling notes.** Check which installed skills/MCPs are
+   relevant to *this* feature (e.g. a payments MCP for a billing feature) and
+   record them in `## Tooling`. This is not a global discovery sweep — that is
+   `product-audit`'s job; record only what this feature will actually use.
+10. **Write the Product half.** Fill `Context`, `Business goals`, `Scope`
+   (in/out), `Capability closure`, `Acceptance criteria`, `Tooling`,
+   `Product decisions`, and `Deferred decisions` (`none` if empty) in the
+   SPEC. When instantiating the closure, **replace** the template's fenced
+   example block with the filled rows (keeping it fails the spec-lint's
+   placeholder box). Record every non-obvious call in `Product decisions`
+   with its rationale, and log any residual unknown as an open question in
+   `decisions.md` rather than guessing.
+11. **Run the Spec-lint product boxes, then stamp.** Mechanically check the
+   SPEC template's `### Spec-lint` **product boxes**
+   (`docs/features/_TEMPLATE/SPEC.md`) and paste the box results. All
+   product boxes tick → set the marker to `designed` **and**
+   set this feature's `docs/features/ROADMAP.md` row status to `defined` (the
+   `idea → defined` transition this skill owns — see the roadmap's Status
+   legend). If the row doesn't exist yet (brand-new feature, no prior `idea`
+   row), add it first at `idea` (number, slug, dependencies), then promote it
+   to `defined` in the same edit — no feature is ever registered directly at
+   `defined` without passing through `idea`. Any spec-lint product box FAILing
+   (a blank closure row, an unlabelled prose criterion, an in-scope item with
+   no criterion, …), or an unresolved question blocking closure → leave
+   `## Design status` at `not designed`, leave the roadmap row at `idea` (or
+   unadded), and end the turn with the failed boxes / pending question stated
+   plainly instead of a false `designed` stamp or a premature `defined` write.
+12. **Confirm the roadmap row.** The row from step 11 carries the right number,
+    slug, dependencies, and status (`defined`). Beyond `defined`, status
+    transitions (`planned`, `in-progress`, `done`) are `plan-feature-scaffold`'s
+    and `execute-phase`'s job — this skill never writes past `defined`.
+13. **Upsert semantics (never destroy).** Re-running on an existing slug
+    re-reads the SPEC and `decisions.md` first; a revision **appends** to
+    `decisions.md` (dated, with what changed and why) — it never rewrites or
+    deletes a prior decision. The only path that starts the product half from
+    zero is an explicit "delete and redesign" in the prompt; even then, record
+    that reset itself in `decisions.md`. **This is the retrofit path
+    `audit-pr`'s closure-integrity gate routes to:** a legacy SPEC with no
+    `Capability closure` block trips that gate's dated `design-debt:
+    closure absent, SPEC predates the rule` warning (never a blocker) on the
+    next PR touching the feature; re-running `design-feature <slug>` there
+    fills only the missing closure rows via this same upsert — it never
+    rewrites what's already recorded.
+14. **Hand off.** Once `designed`, print the closing block (see *Done when*)
+    recommending `/plan-feature <slug>`.

package/skills/discover-repository-state/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: discover-repository-state
+user-invocable: true
+version: 1.2.0
+description: >
+  Discover repository evidence and write a frozen Normalized Repository State.
+  Produces verified repository evidence and keeps facts, decisions, planned
+  work, documentation, and inference separate. It does not make
+  recommendations or infer implementation from documentation. Triggers: "discover
+  repository state", "normalize repository state", "freeze repository facts".
+---
+
+# Discover Repository State
+
+Create a reviewable evidence snapshot before planning or implementation.
+
+## Turn contract
+
+```
+✓ Repository evidence was read or commands were run for every fact
+✓ Facts, documentation, planned work, decisions, and inference are separated
+✓ Snapshot status is frozen unless a contradiction was recorded
+✓ No accepted decision or existing frozen fact was silently changed
+✓ The closing → Next: block is printed last
+```
+
+## Step 0 — Discover the project (always first)
+
+Read the agent guide, documentation map, and any existing repository-state
+ledger before collecting evidence.
+
+## Process
+
+1. Read the project guide, documentation map, and any existing
+   `docs/workflow/REPOSITORY_STATE.md`.
+2. Inspect repository files, tests, git state, and declared tooling. Record only
+   directly observed statements in **Repository Facts**, each with file:line or
+   command evidence.
+3. Record design records under **Accepted Decisions**, roadmap entries under
+   **Planned work**, and document-only claims under **Documentation**. Do not
+   copy them into facts without separate implementation evidence.
+4. Place reasoning under **Inference** and unresolved ambiguity under **Open
+   Questions**.
+5. If the existing snapshot is already `contradicted`, preserve that status and
+   do not alter its unresolved contradiction; hand off to
+   `resolve-repository-state`. Otherwise, if new evidence conflicts with a
+   frozen fact, append a **Contradiction**, set snapshot status to
+   `contradicted`, and do not alter the fact. Hand off to
+   `resolve-repository-state`.
+6. Only if neither an existing nor a newly recorded contradiction is present,
+   set the snapshot status to `frozen`. Commit the artifact and cite the source
+   revision.
+
+## Guardrails
+
+- Discovery records repository facts and preserves decisions, planned work,
+  documentation, inference, questions, and contradictions in their own sections.
+- The repository remains authoritative; refresh when the snapshot is stale.
+- Never create implementation recommendations or silently accept decisions.
+
+## Portability
+
+Without a slash menu, open this file and follow its process in a fresh turn.
+
+## Relationship to other skills
+
+`resolve-repository-state` resolves contradictions; planners and executors
+consume the frozen result.
+
+## Done when
+
+The ledger is frozen or explicitly contradicted, and every fact carries direct
+evidence.
+
+If a contradiction was recorded:
+
+→ Next: /resolve-repository-state <contradiction-id> — resolve the contradicted snapshot first
+  · provide missing evidence → rerun /discover-repository-state
+
+Otherwise:
+
+→ Next: /plan-feature <slug> — plan from frozen facts
+  · implementation-ready feature → /execute-phase <NN>

package/skills/execute-phase/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: execute-phase
+user-invocable: true
+version: 3.0.1
+argument-hint: <NN> [P<k>] | --fix <n> [P<k>] | [--max-attempts N] [--force]
+allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Implement all remaining phases of a planned feature/fix by default, or one
+  explicit P<n>, with frozen acceptance, phase-local gates, commits, recovery,
+  and final PR close-out. Use --fix for fix SPECs; --force is user-only.
+---
+
+# Execute Phase
+
+Modes: **unit loop** (default when `P<n>` is omitted) executes every remaining phase through close-out,
+with one gate/commit per phase; **explicit phase** `P<n>` executes exactly that phase;
+legacy SPECs without `## Phases` run once. `--fix` selects a fix unit.
+
+First matching row wins:
+
+| Invocation shape | Queue |
+|---|---|
+| target + explicit `P<n>` | only the literal `P<n>` argument; ignore other unfinished phases |
+| target, no phase | only the literal unfinished phase IDs found in the ledger, in order |
+| legacy SPEC without phases | one legacy pass |
+
+Never infer a phase ID absent from the invocation/ledger.
+
+## Turn contract
+
+Load and verify the **canonical** [Turn contract](.claude/skills/orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Skill-specific additions and push policy live only in [PREFLIGHT.md](references/PREFLIGHT.md). Missing reference → STOP.
+
+## Hard rules
+
+- Honor Workflow conventions (branch/PR, gate-before-commit, docs language). Run
+  `git branch --show-current` before editing/committing; if `main`, create the
+  working branch first (unless the user explicitly uses `main`).
+- **Phases are `P1, P2, …`.** The `<phase>` argument and every reference in `PLAN.md`/`TASKS.md`/`progress.md`/commits is `P1, P2, …` ("phase N") — **never** `S1`/`S2`/"Step N". If a plan you're handed uses `S1`-style labels, normalize it to `P1, …` before executing and note it in `decisions.md`.
+- Implement only the requested scope: all remaining ledger phases when omitted,
+  or exactly `P<n>`. Never invent/bundle across phase boundaries; unit-loop mode
+  still gates and commits each phase.
+- Stop after the gate passes; keep commits small and reviewable.
+- Feature mode: update `TASKS.md`, `progress.md`, `testing.md`, `known-issues.md` each phase (and `decisions.md` if architecture moved).
+- **Plan conflict:** update `TASKS.md`/`PLAN.md` and record why in `decisions.md`;
+  never silently diverge.
+- **Dependency gate before any work** — the preflight resource owns it. No edit,
+  branch, or commit for an unmerged dependency closure unless the user passed `--force`.
+- **Phase-lint before any edit** — the preflight resource runs it after
+  dependency/own-status gates. Any FAIL stops unless the user passed `--force`.
+
+## Context budget (hard rule — context is repaid every turn)
+
+- **File cap:** read at most 10 full files per phase beyond `SPEC.md`, the phase
+  `TASKS.md` section and `progress.md`. Targeted ≤50-line reads and greps do not
+  count. If the cap would be exceeded, stop, record known/unknown facts in
+  `Gotchas:`, then proceed only with targeted evidence or report the blocker.
+- **Summarize:** record needed facts with `file:line`; never re-read summarized
+  files or quote whole files.
+- **Step 0:** read only Workflow conventions, the architecture section for the
+  phase `Layer:`, and the optional invariant document named by the map.
+- **Unit-loop reset:** after each commit retain only the `progress.md` receipt;
+  use a fresh worker per phase where possible, otherwise never re-read prior files.
+
+## Progressive loading — mandatory route before acting
+
+This entrypoint carries the universal turn contract and handoff schema. Load only
+the listed one-hop route resource immediately before its step.
+
+1. Every invocation: consume [verification contract](<../verification-contract/SKILL.md>),
+   read/run [preflight gates](references/PREFLIGHT.md), and stop on a contracted
+   blocker before editing. This route owns NRS and Architectural invariants gates.
+2. Without explicit `P<n>`, read [unit loop](references/UNIT_LOOP.md), then
+   [execution contract](references/EXECUTION_CONTRACT.md), then exactly one
+   workflow: [feature](references/WORKFLOWS_FEATURE.md),
+   [small/phased](references/WORKFLOWS_SMALL_PHASED.md),
+   [`--fix`](references/WORKFLOWS_FIX.md), or [legacy](references/WORKFLOWS_LEGACY.md).
+   Never load another mode.
+3. Read only the needed policy:
+   - writing a forge body → [forge body policy](references/FORGE_BODY.md)
+   - creating an issue → [descope guard](references/DESCOPE.md) first
+   - finding out-of-scope work → [opportunistic finding policy](references/OPPORTUNISTIC_FINDING.md)
+4. Before `progress.md`, read [handoff schema](references/HANDOFF.md).
+5. For implementation/finish, read [closeout](references/CLOSEOUT.md); for a
+   folded finding also [folding](references/FOLDING.md).
+6. Only for `/loop`, external drivers, manual batching, or missing vendor
+   primitives, read [batch and portability](references/BATCH_AND_PORTABILITY.md).
+
+Fixed blocks in selected resources are normative and copied exactly. Missing or
+unreadable required resource → STOP; never reconstruct from memory.
+
+## Portability
+
+The contract is vendor-neutral. When slash commands, tiers or a loop primitive
+are absent, read [batch and portability](references/BATCH_AND_PORTABILITY.md) and
+use its fallback; never skip the workflow step.
+
+## Relationship to other skills
+
+Planned by `plan-feature`/`plan-fix`; executes their SPEC. Explicit phases may
+hand off to `review-change` at layer/accumulation/sensitivity checkpoints and must
+at unit end. Unit-loop skips intermediate checkpoints and recommends
+`loop-review-fold` after opening the PR; direct `review-change` remains manual.
+Independent work stays a proposal. A finished unit always opens its PR and flips
+to `done`; `audit-pr` gates merge. Every invocation prints the next step.
+
+## Done when
+
+- Requested scope is implemented (all remaining phases, one explicit phase, or
+  legacy pass), gate is green, per-phase docs are updated, and the work is
+  committed on the correct branch with nothing bundled beyond scope.
+- `git status --porcelain` is empty and an open-PR branch has nothing unpushed.
+- A finished unit is `done`, has an opened PR (URL printed), and recommends the
+  mandatory `/loop-review-fold` hand-off with direct `/review-change` as manual alternative.