Add role-scoped automatic investigation guidance

.gitea/ISSUE_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Problem
+
+What is broken or missing, and the evidence for it.
+
+## Scope
+
+The intended change, bounded to what one reviewed pull request can carry.
+
+## Acceptance Criteria
+
+- Observable completion criteria, each checkable on the candidate revision.
+
+## Dependencies
+
+Issues that must complete first, if any.

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,57 @@
+## Summary
+
+<!-- Keep prose brief. Add the smallest useful diagram, diff-sketch, tree,
+pseudocode, or code block when it makes the change faster to understand. Use
+the project's domain language. -->
+
+## Evidence
+
+- **Before:** the screenshot, output, symptom, or failing test run.
+- **After:** the screenshot, output, corrected behavior, or passing test run.
+
+<!-- For a bug fix, name the confirmed root cause or successful hypothesis.
+Merge evidence stays here; it is not a docs/evidence/ record (see
+docs/agents/standards.md). -->
+
+### Checks run
+
+- `the exact command already run` — observed result.
+
+## Documentation disposition
+
+updated / not_required / deferred / blocked — which one, and why in one line.
+
+<!-- Definitions and the recording rule live in docs/agents/standards.md;
+/cleanup blocks the merge without one. -->
+
+## Merge Danger
+
+**Door:** one-way or two-way — why the change is or is not cheap to reverse.
+
+**Blast Radius:** the affected subsystem, consumers, or behavior.
+
+**Rollback:** the exact rollback path, including any state it cannot restore.
+
+## Reviewer prerequisites
+
+- Required runtime, services, credentials or profiles, operating system,
+  fixtures, clean-state conditions, duration, and meaningful cost; or `None`.
+
+## Manual Test Plan
+
+<!-- Include only behavior that automated evidence cannot prove. -->
+
+1. [ ] **Action:** the exact reviewer action, command, route, control label,
+   field value, or UI interaction. Put every command in a copyable fenced block.
+
+   **Expected:** the observable evidence that the step passed, and any
+   condition that requires the reviewer to stop.
+
+## Post-Merge Cleanup
+
+```sh
+git switch main
+git pull --ff-only origin main
+git branch -d ISSUE-<number>
+git push origin --delete ISSUE-<number>
+```

AGENTS.md

@@ -0,0 +1,37 @@
+## Agent skills
+
+### Issue tracker
+
+Gitea issues, driven by the `gitea-issues` helpers.
+See `docs/agents/issue-tracker.md`.
+
+### Domain docs
+
+single layout: CONTEXT.md and ADRs live per `docs/agents/domain.md`.
+
+### Work queue
+
+Priority lives in the `type/roadmap` issue's ordered queue; see `docs/agents/queue.md`.
+
+### Working standards
+
+Docs and tests are first-class artifacts; the tracker is the queue, repository
+documents the durable memory. Read the issue's epic and related issues
+before planning; build test-first at the spec's pre-agreed seams; record each
+change's documentation disposition and the evidence behind its merge; commands
+presented as runnable must be ready to run as written. See
+`docs/agents/standards.md`.
+
+### Focused checks
+
+`python3 -m unittest discover -s tests -v`
+
+Run on the exact current head during implementation and review follow-ups;
+any later change makes this evidence stale.
+
+### Epic gate
+
+`python3 -m unittest discover -s tests -v`
+
+The complete gate, reserved for final epic acceptance — run once on the exact
+integrated commit.

NOTICE.md

@@ -6,6 +6,12 @@ The RelayView owner, its private prompts, and its separate open trust modules ar
 
 The optional role guidance is written for RelayView from the owner's personal skill collection. Several source skills trace to Matt Pocock's skills at revision `c55ee46073ed923f86ce59a5eb3b6d895095d1b7`; the `c4-diff` source skill traces to Jo Van Eyck's skills at revision `f2de8f7042a5125116ed27627fc7320b73048469`. Their MIT copyright and permission notices are preserved below. No plugin text, code, or assets are redistributed. This release has no third-party runtime dependencies or vendored executable assets. Python's standard library runs the authoring checks and is not bundled into a skill package.
 
+The three investigation packages are original RelayView guidance released under
+this repository’s MIT license. They express the role-local investigation method;
+no private owner implementation, protocol, or other private prompt is included.
+Their identical investigation.md resources share one method across separately
+scoped packages.
+
 ## Matt Pocock source-skill notice
 
 MIT License

README.md

@@ -6,6 +6,7 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 
 | Directory | Status | Role / step | Version |
 | --- | --- | --- | --- |
+| `packages/{planner,implementer,reviewer}-investigation` | Maintained automatic guidance | One matching role / step each | 0.7.0 |
 | `packages/planner-scope` | Maintained default | Planner / planning | 0.2.0 |
 | `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 |
 | `packages/issue-designer-default` | Maintained default | Designer / design | 0.6.1 |

docs/agents/domain.md

@@ -0,0 +1,56 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/authoritative/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/authoritative/adr/` for context-scoped decisions. The rest of `docs/authoritative/` holds current product design, contracts, and constraints.
+- **`docs/evidence/`**: curated observations that inform a foundational design decision. Read a record when you need to understand or challenge the decision it supports; it informs that decision but never overrides the authoritative document. Its `README.md` sets what qualifies.
+- **`docs/historical/`**: superseded designs, archived handoffs, and development records, including one issue's retained work under `docs/historical/issue-notes/<issue-number>/`. Read these to understand how the project arrived at its current state — never as current behavior.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved; `/cleanup`-bound work moves superseded context into `docs/historical/` per `docs/agents/standards.md`.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   ├── authoritative/adr/
+│   │   ├── 0001-event-sourced-orders.md
+│   │   └── 0002-postgres-for-write-model.md
+│   ├── evidence/                      ← foundational design evidence
+│   └── historical/issue-notes/186/    ← one issue's retained records
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/authoritative/adr/            ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/authoritative/adr/    ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/authoritative/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

docs/agents/issue-board.toml

@@ -0,0 +1,2 @@
+[status_board]
+project_id = 12

docs/agents/issue-tracker.md

@@ -0,0 +1,135 @@
+# Issue tracker: Gitea
+
+Issues, specs, and pull requests for this repo live on its Gitea host. Use the
+deterministic helpers from the `gitea-issues` skill for every operation — never
+hand-write API calls. Resolve `<gitea-issues>` from the installed skill path.
+
+## Conventions
+
+- **Read an issue**: `python <gitea-issues>/scripts/gitea.py issue read --issue <number> --comments`
+- **Rename an issue**: `issue update-title --issue <number> --title "New title"` (optionally `--expected-title "Old title"` or `--expected-content-version <version>`)
+- **List issues**: `python <gitea-issues>/scripts/gitea.py issue list --state open` (add `--label` / `--exclude-label` filters, `--output json` for structure)
+- **Create an issue**: `issue create --title "..." --body-file - --label status/ready-for-agent` with the body on standard input, using the `## Problem` / `## Scope` / `## Acceptance Criteria` structure
+- **Comment**: `issue comment --issue <number> --body "..."`
+- **Change status**: `issue set-status --issue <number> --status status/<role>`
+- **Edit classification**: `issue edit-labels --issue <number> --add <label> --remove <label>` (repeat either flag; omit either when unused)
+- **Start implementation**: `issue start --issue <number>` — creates the `ISSUE-<number>` branch in a dedicated worktree and prints the path every later command must use
+- **Close reviewed work**: `pr cleanup` merges the reviewed pull request and reconciles the issue; `issue close --status status/done` closes an explicitly authorized resolved decision, and `--status status/wontfix` closes declined non-implementation work with a short marker-backed explanation
+- **Clean up a merged worktree**: `issue remove-worktree --issue <number> --pull <number>` — fast-forwards local `main` to the fetched remote tip (stopping with resolution commands before any deletion when it cannot) and removes the worktree and its branch
+
+Repository identity comes from the `origin` remote or the resolved credentials;
+the helpers never need a token pasted into chat.
+
+`issue update-title` sends a title-only edit with Gitea's preflight
+`content_version` check and verifies a fresh readback. Gitea does not provide
+an atomic title compare-and-swap, so a concurrent edit can still race. The
+command directs a check of the actual owning roadmap or epic entry and reports
+child `Parent:` lines that need separate guarded repair. Its own `Parent:` line
+is only a hint; preserve entry order and checkboxes.
+
+Read-only commands (`issue list`, `queue roadmap|inspect|next`, `epic
+next-ready`/`start-next` selection) reuse unchanged reads through a
+conditional cache that never touches mutation preflights or read-after-write
+verification. Disable it with `GITEA_READ_CACHE=off`, inspect it with
+`read-cache status`, and clear it with `read-cache clear`; see the skill's
+`references/read-cache.md` for the freshness contract.
+
+## Label vocabulary
+
+Status labels are the agent-writeable source of truth. When a status Project is
+configured in `docs/agents/issue-board.toml`, successful lifecycle commands
+request card reconciliation through `issue-project-board`. The board displays
+status and prerequisites; the roadmap remains the priority source:
+
+`status/needs-triage`, `status/needs-info`, `status/ready-for-agent`,
+`status/ready-for-human`, `status/in-progress`, `status/review`,
+`status/done`, `status/wontfix`, plus `priority/P0` as an exceptional interrupt
+indicator. Type labels (`type/epic`, `type/feature`, `type/bug`, …) and area
+labels classify work. Install missing names idempotently with
+`labels setup --dry-run` then `labels setup`; existing labels are preserved.
+`board/archived` is a non-status label for a closed `status/done` or
+`status/wontfix` issue kept searchable outside the status board. Initial board
+migration and later selected archival require reviewed previews in
+`issue-project-board`; ordinary closure still adds a Done or Won't Fix card.
+`board/finalizing` marks an in-progress epic whose listed children are closed
+`status/done` while final gates are checked. Other in-progress epics appear in
+Active Epics; individual work stays in In Progress. Existing eight-column
+boards use the reviewed `issue-project-board` migration.
+See `docs/agents/triage-labels.md` for the triage-role mapping and
+`docs/agents/queue.md` for the roadmap contract.
+
+`issue edit-labels` changes only named existing non-status labels, preserving
+unrelated labels. It validates every requested name before writing, adds before
+removing, and verifies the requested result with a fresh read. A satisfied
+replay writes nothing. Use `issue set-status` for `status/*` transitions.
+Writes are incremental: after a write or verification failure, reconcile with
+`issue read` before retrying. Changing `type/epic` does not create child order,
+blocking edges, or roadmap placement; use their separate helper operations.
+
+## The repository work queue
+
+Exactly one open issue labelled `type/roadmap` holds the
+`## Work Queue In Priority Order` section that defines repository priority;
+epics order children the same way. Each list entry uses `- [ ] #123 Title` or
+`- [x] #123 Title`; checkboxes display closed `status/done` progress and do
+not change workflow state. `queue inspect` reports disagreements. Convert
+numbered lists only through reviewed `checklist preview` and guarded
+`checklist apply`. Dependencies gate execution; they never define priority.
+
+- **Inspect**: `queue inspect` (health, skipped entries, tree-invariant violations, selected leaf)
+- **Read placement state**: `queue roadmap` (top-level order and content version)
+- **Select read-only**: `queue next`
+- **Maintain**: `queue init` (idempotent), `queue insert --issue <n> --position <p> --expected-content-version <v>`, `queue reorder`, `queue link-children preview` / `apply --confirm` (direct-child blocking edges)
+- **Move to `independent` mode**: the reviewed edge migration — `migration preview --history --write-plan <file>`, `migration freeze`, `migration apply --plan <file>`, `migration readiness`, then a reviewed configuration commit (see the gitea-issues `references/repository-queue.md`)
+
+Only top-level delivery epics and explicitly standalone issues
+(`--allow-standalone`) enter the roadmap. When the user has not stated a
+priority, new work enters at the default position from the gitea-issues
+queue-placement contract — the highest its dependencies allow — and an
+explicit statement always wins. The queue tree carries one
+invariant — every open issue except the roadmap itself sits on exactly one
+priority list and blocks that parent — specified in full in the gitea-issues
+`references/repository-queue.md` reference. Inserting an open entry — epic or
+standalone — links it as blocking the roadmap, so the Gitea UI **Blocks**
+section links each level to the root; the roadmap never takes dependency
+edges beyond its direct children (its queue entries). `queue link-children`
+repairs missing direct-child edges.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external
+PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, external PRs run through the same status labels as issues:
+read them with `issue read --issue <number> --comments`, label with
+`issue set-status`, and triage contributor PRs (not owner/maintainer work)
+through `/triage`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue with `issue create`, then place it explicitly: group
+implementation work under a delivery epic (children linked with
+`epic add-dependency --parent <epic> --child <child>`, the legacy alias of
+`prerequisite add --issue <epic> --requires <child>`, and ordered in the epic's
+`## Child Issues In Priority Order` section) and insert only the epic — or an
+explicitly standalone issue — into the roadmap with `queue insert`. Creation
+and placement stay two separate, reconcilable operations; when the user gave
+no priority, apply the default-placement rule from that contract and say so
+with the proposal, and publish unqueued only when placement is genuinely
+unresolved.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `issue read --issue <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue labelled `wayfinder:map`;
+its **child tickets** are plain issues that block the map.
+
+- **Map**: `issue create --title "..." --label wayfinder:map` holding the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: an issue labelled `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`) with `Part of #<map>` at the top of its body, linked to the map with `prerequisite add --issue <map> --requires <n>` (the map waits for each ticket).
+- **Blocking**: Gitea dependency links — the map is blocked by every child. `issue read` reports open blockers, which are the live gate.
+- **Frontier query**: `issue list --state open --label wayfinder:map`-scoped children (list open issues, keep those mentioning `Part of #<map>`), drop any with an open blocker or `status/in-progress`; first in map order wins.
+- **Claim**: move the ticket to `status/in-progress` with `issue set-status`.
+- **Resolve**: `issue comment --issue <n> --body "<answer>"`, then use `issue close --issue <n> --status status/done --comment "Decision accepted; see the resolution comment."` for an explicitly authorized accepted decision; use `status/wontfix` for declined work and `pr cleanup` for PR-backed implementation. Gist the decision into the map's Decisions-so-far.

docs/agents/issue-workflow.toml

@@ -0,0 +1,8 @@
+# The relationship mode and the one authoritative priority source, read by the
+# gitea-issues helpers from the default branch. Change it only through a
+# reviewed commit: activation, rollback, and source changes are migrations.
+relationship_mode = "legacy"
+
+[priority_source]
+kind = "roadmap"
+issue = 2

docs/agents/queue.md

@@ -0,0 +1,104 @@
+# Work Queue
+
+How this repository decides what is next. The contract in one paragraph: exactly
+one open issue labelled `type/roadmap` carries a `## Work Queue In Priority
+Order` section; that order — with epic `## Child Issues In Priority Order`
+sections beneath it — is repository priority. Dependency links gate execution;
+status labels gate readiness. Neither ever overrides the written order. The
+queue tree carries one invariant — every open issue except the roadmap itself
+sits on exactly one priority list and blocks that parent — specified in full
+in the gitea-issues `references/repository-queue.md` reference. Every open
+direct child of the roadmap — epic or standalone entry — blocks the roadmap,
+one edge per direct child and never edges to the whole backlog, so the Gitea
+UI **Blocks** section links each level of the tree to the root.
+
+Priority lists use `- [ ] #123 Title` and `- [x] #123 Title`. Physical order
+sets priority; the checkbox is a progress display. A checked entry represents
+a closed issue with `status/done`, including an epic accepted and closed
+separately. `status/wontfix` and historical closed issues without
+`status/done` stay unchecked. `queue inspect` reports disagreements; clicks
+never change readiness, closure, or prerequisites. Convert numbered lists
+through reviewed `checklist preview` and guarded `checklist apply`.
+
+## Reading the queue
+
+- **Health and explanations**: `queue inspect` — status counts, skipped
+  entries, unqueued ready work, tree-invariant violations, structural
+  anomalies.
+- **Placement and reconciliation**: `queue roadmap` — targeted top-level order
+  and current `content_version`, without dependency scans.
+- **What is next**: `queue next` — read-only selection of the highest-priority
+  executable leaf, with every higher-ranked skip explained.
+
+Both are read-only. Inspecting never claims anything; claim separately with
+`issue start --issue <number>`, which creates the `ISSUE-<number>` worktree and
+moves the issue to `status/in-progress`.
+
+## Changing the queue
+
+Queue edits are explicit mutations, never side effects of other work:
+
+- `queue init` — create the canonical roadmap if absent (idempotent).
+- `queue insert --issue <n> --position <p> --expected-content-version <v>` —
+  add a top-level epic, or a standalone issue with `--allow-standalone`.
+  Inserting an open entry — epic or standalone — also links it as blocking
+  the roadmap (reported separately from the body write).
+- `queue reorder --issue <n> ... --expected-content-version <v>` — rewrite the
+  top-level order, naming every current entry exactly once.
+- `queue link-children preview` / `apply --confirm` — classify and repair the
+  direct-child blocking edges to the roadmap (read-only preview; confirmed
+  apply creates exactly the missing edges, streaming `[queue]` progress
+  milestones with the terminal summary and exit status authoritative).
+
+Mutations send the optimistic-locking `content_version` printed by `queue roadmap`.
+On any ambiguous result, re-run `queue roadmap` and reconcile before retrying;
+never blindly re-run a mutation.
+
+## Adopting existing epics
+
+Epics created before this contract may carry legacy child-order sections.
+`epic migrate-children preview` inventories them read-only and classifies each
+open epic; the owner confirms each proposed migration, and
+`epic migrate-children apply --epic <n> --expected-content-version <v>`
+rewrites one epic at a time under the queue contract's rules. Ambiguous epics
+go back to the owner with their diagnostics. The gitea-issues
+`references/repository-queue.md` reference documents the full contract.
+
+## Moving to independent mode
+
+In `legacy` mode, which this document describes, a native edge may mean
+containment, navigation, or a prerequisite. A repository moves to
+`independent` mode — edges mean prerequisites only — through a reviewed
+migration, never a setup rerun: `migration preview --history --write-plan <file>` classifies every
+edge read-only, the owner reviews the plan, `migration freeze` makes every
+roadmap-driven helper fail closed, `migration apply --plan <file>` removes
+only the projection edges the evidence proves and writes each placed
+issue's `Parent:` line, `migration readiness` confirms nothing blocks, and a
+reviewed commit of `relationship_mode = "independent"` activates it. The
+gitea-issues `references/repository-queue.md` reference documents recovery
+and rollback.
+
+## Who enters the roadmap
+
+Only two kinds of issue: a top-level delivery epic, and an explicitly
+standalone actionable issue. Epic children never enter the roadmap — they stay
+in the epic's child-priority list plus dependency links, under the
+queue-tree invariant stated above.
+
+## Default placement for new issues
+
+Newly published work with no priority statement from the user enters at the
+default position — the highest its dependencies allow, per the default rule
+in the gitea-issues `references/create-and-organize.md` queue-placement
+contract; an explicit statement from the user always wins. Creation and
+placement remain two explicit, reconcilable operations either way, and
+genuinely unresolved placement still publishes unqueued and stays visible
+under "Unqueued ready work".
+
+## After reviewed work merges
+
+`pr cleanup` merges reviewed work and reconciles its issue. Continuation then
+recommends exactly one follow-up, in order: newly unblocked dependents, the
+current epic's next executable child, the roadmap's next executable leaf, or an
+explicit blocked/empty result. Recommendations only — starting the next issue
+needs its own authorization.

docs/agents/standards.md

@@ -0,0 +1,146 @@
+# Working Standards
+
+The philosophies every session in this repository works under. The
+`## Agent skills` block in the agent instructions carries the one-line rules;
+this document is the authority behind them and is safe to extend per repo.
+
+## Documentation and tests are first-class artifacts
+
+Code may be replaced, but durable decisions, behavior, and lessons must remain
+recoverable from focused documentation and verification artifacts. A future
+agent with no conversation history should be able to determine:
+
+- what the system currently does;
+- which behavior is only proposed, not implemented;
+- why important architectural decisions were made, and which observations
+  informed the foundational ones (`docs/evidence/`);
+- how to verify implemented behavior;
+- which earlier approaches are retained only for context (`docs/historical/`).
+
+## Documents versus the issue tracker
+
+The issue tracker is the queue for actionable work and holds the transient
+working context of one change; repository documents are the durable memory. A
+closed issue thread is not a supported reference for current behavior. When an
+issue resolves a term or a decision, record it in `CONTEXT.md` or an ADR
+rather than leaving it only in the thread; an idea too valuable to lose and
+not actionable enough to be an issue belongs in the domain documents, not in
+an issue comment.
+
+Before addressing an issue, read the issue with its comments, every other
+issue in its epic, and the issues in related epics. Confirm scope, boundaries,
+and dependencies before planning.
+
+## Writing current-truth documents
+
+`CONTEXT.md` and the ADRs describe what the system does, in present tense, as
+a contract — not a narrative of the change that produced them.
+
+- Test every sentence carrying an issue reference by deleting the number: if
+  the sentence stays true, the reference was decoration and goes; if it stops
+  making sense, rewrite it as a statement of current behavior. ADRs keep
+  their references — they are decision records.
+- ADRs are immutable. Never rewrite a decided ADR; mark it superseded and
+  record the replacement decision in a new ADR that links back.
+- State uncertainty explicitly, and label proposed behavior as proposed.
+- When verified behavior lands, reconcile `CONTEXT.md` and the ADRs in the
+  same iteration. Never document behavior that does not exist yet.
+
+## Historical records
+
+`docs/historical/` holds superseded designs, archived handoffs, and
+development records. Use it to understand how the project arrived at its
+current state; never treat it as current behavior. When reconciling
+documents after verified behavior lands, move superseded context that still
+explains decisions or discarded alternatives to `docs/historical/` rather
+than deleting it. Decisions themselves supersede through the ADR mechanism,
+not by moving.
+
+## Design evidence and issue history
+
+Choose a record's destination by its purpose, not its format, rigor, or size:
+
+- `docs/evidence/` holds only curated observations that materially inform a
+  named foundational product-design decision and stay useful after the
+  implementation issue is forgotten. Its `README.md` carries the admission
+  rule, examples, and a lightweight record shape.
+- `docs/historical/issue-notes/<issue-number>/` holds durable records of one
+  issue's work — test runs, review findings, debugging chronology, shakedown
+  or replay reports, handoffs — created only when worth retaining.
+- The pull request or issue holds issue-specific verification that needs no
+  repository archive.
+
+The ADR or authoritative document keeps the decision and its concise
+rationale and may link supporting evidence. Evidence never declares current
+behavior, and issue notes are history, never current truth. A routine change
+needs no new document, directory, or evidence record; an ADR link alone does
+not make verification qualify as evidence.
+
+## Documentation disposition
+
+The implementing session records one documentation disposition on the issue
+or pull request before completion — in an issue comment on trackers without a
+pull-request template. On Gitea, `/cleanup` blocks the merge without one.
+
+`CONTEXT.md` and ADRs are created lazily (see `docs/agents/domain.md`): a
+change that resolves no new term or decision records `not_required` rather
+than forcing a document into existence.
+
+- **updated** — verified behavior was reconciled into `CONTEXT.md` and the
+  ADRs as present-tense contracts;
+- **not_required** — the change made no durable behavioral or architectural
+  difference; say why in one line;
+- **deferred** — documentation work remains; normal completion waits unless
+  the owner explicitly accepts the deferral;
+- **blocked** — documentation cannot be reconciled because implementation or
+  verification evidence is insufficient.
+
+## Build discipline
+
+Tests are part of the specification. Write the failing test first at the
+spec's pre-agreed seams and make it green with the minimal change — red
+before green, one seam, one test per cycle. Test-after is reserved for glue
+and wiring, UI verified by a manual test plan, and throwaway prototypes.
+
+## Verification cadence
+
+During implementation and review follow-ups, run the focused checks for the
+changed areas and their immediate contracts or consumers, on the exact
+current head. A later code, test, configuration, or documentation change
+invalidates the affected evidence and requires those checks again.
+
+Reserve the complete gate declared as the epic gate for the final integrated
+epic commit, before epic acceptance and closure. Existing successful CI
+satisfies it only when bound to that exact commit. Run a repository-wide
+suite earlier only when explicitly requested, when a failure cannot be
+localized, or when a change to shared test infrastructure, root
+configuration, or a foundational contract has an unbounded blast radius — and
+state the reason before starting it.
+
+Do not delete, weaken, skip, or consolidate tests solely to reduce runtime.
+Pruning is legitimate only with evidence that the coverage is obsolete or
+redundant, the behavior preserved at the lowest faithful layer, and the
+verification documentation updated.
+When automated coverage is not practical for an enduring contract, record a
+repeatable manual procedure and its expected result beside that contract.
+
+## Merge evidence
+
+Every pull request carries the evidence that caused it to be merged, recorded
+before the merge: screenshots for a visible interface, brief command output
+for command-line behavior, the focused checks that passed and the exact head
+they ran against when the effect is not observable through any interface.
+Attribute a reported observation to whoever made it rather than presenting it
+as independently verified, and never attach evidence that was not examined.
+An unrecorded verification did not happen. Merge evidence lives on the pull
+request (or under `docs/historical/issue-notes/<issue-number>/` when worth
+retaining); it is not a `docs/evidence/` record.
+
+## Commands given to the user
+
+A command presented as runnable must be ready to run as written — no
+unresolved placeholder such as `/absolute/path/to/...`, `<your-token>`, or an
+unassigned `$VALUE`. When a value cannot be known while drafting, give the
+exact command that discovers it, then the command that consumes it, and say
+how to substitute the result. Use the repository's documented shell where it
+declares one; otherwise prefer POSIX-compatible syntax.

docs/evidence/README.md

@@ -0,0 +1,104 @@
+# Design Evidence
+
+This directory holds curated observations and analyses that materially inform
+a named, **foundational** product-design decision: a durable choice about
+product behavior, architecture, boundaries, core methodology, or a constraint
+that shapes the product across individual implementation issues.
+
+It is not an archive. Most changes add nothing here, and completing an issue
+never requires an entry.
+
+## Admission
+
+Ask: **would a future maintainer need this record to understand, challenge, or
+revisit a foundational product choice after forgetting the implementation
+issue?** If the record's value is only establishing that one change passed its
+checks, or describing how work proceeded, it belongs with the issue instead.
+
+A qualifying record explains:
+
+- which foundational decision or documented design question it informs;
+- what observations bear on the alternatives or constraints, and how;
+- why those observations stay useful beyond the issue that produced them.
+
+Purpose decides, not format, rigor, or size. A rigorous measurement, a passing
+test suite, or a link to an ADR does not qualify a record on its own, and an
+ADR is never created just to give routine verification somewhere to point.
+
+## Where material goes
+
+| Material | Destination |
+| --- | --- |
+| Current product design, contracts, and constraints | `docs/authoritative/`, per `docs/agents/domain.md` |
+| A decision and its concise rationale, including meaningful trade-offs | `docs/authoritative/adr/` |
+| Curated observations materially informing a foundational design choice | `docs/evidence/` |
+| Durable records of one issue's work: test runs, review findings, debugging chronology, shakedown or replay reports, handoffs | `docs/historical/issue-notes/<issue-number>/` |
+| Issue-specific verification that needs no repository archive | the pull request or issue body and comments |
+
+`<issue-number>` is the tracker's issue number: issue 186's retained records
+live below `docs/historical/issue-notes/186/`. Create that directory only when
+something is worth retaining.
+
+The ADR or authoritative document keeps the "why"; it links here when a
+supporting record helps. Evidence informs a decision — it never declares
+current behavior or silently overrides the authoritative document. Issue notes
+are history, never current truth.
+
+## Examples
+
+Qualifies:
+
+- An evaluation of methodology alternatives behind the product's durable
+  grading contract or experimental design.
+- A data-quality study that establishes a foundational dataset-selection or
+  exclusion policy.
+- Accuracy, latency, and resource measurements that explain a core
+  model-serving architecture choice.
+- A failed experiment or contradictory observation that materially informs such
+  a decision, or explains why a serious alternative was rejected.
+
+Does not qualify:
+
+- "Issue 186 passed 260 tests", CI output, coverage summaries, or merge receipts.
+- One patch's replay results, admission or qualification receipts, debugging
+  logs, an implementation chronology, or an agent handoff.
+- A benchmark run, literature collection, or research note with no demonstrated
+  connection to a foundational product-design decision.
+
+Mixed purpose: when issue work reveals a foundational insight, leave the
+original verification and history where they are, and write a focused
+synthesis here that states the design implication and links to those sources.
+Do not promote the whole issue diary or duplicate its raw artifacts.
+
+## Record shape
+
+Keep only the provenance that helps someone assess the design implication.
+Name files by topic or decision (`serving-latency-trade-offs.md`), not by issue
+or test run. There is no required schema; a record usually covers:
+
+```md
+# Serving latency trade-offs
+
+Informs: the model-serving architecture (link the ADR or design document).
+Date and identities: 2026-03-02; code a1b2c3d, dataset v4, model m-7.
+
+## Observations
+
+What was measured or seen, how, and from which source. Keep large raw
+artifacts in their artifact store and reference them by stable location and
+hash.
+
+## Interpretation
+
+What the observations suggest for the alternatives, kept separate from the
+observations themselves. Include counterevidence.
+
+## Limitations and implications
+
+What the evidence cannot show, and what it means for the design.
+```
+
+When a later decision changes the picture, add a linked correction or
+superseding analysis rather than rewriting the old result, so its historical
+qualifications stay visible. Records need not endorse the currently accepted
+choice, but each must stay meaningfully connected to a foundational decision.

packages/implementer-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: implementer-investigation
+description: Investigate source, generated configuration, load order and negative search results within the assigned implementer boundary.
+metadata:
+  relayview-display-name: Implementer investigation
+  relayview-version: 0.7.0
+---
+
+Use the admitted command/filesystem boundary. Inspect relevant package defaults,
+system configuration, runtime state, reference repositories and symlink targets
+read-only when that boundary admits them. Use absolute paths and line numbers
+when reporting external findings. If access is denied, use the owner-provided
+recovery contract and identify the missing evidence.
+
+The included investigation resource supplies the search method.

packages/implementer-investigation/investigation.md

@@ -0,0 +1,14 @@
+# Search and investigation
+
+Trace load order before treating a negative search as evidence of absence. Follow
+includes, imports, sources, require/dofile calls, symlinks and generated outputs
+within the assigned boundary. Identify which file is actually loaded and whether
+a generator or package default supplies its value.
+
+Search interpreted configuration for literal values and expression pieces:
+modifier variables (mainMod, modKey, mod, leader), key or path fragments, function
+and dispatcher names, modes, section names and visible outcomes. For example,
+a binding may join mainMod with " + S" rather than contain "SUPER + S".
+Combine alternatives in one broad search where the assigned search tool supports
+it. When results are empty, check the search method, load order and admitted scope
+before concluding the behavior is missing.

packages/implementer-investigation/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.7.0"
+  },
+  "role": "implementer",
+  "step": "implementation",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "7775acb6525cf134d33321c3f4d79c074903086dc948138ef747af53f88e8ef5"
+    },
+    {
+      "path": "investigation.md",
+      "sha256": "714f05eb6cd6f68fe7a44ed352fffcc6309a348d9184edb03b4724c16af9228c"
+    }
+  ]
+}

packages/planner-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: planner-investigation
+description: Investigate source, generated configuration, load order and negative search results within the assigned planner boundary.
+metadata:
+  relayview-display-name: Planner investigation
+  relayview-version: 0.7.0
+---
+
+Use only assigned read roots and the assigned read/search tools. Investigate
+package defaults, generated configuration, runtime state or reference repositories
+only when they are in those roots. If relevant evidence lies elsewhere, identify
+the missing evidence and use the owner-provided supporting-evidence recovery
+contract. Check that each cited file belongs to an assigned root.
+
+The included investigation resource supplies the search method.

packages/planner-investigation/investigation.md

@@ -0,0 +1,14 @@
+# Search and investigation
+
+Trace load order before treating a negative search as evidence of absence. Follow
+includes, imports, sources, require/dofile calls, symlinks and generated outputs
+within the assigned boundary. Identify which file is actually loaded and whether
+a generator or package default supplies its value.
+
+Search interpreted configuration for literal values and expression pieces:
+modifier variables (mainMod, modKey, mod, leader), key or path fragments, function
+and dispatcher names, modes, section names and visible outcomes. For example,
+a binding may join mainMod with " + S" rather than contain "SUPER + S".
+Combine alternatives in one broad search where the assigned search tool supports
+it. When results are empty, check the search method, load order and admitted scope
+before concluding the behavior is missing.

packages/planner-investigation/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.7.0"
+  },
+  "role": "planner",
+  "step": "planning",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "e1410558c392100d9557d118a9d82e1068ed7a42142bcfe076f09ceed0dac966"
+    },
+    {
+      "path": "investigation.md",
+      "sha256": "714f05eb6cd6f68fe7a44ed352fffcc6309a348d9184edb03b4724c16af9228c"
+    }
+  ]
+}

packages/reviewer-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: reviewer-investigation
+description: Investigate source, generated configuration, load order and negative search results within the assigned reviewer boundary.
+metadata:
+  relayview-display-name: Reviewer investigation
+  relayview-version: 0.7.0
+---
+
+Use only assigned read roots and the assigned read/search tools. Investigate
+package defaults, generated configuration, runtime state or reference repositories
+only when they are in those roots. If relevant evidence lies elsewhere, identify
+the missing evidence and use the owner-provided supporting-evidence recovery
+contract. Check that each cited file belongs to an assigned root.
+
+The included investigation resource supplies the search method.

packages/reviewer-investigation/investigation.md

@@ -0,0 +1,14 @@
+# Search and investigation
+
+Trace load order before treating a negative search as evidence of absence. Follow
+includes, imports, sources, require/dofile calls, symlinks and generated outputs
+within the assigned boundary. Identify which file is actually loaded and whether
+a generator or package default supplies its value.
+
+Search interpreted configuration for literal values and expression pieces:
+modifier variables (mainMod, modKey, mod, leader), key or path fragments, function
+and dispatcher names, modes, section names and visible outcomes. For example,
+a binding may join mainMod with " + S" rather than contain "SUPER + S".
+Combine alternatives in one broad search where the assigned search tool supports
+it. When results are empty, check the search method, load order and admitted scope
+before concluding the behavior is missing.

packages/reviewer-investigation/relayview-skill.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.7.0"
+  },
+  "role": "reviewer",
+  "step": "review",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "f3c6395f3d077ad1a7901cf31ec7656df032292d0181be9dc8a18e36b92769c9"
+    },
+    {
+      "path": "investigation.md",
+      "sha256": "714f05eb6cd6f68fe7a44ed352fffcc6309a348d9184edb03b4724c16af9228c"
+    }
+  ]
+}

tests/test_packages.py

@@ -12,6 +12,21 @@ ROOT = Path(__file__).resolve().parents[1]
 
 
 class PackageTests(unittest.TestCase):
+    def test_role_investigation_packages(self):
+        for role, step in (("planner", "planning"), ("implementer", "implementation"), ("reviewer", "review")):
+            package = ROOT / "packages" / f"{role}-investigation"
+            check_package(package)
+            manifest = json.loads((package / "relayview-skill.json").read_text())
+            self.assertEqual((manifest["role"], manifest["step"]), (role, step))
+            text = (package / "SKILL.md").read_text() + (package / "investigation.md").read_text()
+            self.assertIn("Trace load order", text)
+            self.assertIn("expression pieces", text)
+            self.assertNotIn("disable-model-invocation: true", text)
+            if role != "implementer":
+                self.assertIn("assigned read roots", text)
+                for host in ("/etc/", "/usr/share/", "$HOME", "rg -n"):
+                    self.assertNotIn(host, text)
+
     def test_designer_release_modes_and_source(self):
         automatic = "issue-designer-default"
         manual = (