@gluecharm-lab/easyspecs-cli 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gluecharm-lab/easyspecs-cli",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "EasySpecs headless CLI (synthesis, analysis, diagnose, download/upload context, auth, ACE)",
   "license": "Elastic-2.0",
   "homepage": "https://easyspecs.ai/",

package/resources/opencode-agents/agent-list-infrastructure-components.md

@@ -0,0 +1,187 @@
+---
+description: SRS-8 coordination JSON — writes per-feature components list JSON under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Infrastructure components list (per feature, coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-components` |
+| **Display name** | Infrastructure components list |
+| **SRS-8** | §4.6 `IN-<nn>-components-list.json`; §6.2; **AC5**, **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/IN-<nn>-components-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 **infrastructure components** (`IC-*`) with stable codes and names. Barrier for use-case detail markdown and **`IN-<nn>_IC-<uu>-scenarios-list.json`** (§6.2).
+
+**Cardinality:** For any non-trivial feature, **one infrastructure component 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.
+
+## SRS-50 — Stable coordination writes
+
+EasySpecs **merge-by-code** after the run: **existing codes** keep their **previous file order**; **new** codes are moved to the **end** of each coded array (including nested BH/ME/FD/RL rows under the correct parent). **Append** new rows at the end while authoring.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Enumerate goals or user journeys that belong to **feature {{FE_CODE}}** only. Do not change the feature code. Aim for **multiple** infrastructure components whenever the codebase exposes more than one coherent goal or path under this feature (see **Cardinality** under Responsibility). Each infrastructure component 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/components-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/components-list.schema.json`
+
+**Output filename:** `IN-<nn>-components-list.json` must match **`infrastructureCode`** (e.g. `IN-01` → `IN-01-components-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/components-list.schema.json",
+  "title": "IN-nn-components-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": ["infrastructureCode", "components"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.components-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "infrastructureCode": {
+      "type": "string",
+      "pattern": "^IN-[0-9]+$",
+      "description": "Feature code from features-list.json."
+    },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^IC-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Optional; for IN-nn_IC-uu-<slug>.md if PLAN uses slugs on infrastructure components."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per infrastructure component 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
+{
+  "infrastructureCode": "IN-01",
+  "components": [
+    {
+      "code": "IC-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
+
+## Referenced implementation files
+- .gluecharm/context/architecture.md:1-136
+
+
+One JSON file per feature invocation. §3.5.2 with **`{{PARENT_CONTEXT_BLOCK}}`**.

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

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

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

@@ -0,0 +1,187 @@
+---
+description: SRS-8 coordination JSON — writes per-feature test cases list JSON under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: QA test cases list (per feature, coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-test cases` |
+| **Display name** | QA test cases list |
+| **SRS-8** | §4.6 `QA-<nn>-test cases-list.json`; §6.2; **AC5**, **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/QA-<nn>-test 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 **test cases** (`TC-*`) with stable codes and names. Barrier for use-case detail markdown and **`QA-<nn>_TC-<uu>-scenarios-list.json`** (§6.2).
+
+**Cardinality:** For any non-trivial feature, **one test 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.
+
+## SRS-50 — Stable coordination writes
+
+EasySpecs **merge-by-code** after the run: **existing codes** keep their **previous file order**; **new** codes are moved to the **end** of each coded array (including nested BH/ME/FD/RL rows under the correct parent). **Append** new rows at the end while authoring.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Enumerate goals or user journeys that belong to **feature {{FE_CODE}}** only. Do not change the feature code. Aim for **multiple** test cases whenever the codebase exposes more than one coherent goal or path under this feature (see **Cardinality** under Responsibility). Each test 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/test cases-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/test cases-list.schema.json`
+
+**Output filename:** `QA-<nn>-test cases-list.json` must match **`qaCode`** (e.g. `QA-01` → `QA-01-test 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/test cases-list.schema.json",
+  "title": "QA-nn-test 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": ["qaCode", "testCases"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.test 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."
+    },
+    "qaCode": {
+      "type": "string",
+      "pattern": "^QA-[0-9]+$",
+      "description": "Feature code from features-list.json."
+    },
+    "testCases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^TC-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Optional; for QA-nn_TC-uu-<slug>.md if PLAN uses slugs on test cases."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per test 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
+{
+  "qaCode": "QA-01",
+  "testCases": [
+    {
+      "code": "TC-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
+
+## Referenced implementation files
+- .gluecharm/context/architecture.md:1-136
+
+
+One JSON file per feature invocation. §3.5.2 with **`{{PARENT_CONTEXT_BLOCK}}`**.