@gluecharm-lab/easyspecs-cli 0.0.3

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

@@ -0,0 +1,82 @@
+# Agent: Tool / dependency detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-tool-detail` |
+| **Display name** | Tool detail |
+| **SRS-8** | §4.5 **`TS-<nn>-<slug>.md`**; §6.6 (parallel after `tech-stack-list.json`); **R7**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/TS-<nn>-<slug>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/tech-stack-list.json` (repo-relative: `.gluecharm/context/tech-stack-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.
+
+Document **one library, framework, SaaS, or infra dependency** (`TS-*`): version, role, configuration surface, boundaries (what the app does vs what the tool does).
+
+**Coordination JSON** lives **only** under **`.gluecharm/context/`**, not the worktree root. Read **`.gluecharm/context/tech-stack-list.json`** first; if missing, **glob** `.gluecharm/context/**/tech-stack-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Describe **tool {{TS_CODE}}** per **`.gluecharm/context/tech-stack-list.json`**. The tool row **must** include **`sourceReferences`** (`minItems: 1`); seed the **Evidence index** from those anchors (each **`path`** is a file, e.g. manifest or lockfile — not a directory), then extend with deeper reading.
+
+## 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
+
+Basename **`TS-<nn>-<slug>.md`**.
+
+```markdown
+# Tool {{TS_CODE}} — <name>
+
+**Slug:** <slug> · **File:** {{OUTPUT_BASENAME}}
+
+## Summary
+
+## Role in this codebase
+
+## Version and configuration
+
+<!-- Cite package.json, lockfile, env, infra as applicable. -->
+
+## Boundaries
+
+<!-- What the app implements vs what the tool provides. -->
+
+## Integration points
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: version and usage from manifests/config. -->
+
+## 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. Cite `package.json`, lockfiles, env samples, and integration code.
+
+## Prerequisites
+
+**`.gluecharm/context/tech-stack-list.json`** includes this tool.
+
+## OpenCode wiring
+
+§3.5.1. Parallel per tool row (§6.6).

package/resources/opencode-agents/agent-md-use-case-detail.md

@@ -0,0 +1,165 @@
+# Agent: Use case detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-use-case-detail` |
+| **Display name** | Use case detail |
+| **SRS-8** | §4.4 `FE-<nn>_UC-<uu>.md`; §6.2 Feature spine; **R7**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/FE-<nn>_UC-<uu>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/FE-<nn>-use-cases-list.json` (repo-relative: `.gluecharm/context/FE-<nn>-use-cases-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 use case** 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 use cases **typically** have **multiple** scenarios in **`FE-<nn>_UC-<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/FE-<nn>-use-cases-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/**/FE-<nn>-use-cases-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Document **use case {{UC_CODE}}** under **feature {{FE_CODE}}** per the corresponding use-cases list entry. Do not change stable codes.
+
+### Depth (mandatory)
+
+1. **Trace the real implementation** — From the use case’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 use case, **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** use case’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. **`FE-<nn>_UC-<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 use case can start (auth, state, feature flags) — cite checks in code if present. -->
+
+## Data inputs and validation
+
+<!--
+  Concrete inputs for THIS use case:
+  - 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/FE-<nn>-use-cases-list.json`** includes this use case.
+
+## OpenCode wiring
+
+§3.5.1; orchestration supplies FE/UC codes and exact **`{{OUTPUT_FILE_ABSOLUTE}}`**.

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

@@ -0,0 +1,117 @@
+# Agent: View detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-view-detail` |
+| **Display name** | View detail |
+| **SRS-8** | §4.5 **`XP-<nn>-<slug>.md`**; §6.3 (parallel after `experiences-list.json`); **R7**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/XP-<nn>-<slug>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/experiences-list.json` (repo-relative: `.gluecharm/context/experiences-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.
+
+Document **one view** (screen, page, or major UI surface): purpose, layout, key controls, navigation, data shown, and implementation references. Codes and slugs come from **`.gluecharm/context/experiences-list.json`**. The view row **must** include **`sourceReferences`** (`minItems: 1`); seed the **Evidence index** with them (file paths only in JSON, not directories).
+
+In **`## Layout and key components`**, include a **high-level mockup**: one fenced code block of **ASCII / Unicode box-drawing** wireframe (e.g. `╔` `═` `║` `╚`) that shows window chrome (if any), main regions, toolbars, tabs, and where primary content sits. Match the **actual** view under **`{{WORKTREE_ROOT}}`**. Use **Example high-level mockup (style reference)** in this agent file for framing and density only—replace every label with the documented view.
+
+**Coordination JSON** lives **only** under **`.gluecharm/context/`**, not the worktree root. Read that path first; if missing, **glob** `.gluecharm/context/**/experiences-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Describe **view {{XP_CODE}}** (name/slug from list). Ground in components and routes under **`{{WORKTREE_ROOT}}`**.
+
+## 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
+
+Basename **`XP-<nn>-<slug>.md`** per §4.5 and list row.
+
+```markdown
+# View {{XP_CODE}} — <name>
+
+**Slug:** <slug> · **File:** {{OUTPUT_BASENAME}}
+
+## Summary
+
+## User purpose
+
+## Layout and key components
+
+**High-level mockup:**
+
+<!-- One ``` fenced block: Unicode box-drawing wireframe (title/menu, regions, tabs, main canvas). Shape/density: see this agent’s “Example high-level mockup (style reference)”. Then cite Vue/React components, templates, styles. -->
+
+## Navigation
+
+<!-- Routes, links, guards; cite router config. -->
+
+## Data displayed
+
+<!-- Stores, queries, props; cite data layer. -->
+
+## States (loading / empty / error)
+
+## Accessibility and i18n notes
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: UI structure from components/routes. -->
+
+## Evidence index
+
+- <!-- At least one substantive bullet: `path:line` or honest grounding note per Non-empty chapters — never empty; never `readme.md` basenames. -->
+```
+
+### Example high-level mockup (style reference)
+
+Illustrative desktop shell only—**labels must match the view being documented** (not this sample verbatim unless it is that product).
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ Consoft.- Front de Comunicaciones ( Fedicom v1.0 / v2.0 )              _ □ X ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║ Archivo                                                                    ▼ ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║ ┌──────────────────────────────┐ ┌──────────────────────────────┐          ║
+║ │ Estado Módulo Recepción      │ │ Estado Módulo Exportación    │          ║
+║ │  (indicators / text / LEDs)  │ │  (indicators / text)         │          ║
+║ └──────────────────────────────┘ └──────────────────────────────┘          ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║ [ Pedidos Recibidos ] [ Abonos Recibidos ] [ Monitor de Transmisiones ]      ║
+║ [ Configuración ]                                                            ║
+║   ▲ active tab often shown in BLUE on clBtnFace                              ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║                     (content of selected tab — see below)                  ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+## Evidence (**R21**)
+
+Follow **Non-empty chapters and Evidence index** above. Cite files and lines for UI structure and behaviour. Basename must match §4.5 (`XP-<nn>-<slug>.md`).
+
+## Prerequisites
+
+**`.gluecharm/context/experiences-list.json`** includes this view.
+
+## OpenCode wiring
+
+§3.5.1. Parallel per view after the experiences list is fixed (§6.3).

package/resources/opencode-agents/agent-reference-coverage-execution-report.md

@@ -0,0 +1,28 @@
+---
+description: SRS-31 — write reference-coverage-execution-report.md from embedded coverage + no_action JSON in the EasySpecs prompt.
+mode: primary
+---
+
+# Agent: Reference coverage execution report
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-reference-coverage-execution-report` |
+| **SRS-31** | Markdown execution report — coverage metrics + **`no_action`** routing rows |
+| **Output** | Absolute path in the prompt: **`.gluecharm/context/reference-coverage-execution-report.md`** |
+
+## 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.
+
+The EasySpecs prompt contains **two JSON blocks** (coverage summary and **`no_action`** array). Produce **one** markdown file at the **Output** path that:
+
+- Uses the **exact** top-level headings required in the prompt (`# Reference coverage execution report`, then `## Coverage summary`, `## No-action decisions`, `## Revision`).
+- Copies **metrics and counts** from the coverage JSON only — do not guess repository state.
+- Lists every **`no_action`** row with **filePath**, **fileKind**, **projectRelationSummary**, **rationale** verbatim; if the array is empty, state explicitly that there are no **`no_action`** decisions.
+
+## Rules
+
+1. **Write** the file with your tools — raw markdown, no JSON fences around the whole document.
+2. Do **not** add extra top-level `#` headings before **`## Coverage summary`**.
+3. **`## Revision`** must note EasySpecs / SRS-31 and include a timestamp.

package/resources/opencode-agents/agent-repo-surface-scan.md

@@ -0,0 +1,136 @@
+---
+description: SRS-20 pre-flight — writes repo-surface-scan.json (hasUi/hasBackend with evidence or absence reasoning) under .gluecharm/context.
+mode: primary
+---
+
+# Agent: Repo surface scan (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-repo-surface-scan` |
+| **Display name** | Repo surface scan |
+| **SRS-20** | Pre-flight before `experiences-list.json` — UI vs backend assessment |
+| **Output** | `<worktree>/.gluecharm/context/repo-surface-scan.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.
+
+Decide whether this repository has **meaningful user-facing UI** (web/mobile/desktop surfaces, not merely JSON APIs) and whether it has **backend / server-side** code (HTTP APIs, workers, persistence, server entrypoints). Emit **one** JSON file that **always** sets **`hasUi`** and **`hasBackend`** booleans and **grounds** each “yes” with **non-empty** **`uiSourceReferences`** or **`backendSourceReferences`** (file + line ranges). For each “no”, emit **`uiAbsenceReason`** or **`backendAbsenceReason`** — a **short** honest explanation; **do not** invent fake file paths for a dimension you mark false.
+
+## Revision
+
+Coordination output is **JSON** (no markdown `##` headings in the artifact). Maintain an append-only root **`revisionLog`** array (see schema): each pass that **changes** `hasUi` / `hasBackend`, evidence arrays, or absence reasons must **append** at least `{ "summary": "…" }` (optional `"at"` ISO-8601). **Never delete** prior `revisionLog` entries.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+1. **Map the repo** — manifests (`package.json`, etc.), `src/` layout, apps, APIs, CLI-only trees, static frontends.
+2. **`hasUi: true`** only if there are real UI surfaces (components, routes, templates, mobile UI, extension webviews). Cite **at least one** concrete file + line range in **`uiSourceReferences`**.
+3. **`hasUi: false`** if the repo is API-only, library-only, CLI-only, or backend-only — set **`uiAbsenceReason`** explaining why (no UI evidence array, or leave it absent / empty).
+4. **`hasBackend: true`** if there is server/runtime code (Express/Fastify/handlers, jobs, DB layer, server `main`). Cite evidence in **`backendSourceReferences`**.
+5. **`hasBackend: false`** for static SPA-only or pure client repos with no server in-tree — set **`backendAbsenceReason`**.
+6. Optional root **`kind`**: `easyspecs.repo-surface-scan` and **`version`**: `1`.
+
+**Evidence rules:** Each reference is **one repo-relative file** (`path`), **`startLine`** / **`endLine`** (1-based). **Never** a directory path. Do **not** use `readme.md` basenames in evidence (any casing). Do **not** use paths under **`.opencode/`** (injected tooling, not product source).
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/repo-surface-scan.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/repo-surface-scan.schema.json`
+
+Emit **only** JSON that validates against this schema (UTF-8, no comments, no trailing text). The canonical schema is the bundled `.schema.json`; keep the embedded block in sync with **`resources/schemas/context-lists/repo-surface-scan.schema.json`**.
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/repo-surface-scan.schema.json",
+  "title": "repo-surface-scan",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "pattern": "^[^/]+(/[^/]+)*$" },
+        "startLine": { "type": "integer", "minimum": 1 },
+        "endLine": { "type": "integer", "minimum": 1 },
+        "note": { "type": "string" }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["hasUi", "hasBackend"],
+  "properties": {
+    "kind": { "type": "string", "const": "easyspecs.repo-surface-scan" },
+    "version": { "type": "integer", "minimum": 1 },
+    "hasUi": { "type": "boolean" },
+    "hasBackend": { "type": "boolean" },
+    "uiSourceReferences": { "type": "array", "items": { "$ref": "#/$defs/sourceReference" } },
+    "uiAbsenceReason": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "backendSourceReferences": { "type": "array", "items": { "$ref": "#/$defs/sourceReference" } },
+    "backendAbsenceReason": { "type": "string", "minLength": 1, "maxLength": 2000 },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes assessment fields or evidence.",
+      "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."
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "hasUi": { "const": true } } },
+      "then": {
+        "required": ["uiSourceReferences"],
+        "properties": { "uiSourceReferences": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sourceReference" } } },
+        "not": { "required": ["uiAbsenceReason"] }
+      },
+      "else": {
+        "required": ["uiAbsenceReason"],
+        "allOf": [
+          {
+            "anyOf": [
+              { "not": { "required": ["uiSourceReferences"] } },
+              { "properties": { "uiSourceReferences": { "type": "array", "maxItems": 0 } } }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "if": { "properties": { "hasBackend": { "const": true } } },
+      "then": {
+        "required": ["backendSourceReferences"],
+        "properties": {
+          "backendSourceReferences": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/sourceReference" } }
+        },
+        "not": { "required": ["backendAbsenceReason"] }
+      },
+      "else": {
+        "required": ["backendAbsenceReason"],
+        "allOf": [
+          {
+            "anyOf": [
+              { "not": { "required": ["backendSourceReferences"] } },
+              { "properties": { "backendSourceReferences": { "type": "array", "maxItems": 0 } } }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}
+```

package/resources/opencode-agents/agent-resolve-open-question.md

@@ -0,0 +1,42 @@
+# Agent: Resolve one open question (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-resolve-open-question` |
+| **Display name** | Open question resolver |
+| **SRS-28** | Single-question resolution; JSON outcome file |
+| **Output** | Edits existing `.gluecharm/context/*.md` + writes `.opencode/_run/open-question-resolution.json` |
+
+## 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.
+
+You receive **one** question that appeared under **## Open Questions** in a context markdown file. Your job:
+
+1. **Search** the worktree for a grounded answer (files, symbols, config — not README-only hand-waving).
+2. **Edit** the target markdown: fold the answer into an appropriate section, **remove** that bullet/question from **## Open Questions**, or **delete the Open Questions heading** if the section is empty.
+3. **Preserve** **## Evidence index** — it must stay **valid** (non-empty substantive bullets with allowed paths, or follow the same waiver rules as other context markdown agents). **Never** cite `README.md` or `.gluecharm/context/` paths in Evidence index.
+4. **Do not** add new **## Open Questions** entries.
+5. Write the **JSON outcome file** at the **absolute path** given in the prompt (`open-question-resolution.json`). The parent directory exists.
+
+## JSON file (mandatory)
+
+Write **only** JSON to the resolution path, for example:
+
+```json
+{ "outcome": "answered", "question": "…" }
+```
+
+or
+
+```json
+{ "outcome": "cannot_resolve", "question": "…", "reason": "No implementation references found for X after searching src/ and config." }
+```
+
+- **question** must echo the question you addressed.
+- **reason** is required when **outcome** is **cannot_resolve**.
+
+## Failure modes
+
+- If you **cannot** write the JSON file, the pipeline fails — always emit the JSON after attempting the markdown edit.
+- If the markdown is inconsistent after your edit, prefer **cannot_resolve** with an honest **reason** rather than leaving a broken file.

package/resources/opencode-agents/agent-review-data-model-list.md

@@ -0,0 +1,26 @@
+---
+description: SRS-34 — semantic normalization of data-model-list.json after listDataModel; DM codes; JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Data model list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-data-model-list` |
+| **Display name** | Data model list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/data-model-list.json` (overwrite) |
+
+## 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.
+
+Read **data-model-list.json**. Normalize entity rows: duplicates, vague entities, split/merge; each **entity** (and any inline **fields** / **relationships** rows) **must** have **`sourceReferences`** with **`minItems: 1`**. Stable **DM-*** codes.
+
+## Task
+
+Valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+**`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.

package/resources/opencode-agents/agent-review-entity-fields-list.md

@@ -0,0 +1,26 @@
+---
+description: SRS-34 — semantic normalization of per-entity fields list JSON after listEntityFields; FD codes; JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Entity fields list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-entity-fields-list` |
+| **Display name** | Entity fields list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/DM-*-fields-list.json` (overwrite) |
+
+## 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.
+
+Read **DM-*-fields-list.json**. Normalize FD rows: duplicates, false fields, split/merge; each row must keep valid **sourceReferences**; stable **FD-*** codes and slugs; **entityCode** must match.
+
+## Task
+
+Valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+**`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.