@gluecharm-lab/easyspecs-cli 0.3.4 → 0.3.6

package/resources/opencode-agents/agent-list-qa.md

@@ -0,0 +1,222 @@
+---
+description: SRS-8 coordination JSON — incremental schema-valid qa-list.json while discovering the repo; multi-pass refinement; .gluecharm/context (file tools; chat-only insufficient).
+mode: primary
+---
+
+# Agent: QA list (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-qa` |
+| **Display name** | QA list |
+| **SRS-8** | §4.6 `qa-list.json`; §6.1 global discovery; §6.2 Feature scope entry; **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/qa-list.json` |
+| **Pattern** | §3.5.2 — JSON list (coordination) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Emit the **canonical registry of features**: stable **`code`** (`QA-01` …), human-readable **`name`**, and **`<slug>`** for each feature’s detail file basename **`QA-<nn>-<slug>.md`** (§4.1, §4.3). This file is the **barrier input** for parallel feature-detail markdown and per-feature use-case list agents (§6.2).
+
+## Revision
+
+Coordination output is **JSON** (no markdown `##` headings in the artifact). Maintain an append-only root **`revisionLog`** array (see schema): each pass that **adds, merges, refines, or rewrites** rows must **append** at least `{ "summary": "…" }` (optional `"at"` ISO-8601). **Never delete** prior `revisionLog` entries. Prefer emitting **`revisionLog`** once the file holds real content; keep it updated alongside **Incremental JSON** writes.
+
+## SRS-50 — Stable coordination writes
+
+EasySpecs **merge-by-code** after the run: **existing codes** keep their **previous file order**; **new** codes are moved to the **end** of each coded array (including nested BH/ME/FD/RL rows under the correct parent). **Append** new rows at the end while authoring.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Produce **`qa-list.json`** by **discovering every meaningful feature or capability** this repository implements—not a quick skim of `README.md`. Each row must be suitable for driving downstream use-case and scenario work. Do **not** write markdown lists; output **one JSON file** only.
+
+### Incremental JSON (mandatory)
+
+Treat **`{{OUTPUT_FILE_ABSOLUTE}}`** as a **living document** while you navigate and read the project:
+
+1. **Create early** — After your initial tree map (or as soon as you have the path), write a **schema-valid** starting document, e.g. `{ "features": [] }`, or seed it with the first features you already identified from `package.json` / entrypoints.
+2. **Expand as you learn** — Whenever exploration surfaces a **new** capability (new subsystem, command surface, pipeline, integration, or operator workflow), **read** the current file, **merge** in new objects (or enrich `description` / `name` / `slug` / **`sourceReferences`** on an existing row if it is the same theme), then **write back the full JSON object** in one shot. Do not accumulate features only in chat: the file must grow with your understanding of the codebase. Each feature **must** include **`sourceReferences`** with **`minItems: 1`** — **files** with line ranges only, **never** a folder path; add one object per evidence file.
+3. **Always valid** — Every write must be **parseable JSON** and satisfy **`qa-list.schema.json`** (no comments, no trailing text). Prefer rewriting the whole file rather than risky partial edits.
+4. **Stable codes** — Assign **`QA-01`, `QA-02`, …** as you add rows; **do not renumber** existing codes during incremental adds (downstream agents depend on stability). Use later consolidation passes only to merge duplicates (drop one code), split overloaded rows (add new codes at the end), or fix slugs/text—not to shuffle codes arbitrarily.
+
+### Repository discovery (mandatory)
+
+1. **Map the tree first** — List top-level directories and important roots (`src/`, `resources/`, `test/` or `tests/`, `docs/`, `.gluecharm/`, scripts, config). **Skip** **`.opencode/`** for product discovery (materialized agents/schemas only — see **`.opencode/` exclusion** above). Note entry points: `package.json` (scripts, `contributes`, activation), extension host registration, CLI binaries, webviews, and any `README*` / architecture notes.
+2. **Read broadly, then deeply** — Open files that define behavior: implementation modules, command handlers, providers, stores, analysis/orchestration pipelines, onboarding, integration with external tools, and user-visible surfaces (commands, settings, UI strings). Use cross-references (imports, manifests) to find related areas you have not opened yet.
+3. **Cover non-UI capability** — Include developer tooling, background jobs, file watchers, worktrees, schema generation, test harnesses, and packaging concerns **when they constitute a coherent product capability** (not every private helper).
+4. **Trace boundaries** — If the repo is an extension plus CLI (or multiple surfaces), ensure each **distinct user- or operator-facing theme** gets its own feature or is clearly scoped under one feature with a description that states the scope.
+
+### Exhaustiveness
+
+The list must be **as complete as the repository allows**: prefer **splitting** distinct themes over merging unrelated behavior under one vague feature. Before finalizing, mentally check: *commands/settings from `package.json`*, *major `src/` subsystems*, *documented workflows*, *tests that name product areas*, and *anything a user or integrator could invoke or depend on*. Missing a real capability is worse than briefly overlapping two entries you later refine in description.
+
+**Downstream cardinality:** For each **meaningful** product feature, the later **use-cases list** should **usually** enumerate **several** use cases (different goals, surfaces, or actors). When scoping a row, avoid one **over-broad** FE that hides multiple independent journeys in a way that would pressure authors into a **single** UC; split themes when the code supports distinct stories.
+
+### Quality: refine in passes (mandatory)
+
+Discovery and **incremental file updates** above are the primary way the list grows. When navigation is substantially complete, run **at least three** refinement passes **against the current JSON on disk** (read → edit → write full valid JSON each time; no separate staging file):
+
+| Pass | Goal |
+| ---- | ---- |
+| **1 — Coverage check** | Re-walk the repo tree and manifests against the file; append missing features; remove entries with no evidence in code or docs. |
+| **2 — Consolidation** | Merge true duplicates; split overloaded rows; tighten `name` and optional `description`; ensure slugs are kebab-case per schema; set sensible **`order`** if used. |
+| **3 — Final sanity** | Unique `code` values, schema-valid document, each feature has **`sourceReferences`** with **`minItems: 1`** (**file** paths + line ranges, no directories); plus command ids in prose/`description` where useful. |
+| **4 (optional)** | Second gap hunt if the repo is large or you touched new areas late. |
+
+The file at **`{{OUTPUT_FILE_ABSOLUTE}}`** must already contain the near-final list before these passes; passes **refine** it, not replace a chat-only draft.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/qa-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/qa-list.schema.json`
+
+**`sourceReferences` (this list):** **required** on each feature row (`minItems: 1`). Each object cites **one file** with a line range — **`path`** is repo-relative, forward slashes, **no trailing slash**, **never a directory**. **Never** use paths under **`.opencode/`** (see **`.opencode/` exclusion** above). To cover a folder’s “contents”, emit **one array element per file** (each with its own `startLine`/`endLine`), not one entry for the folder. Optional **`note`**.
+
+Emit **only** JSON that validates against this schema (UTF-8, no comments, no trailing text):
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/qa-list.schema.json",
+  "title": "qa-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    },
+    "sourceReferenceList": {
+      "type": "array",
+      "description": "Evidence spans: each item references one file + line range, never a folder path.",
+      "items": { "$ref": "#/$defs/sourceReference" }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["features"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.qa-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "slug", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^QA-[0-9]+$",
+            "description": "Stable feature code; QA- plus one or more digits (e.g. QA-1, QA-01, QA-120)."
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "URL-safe slug for QA-<nn>-<slug>.md basename."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "infrastructureKind": {
+            "type": "string",
+            "enum": ["product", "infrastructure", "testing"],
+            "description": "SRS-27: classify product vs platform/ops vs verification-only surface; omit to treat as product in consumers that care."
+          },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per feature row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Example instance:**
+
+```json
+{
+  "features": [
+    {
+      "code": "QA-01",
+      "name": "User authentication",
+      "slug": "user-authentication",
+      "order": 1,
+      "sourceReferences": [
+        {
+          "path": "src/auth/login.ts",
+          "startLine": 1,
+          "endLine": 120,
+          "note": "login flow"
+        }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial features discovery; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Barriers
+
+- **After** this file exists and is valid, orchestration may fan out **`QA-<nn>-<slug>.md`** and **`QA-<nn>-use-cases-list.json`** in parallel (§6.2).
+
+## OpenCode wiring
+
+Bind this logical agent to your OpenCode CLI (e.g. `runOpenCodeAgent` with a prompt constructed from §3.5.2). Supply **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**. Do **not** write `index-application-context.json`.

package/resources/opencode-agents/agent-md-infrastructure-component-detail.md

@@ -0,0 +1,165 @@
+# Agent: Use case detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-infrastructure-component-detail` |
+| **Display name** | Use case detail |
+| **SRS-8** | §4.4 `IN-<nn>_IC-<uu>.md`; §6.2 Feature spine; **R7**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/IN-<nn>_IC-<uu>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/IN-<nn>-components-list.json` (repo-relative: `.gluecharm/context/IN-<nn>-components-list.json`) |
+| **Pattern** | §3.5.1 — Markdown detail |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Narrative for **one infrastructure component** under a feature: **concrete** actors, **actual** inputs (fields, types, mandatory vs optional), **where and how** validation runs, **what** is persisted or mutated, **what** is returned or surfaced, and **ordered implementation steps** from entrypoint through to outcome—not a generic “the user registers” paragraph.
+
+**Spine context:** Non-trivial infrastructure components **typically** have **multiple** scenarios in **`IN-<nn>_IC-<uu>-scenarios-list.json`** (happy path, errors, permissions, data variants). **`## Related scenarios`** should list **several** `SC-*` rows when they exist; if the list has only one scenario, double-check that branches were not folded into this document instead of separate SC rows.
+
+The matching row in **`.gluecharm/context/IN-<nn>-components-list.json`** **must** include **`sourceReferences`** (`minItems: 1`); seed the **Evidence index** from those anchors (each **`path`** is a file, not a directory), then **extend** with every module you cite in **Code flow**.
+
+**Coordination JSON** for this agent lives **only** under **`.gluecharm/context/`**, not at the worktree root. Read that path first; if it is missing, **glob** `.gluecharm/context/**/IN-<nn>-components-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Document **infrastructure component {{UC_CODE}}** under **feature {{FE_CODE}}** per the corresponding components list entry. Do not change stable codes.
+
+### Depth (mandatory)
+
+1. **Trace the real implementation** — From the infrastructure component’s intent, locate the **actual** route, command, handler, service method, or job that starts this flow; follow **calls, validations, repositories, DTOs/mappers, and responses** in the worktree until the success and failure paths are clear.
+2. **Name specifics** — Use **real** identifiers: HTTP paths/methods, function or method names, class/module filenames, validation schemas, DB tables or ORM entities, error codes or messages the code returns. Avoid vague wording (“the system validates”) without saying **which** validator and **where**.
+3. **Data and conditions** — Spell out **which fields** are required, **what** rules apply (length, format, auth, rate limits, feature flags), **what** happens when a rule fails (HTTP status, exception type, user-visible message if encoded), and **what** data shape is stored or emitted on success.
+4. **Code flow** — Write **`## Code flow`** as an **implementation-order** pipeline: e.g. entrypoint → auth/authorization check → input binding/parsing → per-field or schema validation → business rules → persistence transaction → side effects (events, emails) → response mapping. **Each step** must reference **concrete** code locations (you will mirror those in **Evidence index**).
+5. **Mermaid** — Under **`## Code flow`**, add **at least one** fenced **`mermaid`** block when the implementation has **two or more** meaningful stages (validation, persistence, external call, etc.). Follow **[MERMAID.md](./MERMAID.md)**: **Mermaid 11.13**, **neutral** theme (`%%{init: {'theme':'neutral'}}%%` as first line inside the fence). Use **`flowchart`** or **`sequenceDiagram`** with nodes/actors labeled to match **real** modules or functions (not “Frontend” / “Backend” placeholders unless the repo truly has no finer structure). Skip Mermaid only if the flow is a single trivial call **and** you state why in one line.
+
+### Evidence vs Code flow (mandatory)
+
+- **Entry point alone is insufficient.** The **Evidence index** must cite **implementation** for: the **primary entrypoint**, **validation** (schema, guards, domain checks), **core business logic** touched by this infrastructure component, **persistence** (save/update/query), and **response / error mapping**—each with `path:line` or `path:start-end` (or tight ranges), aligned with the steps in **`## Code flow`**.
+- Prefer **one Evidence bullet per major Code flow stage** (or a small table in **Code flow** with a matching Evidence bullet list)—readers must see **which files** justify **which** part of the narrative.
+- Do **not** cite only the outer controller/route if all substantive logic lives in services, validators, or repositories; those **must** appear too.
+
+## Non-empty chapters and Evidence index (mandatory)
+
+- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected**—do not produce that outcome.
+- **Preferred:** concrete `path:line` or `path:start-end` cites from the worktree (implementation, config, tests, schemas—not README-style narrative files).
+- **`## Code flow`** must not be a generic checklist; it must reflect **this** infrastructure component’s **actual** call chain and data path. If a section is thin after search, say what is missing and cite the closest evidence.
+- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the top-level `#` title**, **and** still add **at least one** Evidence index bullet describing what was searched, partial findings, and that claims are not implementation-backed.
+- **Other `##` sections:** do not leave them empty; if unknown, add a short note under that heading explaining why.
+- **Banned:** never list any path whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index. **Never** list paths under **`.opencode/`** either (tooling copy, not product source).
+
+### Revision log (mandatory)
+
+- **`## Revision`** sits **immediately before** **`## Evidence index`**. **Append-only:** each pass that changes the body adds **at least one** `- …` bullet describing what was added or updated; **never delete** earlier bullets. **First write:** include an initial bullet (e.g. **Initial draft**).
+
+## Output template
+
+Basename e.g. **`IN-<nn>_IC-<uu>.md`** (optional slug per PLAN). **R21:** cite behaviour and rules; **Code flow** and **Evidence index** must stay consistent.
+
+```markdown
+# Use case {{UC_CODE}} — <name> (Feature {{FE_CODE}})
+
+## Summary
+
+<!-- One tight paragraph: goal, primary actor, success outcome — no generic filler. -->
+
+## Actors and stakeholders
+
+## Preconditions
+
+<!-- What must be true before this infrastructure component can start (auth, state, feature flags) — cite checks in code if present. -->
+
+## Data inputs and validation
+
+<!--
+  Concrete inputs for THIS infrastructure component:
+  - Field or parameter names, mandatory vs optional, types.
+  - Validation rules (schema, decorators, manual checks) and where they run.
+  - Failure behaviour (status codes, errors) with code cites in Evidence.
+-->
+
+## Main flow (user- or operator-visible)
+
+<!--
+  Short numbered steps from the actor’s perspective (can mirror Code flow at a higher level).
+  Each step should be traceable to ## Code flow.
+-->
+
+## Code flow
+
+<!--
+  IMPLEMENTATION ORDER — not marketing prose. Numbered steps:
+  - What runs (function/handler/method), in which file.
+  - What data moves (DTO, entity, query).
+  - Branching: validation failure → which path; success → next step.
+
+  When 2+ stages: add a ### heading, then open a fenced block with language tag mermaid (flowchart TD or sequenceDiagram)
+  whose node/participant labels match real modules or symbols from the repo.
+-->
+
+### <!-- e.g. Request path (implementation) -->
+
+<!-- Numbered list: 1. … 2. … each tied to files named in Evidence index. -->
+
+### <!-- Mermaid — required when flow has 2+ stages -->
+
+<!--
+  ```mermaid
+  %%{init: {'theme':'neutral'}}%%
+  flowchart TD
+    ...
+  ```
+  or sequenceDiagram with real handler/service/repository names (see MERMAID.md).
+-->
+
+## Alternate flows
+
+## Postconditions
+
+## Errors and edge cases
+
+<!-- Map error paths to code (guards, catch blocks, HTTP errors) — cite in Evidence. -->
+
+## Technical mapping
+
+<!--
+  Optional: cross-cutting helpers, shared validators, infra (queue, cache) if not fully covered above.
+  Do not duplicate ## Code flow; add only extra touchpoints.
+-->
+
+## Related scenarios
+
+<!-- List SC-* from scenarios list when known. -->
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: data inputs, code flow, and Evidence tied to handlers and services. -->
+
+## Evidence index
+
+<!--
+  Multiple substantive bullets — at minimum: entrypoint, validation, core logic, persistence/IO, response/errors.
+  Each bullet should map to a stage in ## Code flow. Never only the route file if logic lives elsewhere.
+-->
+
+- <!-- `path:line` — entrypoint -->
+- <!-- `path:start-end` — validation -->
+- <!-- `path:start-end` — persistence / domain logic -->
+- <!-- `path:start-end` — response or error mapping -->
+```
+
+## Evidence (**R21**)
+
+Follow **Non-empty chapters and Evidence index** and **Evidence vs Code flow** above. Citations required per §3.5.1. Basename must match §4.4 composite pattern.
+
+## Prerequisites
+
+**`.gluecharm/context/IN-<nn>-components-list.json`** includes this infrastructure component.
+
+## OpenCode wiring
+
+§3.5.1; orchestration supplies FE/UC codes and exact **`{{OUTPUT_FILE_ABSOLUTE}}`**.

package/resources/opencode-agents/agent-md-infrastructure-detail.md

@@ -0,0 +1,95 @@
+# Agent: Feature detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-infrastructure-detail` |
+| **Display name** | Feature detail |
+| **SRS-8** | §4.3 `IN-<nn>-<slug>.md`; §6.2 (parallel after `infrastructure-list.json`); **R7**, **AC5**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/IN-<nn>-<slug>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/infrastructure-list.json` (repo-relative: `.gluecharm/context/infrastructure-list.json`) |
+| **Pattern** | §3.5.1 — Markdown detail |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+**Functional and technical** documentation for **one feature** whose **`code`** and **`slug`** come from **`.gluecharm/context/infrastructure-list.json`**. Feeds human-readable depth; structure for the index comes from JSON lists. That row **must** include **`sourceReferences`** (`minItems: 1`); seed the **Evidence index** with those path+line ranges (then add more from deeper reading). In list JSON, **`sourceReferences[].path`** is always a **file**, never a folder.
+
+**Spine context:** Non-trivial features **typically** map to **multiple** use cases in **`IN-<nn>-use-cases-list.json`**. In **Summary** or **Scope**, avoid implying this feature is a single monolithic journey when the codebase supports several; you may briefly point readers at sibling UCs by code/name when helpful.
+
+**Coordination JSON** lives **only** under **`.gluecharm/context/`**, not the worktree root. Read that path first; if missing, **glob** `.gluecharm/context/**/infrastructure-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Document feature **{{FE_CODE}}** (name/slug from list): scope, behaviour, main dependencies, entry points, and links to code. Ground all claims in the worktree.
+
+## Non-empty chapters and Evidence index (mandatory)
+
+- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected**—do not produce that outcome.
+- **Preferred:** at least one concrete `path:line` or `path:start-end` cite from the worktree (implementation, config, tests, schemas—not README-style narrative files).
+- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the top-level `#` title**, **and** still add **at least one** Evidence index bullet describing what was searched, partial findings, and that claims are not implementation-backed.
+- **Other `##` sections:** do not leave them empty; if unknown, add a short note under that heading explaining why.
+- **Banned:** never list any path whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index. **Never** list paths under **`.opencode/`** either (tooling copy, not product source).
+
+### Revision log (mandatory)
+
+- **`## Revision`** sits **immediately before** **`## Evidence index`**. **Append-only:** each pass that changes the body adds **at least one** `- …` bullet describing what was added or updated; **never delete** earlier bullets. **First write:** include an initial bullet (e.g. **Initial draft**).
+
+## Output template
+
+Write **exactly** the content for **`{{OUTPUT_FILE_ABSOLUTE}}`**. Basename **must** be **`{{OUTPUT_BASENAME}}`** (e.g. `IN-01-user-auth.md`). **R21:** mirror substantive claims under **Evidence index** with file+line cites or labelled inference.
+
+```markdown
+# Feature {{FE_CODE}} — <name from infrastructure-list>
+
+**Slug:** <slug>  
+**Output file:** {{OUTPUT_BASENAME}}
+
+## Summary
+
+## Scope
+
+<!-- In / out of scope for this feature. -->
+
+## Functional behaviour
+
+<!-- User-visible capabilities; cite UI/routes/handlers. -->
+
+## Technical design
+
+<!-- Modules, services, data touched; cite implementation. -->
+
+## Entry points
+
+<!-- Routes, CLI, jobs, public APIs; cite definitions. -->
+
+## Dependencies
+
+<!-- Other features, libs, external APIs; cite manifests and imports. -->
+
+## Open questions
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: scope and behaviour from implementation reads. -->
+
+## Evidence index
+
+- <!-- At least one substantive bullet: `path:line` or honest grounding note per Non-empty chapters — never empty; never `readme.md` basenames. -->
+```
+
+## Evidence (**R21**)
+
+Follow **Non-empty chapters and Evidence index** above. File + line citations for substantive statements; **`{{OUTPUT_BASENAME}}`** must match §4.3.
+
+## Prerequisites
+
+Valid **`.gluecharm/context/infrastructure-list.json`** with this feature row.
+
+## OpenCode wiring
+
+§3.5.1. One markdown file per invocation; orchestration sets output path from FE code and slug.

package/resources/opencode-agents/agent-md-qa-detail.md

@@ -0,0 +1,95 @@
+# Agent: Feature detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-qa-detail` |
+| **Display name** | Feature detail |
+| **SRS-8** | §4.3 `QA-<nn>-<slug>.md`; §6.2 (parallel after `qa-list.json`); **R7**, **AC5**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/QA-<nn>-<slug>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/qa-list.json` (repo-relative: `.gluecharm/context/qa-list.json`) |
+| **Pattern** | §3.5.1 — Markdown detail |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+**Functional and technical** documentation for **one feature** whose **`code`** and **`slug`** come from **`.gluecharm/context/qa-list.json`**. Feeds human-readable depth; structure for the index comes from JSON lists. That row **must** include **`sourceReferences`** (`minItems: 1`); seed the **Evidence index** with those path+line ranges (then add more from deeper reading). In list JSON, **`sourceReferences[].path`** is always a **file**, never a folder.
+
+**Spine context:** Non-trivial features **typically** map to **multiple** use cases in **`QA-<nn>-use-cases-list.json`**. In **Summary** or **Scope**, avoid implying this feature is a single monolithic journey when the codebase supports several; you may briefly point readers at sibling UCs by code/name when helpful.
+
+**Coordination JSON** lives **only** under **`.gluecharm/context/`**, not the worktree root. Read that path first; if missing, **glob** `.gluecharm/context/**/qa-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Document feature **{{FE_CODE}}** (name/slug from list): scope, behaviour, main dependencies, entry points, and links to code. Ground all claims in the worktree.
+
+## Non-empty chapters and Evidence index (mandatory)
+
+- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected**—do not produce that outcome.
+- **Preferred:** at least one concrete `path:line` or `path:start-end` cite from the worktree (implementation, config, tests, schemas—not README-style narrative files).
+- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the top-level `#` title**, **and** still add **at least one** Evidence index bullet describing what was searched, partial findings, and that claims are not implementation-backed.
+- **Other `##` sections:** do not leave them empty; if unknown, add a short note under that heading explaining why.
+- **Banned:** never list any path whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index. **Never** list paths under **`.opencode/`** either (tooling copy, not product source).
+
+### Revision log (mandatory)
+
+- **`## Revision`** sits **immediately before** **`## Evidence index`**. **Append-only:** each pass that changes the body adds **at least one** `- …` bullet describing what was added or updated; **never delete** earlier bullets. **First write:** include an initial bullet (e.g. **Initial draft**).
+
+## Output template
+
+Write **exactly** the content for **`{{OUTPUT_FILE_ABSOLUTE}}`**. Basename **must** be **`{{OUTPUT_BASENAME}}`** (e.g. `QA-01-user-auth.md`). **R21:** mirror substantive claims under **Evidence index** with file+line cites or labelled inference.
+
+```markdown
+# Feature {{FE_CODE}} — <name from qa-list>
+
+**Slug:** <slug>  
+**Output file:** {{OUTPUT_BASENAME}}
+
+## Summary
+
+## Scope
+
+<!-- In / out of scope for this feature. -->
+
+## Functional behaviour
+
+<!-- User-visible capabilities; cite UI/routes/handlers. -->
+
+## Technical design
+
+<!-- Modules, services, data touched; cite implementation. -->
+
+## Entry points
+
+<!-- Routes, CLI, jobs, public APIs; cite definitions. -->
+
+## Dependencies
+
+<!-- Other features, libs, external APIs; cite manifests and imports. -->
+
+## Open questions
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: scope and behaviour from implementation reads. -->
+
+## Evidence index
+
+- <!-- At least one substantive bullet: `path:line` or honest grounding note per Non-empty chapters — never empty; never `readme.md` basenames. -->
+```
+
+## Evidence (**R21**)
+
+Follow **Non-empty chapters and Evidence index** above. File + line citations for substantive statements; **`{{OUTPUT_BASENAME}}`** must match §4.3.
+
+## Prerequisites
+
+Valid **`.gluecharm/context/qa-list.json`** with this feature row.
+
+## OpenCode wiring
+
+§3.5.1. One markdown file per invocation; orchestration sets output path from FE code and slug.