Align maintained package fixture with planner scope release

Reviewed-on: #12

.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,8 +6,14 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 
 | Directory | Status | Role / step | Version |
 | --- | --- | --- | --- |
-| `packages/planner-scope` | Maintained default | Planner / planning | 0.3.0 |
+| `packages/{planner,implementer,reviewer}-investigation` | Maintained automatic guidance | One matching role / step each | 0.7.0 |
+| `packages/planner-scope` | Maintained default | Planner / planning | 0.8.0 |
 | `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 |
+| `packages/issue-designer-default` | Maintained default | Designer / design | 0.6.1 |
+| `packages/designer-wayfinder`, `designer-grilling` | Optional manual guidance | Designer / design | 0.6.0 |
+| `packages/designer-prototype` | Optional manual guidance | Designer / design | 0.6.2 |
+| `packages/designer-research`, `designer-domain-modeling`, `designer-triage` | Optional manual guidance | Designer / design | 0.6.0 |
+| `packages/designer-to-spec`, `designer-to-tickets` | Optional manual guidance | Designer / design | 0.6.0 |
 | `packages/codebase-design` | Optional guidance | Planner / planning | 0.3.0 |
 | `packages/grill-me` | Optional guidance | Planner / planning | 0.3.0 |
 | `packages/grilling` | Optional guidance | Planner / planning | 0.3.0 |
@@ -29,7 +35,7 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 | `packages/c4-diff` | Optional guidance | Reviewer / review | 0.3.0 |
 | `examples/starter-planner` | Illustrative starter; not a production default | Planner / planning | 0.1.0 |
 
-Only named releases of maintained packages receive RelayView compatibility testing and maintenance. Optional guidance requires explicit role assignment; the two original defaults remain available. User forks are maintained by their publishers. This release uses the instruction package schema version 1 admitted by RelayView's Community MVP. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
+Only named releases of maintained packages receive RelayView compatibility testing and maintenance. Optional guidance requires explicit role assignment; the Planner and Implementer defaults remain available alongside the pinned Issue Designer default. User forks are maintained by their publishers. This release uses the instruction package schema version 1 admitted by RelayView's Community MVP. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
 
 ## A named set in RelayView
 
@@ -48,7 +54,7 @@ The screenshot's ordered manual members come from this excerpt under `trustedSki
   members: [code-review, c4-diff]
 ```
 
-The two maintained defaults are original RelayView packages. Some optional guidance adapts earlier MIT-licensed skills; see the [third-party notices](NOTICE.md).
+The maintained defaults are original RelayView packages. Some optional guidance adapts earlier MIT-licensed skills; see the [third-party notices](NOTICE.md).
 
 ## Fork the starter
 
@@ -62,9 +68,19 @@ python -m tools.packages pack examples/starter-planner dist/starter-planner.zip
 
 Replace `examples/starter-planner` in the last two commands with your package directory. The `pack` command writes a reproducible ZIP containing the package, `LICENSE`, and `NOTICE.md`, then prints its SHA-256. The check returns the owner's package identity digest. Both use only Python 3's standard library and this repository's source. Preserve the license and notice when redistributing the package or fork.
 
-To use a user fork, place its closed package directory under the owner's configured trusted root and use Settings → Skills to import the relative `SKILL.md` path under a new unique ID. Import validates and records the package; it does not assign it. Add that ID to a role-compatible named set in the owner configuration and restart the owner to load the set. Then select the set for the matching role in Settings → Skills and save. That selection takes effect for future sessions immediately; existing sessions retain their captured bytes. The Settings catalog displays source, version, digest, role, step, and pending versus effective assignment. The owner's admission remains authoritative even when these local checks pass.
+To use a user fork, place its closed package directory under the owner's configured trusted root. For Planner, Implementer, or Reviewer guidance, use Settings → Skills to import the relative `SKILL.md` path under a new unique ID. Import validates and records the package; it does not assign it. Add that ID to a role-compatible named set in the owner configuration and restart the owner to load the set. Then select the set for the matching role in Settings → Skills and save. For an optional Designer method, declare its ID and relative `SKILL.md` path in `trustedSkills.catalog`, list the ID in `workflowPresets.designerSkills`, and restart the owner. Designer has no Settings import or set selector for this assignment. These assignments affect future sessions; existing sessions retain their captured bytes. The owner's admission remains authoritative even when these local checks pass.
 
-To use a maintained default, copy its release package under the same trusted root, admit its `SKILL.md` through the owner catalog, then select it for its declared role in Settings. Settings import accepts user-source packages; configure first-party packages in the owner catalog. Select a fork with `source.kind: user` and a distinct ID to replace that role's future assignment. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Neither selection changes a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow.
+To use a maintained Planner or Implementer default, copy its release package under the same trusted root, admit its `SKILL.md` through the owner catalog, then select it for its declared role in Settings. Settings import accepts user-source packages; configure first-party packages in the owner catalog. Select a fork with `source.kind: user` and a distinct ID to replace a Planner or Implementer future assignment. RelayView pins and assigns the Issue Designer default automatically; its optional methods use `workflowPresets.designerSkills`. Planner guidance uses existing read and planning tools; Implementer guidance uses existing implementation and reporting tools. Guidance selection does not change a role's tools, credentials, lifecycle stages, validation requirements, Gitea effects, review, merge, or Human acceptance. The owner keeps the existing Gitea task workflow.
+
+## Write the guidance
+
+A package's instructions are read by a model, so write them for one. Before adding an instruction, especially in response to behavior seen in a run, ask:
+
+- Can RelayView's owner determine the result from facts it holds? Then the owner should produce it, and the guidance should use it.
+- Does the text state the action to take and a check the agent can run on the result, rather than what to avoid?
+- Does the environment the agent works in differ from the familiar one it expects? Name each difference and the action that handles it.
+
+Judge a change over several runs, using the tool calls each run made, not one successful conversation. RelayView's `docs/authoritative/architecture-heuristics.md`, under "Model-Facing Work", records these defaults in full.
 
 ## Release identity
 

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/designer-domain-modeling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-domain-modeling
+description: Sharpen project terms, invariants, and boundaries for an issue draft.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer domain modeling
+  relayview-version: 0.6.0
+---
+
+# Domain modeling
+
+Read the assigned project's current context and relevant authoritative contracts. Name concepts in the project's own vocabulary; identify identities, state transitions, invariants, and boundaries that the proposed work touches. Ask the Human when a term or invariant changes acceptance. Put the resulting definitions and open choices in the draft without claiming a repository document was edited.

packages/designer-domain-modeling/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "cfb72adc02cf0a488c341d965c16e22d22e90c52ab0540a9072b09c592d1abd7"
+    }
+  ]
+}

packages/designer-grilling/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-grilling
+description: Stress test one proposed issue design through focused Human questions.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer grilling
+  relayview-version: 0.6.0
+---
+
+# Grilling
+
+State the design and scope to be challenged and seek the Human's agreement before entering this method. Probe one consequential assumption at a time: behavior, boundary, dependency, failure, or verification. Use each answer to choose the next question. Stop when the important branches are resolved or explicitly left open; summarize the agreed design and open decisions in the draft.

packages/designer-grilling/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "431da86a21da7b74fa55bce36c1e0fc806d066cd8b1ace7a784e1eb4a2db4a89"
+    }
+  ]
+}

packages/designer-prototype/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: designer-prototype
+description: Plan a bounded throwaway prototype to answer a design question.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer prototype
+  relayview-version: 0.6.2
+---
+
+# Prototype
+
+Propose the exact question, bounded code or data scope, expected preview or data effects, and limits to the Human before entering this method. Use only owner-admitted prototype controls after agreement. Treat observations as evidence about the question, not production behavior. Record what was tried, observed, and still uncertain; keep throwaway changes out of the issue's implementation claim.
+
+## Let the Human try it as a user
+
+The Human answers the question by using the prototype the way the software's user will. The commands they type are part of the design under review: the command name, its arguments and options, and the directory it runs from.
+
+- Prepare the scenario yourself before handing over. Create the sample data, repositories, and earlier history the question needs, and run any setup steps, so the scenario is ready when the Human arrives.
+- Put the scenario's data where the app finds it by default, such as its default config or source directory under HOME, so the user's command needs no extra options.
+- Make the Human's first command one the software's user will type: the real command name, the syntax this change proposes, and the arguments a user would pass, run from the directory where a user would be.
+- Give each command to try exactly as that user types it, and say what it shows.
+- Give the Human only the commands needed to answer the design question. Add a reset command only when one of those commands changes the scenario; then put it in `/scratch/bin` and give it by its name alone, followed by the command to try again.
+- Ask the Human about what they saw as a user of the software, in terms of the design question.
+
+## Before handing over
+
+Work through this checklist, then give the Human the shell command and the first command to try:
+
+1. The app's command runs by its own name from `/scratch/bin`: a configured command the owner listed, or a launcher you wrote. Run `cd` to the command directory, then the command with an unknown option, and confirm its usage message names the command as the user types it.
+2. The scenario's data is where the app finds it by default under the workspace's HOME.
+3. Helper commands are in `/scratch/bin`, so the Human runs each by its name.
+4. The command directory is set with `configure` to where the app's user runs the app.
+5. You ran the first command to try yourself, exactly as the Human will type it, from that directory, and it showed what the question is about.

packages/designer-prototype/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.2"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "b72f085f33c10ea48f69fbe55c4f364f6a873a8ae2e6baeb8eaf2aaf71df5045"
+    }
+  ]
+}

packages/designer-research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-research
+description: Research a design question using admitted repository, tracker, and public sources.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer research
+  relayview-version: 0.6.0
+---
+
+# Research
+
+Frame the question and the decision it informs. Prefer current primary sources and the assigned repository's authoritative documents. Use only the owner's assigned repository, tracker, and brokered public research tools and active request budget. For each conclusion, keep source, observation time, and completeness visible. Distinguish a source statement from your inference and record material gaps in the draft.

packages/designer-research/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "676c4291d4bab19c76c0d945eefe21aa6787783e4e2d2285e0d6e270303d1e94"
+    }
+  ]
+}

packages/designer-to-spec/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-to-spec
+description: Turn an agreed problem into a complete reviewable issue specification.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer to spec
+  relayview-version: 0.6.0
+---
+
+# To spec
+
+Use the agreed problem and observed project contracts to draft an outcome, scope boundaries, acceptance observations, failure and recovery behavior, and open decisions. Check prerequisites against the assigned tracker and mark uncertain links as proposed. Save the complete text through the owner-stored draft. The Human decides readiness and publication.

packages/designer-to-spec/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "c4b8707f88faf1b9f3e04bb707b45bbb3d89848a8a3b2ac807dc819e8dd29f91"
+    }
+  ]
+}

packages/designer-to-tickets/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-to-tickets
+description: Decompose an agreed specification into ordered issue proposals.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer to tickets
+  relayview-version: 0.6.0
+---
+
+# To tickets
+
+Choose independently reviewable slices with observable outcomes and prerequisite edges only where one slice truly requires another. For each proposed issue, state scope, acceptance, verification, and context a cold-start agent needs. Present the ordered set and relationship rationale to the Human. Keep proposals private until Human review and owner publication.

packages/designer-to-tickets/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "561db3543cfdffe55b8002954d7debcf9d0fc1125d51c688a74cf2469d3d73a1"
+    }
+  ]
+}

packages/designer-triage/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-triage
+description: Classify and route an observed issue before drafting work.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer triage
+  relayview-version: 0.6.0
+---
+
+# Triage
+
+Observe the current report and related tracker state. Separate verified symptoms, missing information, proposed behavior, and duplicate or prerequisite work. Suggest the smallest useful next state and explain the evidence for it. Draft an issue or question for Human review; only owner controls can change tracker status or placement.

packages/designer-triage/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "fa62a0806921d87ddd27e494cfc379513cc147ad658eb5a2981970ccb25babf5"
+    }
+  ]
+}

packages/designer-wayfinder/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: designer-wayfinder
+description: Map an uncertain design decision into options and a Human choice.
+disable-model-invocation: true
+metadata:
+  relayview-display-name: Designer Wayfinder
+  relayview-version: 0.6.0
+---
+
+# Wayfinder
+
+Use this method for a decision whose alternatives materially change the work. First describe the decision, why it matters, and the bounded scope to the Human; enter the method only after the Human agrees. Observe current facts, list viable options with consequences and reversibility, and ask the smallest question that separates them. Record the Human's decision and remaining uncertainty in the owner-stored draft when relevant. This is decision work, not a ready implementation claim.

packages/designer-wayfinder/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.0"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "c5b5db0755af497cfe9be9fee9912f1406fb3b8546d7f389998516ba298f27b0"
+    }
+  ]
+}

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/issue-designer-default/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: issue-designer-default
+description: Guide ordinary Issue Designer Chats from observed facts to a reviewable draft.
+metadata:
+  relayview-display-name: Issue Designer default
+  relayview-version: 0.6.1
+---
+
+# Issue Designer default
+
+Check current facts before drafting. Read the assigned repository's relevant authoritative documentation, code, tests, and tracker observations; state the source, observation time, and any incomplete read. Keep proposed behavior separate from verified current behavior.
+
+Choose the scale with the Human: one issue for bounded work, an ordered issue set for dependent work, or a narrower question when the outcome is unclear. Ask only for decisions that change scope, acceptance, or authority. A useful draft states the problem, observable outcome, boundaries, prerequisites, and verification including failure behavior. Preserve unresolved choices explicitly.
+
+Use the owner-stored draft for one issue and the ordered set for dependent work. Give each item a complete body, an explicit readiness basis, and the relationships needed to read it independently. Keep known facts and proposed behavior distinct.
+
+At readiness marking, recheck the current issue and comments when an issue exists, cited authoritative documentation, source and tests, and the target and installed environment facts available through assigned tools or attributed Human observations. Record when and how completely each input was observed. Include non-secret retrieval instructions for a test target, host or service setup, and verification when a future agent will need them. If a material input is stale or unavailable, mark the affected item `needs-info` and name its specific unresolved question and available evidence. Propose `ready-for-agent` only when a new Planner can start from the item and its references without this Chat. The Human reviews the exact set and publishes through owner controls.

packages/issue-designer-default/relayview-skill.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "kind": "first-party",
+    "reference": "v0.6.1"
+  },
+  "role": "designer",
+  "step": "design",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "d2d4b743cc9bab550910b95a49f9e7c97805510dcb49d66d7a2f79f9c859bf4f"
+    }
+  ]
+}

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/planner-scope/SKILL.md

@@ -3,7 +3,7 @@ name: planner-scope
 description: Check assigned issue scope, neighboring work, and verification before drafting a Plan.
 metadata:
   relayview-display-name: Planner scope
-  relayview-version: 0.3.0
+  relayview-version: 0.8.0
 ---
 
 # Planner scope
@@ -14,4 +14,4 @@ If the owner supplies an admitted work-item identity, use the assigned read tool
 
 Write the Plan through the owner's assigned planning interface. The Plan is ready when each requested outcome has an implementation boundary and a checkable success or recovery observation. Owner-controlled workflow stages and checks determine execution authority.
 
-For a linked Gitea issue, the default claim is the owner's transition from `status/ready-for-agent` to `status/in-progress` after it proves that the exact Plan reached the Implementer. Finalize the Plan through the assigned interface, then use owner-reported handoff and issue-claim outcomes when explaining progress to the Human. An accepted Plan alone does not establish that claim. The operator may disable or replace the status transition through owner policy; follow the effective policy recorded for the task.
+For a linked Gitea issue, this package declares the owner's transition from `status/ready-for-agent` to `status/in-progress` after it proves that the exact Plan reached the Implementer. Finalize the Plan through the assigned interface, then use owner-reported handoff and issue-claim outcomes when explaining progress to the Operator. An accepted Plan alone does not establish that claim. A user may replace this skill with a Planner fork whose package declares a different target status or disables the claim; follow the selected package's policy recorded for the task.

packages/planner-scope/relayview-skill.json

@@ -1,19 +1,22 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "source": {
     "kind": "first-party",
-    "reference": "v0.4.0"
+    "reference": "v0.8.0"
   },
   "role": "planner",
   "step": "planning",
+  "issueClaim": {
+    "statusLabel": "status/in-progress"
+  },
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "bfac8352adffa8e2aaa246a6b5f11a333045a82aeefe5d0e42e76eaa776a6a70"
+      "sha256": "7dbd2ace7472a75c69b70ea118333429dfc7d56e5374454724805aa783cc0112"
     },
     {
       "path": "scope.md",
-      "sha256": "fc365d5f5c90f878992204235f32b1148aa4934a31f8c10eb063292fb64cf248"
+      "sha256": "abed1a1590273b5f62f1e1f47ba8c92d00693de72c0d5e9b014ed1c911ac0a8e"
     }
   ]
 }

packages/planner-scope/scope.md

@@ -6,3 +6,38 @@
 - Distinguish verified current behavior from a proposal.
 - Identify one observable success path and one meaningful failure or recovery path.
 - Record uncertainty as an open decision; do not turn silence into approval.
+
+Focus on:
+- affected files and symbols
+- existing patterns and architecture
+- invariants and edge cases
+- ordering and dependencies between changes
+- tests, validation, and likely failure modes
+- any assumptions that the implementer must know
+- explicitly authorized supporting context that influences behavior
+
+Return a compact structured plan. Prefer YAML-compatible Markdown:
+
+```yaml
+objective: ...
+constraints:
+  - ...
+steps:
+  - id: ...
+    files:
+      - ...
+    symbols:
+      - ...
+    change: ...
+    requirements:
+      - ...
+    depends_on:
+      - ...
+edge_cases:
+  - ...
+validation:
+  - ...
+open_questions:
+  - ...
+```
+

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,50 @@ ROOT = Path(__file__).resolve().parents[1]
 
 
 class PackageTests(unittest.TestCase):
+    def test_planner_scope_presentation_and_claim(self):
+        package = ROOT / "packages/planner-scope"
+        check_package(package)
+        text = (package / "scope.md").read_text()
+        for phrase in ("affected files and symbols", "invariants and edge cases", "YAML-compatible Markdown", "open_questions:"):
+            self.assertIn(phrase, text)
+        self.assertNotIn("follow-up monitor", text)
+        manifest = json.loads((package / "relayview-skill.json").read_text())
+        self.assertEqual(manifest["issueClaim"], {"statusLabel": "status/in-progress"})
+
+    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 = (
+            "designer-wayfinder", "designer-grilling", "designer-prototype",
+            "designer-research", "designer-domain-modeling", "designer-triage",
+            "designer-to-spec", "designer-to-tickets",
+        )
+        for name in (automatic, *manual):
+            with self.subTest(name=name):
+                package = ROOT / "packages" / name
+                skill = (package / "SKILL.md").read_text()
+                frontmatter = skill.split("---", 2)[1]
+                self.assertEqual("disable-model-invocation: true" in frontmatter, name in manual)
+                version = {automatic: "0.6.1", "designer-prototype": "0.6.2"}.get(name, "0.6.0")
+                self.assertIn(f"relayview-version: {version}", frontmatter)
+                manifest = json.loads((package / "relayview-skill.json").read_text())
+                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": f"v{version}"})
+                check_package(package)
+
     def test_tdd_is_available_to_owner_started_implementers(self):
         package = ROOT / "packages/tdd-auto"
         skill = (package / "SKILL.md").read_text()
@@ -39,7 +83,11 @@ class PackageTests(unittest.TestCase):
                     "code-review": ("reviewer", "review"),
                     "c4-diff": ("reviewer", "review"),
                     "research": ("planner", "planning"),
-                    "improve-codebase-architecture": ("planner", "planning")}
+                    "improve-codebase-architecture": ("planner", "planning"),
+                    **{name: ("designer", "design") for name in (
+                        "issue-designer-default", "designer-wayfinder", "designer-grilling", "designer-prototype",
+                        "designer-research", "designer-domain-modeling", "designer-triage",
+                        "designer-to-spec", "designer-to-tickets")}}
         for name, role_step in expected.items():
             with self.subTest(name=name):
                 package = ROOT / "packages" / name
@@ -65,7 +113,7 @@ class PackageTests(unittest.TestCase):
                 package = ROOT / "packages" / name
                 manifest = json.loads((package / "relayview-skill.json").read_text())
                 self.assertEqual((manifest["role"], manifest["step"]), (role, step))
-                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.4.0" if name == "planner-scope" else "v0.2.0"})
+                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.8.0" if name == "planner-scope" else "v0.2.0"})
                 self.assertIn(resource, [item["path"] for item in manifest["files"]])
                 self.assertIn(marker, (package / "SKILL.md").read_text() + (package / resource).read_text())
 

tools/packages.py

@@ -44,15 +44,26 @@ def check_package(path):
         manifest = json.loads(_text(raw_manifest, str(sidecar)))
     except (ValueError, TypeError) as error:
         _fail(f"{sidecar}: invalid JSON: {error}")
-    if not isinstance(manifest, dict) or set(manifest) != {"schemaVersion", "source", "role", "step", "files"}:
+    if not isinstance(manifest, dict) or (
+        (manifest.get("schemaVersion") == 1 and set(manifest) != {"schemaVersion", "source", "role", "step", "files"}) or
+        (manifest.get("schemaVersion") == 2 and set(manifest) != {"schemaVersion", "source", "role", "step", "files", "issueClaim"}) or
+        manifest.get("schemaVersion") not in (1, 2)
+    ):
         _fail(f"{path}: unsupported manifest fields")
     source = manifest["source"]
     if not isinstance(source, dict) or set(source) != {"kind", "reference"}:
         _fail(f"{path}: invalid source")
     if source["kind"] not in ("first-party", "user") or not isinstance(source["reference"], str) or not re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", source["reference"]):
         _fail(f"{path}: invalid source identity")
-    if manifest["schemaVersion"] != 1 or (manifest["role"], manifest["step"]) not in (("planner", "planning"), ("implementer", "implementation"), ("reviewer", "review")):
+    if (manifest["role"], manifest["step"]) not in (("planner", "planning"), ("implementer", "implementation"), ("reviewer", "review"), ("designer", "design")):
         _fail(f"{path}: incompatible role or step")
+    if manifest["schemaVersion"] == 2:
+        claim = manifest["issueClaim"]
+        label = claim.get("statusLabel") if isinstance(claim, dict) else None
+        if (manifest["role"], manifest["step"]) != ("planner", "planning") or not isinstance(claim, dict) or set(claim) != {"statusLabel"} or (
+            label is not None and (not isinstance(label, str) or not re.fullmatch(r"status/[a-z][a-z0-9-]{0,63}", label) or label == "status/ready-for-agent")
+        ):
+            _fail(f"{path}: invalid issue claim policy")
     files = manifest["files"]
     if not isinstance(files, list) or not 1 <= len(files) <= 16:
         _fail(f"{path}: invalid file list")