@gluecharm-lab/easyspecs-cli 0.0.3

package/resources/opencode-agents/agent-list-use-cases.md

@@ -0,0 +1,179 @@
+---
+description: SRS-8 coordination JSON — writes per-feature use-cases list JSON under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Use cases list (per feature, coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-use-cases` |
+| **Display name** | Use cases list |
+| **SRS-8** | §4.6 `FE-<nn>-use-cases-list.json`; §6.2; **AC5**, **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/FE-<nn>-use-cases-list.json` (one run per feature) |
+| **Pattern** | §3.5.2 — JSON list + **`{{PARENT_CONTEXT_BLOCK}}`** with **`FE_CODE`** |
+
+## 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.
+
+For a **single feature** already fixed in `features-list.json`, emit all **use cases** (`UC-*`) with stable codes and names. Barrier for use-case detail markdown and **`FE-<nn>_UC-<uu>-scenarios-list.json`** (§6.2).
+
+**Cardinality:** For any non-trivial feature, **one use case is usually too few**. Real capabilities almost always decompose into **several** distinct goals or journeys (different actors, entrypoints, commands, APIs, or outcomes). Treat a single-UC list as a **red flag**: look again for separate flows you collapsed into one umbrella. Reserve a lone UC for **genuinely atomic** features (one narrow operation with no meaningful variants).
+
+## 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}}`)
+
+Enumerate goals or user journeys that belong to **feature {{FE_CODE}}** only. Do not change the feature code. Aim for **multiple** use cases whenever the codebase exposes more than one coherent goal or path under this feature (see **Cardinality** under Responsibility). Each use case row **must** include **`sourceReferences`** with **`minItems: 1`** (`path`, `startLine`, `endLine`, optional `note`). **`path`** must be a **single file** (never a directory); use multiple objects for multiple files under a folder.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/use-cases-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/use-cases-list.schema.json`
+
+**Output filename:** `FE-<nn>-use-cases-list.json` must match **`featureCode`** (e.g. `FE-01` → `FE-01-use-cases-list.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/use-cases-list.schema.json",
+  "title": "FE-nn-use-cases-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": ["featureCode", "useCases"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.use-cases-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "featureCode": {
+      "type": "string",
+      "pattern": "^FE-[0-9]+$",
+      "description": "Feature code from features-list.json."
+    },
+    "useCases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^UC-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Optional; for FE-nn_UC-uu-<slug>.md if PLAN uses slugs on use cases."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per use case 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
+{
+  "featureCode": "FE-01",
+  "useCases": [
+    {
+      "code": "UC-01",
+      "name": "Sign in with password",
+      "order": 1,
+      "sourceReferences": [
+        { "path": "src/auth/handlers.ts", "startLine": 40, "endLine": 90, "note": "password sign-in" }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial use-case list for feature; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Prerequisites
+
+Valid **`features-list.json`**; orchestration passes **`{{FE_CODE}}`** in the parent context block.
+
+## OpenCode wiring
+
+One JSON file per feature invocation. §3.5.2 with **`{{PARENT_CONTEXT_BLOCK}}`**.

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

@@ -0,0 +1,139 @@
+# Agent: Architecture (markdown detail)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-architecture` |
+| **Display name** | Architecture narrative |
+| **SRS-8** | §4.2 `architecture.md`; §6.1 (parallel with global lists); **R7**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/architecture.md` |
+| **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.
+
+Produce **application-wide** architecture narrative: components, boundaries, data flow, integrations, deployment view as appropriate. This is **not** the canonical feature list (that is `features-list.json`, §4.6).
+
+**Mermaid is mandatory:** **`architecture.md` must contain at least one** fenced **Mermaid** diagram that reflects the real structure or behaviour of this codebase (not placeholder boxes). You **should** add **further** Mermaid diagrams wherever they improve clarity—e.g. separate views for **context vs internal components**, **request/sequence** paths, **state**, or **deployment**—without duplicating the same graph verbatim. **Target runtime:** **[MERMAID.md](./MERMAID.md)** — **Mermaid 11.13**, **neutral** theme (first line inside each fence: `%%{init: {'theme':'neutral'}}%%`).
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Document how the system is structured and how major parts interact, grounded in the repository under **`{{WORKTREE_ROOT}}`**.
+
+1. **Survey** entrypoints, packages, `src/` layout, configs, and integration boundaries so diagrams and prose match reality.
+2. **Include `## Architecture diagrams (Mermaid)`** (see template) with **at least one** valid `mermaid` fenced block—typically a **component** or **system-context** view as **`flowchart`** / **`graph`** (layered boxes and edges that *read* like C4 are fine; **do not** use Mermaid **`C4Component`** or any other **`C4*`** diagram declaration—see **[MERMAID.md](./MERMAID.md)**). Prefer **node labels** that map to real modules, services, or deployable units.
+3. **Add more diagrams** in that section or next to relevant headings (**Data flow**, **Context and boundaries**, etc.) when useful: e.g. `sequenceDiagram` for a critical path, `flowchart` for pipeline/steps, second graph for external dependencies. Each diagram should earn its place (no decorative noise).
+4. Give each diagram a **short title** (heading or bold line above the fence) so readers can scan the doc.
+5. **R21:** support diagram claims with **Evidence index** cites to the files that justify nodes and edges.
+6. When applicable, fill **`## What kind of UI this is`** per **What kind of UI this is (when applicable)** below (table + non-UI callouts); otherwise omit or one line — never leave that heading empty without explanation.
+
+## What kind of UI this is (when applicable)
+
+When the codebase has an **operator or end-user UI** (not API-only or headless-only), add **`## What kind of UI this is`** to the generated `architecture.md`. Use a **compact table** so readers immediately see platform, framework, visual language, whether the product is one surface or many apps, and how UI ties to data if that matters. **Ground every row in Evidence index** cites (forms, project files, framework imports). If there is **no** meaningful UI, **omit** this section or use a single honest line under the heading (e.g. no operator UI; CLI/service only).
+
+**Example** (shape and level of detail — **replace** with what the repo actually is; the rows below illustrate a classic Windows desktop / Delphi VCL operations suite):
+
+| Aspect | Description |
+|--------|-------------|
+| **Platform** | Windows desktop (native Win32-style controls) |
+| **Framework** | Embarcadero **Delphi VCL** (`TForm`, `TPanel`, `TTabSheet`, `TMainMenu`, etc.) |
+| **Visual style** | Classic “business / operations” look: **MS Sans Serif** / **Microsoft Sans Serif**, `clBtnFace` backgrounds, raised/lowered panel bevels, **tabbed notebooks** and **data grids** |
+| **Architecture** | Several **separate executables** (`.dpr`), each with its own windows — not a single web SPA |
+| **Data binding** | Grids such as `TOrderDBGrid` tie to **data sources** (`TDataSource`) backed by the SQL Server database |
+
+**Non-UI components:** Call out things that are **not** operator screens when they share the same repo — e.g. Windows **services** (`ReceptorSvc`, `ExportadorSvc`) that ship `.dfm` files for **service data modules**, not forms for users; **“No Service”** variants as small **program** windows that often **minimize to the system tray**. Adapt names and patterns to the actual codebase.
+
+## 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}}`** using this skeleton. Replace prose; keep headings unless PLAN overrides. **R21:** every substantive statement in the body sections must appear again in **Evidence index** with `path:line` or `path:start-end`, or as *(inference)* with the strongest supporting cite (`{{CITATION_FORMAT_EXAMPLE}}`).
+
+```markdown
+# Application architecture
+
+**Repository root (analysis):** {{WORKTREE_ROOT}}
+
+## Summary
+
+<!-- One short paragraph; cite high-level entry points. -->
+
+## What kind of UI this is
+
+<!--
+  When applicable only: table (Platform, Framework, Visual style, Architecture, Data binding, etc.).
+  Note non-UI pieces (services, data-module .dfm, tray/minimize behaviour) vs operator screens.
+  Omit this section or one honest line if there is no UI. Evidence index must support each row.
+-->
+
+## Architecture diagrams (Mermaid)
+
+<!--
+  MANDATORY: at least one fenced code block with language "mermaid" below this heading.
+  First line inside each fence: %%{init: {'theme':'neutral'}}%% (see MERMAID.md — Mermaid 11.13, neutral theme).
+  Recommended coverage (use what fits the repo — add more blocks in this section or under other ## headings as needed):
+  - System / context: major actors, external systems, this app boundary (flowchart or graph).
+  - Components: internal subsystems and dependencies (graph or flowchart).
+  - Data or control flow: sequenceDiagram or flowchart for a representative request, job, or event path.
+  Each diagram: short title (### or bold line), then the fence, then optional one-line caption.
+  Add extra diagrams when they clarify; avoid redundant copies of the same structure.
+-->
+
+### <!-- e.g. System context -->
+
+<!-- Open fence with language tag mermaid; first line %%{init: {'theme':'neutral'}}%% then diagram body; close fence. -->
+
+### <!-- Optional: further diagrams — e.g. Internal components, Request sequence, Deployment -->
+
+## Context and boundaries
+
+<!-- Runtime, deployment units, external systems; cite configs and docs. You may add another Mermaid block here if it fits better than the main diagrams section. -->
+
+## Major components
+
+<!-- Subsystems, apps, packages; cite module layout. -->
+
+## Data flow
+
+<!-- Request/response, events, persistence; cite pipelines. A sequenceDiagram or flowchart here is encouraged when non-trivial. -->
+
+## Cross-cutting concerns
+
+<!-- Auth, logging, i18n, etc.; cite shared modules. -->
+
+## Risks and gaps
+
+<!-- Explicit unknowns; still cite whatever partial evidence exists or mark inference. -->
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: diagrams and narrative from src/ and configs. -->
+
+## Evidence index
+
+- <!-- claim → `src/...:42` -->
+- <!-- diagram edge "A→B" grounded → `src/...:10-18` -->
+- <!-- *(inference)* … → `src/...:10-18` -->
+```
+
+## Evidence (**R21**)
+
+Follow **Non-empty chapters and Evidence index** above. Every substantive claim must cite **`path:line`** or **`path:start-end`** per **`{{CITATION_FORMAT_EXAMPLE}}`**. Label inference explicitly. **Architecture diagrams:** tie major nodes and relationships to **Evidence index** entries (same file may support multiple diagram elements).
+
+## OpenCode wiring
+
+§3.5.1. Exactly **one** output file at **`{{OUTPUT_FILE_ABSOLUTE}}`**. Do not write coordination list JSON or `index-application-context.json`.

package/resources/opencode-agents/agent-md-docs-project.md

@@ -0,0 +1,172 @@
+# Agent: Repository project overview (`project.md` in context)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-docs-project` |
+| **Display name** | Docs — project overview |
+| **SRS-8** | Markdown detail under **`.gluecharm/context/`** (same folder as `architecture.md`); **R7** / **R21** apply. |
+| **Output** | `<worktree>/.gluecharm/context/project.md` |
+| **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.
+
+Produce or refresh **`project.md`**: a **single entry-point document** for humans that explains **what this repository is for**, its **overall goal**, a **concise upfront summary**, **illustrative** capabilities and use cases (not exhaustive), how it behaves at a high level, how to run and build it, and where deeper docs live. It complements **`architecture.md`** in the same directory (architecture = structure and flows; **project** = product/repo handbook).
+
+**Incremental delivery:** Treat **`{{OUTPUT_FILE_ABSOLUTE}}`** as a **living document**. **Survey the whole worktree** (top-level folders and important subtrees: `src/`, `resources/`, `test(s)/`, `docs/`, `.github/`, config roots, etc.) and **open representative files** until you have a grounded picture; on **each** pass that changes the file, **append** to **`## Revision`** (see template) **at least one** new line stating **what** you added or changed. Do not drop prior revision lines when you rewrite the file.
+
+**Clarity over rigidity:** You **may** add **extra `##` or `###` chapters** anywhere in the body (before **`## Revision`**) when they help explain the repository—e.g. key workflows, CLI vs UI surfaces, analysis pipeline, deployment path, domain concepts. You **may** embed **Mermaid** diagrams in standard fenced **` ```mermaid `** blocks to illustrate flows, component relationships, or state; follow **[MERMAID.md](./MERMAID.md)** (**Mermaid 11.13**, **neutral** theme). Keep diagrams **grounded in the codebase**, **legible** (avoid huge graphs), and mention new diagrams or sections in **`## Revision`**.
+
+Target audience: contributors, release engineers, and context consumers that read the analysis worktree.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Analyse **`{{WORKTREE_ROOT}}`** systematically: **map directories and files** (list roots, then drill into areas that define behaviour), and read **`README`**, **`package.json`** / manifests, **`src/`** entrypoints, **`docs/`**, SRS under **`.gluecharm/docs/`** when present, plus any other paths that clarify product intent. **If `project.md` already exists**, read it first; **preserve and extend** **`## Revision`** (append new entries; never delete history). Improve content **incrementally**—you may do multiple read→edit→write cycles in one run: after **each** write, the on-disk file must include **all** previous revision bullets **plus** new line(s) for that step.
+
+Write **`{{OUTPUT_FILE_ABSOLUTE}}`** = `<worktree>/.gluecharm/context/project.md`.
+
+**Required narrative shape (in order):**
+
+1. **Summary** — Place **first** after the title: a short block (roughly **3–6 sentences** or a tight bullet list) answering: what this repo is, who it serves, and the main outcomes or problems it addresses. No deep implementation detail here.
+2. **Overall goal** — A dedicated section stating the **north star**: why the repository exists, the problem space or product mission, and what “success” means at repo level (still high level; cite sources in the Evidence index).
+3. **Illustrative capabilities and use cases** — A **non-exhaustive** section with two sub-parts:
+   - **Capabilities / functionalities** — Bullet list of **representative** features or subsystems (from commands, UI, APIs, CLIs, pipelines—whatever the repo actually exposes). Label explicitly that the list is **illustrative, not complete**.
+   - **Example use cases** — Short **user- or operator-oriented** scenarios (e.g. “As a developer, I …”) that **illustrate** how the product is used; these are **examples**, not a formal requirements catalogue.
+4. Then cover **purpose** (product behaviour in slightly more detail), **repository role** (shipping/CI), **tech stack**, **scripts**, **source layout**, **configuration**, **related documentation**, **out of scope** as in the template below—**unless** you reorder slightly to group related ideas; the **Summary** must stay **first** after the title, and **`## Revision`** / **`## Evidence index`** stay **last** in that relative order.
+5. **Optional sections** — Insert **additional chapters** (with clear headings) when needed for a faithful overview. Prefer handbook-level depth; defer deep system design to **`architecture.md`** unless a short diagram here prevents confusion.
+6. **Mermaid** — Use **` ```mermaid `** … **` ``` `** blocks for flowcharts, sequence diagrams, or graphs when they clarify **how the product works** (activation, command routing, worktree/analysis flow, etc.); first line inside each fence **`%%{init: {'theme':'neutral'}}%%`** per **MERMAID.md**. Add a one-line caption before or after the block if helpful. Log “Added Mermaid …” (or similar) in **`## Revision`**.
+
+Cross-link **`architecture.md`** in the same folder and repo **`README.md`** / **`docs/`** when they exist. Align filenames and claims with the actual tree.
+
+## 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. (You may still *mention* `README.md` in prose or **Related documentation**; do not use it as a code-grounding cite.) **Never** list paths under **`.opencode/`** either (tooling copy, not product source).
+
+### Revision log (mandatory)
+
+- Maintain a **`## Revision`** section (**append-only** list: `- …` bullets or dated lines).
+- **Every** time you write an updated `project.md`, add **at least one** new bullet describing what this edit introduced or changed (e.g. “Added scripts table from `package.json`”, “Expanded illustrative use cases after reviewing `src/extension.ts`”, “Fixed tech stack from `tsconfig`”).
+- **First creation** (no prior file): start the section with a line such as **Initial draft** and what was covered in that pass.
+- **Later passes:** keep **all** earlier bullets; append **new** bullets at the **bottom** of the list (newest last), unless you adopt ISO date prefixes for sorting—then be consistent.
+
+## Output template
+
+Write **exactly** the content for **`{{OUTPUT_FILE_ABSOLUTE}}`**. **R21:** substantive claims carry **Evidence index** entries with `path:line` or `path:start-end`, or *(inference)* with best cite.
+
+```markdown
+# <Product or repo name> — project
+
+## Summary
+
+<!--
+  First thing a reader sees after the title. 3–6 sentences (or a few bullets):
+  what this repository is, primary audience, main value or outcomes.
+  No long lists here — those go below.
+-->
+
+## Overall goal
+
+<!--
+  North star: mission, problem space, why this codebase exists.
+  What success looks like for this repo/product at a high level.
+-->
+
+## Illustrative capabilities and use cases
+
+> **Note:** The lists below are **illustrative only**, not an exhaustive inventory of every feature or workflow.
+
+### Representative functionalities
+
+- <!-- capability 1 — e.g. VS Code command, web surface, CLI subcommand, background job -->
+- <!-- capability 2 -->
+- <!-- add more as needed; stop when coverage feels representative, not encyclopedic -->
+
+### Example use cases
+
+- <!-- UC-style vignette: actor + goal + short outcome, e.g. “Contributor runs tests locally before opening a PR.” -->
+- <!-- another example -->
+- <!-- optional: link to formal use-case docs if the repo defines them -->
+
+<!--
+  Optional: insert one or more additional ## (or ###) sections anywhere among the body (before ## Revision) when they clarify the repository — e.g. "Key workflows", "Analysis pipeline", "CLI vs extension host".
+  You may use Mermaid: open a fenced code block with language tag "mermaid"; first line %%{init: {'theme':'neutral'}}%%; then flowchart / sequenceDiagram / graph syntax grounded in the real codebase (Mermaid 11.13, neutral — MERMAID.md). Close the fence. Avoid oversized diagrams. Record diagram/chapter changes in ## Revision.
+-->
+
+## Purpose
+
+<!-- What users get; client vs server; data persistence; main user journeys in one paragraph (can elaborate beyond Summary/Goal). -->
+
+## Repository role
+
+<!-- Deployable artefact (e.g. static SPA), how it ships, notable CI/release hooks. -->
+
+## Tech stack
+
+| Area | Choice |
+| ---- | ------ |
+| … | … |
+
+## Scripts
+
+| Command | Description |
+| ------- | ----------- |
+| … | … |
+
+## Source layout (high level)
+
+| Path | Role |
+| ---- | ---- |
+| … | … |
+
+## Configuration and environment
+
+<!-- Key env vars, `.env.example`, feature flags. -->
+
+## Related documentation
+
+<!-- e.g. architecture.md (same context folder), README.md, docs/, .gluecharm/docs/srs/ -->
+
+## Out of scope (current phase)
+
+<!-- Explicit non-goals. -->
+
+## Revision
+
+<!--
+  Append-only changelog of edits to this file. Newest entry at the bottom (or use consistent ISO-8601 date prefixes).
+  Each time you save an improved version, add at least one new bullet describing what was added or updated.
+-->
+
+- <!-- e.g. Initial draft: summary, goal, and tech stack from README + package.json. -->
+- <!-- e.g. Added illustrative use cases after reviewing src/commands. -->
+- <!-- e.g. Populated source layout table from repository tree. -->
+
+## Evidence index
+
+- <!-- At least one substantive bullet with `path:line` or explanation per Non-empty chapters and Evidence index — never empty. -->
+```
+
+## Evidence (**R21**)
+
+Follow **Non-empty chapters and Evidence index** above. Substantive claims carry Evidence index entries with `path:line` or `path:start-end`, or *(inference)* with best cite.
+
+## Prerequisites
+
+Ensure **`<worktree>/.gluecharm/context/`** exists (or create it). Do **not** write `index-application-context.json`.
+
+## OpenCode wiring
+
+§3.5.1. Set **`{{OUTPUT_FILE_ABSOLUTE}}`** to `join({{WORKTREE_ROOT}}, '.gluecharm', 'context', 'project.md')`. One file per run.
+
+## Distinction from other agents
+
+| Output | Role |
+| ------ | ---- |
+| **`project.md`** (this agent) | Repo handbook: **summary**, **overall goal**, **illustrative** capabilities & use cases, purpose, stack, scripts, layout, links; **optional** extra chapters + **Mermaid**; **incremental** updates; **`## Revision`** append-only log. |
+| **`architecture.md`** (`ctx-md-architecture`) | Application architecture for context assembly / SRS-8 pipeline. |
+| **`README.md`** (repo root) | Install quick start; may point readers to deeper docs. |

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

@@ -0,0 +1,86 @@
+# Agent: Entity detail (markdown)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-md-entity-detail` |
+| **Display name** | Entity detail |
+| **SRS-8** | §4.5 **`DM-<nn>-<slug>.md`**; §6.5 (parallel after `data-model-list.json`); **R7**, **R21** |
+| **Output** | `<worktree>/.gluecharm/context/DM-<nn>-<slug>.md` |
+| **Input (coordination)** | `<worktree>/.gluecharm/context/data-model-list.json` (repo-relative: `.gluecharm/context/data-model-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 aggregate or persistent entity** (`DM-*`): lifecycle, invariants, storage, mapping to schema or ORM models.
+
+**Coordination JSON** lives **only** under **`.gluecharm/context/`**, not the worktree root. Read **`.gluecharm/context/data-model-list.json`** first; if missing, **glob** `.gluecharm/context/**/data-model-list.json` before failing.
+
+## Task (for `{{TASK_DESCRIPTION}}`)
+
+Describe **entity {{DM_CODE}}** per **`.gluecharm/context/data-model-list.json`**. The entity row **must** include **`sourceReferences`** (`minItems: 1`); seed the **Evidence index** with them (file paths only, not directories).
+
+## 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 **`DM-<nn>-<slug>.md`**.
+
+```markdown
+# Entity {{DM_CODE}} — <name>
+
+**Slug:** <slug> · **File:** {{OUTPUT_BASENAME}}
+
+## Summary
+
+## Purpose and lifecycle
+
+## Invariants
+
+## Storage mapping
+
+<!-- Table/collection, ORM model; cite schema/migrations. -->
+
+## Fields overview
+
+<!-- Pointer to FD-* detail files when generated. -->
+
+## Relationships overview
+
+<!-- Pointer to RL-* detail files. -->
+
+## Revision
+
+<!--
+  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
+-->
+
+- <!-- e.g. Initial draft: entity lifecycle from models/schema. -->
+
+## 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 migrations, models, and repository code.
+
+## Prerequisites
+
+**`.gluecharm/context/data-model-list.json`** lists this entity.
+
+## OpenCode wiring
+
+§3.5.1. Parallel per entity (§6.5).