@lemoncode/lemony 0.1.0

package/catalog/skills/note-side-finding/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: note-side-finding
+description: Surface an independent, non-blocking defect you spotted mid-task in your return summary instead of pausing or fixing it. Use when a sub-agent (Spec Author, Implementer, Reviewer, Architect) notices a real bug that is unrelated to its current task — the task finishes fine without touching it — so it should be parked for later, not escalated. The non-pausing sibling of raise-discovery.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [spec-author, implementer, reviewer, architect]
+---
+
+# Note Side-Finding
+
+## Core Principle
+
+While doing your task with fresh context, you sometimes spot a **real defect that has
+nothing to do with the task you were given** — the task finishes correctly without
+touching it ("while implementing the parser I noticed the unrelated CSV export drops
+the last row"). You **cannot interrupt** the human (you run via `Task`, not in the
+hat's conversation) and you should **not** silently fix it (it is outside your task's
+scope) or pause for it (it is not blocking you). So you do neither: you **note it in
+your return summary and keep going**. The Orchestrator collects it and offers the human
+a `/spinoff` capture — nothing is lost, nothing is context-switched.
+
+This is the **non-pausing** half of the discovery family. You write one bullet and
+return; you do not create an issue, flip a label, write to `discoveries.md`, or stop.
+
+## Which channel — side-finding vs discovery vs just-do-it
+
+Pick by **two questions: does it block your task, and is it in your task's scope?**
+
+| Situation                                                       | Channel               | What you do                                                                                         |
+| --------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------- |
+| Defect is **in scope** for your task (your change touches it)   | **Just fix it**       | Fix it in your normal work — no note, no escalation.                                                |
+| Defect **blocks** your task / the plan forces it (T1–T6)        | **`raise-discovery`** | Pause: write `discoveries.md`, return one line, stop.                                               |
+| Defect is **independent and non-blocking** (task finishes fine) | **note-side-finding** | Add a `## Side-findings` bullet, **keep working**.                                                  |
+| A feature **idea** (not a defect)                               | mention it in prose   | No capture channel here — drop it in your summary prose; the human may pick it up and `/define` it. |
+
+The discriminator against `raise-discovery` is **blocking**: if you can complete your
+task without the defect being touched, it is a side-finding (note and continue), never a
+discovery (pause and stop). When genuinely unsure whether it blocks you, prefer
+`raise-discovery` — a wrong pause is cheaper than coding past a real contradiction.
+
+The same channel covers **architecturally-significant drift in `docs/architecture.md`**
+(ADR 0011) — when you read the map to orient and find it states a boundary/seam the code no
+longer matches, in an area your task doesn't touch. That is a defect of the _map_, not the
+code: non-blocking and out of your scope, so it rides here. Tag such a bullet `kind: drift`
+(see the contract below) so the Orchestrator routes it to the Architect's
+`update-architecture` rather than a generic follow-up; don't fix the map yourself and don't
+silently trust one side.
+
+## The contract
+
+When you have one or more independent non-blocking defects, append **one** section to
+the **end of your return summary** to the Orchestrator (omit it entirely when you have
+none — never emit an empty block):
+
+```markdown
+## Side-findings
+
+- **symptom:** <one line — what is wrong>
+  **location:** <file:line or the area you saw it>
+  **severity:** <low | medium | high | critical — optional>
+  **kind:** <drift — optional; only for architecture.md drift>
+```
+
+One bullet per finding. `symptom` and `location` are required; `severity` is your
+optional read. `kind` is optional and, today, only takes the value `drift` — set it
+**only** for `docs/architecture.md` map staleness (above), so the Orchestrator routes the
+stub to `update-architecture`; omit it for an ordinary code defect. Keep each to the
+symptom + where you saw it — do **not** root-cause or propose a fix (the capture is
+deliberately shallow; investigation happens at pickup). Everything else in your return
+summary stays exactly as it was — the section is an addition, not a replacement.
+
+Then **continue your task to its normal end** (or, if you were already done, just
+return). Do not wait for a reply, do not act on the finding, do not open anything.
+
+## What the Orchestrator does with it
+
+It reads the `## Side-findings` block from your summary and, for each entry, makes the
+same single-line `/spinoff` offer it makes for a human-mentioned defect — lean toward
+offering, one-tap dismissal, never re-offered twice, never pausing. The active task is
+recorded as the parent. You are not involved past returning the bullet.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching channel with reasoning (when torn between side-finding and
+   discovery, default to `raise-discovery` — blocking is the safe assumption).
+2. **Flag it**: "This didn't clearly fit note-side-finding. I [noted it / raised it]
+   because [reason]. Want to refine the skill?"

package/catalog/skills/playbook-iterate/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: playbook-iterate
+description: Propose changes to a client playbook — or extract a new one from the codebase — when the spec collides with a documented pattern (a T6 PLAYBOOK_CONFLICT) or the client asks. Playbooks are client-owned (decision #8); the Architect proposes and the human decides. Use when the Orchestrator routes a T6 discovery resolution to the Architect, or on an explicit "capture how we do X" request.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [architect]
+trigger-condition: a T6 PLAYBOOK_CONFLICT needs the playbook changed, or the client asks to extract/iterate one
+---
+
+# Playbook Iterate
+
+## Core Principle
+
+A **playbook** describes _how to build_ a category of software (a backend service, an
+SPA, a testing strategy) in **project-agnostic** terms — placeholder names, never a real
+codebase's symbols. Playbooks are **client-owned** (decision #8): the vendor ships the
+_format_ and the _lookup convention_, never the content. So this skill **proposes**; the
+human **decides**. The Architect never rewrites a client playbook unilaterally.
+
+## Where playbooks live (the lookup convention)
+
+Two layers, discovered by convention `<topic>.md` — **no index** (an index drifts):
+
+1. **Project-local** — `docs/playbooks/<topic>.md`. Harness-managed home, committed.
+2. **User-global** — `~/.claude/playbooks/<topic>.md`. The developer's own generic playbooks.
+
+(Both locations are configurable via `paths.playbooks` / `paths.playbooks_global`
+in `harness.config.yml`; the defaults above apply when those keys are unset.)
+
+Lookup is **local → global**, and the **local entry overrides** the global one for the
+same topic. A missing playbook is not an error — degrade gracefully. New project-local
+playbooks land in `docs/playbooks/`.
+
+## Mode A — resolve a T6 PLAYBOOK_CONFLICT
+
+The Orchestrator routes you here when a discovery resolution decided that honoring the
+spec means the **playbook** should change (the playbook is the artifact being updated).
+
+1. **Read both sides.** The playbook section in conflict and the spec requirement that
+   collides with it. State the contradiction precisely.
+2. **Propose the smallest change** that resolves it, framed as a diff to the playbook
+   prose — and note the alternative (change the spec instead). The human already chose
+   the direction during `resolve-discovery`; you render that choice into the playbook.
+3. **Edit the project-local playbook** (`docs/playbooks/<topic>.md`), keeping it
+   project-agnostic — placeholder names, no symbols from this codebase. A rule that is
+   really project-specific belongs in `CLAUDE.md` / an ADR / `CONTEXT.md`, **not** a
+   playbook; say so if that's what the conflict actually reveals.
+4. **Return** the updated playbook path and a one-line summary to the Orchestrator, so it
+   can record the resolution and resume the paused sub-agent against the corrected source.
+
+## Mode B — extract a playbook from the codebase (client-triggered)
+
+On an explicit request ("capture how we do X here"):
+
+1. **Find the pattern** in the code — the repeated shape, the convention the codebase
+   already follows (use `code-explorer` first if the codebase is unfamiliar).
+2. **Generalize it.** Strip the project's real names down to placeholders; describe the
+   _pattern_, not the instance. If it can't be generalized, it's project-specific and
+   doesn't belong in a playbook.
+3. **Write** `docs/playbooks/<topic>.md` following the playbook conventions documented
+   in `docs/playbooks/README.md` (project-agnostic, placeholder names), and report it for
+   the human to review.
+
+## Report
+
+Return to the Orchestrator: the playbook path written/changed, a one-line summary, and —
+for Mode A — confirmation it resolves the cited T6. If the change turned out to be
+project-specific (belongs in `CLAUDE.md`/ADR, not a playbook), report that instead and
+make no playbook edit.
+
+## Uncontemplated Scenarios
+
+When a case doesn't clearly fit:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This isn't covered by the playbook-iterate skill. I did [approach]
+   because [reason]. Want to refine the skill?"
+3. Offer to add a rule for the case.

package/catalog/skills/prd-to-spec/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: prd-to-spec
+description: Turn a completed PRD into a task spec — requirements.md (EARS), design.md, and tasks.md. Use when the Spec Author decomposes a PRD into an implementable specification, mentions "write the spec", "EARS requirements", or "requirements/design/tasks".
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: pre-implementation
+invoked-by: [spec-author]
+---
+
+# PRD to Spec
+
+## Core Principle
+
+A spec is a contract, not a diff. It says **what** must be true and **why**, never
+**how** line by line. The PRD captured intent through grilling; this skill turns that
+intent into three artifacts an Implementer can build against and a Reviewer can check
+against — without re-interviewing the human.
+
+The Spec Author runs with **fresh context**. That is the point: if the PRD is too
+vague to write a testable requirement from, the PRD is not done. Do not paper over
+the gap by guessing — surface it (see "When the PRD is insufficient").
+
+## Inputs and outputs
+
+- **Input**: a PRD at `docs/prds/<topic>-<date>.md` (owned by the Orchestrator via
+  `grill-with-docs`). This skill **consumes** the PRD — it never edits or closes it.
+- **Output**: three files under `.claude/state/tasks/<id>/spec/`. The Orchestrator
+  created the issue and the task branch before invoking the Spec Author, so `<id>` is
+  real from the start — there is no `draft-<slug>` holder:
+  - `requirements.md` — EARS requirements with acceptance criteria
+  - `design.md` — files, functions, approach, edge cases, testing
+  - `tasks.md` — atomic, ordered, checkbox tasks
+
+## Process
+
+### 1. Read the PRD in full
+
+Read the whole PRD, plus any `CONTEXT.md` glossary terms and `docs/adr/` it
+references. Identify: the user stories, the decisions already closed, what's
+explicitly out of scope, and the assumptions/risks flagged. The closed decisions are
+constraints — the spec must honor them, not relitigate them.
+
+### 2. Write `requirements.md` (EARS)
+
+Express every requirement in **EARS** (Easy Approach to Requirements Syntax). EARS is
+five sentence patterns — pick the one that fits each requirement:
+
+| Pattern               | Template                                                           | Use for                                           |
+| --------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
+| **Ubiquitous**        | The `<system>` shall `<response>`.                                 | Always-active properties, invariants              |
+| **Event-driven**      | When `<trigger>`, the `<system>` shall `<response>`.               | A response to a specific event/input              |
+| **State-driven**      | While `<state>`, the `<system>` shall `<response>`.                | Behavior that holds during a state                |
+| **Optional-feature**  | Where `<feature>`, the `<system>` shall `<response>`.              | Behavior that exists only if a feature is present |
+| **Unwanted-behavior** | If `<unwanted condition>`, then the `<system>` shall `<response>`. | Error handling, invalid input, failure paths      |
+
+Complex requirements combine patterns, outer-clause first:
+_"While `<state>`, when `<trigger>`, the system shall `<response>`."_
+
+Rules:
+
+- **Number every requirement** (`R1`, `R2`, …) so design and tasks can reference them.
+- **Always include the unwanted-behavior path.** A spec with no `If … then …`
+  requirements is almost always incomplete — error and invalid-input handling is
+  where bugs live.
+- **One requirement, one shall.** Split compound sentences.
+- **Testable, not vague.** "shall respond quickly" is not a requirement; "shall
+  respond within 200ms" is.
+- Group requirements under the user story or capability they serve.
+- Add a short **Acceptance criteria** list per capability — the observable facts a
+  Reviewer checks.
+
+Template:
+
+```markdown
+# Requirements — <topic>
+
+> Source PRD: docs/prds/<topic>-<date>.md
+
+## <Capability / user story>
+
+- **R1** (event): When <trigger>, the system shall <response>.
+- **R2** (unwanted): If <invalid condition>, then the system shall <response>.
+- **R3** (ubiquitous): The system shall <invariant>.
+
+### Acceptance criteria
+
+- [ ] <observable fact a reviewer can verify>
+```
+
+### 3. Write `design.md`
+
+The _how_, at the level a competent implementer needs — not a transcript of the code.
+
+```markdown
+# Design — <topic>
+
+## Approach
+
+<2–5 sentences: the shape of the solution and why, honoring the PRD's closed decisions.>
+
+## Files
+
+- `path/to/file.ts` — <created|modified> — <what it holds>
+
+## Functions / interfaces
+
+- `functionName(args): ReturnType` — <contract: what it guarantees, which Rs it serves>
+
+## Edge cases
+
+- <edge case> → <intended behavior> (maps to R#)
+
+## Testing approach
+
+- <what to test and at which level — unit / integration; what NOT to test and why>
+```
+
+Honor the project's playbooks (looked up by topic — `docs/playbooks/<topic>.md`, then
+the global layer) and `coding-conventions` for structure, naming, and the testing
+pyramid. If the design would contradict a playbook, that's a discovery, not a silent
+deviation (T6).
+
+### 4. Write `tasks.md`
+
+Atomic, ordered checkboxes. Each task is a **vertical slice** (a behavior, not a
+layer) so the Implementer can run TDD red→green per task. Reference the requirements
+each task satisfies.
+
+```markdown
+# Tasks — <topic>
+
+- [ ] T1 — <smallest behavior that proves the path end-to-end> (R1)
+- [ ] T2 — <next behavior> (R2)
+- [ ] T3 — <error path> (R2, R3)
+```
+
+Rules: order so the first task is a tracer bullet; never "write all tests" then
+"write all code"; keep each task small enough to verify on its own.
+
+### 5. Self-check before handing off
+
+- [ ] Every PRD user story maps to at least one requirement.
+- [ ] Every requirement is EARS-formatted and testable.
+- [ ] At least one unwanted-behavior (`If … then …`) requirement exists.
+- [ ] Every requirement is covered by at least one task.
+- [ ] No closed PRD decision is contradicted.
+
+### 6. Emit `spec_created`
+
+Telemetry — record that the spec landed. Count the EARS requirements in
+`requirements.md` (each `R<N>` entry, e.g. `R1`, `R2`, …) and emit via Bash:
+
+```bash
+.claude/hooks/lib/lemony.sh emit spec_created \
+  --task-id="<id>" \
+  --topic="<slug>" \
+  --requirements=<count>
+```
+
+`<slug>` is the topic part of the task branch (`harness/<id>-<slug>`). The CLI
+Zod-validates the line and appends it to `.claude/state/events.jsonl`.
+
+Then hand off to `spec-to-issue` to fill the issue body with the externalized spec.
+
+## When the PRD is insufficient
+
+If a requirement can't be written without choosing between >1 valid option the PRD
+left open, that's a **T2 UNSPECIFIED_DECISION** discovery — the spec cannot be
+self-sufficient. Do not guess. **Run the `raise-discovery` skill**: write the entry to
+`discoveries.md`, return the one-line summary, and stop. The Orchestrator mediates the
+question with the human, the PRD/spec improves, and you are re-invoked with the
+decision.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This scenario isn't covered by the prd-to-spec skill. I applied
+   [approach] because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case.

package/catalog/skills/raise-discovery/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: raise-discovery
+description: Pause the task and escalate when reality contradicts or exceeds the plan, instead of improvising. Use when a sub-agent (Spec Author, Implementer, Reviewer, Architect) hits a T1–T6 case — a contradiction, an unspecified decision, scope drift, an existing solution, an infeasibility, or a playbook conflict — and needs a human decision before continuing.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [spec-author, implementer, reviewer, architect]
+---
+
+# Raise Discovery
+
+## Core Principle
+
+A sub-agent does **not** improvise when reality contradicts or exceeds the plan. It
+**escalates to the human** through the Orchestrator — like a compiler stopping on a
+type error instead of guessing what you meant. The fresh-context sub-agent is the
+sensor; the human is the arbiter. Guessing past a real ambiguity is how a confident,
+wrong implementation gets built.
+
+This skill is the **raising** half of the protocol. You write one entry, return a
+one-line summary, and **stop**. You do not flip labels, you do not dialogue with the
+human, and you do not resume yourself — the Orchestrator owns all of that (it runs
+`resolve-discovery`) and will re-invoke you with the decision when it's settled.
+
+## When to raise — the taxonomy (T1–T6)
+
+| Tag    | Type                 | Raise when…                                                |
+| ------ | -------------------- | ---------------------------------------------------------- |
+| **T1** | CONTRADICTION        | Existing code/env contradicts the plan or spec.            |
+| **T2** | UNSPECIFIED_DECISION | The plan is silent and **>1 valid option** exists.         |
+| **T3** | SCOPE_DRIFT          | Implementing the plan requires touching out-of-scope work. |
+| **T4** | EXISTING_SOLUTION    | The plan assumes building something that already exists.   |
+| **T5** | INFEASIBILITY        | The plan is not implementable as written.                  |
+| **T6** | PLAYBOOK_CONFLICT    | Honoring the spec would contradict a client playbook.      |
+
+## When NOT to raise (resolve it yourself)
+
+Escalation is for decisions with architectural or scope impact, not for everything
+unstated. Decide these yourself and note them in your normal output:
+
+- Local naming, formatting, file layout with no downstream impact.
+- Cases already covered by a playbook or `coding-conventions` — follow it.
+- A single obviously-correct option (no genuine fork).
+
+The bar for **T2** is the sharpest: raise only when the options are genuinely
+different _and_ the choice has consequences a human would want to make. "The spec
+didn't name the variable" is not a discovery; "the spec didn't say whether an empty
+input errors or defaults, and both are defensible" is.
+
+## Process
+
+### 1. Confirm it's a real discovery
+
+Re-read the relevant spec / PRD / playbook section. If it actually answers the
+question, you don't have a discovery — proceed. If, and only if, it leaves a
+consequential fork open, continue.
+
+### 2. Append an entry to `discoveries.md`
+
+The file is `.claude/state/tasks/<id>/discoveries.md`, **append-only**. Create it with
+an `# Discoveries — task <id>` heading if it doesn't exist yet. Read any existing
+entries to pick the next sequential id (`D001`, `D002`, …). Append a new section —
+never edit or delete a prior one:
+
+```markdown
+## D001 — T2 UNSPECIFIED_DECISION · raised <YYYY-MM-DD>
+
+- **Subtask context:** <which agent + which subtask/step you were on>
+- **Plan says:** <what the spec/PRD/plan states — quote or cite the line>
+- **Reality:** <what you found that contradicts or exceeds it>
+- **Proposed:** <the option(s) you see, with a one-line trade-off each>
+- **Question:** <the single, precise decision the human must make>
+```
+
+Fill **every** field. The entry must be self-sufficient: the Orchestrator and the
+human resolve from this file alone, without your context. Leave the `**Resolution**`
+block out — the Orchestrator appends it under this same header when the decision is
+made. Leave `paused_from` out too: the Orchestrator records the state being left when
+it pauses the task; that is its job, not yours.
+
+### 3. Return a one-line summary and stop
+
+Return to the Orchestrator exactly this shape, nothing more:
+
+```
+Discovery D001 (T2/UNSPECIFIED_DECISION) raised — see tasks/<id>/discoveries.md
+```
+
+Then **stop**. Do not keep working, do not pick an option, do not transition labels.
+The Orchestrator will move the task to `paused_for_clarification`, add the
+`harness:discovery:T*` label, mediate with the human, and re-invoke you with the
+resolution. (The issue exists from the start of `spec-in-progress`, before any
+sub-agent runs, so there is always an issue to label.) When it does, you resume from
+the decision in the entry's `**Resolution**` block — the `paused_from` state the
+Orchestrator records at pause time tells it where you left off.
+
+## Scope note
+
+T6 PLAYBOOK_CONFLICT (and any resolution that updates an ADR, `docs/architecture.md`,
+or a client playbook) is owned by the **Architect**: raise it normally, and the
+Orchestrator routes the artifact update to the on-demand Architect (`write-adr` /
+`update-architecture` / `playbook-iterate`) before resuming you. Telemetry for
+discoveries (a `discovery_raised` event) is deferred to a later phase; in this build the
+durable record is `discoveries.md` plus the issue label.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This scenario isn't covered by the raise-discovery skill. I applied
+   [approach] because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case.

package/catalog/skills/resolve-discovery/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: resolve-discovery
+description: Mediate a raised discovery with the human and resume the paused sub-agent. Use when the Orchestrator receives a "Discovery D00x raised" summary — it pauses the task, arbitrates the T1–T6 question with the human, routes the artifact update to its owner, records the resolution, and re-invokes the paused sub-agent with the decision.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+invoked-by: [orchestrator]
+---
+
+# Resolve Discovery
+
+## Core Principle
+
+This is the **resolving** half of the interrupt-on-discovery protocol; the sub-agent
+side is `raise-discovery`. The Orchestrator is the only one who talks to the human and
+the only one who moves labels, so it owns mediation end to end: pause the task,
+arbitrate, route the fix to whoever owns the artifact, record the decision, and resume
+the sub-agent that stopped. The discovery is not closed until the paused sub-agent has
+been re-invoked with the decision.
+
+You run this when a sub-agent returns a summary of the shape
+`Discovery D001 (T2/UNSPECIFIED_DECISION) raised — see tasks/<id>/discoveries.md`.
+
+## Process
+
+### 1. Pause the task
+
+The sub-agent already wrote the entry and stopped. Record where it stopped and flip
+state:
+
+1. In the discovery's section in `.claude/state/tasks/<id>/discoveries.md`, add a
+   `paused_from:` line capturing the status the task is leaving (`spec-in-progress`,
+   `in-progress`, or `in-review`) — this is the state you'll resume to. You write this,
+   not the sub-agent.
+2. Reflect the pause onto the GitHub issue with the `discovery` CLI verb. In one
+   fail-loud call it flips the status label (mutually exclusive)
+   `harness:status:<current> → harness:status:paused-for-clarification`, adds the
+   discovery flag `harness:discovery:T<n>` (presence-based, multiple allowed), and posts
+   a comment with the entry so the pause is visible on GitHub, not just in local state:
+
+   ```bash
+   .claude/hooks/lib/lemony.sh discovery pause \
+     --task-id=<id> --tier=T<n> --status=<current> \
+     --note="<one-line gist of the question>"
+   ```
+
+   Keep `--note` to a single line — the full `Plan says / Reality / Question` entry
+   lives in `discoveries.md`; the comment only needs a pointer-gist (omit `--note`
+   entirely and it links to the file). The label flip is **load-bearing**: a non-zero
+   exit means it did not land — surface it and retry, do **not** proceed as if the task
+   were paused. The comment is best-effort; if only it fails you'll see a `Warning:` but
+   the pause still stands. The Orchestrator creates the issue at the start of
+   `spec-in-progress`, before any sub-agent runs, so the issue always exists by the time
+   a discovery is raised — even a spec-time T2 during `prd-to-spec`.
+
+### 2. Mediate with the human
+
+Read the entry. Present it faithfully — the `Plan says` / `Reality` / `Proposed` /
+`Question` — and ask the human the single question it poses. Add your own read if it
+helps, but **do not decide for them**: a discovery exists precisely because the choice
+has consequences worth a human's call. If the human's answer raises a _new_ fork, that
+is a second discovery — append it, don't fold it in.
+
+### 3. Route the artifact update to its owner
+
+The agent that **created** an artifact is the one that updates it. Map the decision to
+the artifact it changes, then invoke that owner (fresh context, Task tool) with the
+decision + the entry as context:
+
+| Artifact changed by the decision                                     | Owner to invoke                                                                                                                                             |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spec/requirements.md`, `spec/design.md`, `spec/tasks.md`            | **Spec Author**                                                                                                                                             |
+| Implementation code, `progress.md`, `notes.md`                       | **Implementer** (often just the resumed sub-agent)                                                                                                          |
+| `docs/adr/NNNN-<slug>.md`, `docs/architecture.md`, `docs/playbooks/` | **Architect** (on-demand) — `write-adr` to record the decision, `update-architecture` to keep the map true, `playbook-iterate` for a `T6 PLAYBOOK_CONFLICT` |
+
+Not every resolution needs an artifact update first. If the decision is simply "do X"
+with no change to the contract, skip straight to recording it and resuming. If it
+changes the contract (a spec requirement, an ADR), the owner updates the artifact
+**before** the paused sub-agent resumes, so it resumes against the corrected source.
+
+### 4. Record the resolution
+
+Append a `**Resolution**` block under the discovery's existing header (append-only —
+do not edit the raise fields):
+
+```markdown
+**Resolution** (Orchestrator)
+
+- **Decision:** <the human's call, stated plainly>
+- **Artifact updated:** <file + owner who changed it, or "none — decision only">
+- **Resumed at:** <YYYY-MM-DD> — <agent> re-invoked from `paused_from: <state>`
+```
+
+### 5. Resume and clear the flag
+
+1. Reflect the resume onto the issue with the same `discovery` CLI verb — it removes
+   the `harness:discovery:T<n>` flag and flips the status back to `paused_from`
+   (`in-progress`, `in-review`, or `spec-in-progress`):
+
+   ```bash
+   .claude/hooks/lib/lemony.sh discovery resume \
+     --task-id=<id> --tier=T<n> --status=<paused_from>
+   ```
+
+   Same fail-loud contract: a non-zero exit means the flag/status did not flip back.
+
+2. Re-invoke the paused sub-agent (fresh context) with: the issue, the task-state
+   paths, the decision, and the updated artifact. It picks up from where it stopped.
+
+## Closeout invariant
+
+At `task-closeout`, **no `discoveries.md` entry may lack a `Resolution` block** with
+`Decision` / `Resumed at` filled, and **no `harness:discovery:*` label may remain** on
+the issue. An unresolved discovery means a sub-agent is still paused — the task is not
+done. If you find one at closeout, resolve it first.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This scenario isn't covered by the resolve-discovery skill. I applied
+   [approach] because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case.