@gtrabanco/pi-agentic-workflow 0.36.0 → 4.10.0

package/skills/triage-issue/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: triage-issue
 user-invocable: true
-version: 2.12.0
+version: 4.10.0
 argument-hint: <issue-number> [more issue numbers…] | <audit-id> F<k> [F<j>…] | --prioritize-now <unit> F<k> [F<j>…]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -60,6 +60,11 @@ first on purpose).
 
 ## Step 0 — Discover the project (always first)
 
+**Backlog-sweep citation (S9 c, from #218).** Every newly opened issue must
+cite its backlog-sweep `Checked:` line in the body — procedural, auditable
+after the fact. When triaging a new issue on behalf of the user, the body
+includes a `Checked: <what was searched>` line.
+
 Per the agent guide's **Workflow conventions** + **documentation map**, then read
 what THIS skill needs: the fix index (e.g. `docs/fix/README.md`) and fix SPEC
 template, and the roadmap. **Retrieval aid (optional, never authoritative):**
@@ -102,6 +107,9 @@ audit findings and fold ledger.
 
 ## Guardrails
 
+- The all-stages no-assumption rule binds verification work — **ask-don't-infer**,
+  owner `skills/unit-lane/references/DESIGN.md` (`ask-dont-infer@1`): a trigger
+  the tree does not evidence is checked and asked about, never assumed.
 - Don't build deferred work just because asked to "look at" the issue — surface
   that the trigger is unmet and stop.
 - Keep issues, the fix index, and docs in sync with reality.

package/skills/triage-issue/references/LABELS.md

@@ -81,3 +81,25 @@ verdict — never a separate, silent step:
 A **fix-now** verdict is unchanged by this section — it gets no disposition
 label (it is tracked via the fix index + its route, and its high-severity
 case already gets the urgency label above).
+
+## Review-gate label vocabulary (human-owned)
+
+Not a verdict this skill reaches: this label is a **human's hold**, applied when
+an agent's plan, report or change set needs a look before more work builds on top
+of it. Issues, unit docs and PRs are held equally.
+
+| Label | Color | Meaning |
+|---|---|---|
+| `human-revision-needed` | `#FBCA04` | Hold — a human reviews before anything else is planned, implemented or merged. |
+
+**Ownership is inverted here, and that inversion is the invariant.**
+`triage-issue` neither applies nor clears it, because the label's whole value is
+"a machine may not declare its own work reviewed". An agent **may** apply it (and
+must then stop) with the same create-if-missing call as above:
+
+1. `gh label create human-revision-needed --color FBCA04 --description "<one-line meaning>"` — an "already exists" error is success.
+2. `gh issue edit <N> --add-label human-revision-needed` (or `gh pr edit <N> --add-label …`).
+
+No skill and no agent ever removes it: `--remove-label human-revision-needed` is
+a human's act only. A verdict comment never substitutes for the label — presence
+is the signal, and the absence a human creates is what releases the hold.

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 2.5.1
+version: 4.10.0
 argument-hint: <NN-slug | "<idea>"> [--retriage] | --fix <issue-number> | --from-issue <issue-number>
 description: >
   One-shot lane conductor for a delivery unit: triage, implement, evidence, and
@@ -102,7 +102,8 @@ create it from the tree the unit belongs to:
 For `--fix`/`--from-issue`, read the tracked issue in the forge first and keep
 its number; the folder name carries it (`fix/<issue-number>-<topic>`). Fill
 objective, why, user outcome, and non-goals from the invocation (or the issue).
-Acceptance criteria are induced from user scenarios — **ask-don't-infer**; if the
+Acceptance criteria are induced from user scenarios — **ask-don't-infer**
+(owner: `references/DESIGN.md`, block `ask-dont-infer@1`); if the
 request is too vague, STOP and ask the user with concrete options. Open
 decisions that are not acceptance criteria run through the design step's
 **gap interview** — one batched form-turn with recommended options + why,
@@ -117,7 +118,25 @@ its stdout block **verbatim** into the unit doc's Evidence section header under
 a `## Triaged steps` heading. This block is authoritative. The model never
 re-derives, reorders, or invents steps — it executes only what the catalog says.
 
-### 3. Execute triaged steps in order
+### 3. Forward closure + retirements (design/plan steps)
+
+The two steps that own this are their reference files, not this conductor —
+§4 below links both. The rule is duplicated here for nobody:
+
+- the **design** step carries the three-direction closure (backward: the
+  constraints in force; sideways: callers and consumers of what changes;
+  forward: every promise coined, behind the **ask-don't-infer**
+  (owner: `references/DESIGN.md`, block `ask-dont-infer@1`) and
+  **document-or-don't-coin** gates) and the **retirements** the unit declares.
+- the **plan** step turns every declared retirement into its own task carrying
+  the negative-capability pin, the sweep grep and the before/after reference
+  count.
+
+This section states only that the two steps carry it. The text lives with the
+step that executes it, so a model running `design` reads the rule instead of a
+copy of it — and cannot read a stale copy.
+
+### 4. Execute triaged steps in order
 
 For each step the triage returned, follow its reference file. Judgment steps
 (research, design, plan, evidence, docs, review) run inline, **one step per
@@ -155,14 +174,14 @@ survives only as an explicit operator choice. When the last phase's turn
 closes, `execute-phase` resumes the lane and the remaining judgment steps
 (evidence, review, docs, release) run here.
 
-### 4. Diff-size guard (after each implement step)
+### 5. Diff-size guard (after each implement step)
 
 Run `bun scripts/diff-guard.mjs --base <last-reviewed-ref> --unit <NN>`. Paste
 the output verbatim. On **BREACH**: stop, re-triage the unit, or record an
 exception. **Anti-gaming: NEVER shrink a diff by deleting comments, blank lines,
 docs or tests.** If the unit cannot fit the budget, record the exception and stop.
 
-### 5. Update evidence and progress
+### 6. Update evidence and progress
 
 Before every commit:
 
@@ -171,7 +190,7 @@ Before every commit:
 - **Progress log**: `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next:
   <what is next>`
 
-### 5b. Memory boundaries
+### 7. Memory boundaries
 
 Engram is the required memory substrate; a down layer never blocks a unit —
 follow [the memory protocol](references/MEMORY.md).
@@ -185,7 +204,7 @@ follow [the memory protocol](references/MEMORY.md).
   retry → `mem_get_observation` → the unit doc wins. A miss is keyword-bound,
   never proof nothing was saved; an unavailable mirror is marked pending.
 
-### 6. Close the unit — the close-out ladder
+### 8. Close the unit — the close-out ladder
 
 When all triaged steps are done, in order:
 

package/skills/unit-lane/references/DESIGN.md

@@ -48,7 +48,6 @@ repository has been asked.
    and cites the scenario or owner answer it came from.
 4. **Close boundaries**: entities and their roles, actors, accepted and rejected
    inputs (the expectation sweep), deferrals (→ `## Future`).
-
 Pass only if: ✓ the provenance search ran and its receipt is recorded ✓ every
 claim is a `sources.md` row ✓ every AC is induced from a user scenario.
 
@@ -77,6 +76,56 @@ Pass only if: ✓ every `INV-*` row carries a tier and a cost verdict ✓ every
 tier-0 row names the source that settled it ✓ no claim was researched or asked
 before the provenance tier ran.
 
+### Three-direction closure (S2, S6, S8)
+
+The provenance tier answers *what exists*; closure answers *what this change
+touches*, and each direction decides whether a question is left to ask.
+
+**Backward — constraints in force.** A design system's tokens/components with
+their `sources.md` evidence; with none, the precedent read from siblings.
+
+**Sideways — siblings of the mechanism.** What it receives changes → its
+callers. What it delivers changes → its consumers. Something is removed → what
+still uses it, asked before breaking (the sweep `fold-findings` runs on a defect).
+
+**Forward — promises coined.** Every name, field, endpoint or file is a
+`sources.md` row and a node another party references, behind two gates:
+
+- **ask-don't-infer** — an expectation in neither the tree nor the user's words
+  is a stage-3 question; a coined name with no owner answer is already a defect.
+  This is the design/plan case of the all-stages rule below —
+  `ask-dont-infer@1`, whose single normative owner is this file.
+- **document-or-don't-coin** — a new contract lands with the consumer-facing doc
+  its consumer will look for (the promise registry renders into this step's
+  output and the PR).
+
+**Retirements.** Every surface, token, pane, helper or contract this unit
+**retires**, with its replacement or no-consumer evidence; an empty answer says
+*why nothing can be removed*. Retirements are a design deliverable, not a
+review-time discovery — the plan step turns each into a planned task.
+
+### Third-party before homemade (#340)
+
+When the design reaches for code that solves a solved problem, a **widely
+community-supported library is the preferred option** over writing our own
+where a comparable option exists. Own code for a solved problem carries a
+**recorded justification** in the design output — a `sources.md` row (or a
+decision row) stating why no comparable community option fits. Owner-cited
+precedent: the substrate-reuse approach of pi-extensible-workflows.
+
+### The all-stages no-assumption rule (`ask-dont-infer@1`, #340)
+
+This block is the **single normative owner** of the no-assumption rule for
+every stage — development, modification, deletion, planning, design, review,
+audit. Stage skills reference this block; they **never restate** it — a
+restatement is a defect (`scripts/residue-dimensions.test.mjs` counts them).
+
+```text
+ask-dont-infer@1
+stage | when the rule binds | what the stage does
+any (development, modification, deletion, planning, design, review, audit) | an expectation is not evidenced by the tree, the docs, or a prior owner decision | understand the context of the question; research if useful — without leaking data, secrets or project details; propose options; the user decides. Research informs and proposes — it never answers on the user's behalf
+```
+
 ## Stage 3 — ask
 
 Batch the tier-2 claims from the orient stage. This stage reads the **orient
@@ -176,6 +225,9 @@ The unit doc's **Acceptance criteria** section, numbered and command-verified.
 - [ ] Entity closure: every entity mentioned has its role in the unit stated
 - [ ] Role closure: every actor/role that interacts with the unit is listed
 - [ ] Expectation sweep: user's accepted and rejected inputs are bounded
+- [ ] The three-direction closure (§ Stage 2) ran: backward, sideways, forward — each with its evidence
+- [ ] Retirements stated: each retired surface carries its replacement or no-consumer evidence, or the answer says why nothing can be removed
+- [ ] Third-party before homemade (#340): a solved problem prefers a widely community-supported library; own code for a solved problem carries a recorded justification in the design output
 - [ ] Deferrals landed in `## Future`, not in scope
 
 ## Forbidden
@@ -192,5 +244,7 @@ The unit doc's **Acceptance criteria** section, numbered and command-verified.
 - Do not implement, spec, or task anything from `## Future`
 - Do not install a missing tool without explicit user consent
 - Do not build a separate DESIGN.md — one SPEC, all in the unit doc
+- Do not coin a name, field or endpoint without an owner answer and a named place its consumer will read it
+- Do not answer the retirement question with silence: “nothing can be removed” is a stated reason, not an omission
 - Do not pre-fill engineering content (phases, tests, architecture)
 - Do not stamp "designed" with an incomplete closure row

package/skills/unit-lane/references/PLAN.md

@@ -117,6 +117,31 @@ set, written from the planner's own discovery, and a file that is missing from
 it is never out of scope for the executor.
 <!-- tasks:end -->
 
+<!-- retirements:start -->
+Every retirement the design step declared (S8) becomes **its own task**: a
+deliberate deletion gets the same rigor as a deliberate construction — task,
+validator, evidence row — because an ad-hoc deletion skips evidence and a
+planned one cannot. A replacement is a retirement: a task that supersedes an
+existing part (a feature changed for another, a function/code path that does
+the same or better) declares the superseded part retired, and its deletion
+task follows the same three pieces (#340, replace-implies-delete). Three
+pieces per retirement task:
+
+- **the negative-capability pin** — the test proving the removed thing cannot
+  return (`grep -c '<removed name>' <scope>` → 0, or a suite that fails if the
+  surface reappears). This is the task's `(validator: …)`, never prose.
+- **the sweep grep** — the pattern that found the remaining references, with its
+  scope, so a reviewer re-runs the same command.
+- **the surviving-reference count** — before and after, so the deletion is
+  measured rather than asserted.
+
+No declared retirements → write exactly
+``none — the design states why nothing can be removed``. The anti-gaming rule
+(“never shrink a diff by deleting comments, blank lines, docs or tests”) gains
+its complement: verified shrinkage is legitimate work, only unverified
+shrinkage is suspect.
+<!-- retirements:end -->
+
 <!-- sources:start -->
 `sources.md` — every `CLAIM-*` row with a source or an owner answer. A claim row
 whose source is empty, `—`, or `n/a` is a **defect**: find the source in the
@@ -167,6 +192,10 @@ name those files instead.
 - [ ] Every claim was swept against the candidate sources; each `contradicts` hit is resolved or asked
 - [ ] Every question asked was recorded in `decisions.md` with its resolution (or the questions pane says `none`)
 - [ ] Every AC maps to at least one task, and no task re-decides an AC
+- [ ] Every retirement the design declared is its own task, carrying the negative-capability pin as its validator plus the sweep grep and the before/after reference count — or the plan states why nothing can be removed
+- [ ] The plan obeys the all-stages no-assumption rule — **ask-don't-infer**, owner `skills/unit-lane/references/DESIGN.md` (`ask-dont-infer@1`); a claim no source settles is asked, never invented
+- [ ] Reuse-first (#340): every task that adds functionality names the pre-existing parts it reuses (functions, scripts, skills, schemas, prose surfaces) — or records why reuse is not possible; a task that re-implements an existing part without saying why does not pass
+- [ ] Replace-implies-delete (#340): every task that changes a feature for another, or adds a function/code path that supersedes an existing one, carries the superseded part's deletion as its own planned task with its evidence — and where no superseded part exists, nothing is deleted: the obligation exists when the case exists, never as a ritual
 - [ ] Tasks are ordered smallest first
 - [ ] Each task names its validator (a backticked command plus its expected outcome)
 - [ ] Final task is verification (proves the whole unit works); a unit that

package/skills/verification-contract/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: verification-contract
 user-invocable: false
-version: 1.5.0
+version: 4.10.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 description: >
@@ -43,6 +43,14 @@ canonical acceptance source. Criteria are numbered, each induced from a concrete
 user scenario, and command-verified where possible (label `read-verified` for
 prose-only checks). Unlabelled prose is invalid.
 
+**Every criterion names its demonstrating command (S5).** A criterion that a
+command can settle carries that command — ``<cmd> exits 0``, ``<cmd> matches
+<N>`` — so a reviewer re-runs it instead of re-deriving the change, and `audit-pr`
+can demand a demonstration for every AC. A criterion only a human can settle
+keeps an explicit `manual:` label with the exact observation; a criterion with
+neither fails closed at review (the `no command, no claim` admission rule
+applied to the acceptance surface).
+
 **Validator stability.** A validator must never gate on a surface other workflow
 actors mutate — the branch diff as a whole, the session log, progress entries,
 review ledgers, or forge state — because any out-of-unit commit (a session-log

package/skills/workflow-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: workflow-status
 user-invocable: true
-version: 3.9.4
+version: 4.10.0
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
 argument-hint: "[--json-only] [--last-envelope <json|path>] [--compact]"