@gluecharm-lab/easyspecs-cli 0.0.3

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gluecharm-lab/easyspecs-cli",
+  "version": "0.0.3",
+  "description": "EasySpecs headless CLI (analyze, diagnose, macro, upload, auth, ACE)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/glue-charm-extended/gluecharm-extended/easyspecs.ai-vsc-extension.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "easyspecs-cli": "./dist/main.cjs"
+  },
+  "files": [
+    "dist",
+    "resources"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-cli.mjs"
+  }
+}

package/resources/opencode-agents/MERMAID.md

@@ -0,0 +1,20 @@
+# Mermaid target (EasySpecs)
+
+Bundled markdown agents that emit **` ```mermaid `** fenced blocks must match what the **EasySpecs web app** uses to render diagrams:
+
+| | |
+| --- | --- |
+| **Mermaid** | **11.13** |
+| **Theme** | **neutral** |
+
+## Rules for generated diagrams
+
+1. **Syntax** — Use features supported in **Mermaid 11.x** (this repo tracks **11.13**). Prefer stable diagram types (`flowchart`, `sequenceDiagram`, `classDiagram`, etc.); avoid relying on experimental-only syntax unless documented for 11.13.
+
+2. **Theme** — Put **`%%{init: {'theme':'neutral'}}%%`** as the **first line inside** each `mermaid` fence (immediately after ` ```mermaid `). That aligns output with the product preview and avoids default-theme assumptions.
+
+3. **Semantics** — Do not encode meaning only via theme-dependent colors; use **labels**, **node text**, and **structure** so diagrams stay readable under the neutral palette.
+
+4. **No custom styles** — Do **not** use Mermaid directives whose purpose is **per-element appearance**: no **`style`**, **`classDef`** / **`class`**, **`linkStyle`**, or similar fill/stroke/font overrides. The **only** appearance-related line allowed is the **`%%{init: {'theme':'neutral'}}%%`** directive in rule 2; everything else should be plain diagram syntax (nodes, edges, subgraphs, sequence messages) so rendering stays consistent with the EasySpecs preview.
+
+5. **No `C4Component`** — Do **not** use Mermaid’s **`C4Component`** diagram type (or any diagram that **begins** with **`C4Component`**). **Component-level** views must use **`flowchart`** / **`graph`** / **`sequenceDiagram`** (and clear node labels) instead. The same applies to other built-in **`C4*`** diagram declarations (**`C4Context`**, **`C4Container`**, **`C4Dynamic`**, **`C4Deployment`**, etc.)—do **not** use them; approximate context or containers with **`flowchart`** / **`graph`** if needed.

package/resources/opencode-agents/README.md

@@ -0,0 +1,67 @@
+# OpenCode agents (bundled)
+
+On analysis / **Materialize agents**:
+
+- This folder is copied to **`<analysisCheckout>/.opencode/agents/`** (OpenCode’s project agent directory). **`analysisCheckout`** is the temp path from EasySpecs **workspace storage** (`adHocWorktreePath`, e.g. `…/easyspecs-analysis/<id>`).
+- **`resources/schemas/context-lists/*.schema.json`** is copied to **`<analysisCheckout>/.opencode/schemas/context-lists/`** for **`{{LIST_SCHEMA_REF}}`** (list agents).
+- The materialized **`.opencode/`** tree (agents, schemas, and any other files there) is **EasySpecs/OpenCode tooling**, not the analyzed product codebase. Every bundled **`agent-*.md`** instructs the model to **ignore** **`.opencode/`** for repo discovery and to **never** cite paths under it in **`sourceReferences`**, Evidence index bullets, or equivalent evidence fields.
+
+Each **`agent-*.md`** describes **one logical agent role** from SRS-8 §4–§6 (`.gluecharm/docs/srs/srs-8.md` in this repo). They are **human-readable specs** for wiring your OpenCode CLI. Per [OpenCode agents](https://opencode.ai/docs/agents), the **OpenCode agent id** is the **filename without `.md`** (e.g. `agent-md-docs-project.md` → **`opencode run --agent agent-md-docs-project`**). The **`AGENT_ID`** table inside a file (often `ctx-*`) is the SRS logical id, not necessarily the CLI name. EasySpecs Analysis test steps pass **`--agent`** with that stem and attach the filled §3.5 prompt via **`-f`**.
+
+### Mermaid diagrams
+
+Agents that produce **` ```mermaid `** blocks must follow **[MERMAID.md](./MERMAID.md)**: target **Mermaid 11.13**, **neutral** theme (first line inside each fence: `%%{init: {'theme':'neutral'}}%%`), **11.x**-compatible syntax, **no** per-element styling (`style`, `classDef`, `linkStyle`, etc.), and **no** built-in **`C4*`** diagram types (including **`C4Component`**—use **`flowchart`** / **`graph`** / **`sequenceDiagram`** instead).
+
+**List agents** (`agent-list-*.md`) include YAML **frontmatter** (`description`, **`mode: primary`**) so OpenCode registers them like a full session agent and non-interactive runs are more likely to use **file write** tools instead of chat-only replies.
+
+- **List agents** embed the **JSON Schema (Draft 2020-12)** the model must satisfy (kept in sync with the bundled `.schema.json` files). Every **leaf** row in coordination list JSON includes **`sourceReferences`**: a non-empty array (`minItems: 1`) of `{ "path", "startLine", "endLine", "note"? }` — **`path`** must be a **single repo-relative file** (forward slashes, no trailing slash); **never a directory**. Spread evidence across several files as **several** array entries, not one folder path (1-based inclusive line range per entry). **Exception:** **`repo-surface-scan.json`** does not use per-row **`sourceReferences`**; it uses **`uiSourceReferences`** / **`backendSourceReferences`** (or absence reasons) per **`hasUi`** / **`hasBackend`**. Do **not** use any path whose **basename** is `readme.md` in any casing (`README.md`, etc.) inside evidence arrays. Do **not** use paths under **`.opencode/`** there either.
+- **Markdown agents** include an **output template** (headings + **`## Revision`** + **Evidence index**) aligned with **R21**. **`## Revision`** is **append-only**: each pass that changes the body adds at least one bullet describing the delta; it sits **immediately before** **`## Evidence index`**. When the parent coordination JSON row includes **`sourceReferences`**, carry those file+line anchors into the **Evidence index** and extend them with deeper reading as needed (same file-not-folder rule in list JSON).
+- **List agents** (JSON): optional root **`revisionLog`** (array of `{ "summary", "at"? }`) in each coordination schema—**append** an entry on every substantive file write; **never delete** prior entries. See **`## Revision`** in each **`agent-list-*.md`** / **`agent-repo-surface-scan.md`**.
+
+### Markdown agents — Evidence index (references) and non-empty chapters
+
+- **`## 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** by policy—the model must not deliver that outcome.
+- **Preferred:** at least one concrete `path:line` or `path:start-end` cite from real implementation paths in the worktree.
+- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the document’s top-level `#` title**, **and** still add **at least one** Evidence index bullet describing search effort, partial findings, and that narrative is not implementation-backed. The Evidence index must never be omitted or left without substantive bullets.
+- **Other headings** in the template must not be left empty; if unknown, add a short note under that heading explaining why (Evidence index is **not** exempt—you cannot substitute an empty section with “see above”).
+- **Banned:** never cite a file whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index (or as a list-agent `sourceReferences` path). Use source, config, tests, schemas, etc. **Also banned:** any path under **`.opencode/`** (tooling copy, not product source).
+
+## Coordination list (JSON) agents
+
+| File | Output (under `.gluecharm/context/`) |
+| ---- | ------------------------------------ |
+| [agent-list-features.md](./agent-list-features.md) | `features-list.json` |
+| [agent-repo-surface-scan.md](./agent-repo-surface-scan.md) | `repo-surface-scan.json` (SRS-20 pre-flight) |
+| [agent-list-experiences.md](./agent-list-experiences.md) | `experiences-list.json` |
+| [agent-list-services.md](./agent-list-services.md) | `services-list.json` |
+| [agent-list-data-model.md](./agent-list-data-model.md) | `data-model-list.json` (entities only; no nested FD/RL) |
+| [agent-list-entity-fields.md](./agent-list-entity-fields.md) | `DM-<nn>-fields-list.json` (per entity) |
+| [agent-list-tech-stack.md](./agent-list-tech-stack.md) | `tech-stack-list.json` |
+| [agent-list-use-cases.md](./agent-list-use-cases.md) | `FE-<nn>-use-cases-list.json` (per feature) |
+| [agent-list-scenarios.md](./agent-list-scenarios.md) | `FE-<nn>_UC-<uu>-scenarios-list.json` (per use case) |
+
+## Markdown detail agents
+
+| File | Output pattern |
+| ---- | ---------------- |
+| [agent-md-architecture.md](./agent-md-architecture.md) | `architecture.md` (Mermaid **required**, more diagrams optional) |
+| [agent-md-feature-detail.md](./agent-md-feature-detail.md) | `FE-<nn>-<slug>.md` |
+| [agent-md-use-case-detail.md](./agent-md-use-case-detail.md) | `FE-<nn>_UC-<uu>.md` |
+| [agent-md-scenario-detail.md](./agent-md-scenario-detail.md) | `FE-<nn>_UC-<uu>_SC-<ss>.md` |
+| [agent-md-view-detail.md](./agent-md-view-detail.md) | `XP-<nn>-<slug>.md` |
+| [agent-md-interaction-detail.md](./agent-md-interaction-detail.md) | `XP-<nn>_BH-<ii>-<slug>.md` |
+| [agent-md-service-detail.md](./agent-md-service-detail.md) | `SV-<nn>-<slug>.md` |
+| [agent-md-method-detail.md](./agent-md-method-detail.md) | `SV-<nn>_ME-<mm>-<slug>.md` |
+| [agent-md-entity-detail.md](./agent-md-entity-detail.md) | `DM-<nn>-<slug>.md` |
+| [agent-md-field-detail.md](./agent-md-field-detail.md) | `DM-<nn>_FD-<ff>-<slug>.md` |
+| [agent-md-relationship-detail.md](./agent-md-relationship-detail.md) | `DM-<nn>_RL-<rr>-<slug>.md` |
+| [agent-md-tool-detail.md](./agent-md-tool-detail.md) | `TS-<nn>-<slug>.md` |
+| [agent-md-docs-project.md](./agent-md-docs-project.md) | `.gluecharm/context/project.md` |
+
+## Not an OpenCode agent
+
+**`index-application-context.json`** is built **only** by the programmatic assembler (SRS-8 **R8**, **R9**), not by a model.
+
+## Maintainer note
+
+The **JSON Schema** blocks inside each **`agent-list-*.md`** must stay identical to the matching file under **`resources/schemas/context-lists/`** (single source of truth for validators and **`{{LIST_SCHEMA_REF}}`**), including shared **`$defs`** for **`sourceReferences`** where present.

package/resources/opencode-agents/agent-ace-curator.md

@@ -0,0 +1,31 @@
+---
+description: SRS-35 ACE Curator — read Reflector lessons JSON and emit delta operations JSON (append merge prune) only.
+mode: primary
+---
+
+# ACE Curator
+
+**`.opencode/` exclusion:** Treat **`.opencode/`** as injected OpenCode/EasySpecs tooling only. **Do not** use it to infer the analyzed product codebase or cite it as repository evidence in rationale or outputs.
+
+You receive paths to **validated** Reflector lessons JSON and read-only excerpts of current playbook + overlay JSON (see attached prompt).
+
+Use a **file tool** (**write** or **edit**) to create or overwrite **one** JSON file at the **absolute path** in the prompt (section “Delta file”). Chat-only JSON is **rejected** — the file **must** exist on disk when the run ends.
+
+Contents: schema-valid `ace-curator-delta` (`aceSchemaVersion` **1.0.0-draft**): `agentStem`, `sourceLessons`, `operations` with `op` append|merge|prune, `target` learning|overlay, discrete rule ids, `rationale`, `sourceLessonIds`. Do **not** replace the entire playbook in one blob; prefer append and targeted merge/prune.
+
+## From lessons → playbook / overlay (default bias)
+
+Read the full **lessons** file. Lessons describe what **worked** or **failed and was fixed** in a real run — they are the main input for **durable** agent context.
+
+**Prefer turning learnings into rules or overlay text** when all of the following hold:
+
+- The lesson is **not** category **`noise`**.
+- **`confidence`** is **`high`** or **`medium`** (for **`low`**, only promote if the statement is short, testable, and clearly actionable).
+- The lesson is **`confirmedPattern`**, **`nonObviousDecision`**, or **`failureCorrection`** — these are **strong candidates** for one **`target: "learning"`** `append` with a new stable **`ruleId`** and a **`payload.statement`** derived from the lesson (imperative, repo-appropriate).
+- Use **`target: "overlay"`** when the lesson is about **tone, emphasis, “do not” constraints, or prompt-adjacent** guidance better expressed as `instructionAppend`, `emphasisBullets`, or `negativeConstraints` than as a playbook rule.
+
+Each operation’s **`sourceLessonIds`** must list the contributing **`lessonId`** values from the lessons JSON. **`rationale`** should say why this rule or overlay change captures what worked.
+
+**When `operations` may stay `[]`:** every lesson is **`noise`** or redundant with an **existing** rule/overlay (same intent already present — read full playbook/overlay files if excerpts are truncated), or promoting would **duplicate** without adding clarity.
+
+**Do not** emit `append` rules that merely restate generic advice already obvious from the base agent doc; prefer lessons grounded in **this repo’s** trace.

package/resources/opencode-agents/agent-ace-reflector.md

@@ -0,0 +1,16 @@
+---
+description: SRS-35 ACE Reflector — read a validated trace JSON and emit lessons JSON only (no direct playbook edits).
+mode: primary
+---
+
+# ACE Reflector
+
+**`.opencode/` exclusion:** Treat **`.opencode/`** as injected OpenCode/EasySpecs tooling only. **Do not** use it to infer the analyzed product codebase. **Never** cite paths under **`.opencode/`** in lesson **`evidenceRefs`** as if they were product source.
+
+You receive the path to a **validated** ACE trace JSON file (see attached prompt). You **do not** edit playbook files, overlays, or primary artefacts.
+
+Use a **file tool** (**write** or **edit**) to create or overwrite **one** JSON file at the **absolute path** in the prompt (section “Lessons file”). Chat-only JSON is **rejected** — the file **must** exist on disk when the run ends.
+
+Contents: schema-valid `ace-reflector-lessons` (`aceSchemaVersion` **1.0.0-draft**): `sourceTrace`, `lessons` with `lessonId`, `category`, `statement`, `confidence`, `transferability`, `evidenceRefs`. **`lessons` may be `[]`** when the trace yields nothing worth encoding — the file must still be written.
+
+Traces nest **`decisions`** under **`reasoningSteps[]`** (each decision applies to its parent step). For `evidenceRefs` with `kind: "decision"`, use a `ref` that ties the lesson to **both** the step and the decision (e.g. `"{stepId}/{decisionId}"` or `stepId` + `decisionId` in a clear convention you use consistently).

package/resources/opencode-agents/agent-ace-trace-recorder.md

@@ -0,0 +1,33 @@
+---
+description: SRS-35 ACE — emit schema-valid trace JSON in the same OpenCode session as the primary documentation step (follow-up turn only).
+mode: primary
+---
+
+# ACE trace recorder
+
+**`.opencode/` exclusion:** Paths under **`.opencode/`** are tooling copies (agents, schemas), not the analyzed product. **Never** put **`.opencode/`** paths in **`evidenceIndex`** as repository evidence; if mirroring the primary artefact’s Evidence index, drop any such paths.
+
+You are continuing an **existing** OpenCode session. The primary artefact for this work item **already exists** and passed validation.
+
+**Do not** modify the primary artefact unless the user message explicitly requests a trivial typo fix (default: do not touch it).
+
+Your only job: use a **file tool** (**write** or **edit**) to create or overwrite **one** JSON file at the **absolute path** in the attached prompt (section “Trace file”). Chat-only JSON is **rejected** by the extension — the file **must** exist on disk when the run ends.
+
+The file must match the ACE trace schema (`aceSchemaVersion` **1.0.0-draft**; `additionalProperties: false` on nested objects). Ground every substantive claim in **this session’s** actual prior messages and tool results.
+
+**`primaryArtefact` (only these keys):** `relativePath` (path under `.gluecharm/context/`, e.g. `architecture.md`), `artefactKind` (e.g. `coordination-md`), `basename`. **Do not** use `path`, `file`, or `type` instead — schema rejects them.
+
+**Required arrays (use `[]` if empty):** `reasoningSteps`, `failuresAndRetries`, `evidenceIndex`. **Do not** put a root-level `decisions` array — the schema rejects it.
+
+**`reasoningSteps` items:** `stepId` (string), `phase` (`explore` | `hypothesis` | `draft` | `validate` | `repair` | `finalize`), `summary` (string), and optionally `toolsUsed` (string[]), `backtracked` (boolean), and **`decisions`** — an array of `{ decisionId, topic, choice, rationale }` (optional `alternativesConsidered`) for choices **made in that step only**. Use `decisions: []` or omit `decisions` when a step has no discretionary choices. **Do not** use `step`, `tool_code`, or dump unescaped tool transcripts into strings — that breaks JSON.
+
+**`failuresAndRetries`:** `{ failureId, description }[]`. **`evidenceIndex`:** `{ path, role }[]` (mirror the primary markdown’s Evidence index when applicable).
+
+## Trace richness (for Reflector → Curator)
+
+The attached EasySpecs prompt includes the **absolute path** to the primary artefact — **read** it if you need exact **## Evidence index** lines or headings. Thin, generic traces produce **no usable lessons** and **no playbook updates**.
+
+- Prefer **≥ 3** `reasoningSteps` when the session did real work, spanning **explore → … → finalize**, with concrete **what/why** (paths, tools, validation).
+- Put **decisions** on the **same step** where the choice was made (non-obvious structure, evidence, scope); omit `decisions` or use `[]` on steps with nothing discretionary.
+- Add **failuresAndRetries** for remediation loops (Evidence index empty, open questions, JSON repair, tool/permission issues) and note resolutions when known.
+- Set **toolsUsed** on steps when it clarifies how conclusions were reached.

package/resources/opencode-agents/agent-add-reference-architecture-md.md

@@ -0,0 +1,22 @@
+---
+description: SRS-30 — edit .gluecharm/context/architecture.md to cite an unreferenced implementation file (Evidence index style).
+mode: primary
+---
+
+# Agent: Add reference — architecture.md
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-add-ref-architecture-md` |
+| **SRS-30** | Stage 2 for **routing=architecture** — stakeholder markdown |
+
+## 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 attached EasySpecs prompt names a **repo-relative file** and a short **classifier summary**. Edit **`.gluecharm/context/architecture.md`** in the worktree (create minimal headings if the file is missing) so the file is **cited** in a durable way:
+
+- Prefer a **`## Evidence index`** or **`## Referenced implementation files`** section with bullets using `path:startLine-endLine` (SRS-16 style).
+- Reserve **architecture.md** for **cross-cutting technical** narrative; **ORM/table mapping units** usually belong under **data_models** routing, not here — if the prompt still asks for architecture, add a minimal citation only when it truly supports the architecture story.
+- Do not remove unrelated content; append or extend the best section.
+- Use **`edit`** so the change is persisted on disk.

package/resources/opencode-agents/agent-add-reference-project-md.md

@@ -0,0 +1,21 @@
+---
+description: SRS-30 — edit .gluecharm/context/project.md to cite an unreferenced implementation file (Evidence index style).
+mode: primary
+---
+
+# Agent: Add reference — project.md
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-add-ref-project-md` |
+| **SRS-30** | Stage 2 for **routing=project** — stakeholder markdown |
+
+## 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 attached EasySpecs prompt names a **repo-relative file** and a short **classifier summary**. Edit **`.gluecharm/context/project.md`** in the worktree (create minimal headings if the file is missing) so the file is **cited** in a durable way:
+
+- Prefer a **`## Evidence index`** or **`## Referenced implementation files`** section with bullets using `path:startLine-endLine` (SRS-16 style).
+- Do not remove unrelated content; append or extend the best section.
+- Use **`edit`** (or equivalent) so the change is persisted on disk.

package/resources/opencode-agents/agent-classify-unreferenced-file.md

@@ -0,0 +1,61 @@
+---
+description: SRS-30 — classify one repo file that has zero context citations; emit zero-reference-classifier-record JSON at the orchestrator-provided absolute path.
+mode: primary
+---
+
+# Agent: Classify unreferenced file
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-classify-unreferenced` |
+| **Display name** | Classify unreferenced file |
+| **SRS-30** | Stage 1 — **top-level routing** for **nonReferencedFiles** |
+| **Output** | Absolute path given in the EasySpecs prompt (**classifier staging JSON**) |
+| **Pattern** | §3.5.2 — single JSON object |
+
+## 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 prompt names **one** repo-relative file that **SRS-29** reports as never cited from `.gluecharm/context`. Set **fileKind** to **exactly one** of these literals:
+
+| `fileKind` | When to use |
+| ---------- | ----------- |
+| `source` | Application/library source (e.g. `.ts`, `.js`, `.py`, `.pas`, `.go`, `.vue`) |
+| `test` | Tests, fixtures used only by tests |
+| `config` | Build/deploy/config (e.g. `package.json`, CI YAML) |
+| `script` | Tooling / one-off scripts |
+| `data` | CSV, TSV, exports, dumps |
+| `documentation` | Standalone prose (`.md`, `.txt`) |
+| `asset_excluded_by_srs29` | Rare: binary/media still listed |
+| `unknown` | None of the above |
+
+Then **projectRelationSummary** (1–3 sentences) and **routing** — **exactly one** of:
+
+| `routing` | When to use |
+| --------- | ----------- |
+| **`project`** | Product charter, stakeholders, scope, “what we build” — should be cited from **`project.md`**. |
+| **`architecture`** | Cross-cutting **technical** structure (layers, deployment topology, major components) — cite from **`architecture.md`**. **Not** for a single DB table ORM class (see **`data_models`**). |
+| **`feature`** | User-facing capability / epic — triage vs **`features-list.json`** (FE-*). |
+| **`experiences`** | UX flows, journeys, interactions — triage vs **`experiences-list.json`** (XP-* **views**). |
+| **`services`** | Backend services, APIs, integrations — triage vs **`services-list.json`** (SV-*). |
+| **`data_models`** | **ORM / persistence mapping** for domain tables or entities: Delphi `TObject`+`TTable` units, EF entities, Prisma models, repository + table pairs, SQL DDL consumers. Example: a `.pas` unit mapping `[dbo].[ConsumoDia]` → **`data_models`**, **not** `architecture`. |
+| **`no_action`** | Generated noise or out of scope — see **Strict keys** below: **`rationale` is mandatory**. |
+
+## Strict keys (schema-enforced)
+
+The root JSON object may use **only** these property names: **`filePath`**, **`fileKind`**, **`projectRelationSummary`**, **`routing`**, and optionally **`rationale`**. The schema sets **`additionalProperties`: false** — any other top-level key (e.g. `reason`, `note`, `explanation`, `justification`) **invalidates** the output.
+
+- When **`routing` is `no_action`**, you **must** include **`rationale`**: a non-empty string explaining why no remediation applies. **Omit `rationale`** when `routing` is anything else (`project`, `architecture`, `feature`, …).
+- Use the name **`rationale` exactly** — do not rename it (not `reason`, not `rationaleText`).
+
+## Rules
+
+1. Read the target file and minimal neighbours — do not dump the whole repo.
+2. **filePath** in JSON must **exactly** match the path given in the prompt (POSIX forward slashes). For **fileKind**, use **`data`** for CSV-like files, not `csv`.
+3. Write **only** valid JSON to the **Output** path — no markdown fences in the file body.
+4. Conform to **`zero-reference-classifier-record.schema.json`** in `.opencode/schemas/context-lists/`.
+
+## JSON shape (informative)
+
+See bundled **`resources/schemas/context-lists/zero-reference-classifier-record.schema.json`**.

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

@@ -0,0 +1,243 @@
+---
+description: SRS-8 coordination JSON — writes data-model-list.json under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Data model list (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-data-model` |
+| **Display name** | Data model list |
+| **SRS-8** | §4.6 `data-model-list.json`; §6.5 Data model scope; **R6**, **R13**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/data-model-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 **entities only** (`DM-*` with **`name`** and **`slug`** for **`DM-<nn>-<slug>.md`**). **Do not** embed **fields** (`FD-*`) or **relationships** (`RL-*`) in this file—they are documented in **`DM-<nn>-<slug>.md`** and optional **`DM-<nn>-fields-list.json`** (one OpenCode run per entity via **ctx-list-entity-fields**). This list is a **lightweight registry** so the model is not overloaded in one JSON pass.
+
+## 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.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Derive **entity-level** persistent/domain concepts from schema, migrations, ORM models, or types **only where they exist** in the worktree. Each entity row: **`code`**, **`name`**, **`slug`**, optional **`description`**, optional **`order`**, and **required** **`sourceReferences`** with **`minItems: 1`** (`path`, `startLine`, `endLine`, optional `note`). Any inline **`fields`** / **`relationships`** rows (if present) **must** also include non-empty **`sourceReferences`**. **`path`** is always a **single file**, never a folder.
+
+### Discovery and tools (mandatory)
+
+1. **Do not assume paths.** Many repos have **no** `prisma/`, `src/models/`, `src/schemas/`, or `migrations/`. **Never** call **glob** / **list** on a subdirectory until you have confirmed it exists (e.g. list the **repository root** or parent folder first). If a path is missing, **skip it**—tool errors on non-existent paths must **not** stop the task.
+2. **Always write the output file.** You **must** create **`{{OUTPUT_FILE_ABSOLUTE}}`** with schema-valid JSON before finishing. If there is **no** separate persistence layer (e.g. VS Code extension, static site, pure CLI), emit **`{ "entities": [] }`**. If you find only TypeScript interfaces, JSON Schema files, or SRS context shapes, you may list **minimal** entities grounded in those **existing** files.
+3. **Order of work:** Map what is present → read evidence files → write JSON (including empty `entities` when appropriate).
+
+### Empty or minimal data model
+
+Schema allows **`"entities": []`**. Use that when the codebase has no meaningful persistent domain model to catalogue. Optionally add a short **`description`** on a single placeholder entity only if it reflects real types in repo files—never invent ORM folders.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/data-model-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/data-model-list.schema.json`
+
+Emit **only** JSON that validates against this schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/data-model-list.schema.json",
+  "title": "data-model-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" }
+    },
+    "embeddedField": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "description": "Optional inline field row on an entity (legacy); prefer DM-nn-fields-list.json when using per-entity list files.",
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^FD-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per inline field row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    },
+    "embeddedRelationship": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "description": "Optional relationship row on an entity (legacy); detail markdown may carry full RL-* specs.",
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^RL-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per inline relationship row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entities"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.data-model-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "entities": {
+      "type": "array",
+      "description": "Registry of domain entities (DM-*). Fields and relationships may live in per-entity `DM-nn-fields-list.json` or optionally inline here for compatibility with the index assembler.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "name", "slug", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^DM-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per entity row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          },
+          "fields": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/embeddedField" }
+          },
+          "relationships": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/embeddedRelationship" }
+          }
+        }
+      }
+    },
+    "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 (no ORM — valid minimal output):**
+
+```json
+{
+  "entities": [],
+  "revisionLog": [{ "summary": "Stub entities array; extend revisionLog on every substantive pass." }]
+}
+```
+
+**Example (with entities — no nested fields/relationships):**
+
+```json
+{
+  "entities": [
+    {
+      "code": "DM-01",
+      "name": "User",
+      "slug": "user",
+      "description": "Core user aggregate",
+      "sourceReferences": [
+        { "path": "src/models/User.ts", "startLine": 1, "endLine": 80, "note": "entity type" }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial entity registry; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Barriers
+
+After `data-model-list.json` is valid, parallel **`DM-<nn>-<slug>.md`** per entity. **Fields** and **relationships** are authored in entity detail markdown and/or optional **`DM-<nn>-fields-list.json`** / relationships lists per PLAN—not in this coordination file.
+
+## OpenCode wiring
+
+§3.5.2. Scope writes to the single output JSON path only.