@lemoncode/lemony 0.1.2 → 0.3.0

package/catalog/skills/task-closeout/SKILL.md

@@ -27,7 +27,8 @@ Three moves, in this order:
    `_archive/<id>/`; drop only `progress.md` (true scratch). The high-value memory stays
    live and grep-able.
 3. **Land via a PR** — the `history.md` append, the archival move, and any new ADR ride a
-   dedicated `harness/closeout-<id>` PR merged with `--auto`. No direct push to the base.
+   dedicated `harness/closeout-<id>` PR that self-merges **only on green checks**
+   (through `.claude/hooks/lib/merge-pr.sh`). No direct push to the base.
 
 Run this only when the **Reviewer has approved** and the task PR is merged. The merge is a
 human decision (the merge gate) — closeout never merges the task; it **confirms** the
@@ -87,8 +88,9 @@ The three differ in **who decides** — and the asymmetry is deliberate:
 
 - **`update-architecture` — automatic dispatch, no pre-offer.** Only when
   `docs/architecture.md` exists (the skill installs solely then). Dispatch the
-  **Architect** (`update-architecture`, fresh context) with the task's **merged diff**
-  (`gh pr diff <pr>`) plus the task's `spec/design.md` (still live here — archival is
+  **Architect** (`update-architecture`, fresh context) with the task's **PR number**
+  (it runs `gh pr diff <pr>` itself) plus the **path** of the task's `spec/design.md`
+  (still live here — archival is
   step 4 below). The Architect reads the change, makes
   the smallest true edit if the system's **shape** moved (referencing any ADR just
   written — `see ADR-NNNN`), or reports **no-op** when nothing architectural changed.
@@ -157,34 +159,74 @@ working scratch are gone. A UI task's **`ui-handoff.md`** is a sibling **inside*
 `spec/`, so the single `git mv` of `spec/` archives it with the rest — no special
 handling.
 
-### 5. Open the closeout PR and auto-merge
+### 5. Open the closeout PR and self-merge on green
 
-Commit the record, push the branch, open a PR, and let GitHub apply the repo's own rules:
+Commit the record, push the branch, open a PR, and self-merge it **through the
+checks-precondition executor** — never a bare `gh pr merge`. There is no standing human
+authorization on this path, so the precondition stands alone: **the executor merges
+only on green; every other outcome takes one of the exits below** (some end in a
+human's informed decision — what never happens is an autonomous merge on not-green).
+The executor verifies the check status the platform reports for
+the PR, waiting — bounded (`merge.checks_timeout_secs`, default ~10 min) — for pending
+checks:
 
 ```bash
 git commit -m "closeout(<id>): archive task state, record in history.md"
 git push -u origin harness/closeout-<id>
 gh pr create --base <default> --head harness/closeout-<id> \
   --title "closeout(<id>): <topic>" --body "Closeout record for #<id>."
-gh pr merge harness/closeout-<id> --auto --squash --delete-branch
+.claude/hooks/lib/merge-pr.sh harness/closeout-<id> --squash --delete-branch
 ```
 
+(If the human recorded a standing merge answer at this task's merge gate — a
+`merge.allow_no_checks: true` line sitting uncommitted in `harness.config.yml` —
+stage it into the record commit above: the answer rides the closeout PR to the base.)
+
 The closeout PR **must not** carry `Closes #<id>` — the task PR already auto-closed the
 issue on merge; closeout only flips the label and finalizes.
 
-`gh pr merge` `--auto` defers to branch protection:
-
-- **Protection is PR + checks only** → the PR self-merges once checks pass. Continue to
-  step 6 (finalize) once the closeout PR reports merged.
-- **Protection requires human approval** → the PR waits. **Park** (see below).
-- **Auto-merge is disabled repo-wide** → `gh pr merge` `--auto` **errors** ("auto-merge is
-  not allowed for this repository") rather than queuing. This is a repo setting,
-  independent of branch protection. Treat the error as the wait case: **park**. (You may
-  instead merge it immediately with a plain `gh pr merge` `--squash --delete-branch` if the
-  human has authorized you to merge — same gesture as the task merge gate.)
+Act on the executor's exit code:
+
+- **0 — merged.** Continue to step 6 (finalize).
+- **10 — checks red.** Red does **not** automatically mean the base is broken — look at
+  what failed (`gh run view` / the check's output), then take one of three exits:
+  1. **Failure in the closeout's own files** (format/lint on the moved docs): fixable
+     by you alone — run the formatter, commit, push, re-run the executor; green ⇒
+     self-merge normally. No human interruption; fixing format on your own docs-only PR
+     is harmless and autonomous.
+  2. **Failure in the base** (main was already broken): **park** and surface with the
+     diagnosis — the human's informed merge-on-red decision is legitimate precisely
+     here, since the red isn't this PR's (on their explicit yes, re-run with
+     `--force`). Free side effect: every closeout is a broken-main detector.
+  3. **Can't tell:** **park** and surface what you saw — in doubt, the human.
+
+  The uniform rule stands: **never merge on red alone** — no "it's only docs"
+  exception (automatic exceptions are how the bug comes back).
+
+- **20 — no checks reported (after the grace window).** Never merge alone, whatever the
+  cause — don't auto-classify (no CI, CI dead, path filters all look identical). The
+  once-per-repo memory is the **standing answer only**: if `merge.allow_no_checks: true`
+  is recorded (or sits uncommitted on this branch, staged per step 5), the executor
+  applies it itself — you won't see exit 20. A **one-shot** yes given at an earlier
+  merge (including this task's merge gate) authorized **that merge only** and does
+  **not** carry over — never re-apply it here on your own. Seeing exit 20 means no
+  standing answer exists, so ask: "I saw no checks on the closeout PR — merge?". A
+  standing answer ("this repo has no CI — merge without checks") is recorded as
+  `merge.allow_no_checks: true` in `harness.config.yml` — add the line on this very
+  closeout branch, push, and re-run the executor (it reads the working tree, and the
+  answer lands on the base with the record). A one-shot yes ⇒ re-run with `--force`.
+  No human available ⇒ **park**.
+- **30 — checks still pending past the bound.** **No merge**: **park**. The closeout is
+  docs-only archival — leaving it pending blocks nothing already merged.
+- **1 (or any other non-zero) — no verdict.** Read the executor's stderr: either the
+  check status could not be read (`gh`/auth/network — the precondition is
+  unverifiable), or the merge attempt itself was rejected (branch protection requires
+  human approval, a conflict). Both ⇒ **park**, surfacing that stderr — a
+  protection-parked record PR is merged by the human by hand.
 
 **Park:** flip the issue to `harness:status:closeout-pending`, tell the human the closeout
-PR is open and awaiting their merge, and stop. The task issue is **already closed** (the
+PR is open, why it did not merge (the executor's output — failing checks, no checks,
+pending past the bound, or protection), and stop. The task issue is **already closed** (the
 task PR's `Closes #<id>` fired on its merge), so `/resume` finds the parked closeout only
 by listing closed issues too (`--state all`) — a default open-only queue would miss it. A
 later `/resume` picks up at step 6 once the PR is merged. (Authority for the RESUME entry:
@@ -192,7 +234,10 @@ the Orchestrator.)
 
 ### 6. Finalize (once the closeout PR is merged)
 
-Confirm the closeout PR merged (`gh pr view <pr> --json state,mergedAt` → `MERGED`; on a
+On a `/resume` that finds the record PR **still open**, first re-run the executor on it
+(step 5's `merge-pr.sh` line, verbatim): a park on pending or red checks is transient
+and may have settled green — a repeat not-green outcome just re-parks. Then confirm the
+closeout PR merged (`gh pr view <pr> --json state,mergedAt` → `MERGED`; on a
 `/resume`, pass the deterministic branch `harness/closeout-<id>` as `<pr>` — the
 merge-confirm accepts a branch name in place of a PR number), land the merged base
 (`git checkout <default> && git pull`), then:
@@ -208,11 +253,31 @@ single emit point for either path). You compute the envelope (cycle time, review
 rejections, level) as the Orchestrator running this skill; the fields and the `emit`
 command line are in `orchestrator.md` §Closeout. `events.jsonl` is local-only/gitignored, so the emit never dirties the base.
 
+**If the task is a part of a partitioned feature** — its issue body (read it with
+`gh issue view <id> --json body`; the issue is closed by now) carries a
+`Part <k> of #<parent>` trace line — update the parent **partition-plan** issue here, in
+the same finalize, **read-modify-write**: read the parent body immediately before
+editing (`gh issue view <parent> --json body`), tick only your row and set it to
+`- [x] Part <k> — <slice> → #<id> merged`, write it back with
+`gh issue edit <parent> --body-file`, then re-read to confirm the tick is present — if another row moved
+underneath you (a sibling closing out elsewhere), redo it **once** on the fresh body
+(match rows tolerant of a trailing `\r`: a body edited on the web may carry CRLF); still
+absent → leave the tick to the human and say so. Idempotent on a retried finalize: an
+already-ticked row is left alone, and the all-ticked check still runs. When that
+leaves **every** row ticked (merged or dropped), close the parent with a summary comment
+(`gh issue close <parent> --comment "<what shipped, part by part>"`) — mechanical, no
+human prompt: each part's merge already passed the human gate; a parent the human already
+closed takes the tick and the close is a no-op. A parent with unticked rows stays open;
+`/resume` surfaces its next part. The contract is the Orchestrator's companion
+`.claude/agents/partition.md`.
+
 ### 7. Report
 
 Return a one-line summary: the task id, the `history.md` entry, the archive path
-(`_archive/<id>/`), any ADR raised, and confirmation that the issue is closed (or that
-closeout is parked at `closeout-pending` awaiting the record PR's merge).
+(`_archive/<id>/`), any ADR raised, confirmation that the issue is closed (or that
+closeout is parked at `closeout-pending` awaiting the record PR's merge), and — for a
+partition part — that the parent row was ticked (and the parent closed, on the last
+part).
 
 ## Scope note
 

package/catalog/skills/test-gap-report/SKILL.md

@@ -52,6 +52,10 @@ For each file in the "always" set:
 
 ### 3. Report
 
+Destination: the full-pass **issue comment**. In your return summary — and always on
+a per-step review, which posts no comment — carry only the counts + the gaps, per
+the Reviewer's verdict-size rule (a REJECT lifts the cap entirely).
+
 ```
 ## Test Gap Report — <task name>
 

package/catalog/skills/triage-issue/SKILL.md

@@ -44,7 +44,7 @@ Look at:
 Determine:
 
 - The minimal change needed to fix the root cause
-- Which modules/interfaces are affected
+- Which modules/interfaces are affected, and **which files the fix will change**
 - What behaviors need to be verified via tests
 - Whether this is a regression, missing feature, or design flaw
 
@@ -65,12 +65,70 @@ Rules:
 For TDD philosophy → see the **tdd** skill. For test recipes → see your project's
 testing playbook.
 
-### 5. Confirm with the user
+### 5. Declare the risk surfaces
 
-Present the issue draft: problem summary, root cause analysis, and TDD fix plan.
+This is the L2 counterpart of the `[risk: …]` tag a spec's group header carries at L1:
+the declaration of **what kind of damage this change can do**, made at the structuring
+moment, outside the Reviewer, and visible to the human before execution.
+
+One line per surface — a class paired with **one concrete file the fix changes**, never
+a module in the abstract — using the same vocabulary as `prd-to-spec`; each class names
+what kind of damage the surface can do:
+
+<!-- risk-vocabulary:start -->
+
+| Class             | Surface                                                          |
+| ----------------- | ---------------------------------------------------------------- |
+| `auth`            | authentication, authorization, session or token handling         |
+| `payments`        | money movement, billing, pricing                                 |
+| `shell-process`   | shell invocation, subprocess spawning, argument construction     |
+| `data-loss`       | writes, deletes, migrations, anything that can destroy user data |
+| `secrets`         | credentials, keys, tokens — at rest or in transit                |
+| `executable-mode` | file permissions, exec bits, anything that changes what can run  |
+
+<!-- risk-vocabulary:end -->
+
+A fix that carries one class into three files declares three lines:
+
+```
+## Risk surfaces
+- data-loss: src/storage/sync.ts
+- shell-process: src/hooks/run-hook.ts
+```
+
+A fix that touches no such surface carries the section with a single line — `- none` —
+never an omitted section: the absence of a declaration and a declaration of absence are
+different claims, and only the second is auditable. `- none` is a claim about the change,
+so make it only when it is true.
+
+Declare it **now**, before the fix is written: a surface named afterwards describes what
+happened, it does not declare what could. The human reviews it with the rest of the draft
+in the next step and edits it in the issue like any other section — that review is the
+first thing the section buys. The second comes at review time: the Reviewer hands the
+declared surfaces to `security-review`, which presses hardest where they point. Nothing
+checks it automatically.
+
+If a surface has no home in the vocabulary, declare it as `unclassified` and say what it
+can do:
+
+```
+- unclassified: src/queue/drain.ts — replays messages, can double-deliver
+```
+
+**Never fold it into `- none`.** `- none` claims no such surface exists, and that claim
+would be false — an unnameable surface is the one most worth seeing. Do not invent a
+one-off class either, and do not edit the table here: it is vendor-owned — generated into
+this skill and `prd-to-spec` from one source, so the two always agree — and a local edit
+is discarded on the next update. Say in the next step that the vocabulary came up short,
+so the human can decide whether it grows.
+
+### 6. Confirm with the user
+
+Present the issue draft: problem summary, root cause analysis, TDD fix plan, and the
+declared risk surfaces.
 Ask: "Does this look right? Should I create the issue?"
 
-### 6. Create the GitHub issue
+### 7. Create the GitHub issue
 
 After confirmation, create with `gh issue create` and the `harness:managed` label.
 Use a structure like:
@@ -86,6 +144,9 @@ Use a structure like:
 - [ ] RED: <test capturing behavior 1> → GREEN: <minimal change>
 - [ ] RED: <test capturing behavior 2> → GREEN: <minimal change>
 
+## Risk surfaces
+- <class>: <path the fix writes to>
+
 ## Affected
 <modules / interfaces touched>
 ```

package/catalog/skills/verify/SKILL.md

@@ -84,6 +84,9 @@ and the error output (unexpected warnings/errors even when the happy path worked
 **Verdict**: works / does not work — <one-line reason>
 ```
 
+This block is your working record; a capped return summary condenses it to the
+verdict line (plus any ❌ detail — failures are signal, never trimmed).
+
 On a failure, read the **full** error, find the origin (not where it surfaced), fix
 the root cause, and re-run from the failed gate. If a failure reveals the spec itself
 is wrong or silent, that's a **discovery** — run `raise-discovery`, don't paper over

package/catalog/templates/claude-code/agents.md.tpl

@@ -27,7 +27,9 @@ surface the menu.
 - **DEFINE** — the L1 full-SDD round-trip (see below).
 - **RESUME** — for an SDD task, `git fetch` and check out `harness/<id>-<slug>` first
   (the task state and spec live only on the branch until merge), then reload
-  `.claude/state/tasks/<id>/` and continue from `progress.md`.
+  `.claude/state/tasks/<id>/` and continue from `progress.md`. An issue carrying
+  `harness:partition-plan` is a partition parent, not a task — start its next part per
+  `.claude/agents/partition.md`.
 - **TRIAGE** — the L2 lightweight path (see below). Invoke the `triage-issue` skill.
 - **ORIENT** — an intentless entry (greeting / "what should I pick up?" / nothing).
   Render the **dispatch menu**: the parked queue (the same listing `/resume` runs with
@@ -52,12 +54,17 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
 ## L1 round-trip (DEFINE)
 
 1. **Grill** — `grill-with-docs`: interview the idea into a PRD at
-   `docs/prds/<topic>-<date>.md`.
+   `docs/prds/<topic>-<date>.md`. If the closed PRD bundles separable, independently
+   mergeable wants, ask the **partition question** before opening the task (authority:
+   `.claude/agents/partition.md`, read on trigger): an approved cut opens a parent
+   partition-plan issue (`harness:partition-plan`, never a task) and Part 1 as a normal
+   task; later parts open at their turn.
 2. **Open the task** — create the issue (skeleton body + `harness:managed` +
    `harness:sdd` + `harness:status:spec-in-progress`) and the branch
    `harness/<id>-<slug>`. `<id>` is the GitHub issue number in this build; spec and code
    both live on that branch — nothing touches the default branch until the merge gate.
-3. **UI design (if it touches UI)** — **UI design gate** (§UI design in `orchestrator.md`):
+3. **UI design (if it touches UI)** — **UI design gate** (canonical: the orchestrator's
+   L1 step 3, evaluated core-only — read `.claude/agents/ui-design.md` only when it fires):
    if the repo has a frontend AND the task touches UI, put `harness:needs-design`, offer the
    design-stop, and on "continue" **run `grill-ui` yourself** (the interactive design
    interview) to author `ui-handoff.md` under `tasks/<id>/spec/`, then dispatch the **UI
@@ -67,31 +74,55 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
    under `tasks/<id>/spec/`) then `spec-to-issue` (fills the issue body — it creates nothing
    and moves no labels).
 5. **Spec-ready + handoff** — remove `harness:needs-design` once `ui-handoff.md` is
-   complete (a spec-ready task never carries it), flip to `harness:status:spec-ready`,
+   complete (a spec-ready task never carries the label), flip to `harness:status:spec-ready`,
    commit and push the task state to the branch. DEFINE can stop here: the spec-ready
    queue (`gh issue list -l harness:status:spec-ready`) is the handoff. Ask: implement
    now or hand off?
 6. **Approval gate** — run by whoever implements (a RESUME of a spec-ready issue runs
    it). Present the spec; the human approves (or asks for changes → Spec Author
    revises). On approval, flip to `harness:status:in-progress`. The spec, not the code,
-   is the source of intent — never self-approve.
+   is the source of intent — never self-approve. If `harness.config.yml` declares no
+   `gates` list, propose one here (from the manifest + CI; hand-edited on
+   confirmation) — never mid-review (orchestrator §Approval gate).
 7. **Implement** — Implementer sub-agent, `tdd` skill, on the branch, keeping
-   `.claude/state/tasks/<id>/progress.md` live.
+   `.claude/state/tasks/<id>/progress.md` live. The gate interaction settles two
+   knobs, both recorded in `progress.md`: the **implementation mode** (all-at-once,
+   or step-by-step with per-group human checkpoints) and **pre-commit review**
+   (config `implementation.pre_commit_review`; ON = the human reviews the work
+   **uncommitted** — zero commits until each checkpoint OK). Authority:
+   orchestrator §Implementation mode / §Pre-commit review ON.
 8. **Review** — flip to `harness:status:in-review`, open the PR (`gh pr create`,
    branch → default), Reviewer sub-agent reviews it (`senior-review`, fresh context). If
    the task touched UI, the **UI Designer** reviews as a distinct design + a11y lens too
-   — either lens rejecting routes back to the Implementer.
+   — either lens rejecting routes back to the Implementer. Every APPROVE carries an
+   **evidence ledger** — a JSON sidecar under the task's state that a script validates
+   (`lemony review-ledger validate`), never an agent: a red ledger sends a fresh Reviewer
+   back once, then the human; it never routes to the Implementer and is never relayed as
+   an APPROVE.
 9. **Merge gate** — never auto-merge. Surface the approved PR; the human merges (or
-   authorizes you to). The task stays at `in-review` until merged.
-10. **Closeout** — `task-closeout`: confirm the merge via `gh`, offer durable discoveries
-   to the Architect (`write-adr`, HITL), archive the spec + discoveries to `_archive/<id>/` (drop
+   authorizes you to — a conditional yes: the agent's merge runs through the
+   checks precondition (`.claude/hooks/lib/merge-pr.sh --approve-issue <issue>`)
+   and never lands on red, absent, or still-pending checks without asking — nor
+   content that no longer matches what the Reviewer's APPROVE reviewed (the
+   stale-approve guard; a clean update-branch stays valid, any content change
+   routes back to re-review). The task stays at `in-review`
+   until merged.
+10. **Closeout** — `task-closeout`: confirm the merge via `gh`, run the three Architect
+   activations (`write-adr` — HITL offer per resolved discovery; `update-architecture` —
+   automatic when `docs/architecture.md` exists; `playbook-iterate` — HITL offer once
+   per task), archive the spec + discoveries to `_archive/<id>/` (drop
    `progress.md`), and land `history.md` + the archival via a dedicated
-   `harness/closeout-<id>` PR (`gh pr merge --auto`) — never a direct push to the base.
-   If protection needs approval the PR waits: park at `closeout-pending`, `/resume`
-   finalizes. Then close the issue and delete the branch.
+   `harness/closeout-<id>` PR that self-merges **only on green checks**
+   (`.claude/hooks/lib/merge-pr.sh`) — never a direct push to the base.
+   A red on its own files (format/lint) it fixes and retries autonomously; any
+   other not-green outcome or protection needing approval parks the PR at
+   `closeout-pending`, and `/resume` finalizes. Then close the issue and delete
+   the branch.
 
 ## L2 round-trip (TRIAGE)
 
+Authority for the steps: `.claude/agents/triage.md` (the Orchestrator's lazy companion).
+
 1. **Triage** — `triage-issue`: investigate, find root cause, draft a TDD-based fix
    plan, and create the issue with `harness:managed` (no `harness:sdd` — its absence
    marks the lightweight path).
@@ -100,11 +131,14 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
 3. **Implement** — Implementer sub-agent, `tdd` skill.
 4. **Review** — flip to `harness:status:in-review`, open the PR, Reviewer sub-agent
    (`senior-review`, fresh context).
-5. **Merge gate** — the same human-explicit gate as L1: never auto-merge.
+5. **Merge gate** — the same human-explicit gate as L1: never auto-merge, and an
+   authorized merge runs the same checks precondition and stale-approve guard.
 6. **Closeout** — `task-closeout`: confirm the merge, archive the spec + discoveries to
    `_archive/<id>/`, and land `history.md` + the archival via a dedicated
-   `harness/closeout-<id>` PR (`gh pr merge --auto`); park at `closeout-pending` if it
-   needs approval. Then close the issue and delete the branch. Same as L1.
+   `harness/closeout-<id>` PR that self-merges only on green checks (own-file
+   format reds are self-fixed and retried); park at `closeout-pending` if checks
+   stay not-green or it needs approval. Then close the issue and delete the
+   branch. Same as L1.
 
 ## Discovery interrupts
 

package/catalog/templates/claude-code/harness.config.yml.tpl

@@ -46,6 +46,39 @@ rollback:
 # telemetry:
 #   enabled: false
 
+# Agent-executed merges. Before the agent runs any `gh pr merge` (an authorized
+# task-PR merge, or the closeout record PR), the shared executor
+# `.claude/hooks/lib/merge-pr.sh` verifies the check status the platform reports
+# for the PR and only merges on green — red, absent, or still-pending checks are
+# surfaced to a human instead. Defaults shown — declare only overrides.
+# merge:
+#   # Max seconds to wait for pending checks before surfacing instead of merging.
+#   checks_timeout_secs: 600
+#   # Standing answer for a repo with no CI: `true` lets the executor merge when
+#   # the platform reports no checks at all (otherwise it asks, every time).
+#   allow_no_checks: false
+
+# Implementation-phase knobs the Orchestrator reads at the L1 approval gate.
+# pre_commit_review — human review of the UNCOMMITTED work before anything is
+# committed (zero-commit mode): `human` (default) asks at the gate, in the same
+# interaction as the all-at-once / step-by-step choice, suggesting OFF (today's
+# commit-as-you-go flow); `on` / `off` pin the answer and skip the question
+# (bench/headless runs pin `off`). Bare on/off are strings here (YAML 1.2).
+# implementation:
+#   pre_commit_review: human
+
+# Review gates. The mechanical gates a Reviewer must attest in its evidence
+# ledger, one entry per name, beyond the always-required real run — a flat list of
+# this project's script names (`package.json` scripts, or your CI's equivalents).
+# Declare every gate your CI enforces, drift checks included: an undeclared project
+# reviews against a floor of the real run only (honest, but thin). The agent may
+# propose this list from your manifest at the approval gate — confirmed by a human
+# and added by hand (this block is the shape); no tool writes it for you.
+# gates:
+#   - lint
+#   - test
+#   - build
+
 # Design tokens (`design-tokens validate`). The anti-hardcode scan inspects a built-in
 # set of UI/style extensions (.css/.scss/.ts/.tsx/.vue/.svelte/.astro/.js/.mdx/.html/…).
 # Add extra suffixes here for a stack the built-ins don't cover — additive, never a