@lemoncode/lemony 0.2.0 → 0.3.0

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/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,7 +54,11 @@ 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
@@ -75,23 +81,43 @@ A task deserves the harness if it is **specifiable**, **verifiable**, or
 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.
+   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)
 
@@ -105,11 +131,14 @@ Authority for the steps: `.claude/agents/triage.md` (the Orchestrator's lazy com
 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