@gluecharm-lab/easyspecs-cli 0.0.3

package/resources/opencode-agents/agent-review-experiences-list.md

@@ -0,0 +1,72 @@
+---
+description: SRS-34 — semantic normalization of experiences-list.json after listExperiences; XP/BH codes; JSON only; .gluecharm/context; repo-grounded views (no invented UIs).
+mode: primary
+---
+
+# Agent: Experiences list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-experiences-list` |
+| **Display name** | Experiences list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/experiences-list.json` (overwrite) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Read the existing **experiences-list.json** (schema-valid from **listExperiences**). Rewrite as canonical: merge duplicate views/interactions, remove false XP/BH rows, fix split/merge; each **view** and **interaction** **must** have **`sourceReferences`** with **`minItems: 1`** (add evidence or **drop** the row). Keep stable **XP-*** / **BH-*** codes. Append **revisionLog** if the schema supports it.
+
+**Critical:** A **view** is any **user-facing surface** the product exposes for interaction—not only full graphical windows. Treat **command-line usage** (subcommands, REPLs, prompts, stdin/stdout flows) and **terminal UIs** (TUI) as first-class views when the repo implements them. **Do not assume** the project is a web app or a single-page stack.
+
+## Reasoning workflow (mandatory order)
+
+Work through these steps **explicitly** (brief notes in your own trace are fine; the **deliverable** remains the JSON file only). Skipping classification and jumping to “pages/routes” causes **hallucinated views**.
+
+### 1. Classify UI paradigm(s) for this repository
+
+Before naming views, infer from **evidence under `{{WORKTREE_ROOT}}`** (build files, entrypoints, frameworks, docs—not guesses):
+
+- **Web** (browser): SPAs, SSR, static sites, server-rendered HTML.
+- **Desktop GUI**: native or cross-platform windowing (e.g. Electron, Qt, WPF, WinForms, **Embarcadero Delphi/VCL/FMX**, etc.).
+- **CLI / terminal**: binaries, scripts, `argparse`/cobra/clap-style CLIs, interactive prompts.
+- **TUI**: ncurses, bubbletea, textual, etc.
+- **Hybrid**: e.g. desktop shell + embedded webview, or CLI + optional GUI.
+- **Library / headless**: if there is **no** end-user UI in this repo, reflect that honestly—do not invent screens; align list rows with what actually exists (API-only packages may have **no** XP views, or only “usage via API/docs” if the schema allows).
+
+If multiple paradigms apply, **list each** and later assign views to the correct paradigm.
+
+### 2. Map “where views live” to the stack (non-linear)
+
+Do **not** use a single template (e.g. “always Vue routes”). For each paradigm you identified, decide **which artifacts constitute a distinct user interface**:
+
+| Paradigm | Typical grounding (examples—verify in repo) |
+| -------- | -------------------------------------------- |
+| Web | Route tables, page components, app shells, server templates |
+| Desktop (generic) | Windows/forms/scenes, XAML, storyboards, main window entry |
+| **Delphi (Object Pascal)** | **Forms**: paired **`.dfm`** (layout) **+** **`.pas`** units (behavior); projects **`.dproj` / `.dpr`**; frames and datamodules may compose multiple surfaces—one **logical** form/dialog can be one view or split per user task per list rules |
+| CLI | Main entry, command dispatchers, help text, config flags, subcommand modules |
+| TUI | Screen definitions, keymaps, panel layouts |
+| Extension / IDE | `package.json` contributions, webview panels, commands |
+
+**Delphi note:** Discovery is **not** linear like “one folder = one page.” Follow **project file → units → forms**: a `.dfm` names a form class; the matching `.pas` holds code. Count **user-openable** forms/dialogs/wizards the product actually ships, not every internal data module unless the user interacts with it as a surface.
+
+### 3. Ground every retained or new view row
+
+For each experience/view row you keep or add:
+
+- There must be **at least one** plausible **source reference** (path to implementation: form unit, route file, CLI module, etc.) **or** explicit evidence that the prior list row was already correct—**never** invent routes, forms, or “screens” with no file/project backing.
+- If **listExperiences** proposed a view you cannot verify, **remove or merge** it into a verified sibling; do not leave placeholder views to satisfy a mental model of “what a normal app has.”
+- Prefer **fewer, accurate** views over **many, speculative** ones.
+
+### 4. Normalize (original duty)
+
+Merge duplicates, fix XP/BH codes and slits, preserve valid **sourceReferences**, append **revisionLog** when supported.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Execute the **reasoning workflow**, then normalize per **Responsibility**. Output one JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** validating against **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+Use **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.

package/resources/opencode-agents/agent-review-features-list.md

@@ -0,0 +1,52 @@
+---
+description: SRS-27 — semantic normalization of features-list.json after listFeatures; duplicates, splits, featureKind (product/infrastructure/testing); JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Features list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-features-list` |
+| **Display name** | Features list — semantic review |
+| **SRS-27** | Gate before feature-detail markdown and `listRepoSurface` fan-out |
+| **Output** | `<worktree>/.gluecharm/context/features-list.json` (overwrite) |
+| **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.
+
+**Read** the **existing** `features-list.json` (already schema-valid from **listFeatures**). **Rewrite** it as the **single canonical** list downstream agents will use. You **do not** re-discover the repo from scratch; you **normalize** semantics:
+
+1. **Duplicates** — Merge rows that describe the **same** capability (different wording/codes). Keep **one** canonical row; **drop** the duplicate codes. Prefer keeping the **lower** `FE-<nn>` when ties are arbitrary. **Append** `revisionLog` explaining merges.
+2. **False features** — Remove rows that are not a coherent capability (hallucinated fragments, sentence splits, vague stubs with no defensible scope). **revisionLog** each removal.
+3. **Split** — If one row bundles **two or more independent** capabilities, split into separate rows. Assign **new** `FE-<nn>` codes using the **next** unused integers (max existing + 1, +2, …). Update `slug`/`name`/`description` accordingly. **revisionLog** splits. (Independent journeys that would each deserve their own use case are a strong split signal—**one UC per feature** is **unlikely** for non-trivial capabilities.)
+4. **Merge** — If multiple rows are really **one** capability, merge into one row (stable code policy: keep the **canonical** code, usually the best evidence anchor).
+5. **Testing vs product** — If **“test login”** (or similar) duplicates **“login”**, **merge** into the product feature and describe test hooks in `description`, **or** keep one row with `featureKind`: `testing` **only** when it is a **pure** harness with **no** user-facing counterpart. Do **not** leave two product rows for the same capability.
+6. **Infrastructure** — Rows that are primarily **ops/deployment/platform** (not a user story) **must** set `featureKind`: `infrastructure`. Ordinary capabilities use `featureKind`: `product` or omit (treated as product).
+7. **featureKind** — Every surviving row **should** explicitly set **`product`**, **`infrastructure`**, or **`testing`** (schema enum). Omit only when clearly product-equivalent.
+8. **`sourceReferences`** — Every surviving feature row **must** have **`minItems: 1`** valid evidence; add from manifests/code if missing. Drop or fix entries that violate schema (no directories, no `.gluecharm/` paths, no `.opencode/` paths, no README basenames).
+9. **`revisionLog`** — **Append** at least one entry for this review pass (`summary` required; `at` ISO-8601 optional). **Never delete** prior `revisionLog` entries.
+
+## Stable codes
+
+- When **merging** duplicates: keep **one** `FE-*` code (prefer the row with stronger evidence).
+- When **splitting**: add **new** codes only; do **not** renumber unrelated existing rows.
+- **`slug`** must remain kebab-case and match `^FE-<nn>-<slug>.md` detail file convention.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Execute the normalization above. Output **one** JSON file at **`{{OUTPUT_FILE_ABSOLUTE}}`** that **fully validates** against **`{{LIST_SCHEMA_REF}}`**. Do **not** output markdown.
+
+## JSON Schema
+
+Use the same bundled schema as **listFeatures** (`features-list.schema.json`), including optional **`featureKind`**: `product` | `infrastructure` | `testing`.
+
+## Barriers
+
+- Downstream orchestration runs **only** after this file passes EasySpecs validation (schema + forbidden `sourceReferences` paths).
+
+## OpenCode wiring
+
+Supply **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**. Do **not** write `index-application-context.json`.

package/resources/opencode-agents/agent-review-scenarios-list.md

@@ -0,0 +1,28 @@
+---
+description: SRS-34 — semantic normalization of per–use-case scenarios list JSON after listScenarios; SC codes; JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Scenarios list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-scenarios-list` |
+| **Display name** | Scenarios list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/FE-*_UC-*-scenarios-list.json` (overwrite) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Read the scenarios list for the scoped feature/use case. Merge duplicates, remove false scenarios; each surviving row **must** have **`sourceReferences`** with **`minItems: 1`**. Stable **SC-*** codes; **featureCode** and **useCaseCode** in JSON must match scope.
+
+**Cardinality:** After normalization, **one** remaining scenario is **suspicious** for a non-trivial use case—re-check that error paths, permission denials, boundary data, and alternate success paths were not folded into one overly broad SC. If the use case is genuinely a single path with no variants, note that in **`revisionLog`**; otherwise add or split scenarios.
+
+## Task
+
+Valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+**`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.

package/resources/opencode-agents/agent-review-services-list.md

@@ -0,0 +1,26 @@
+---
+description: SRS-34 — semantic normalization of services-list.json after listServices; SV/ME codes; JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Services list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-services-list` |
+| **Display name** | Services list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/services-list.json` (overwrite) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Read **services-list.json** from **listServices**. Normalize: merge duplicate services/methods, remove false SV/ME rows, fix granularity; each **service** and **method** row **must** have **`sourceReferences`** with **`minItems: 1`**. Stable **SV-*** / **ME-*** codes. **revisionLog** if supported.
+
+## Task
+
+Output valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+**`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.

package/resources/opencode-agents/agent-review-tech-stack-list.md

@@ -0,0 +1,26 @@
+---
+description: SRS-34 — semantic normalization of tech-stack-list.json after listTechStack; TS codes; JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Tech stack list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-tech-stack-list` |
+| **Display name** | Tech stack list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/tech-stack-list.json` (overwrite) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Read **tech-stack-list.json**. Normalize tool rows: duplicates, false tools; stable **TS-*** codes and slugs. **Every** surviving tool **must** keep valid **`sourceReferences`** with **`minItems: 1`** (schema-required). **Drop** tools you cannot ground with at least one allowed file+line span, or **add** evidence from manifests/configs before writing — empty/missing **`sourceReferences`** fails validation.
+
+## Task
+
+Valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+**`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.

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

@@ -0,0 +1,28 @@
+---
+description: SRS-34 — semantic normalization of per-feature use-cases list JSON after listUseCases; UC codes; JSON only; .gluecharm/context.
+mode: primary
+---
+
+# Agent: Use cases list — semantic review (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-review-use-cases-list` |
+| **Display name** | Use cases list — semantic review |
+| **Output** | `<worktree>/.gluecharm/context/FE-*-use-cases-list.json` (overwrite) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Read the use-cases list for the scoped feature. Merge duplicate UCs, remove false use cases, fix split/merge; each surviving row **must** keep **`sourceReferences`** with **`minItems: 1`** (add evidence or **drop** the row). Stable **UC-*** codes matching **featureCode** in JSON.
+
+**Cardinality:** After normalization, **one** remaining UC is **suspicious** for a non-trivial feature—re-check that distinct goals or entry paths were not over-merged. If the feature truly has a single linear journey, note that in **`revisionLog`**; otherwise split or add UCs so the list reflects multiple meaningful journeys.
+
+## Task
+
+Valid JSON at **`{{OUTPUT_FILE_ABSOLUTE}}`** per **`{{LIST_SCHEMA_REF}}`**.
+
+## OpenCode wiring
+
+**`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**.

package/resources/opencode-agents/agent-triage-unreferenced-coordination.md

@@ -0,0 +1,35 @@
+---
+description: SRS-30 — triage one unreferenced file against a coordination list (feature, experience, service, or data_model); emit zero-reference-triage-record JSON at the path in the EasySpecs prompt.
+mode: primary
+---
+
+# Agent: Triage unreferenced file (coordination list)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-triage-unreferenced-coordination` |
+| **Display name** | Triage unreferenced file — coordination |
+| **SRS-30** | Stage 2 — new row vs enrich existing for **features** / **experiences** / **services** / **data model** lists |
+| **Output** | Absolute path in the EasySpecs prompt (**triage staging JSON**) |
+| **Pattern** | 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 EasySpecs prompt names the **target file**, the **coordinationScope** (`feature` | `experience` | `service` | `data_model`), and which **list JSON** to read (`features-list.json`, `experiences-list.json`, `services-list.json`, or `data-model-list.json`).
+
+Decide:
+
+- **new_item** — add a new row (**proposedSummary** required; optional **proposedCode** with correct prefix: FE-/XP-/SV-/DM-, **proposedSlug** kebab-case).
+- **enrich_existing** — add **sourceReferences** evidence to an existing row; **targetItemRef** = that row’s **code** string.
+- **defer** / **no_action** — no list change.
+
+## Rules
+
+1. Read the indicated list file under `.gluecharm/context/` before deciding.
+2. Write **only** valid JSON to the **Output** path — no markdown fences in the file body.
+3. Conform to **`zero-reference-triage-record.schema.json`**.
+4. **coordinationScope** in JSON must **exactly** match the value requested in the prompt (`feature`, `experience`, `service`, or `data_model`).
+5. **targetItemRef** must be a JSON **string** when **enrich_existing**; omit or omit null for other decisions.
+6. **evidenceNotes** must be a JSON **array of strings** (use `[]` if none).

package/resources/schemas/ace/ace-agent-overlay.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.local/schemas/ace/ace-agent-overlay.schema.json",
+  "title": "ACE per-agent overlay",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["aceOverlayVersion", "agentStem"],
+  "properties": {
+    "aceOverlayVersion": { "type": "string", "const": "1.0.0-draft" },
+    "agentStem": { "type": "string", "minLength": 1 },
+    "instructionAppend": {
+      "type": "string",
+      "description": "Markdown or plain text appended to agent instructions after materialize"
+    },
+    "systemPromptSuffix": { "type": "string" },
+    "negativeConstraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "emphasisBullets": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/resources/schemas/ace/ace-curator-delta.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.local/schemas/ace/ace-curator-delta.schema.json",
+  "title": "ACE CuratorAgent delta",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["aceSchemaVersion", "agentStem", "sourceLessons", "operations"],
+  "properties": {
+    "aceSchemaVersion": { "type": "string", "const": "1.0.0-draft" },
+    "agentStem": { "type": "string", "minLength": 1 },
+    "sourceLessons": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["relativePath"],
+      "properties": {
+        "relativePath": { "type": "string" }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["opId", "op", "target", "rationale", "sourceLessonIds"],
+        "properties": {
+          "opId": { "type": "string", "minLength": 1 },
+          "op": { "type": "string", "enum": ["append", "merge", "prune"] },
+          "target": {
+            "type": "string",
+            "enum": ["learning", "overlay"]
+          },
+          "ruleId": { "type": "string" },
+          "payload": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "rationale": { "type": "string", "minLength": 1 },
+          "sourceLessonIds": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "overlayPatch": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/resources/schemas/ace/ace-generator-trace.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.local/schemas/ace/ace-generator-trace.schema.json",
+  "title": "ACE trace record (same OpenCode session as primary)",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "aceTraceDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["decisionId", "topic", "choice", "rationale"],
+      "properties": {
+        "decisionId": { "type": "string", "minLength": 1 },
+        "topic": { "type": "string" },
+        "choice": { "type": "string" },
+        "rationale": { "type": "string" },
+        "alternativesConsidered": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  },
+  "required": [
+    "aceSchemaVersion",
+    "sessionMeta",
+    "primaryArtefact",
+    "reasoningSteps",
+    "failuresAndRetries",
+    "evidenceIndex"
+  ],
+  "properties": {
+    "aceSchemaVersion": { "type": "string", "const": "1.0.0-draft" },
+    "sessionMeta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "agentStem", "startedAt", "openCodeSessionId"],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "agentStem": { "type": "string", "minLength": 1 },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "openCodeSessionId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Must equal OpenCode session ID used with opencode run -s"
+        },
+        "sessionTitle": { "type": "string" },
+        "modelId": { "type": "string" }
+      }
+    },
+    "primaryArtefact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["relativePath", "artefactKind"],
+      "properties": {
+        "relativePath": {
+          "type": "string",
+          "description": "Path under .gluecharm/context/"
+        },
+        "artefactKind": {
+          "type": "string",
+          "enum": [
+            "coordination-md",
+            "coordination-list-json",
+            "detail-md",
+            "repo-surface-json",
+            "zero-ref-json",
+            "report-json",
+            "other"
+          ]
+        },
+        "basename": { "type": "string" }
+      }
+    },
+    "reasoningSteps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["stepId", "phase", "summary"],
+        "properties": {
+          "stepId": { "type": "string", "minLength": 1 },
+          "phase": {
+            "type": "string",
+            "enum": ["explore", "hypothesis", "draft", "validate", "repair", "finalize"]
+          },
+          "summary": { "type": "string", "minLength": 1 },
+          "toolsUsed": { "type": "array", "items": { "type": "string" } },
+          "backtracked": { "type": "boolean" },
+          "decisions": {
+            "type": "array",
+            "description": "Non-obvious choices taken during this step only (omit or use [] if none).",
+            "items": { "$ref": "#/$defs/aceTraceDecision" }
+          }
+        }
+      }
+    },
+    "failuresAndRetries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["failureId", "description"],
+        "properties": {
+          "failureId": { "type": "string" },
+          "description": { "type": "string" },
+          "resolution": { "type": "string" }
+        }
+      }
+    },
+    "evidenceIndex": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "role"],
+        "properties": {
+          "path": { "type": "string" },
+          "role": { "type": "string" },
+          "symbols": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "playbookHooks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ruleRef", "effect"],
+        "properties": {
+          "ruleRef": { "type": "string" },
+          "effect": { "type": "string", "enum": ["applied", "violated", "absent"] }
+        }
+      }
+    }
+  }
+}

package/resources/schemas/ace/ace-playbook.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.local/schemas/ace/ace-playbook.schema.json",
+  "title": "ACE per-agent playbook (durable learning JSON)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["acePlaybookVersion", "agentStem", "rules"],
+  "properties": {
+    "acePlaybookVersion": { "type": "string", "const": "1.0.0-draft" },
+    "agentStem": { "type": "string", "minLength": 1 },
+    "rules": {
+      "type": "array",
+      "description": "Ordered rules; render order for prompt injection is extension-defined",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ruleId", "statement"],
+        "properties": {
+          "ruleId": { "type": "string", "minLength": 1 },
+          "statement": { "type": "string", "minLength": 1 },
+          "priority": { "type": "integer" },
+          "tags": { "type": "array", "items": { "type": "string" } },
+          "sourceRunIds": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Optional provenance from Curator applier"
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/resources/schemas/ace/ace-reflector-lessons.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.local/schemas/ace/ace-reflector-lessons.schema.json",
+  "title": "ACE ReflectorAgent lessons",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["aceSchemaVersion", "sourceTrace", "lessons"],
+  "properties": {
+    "aceSchemaVersion": { "type": "string", "const": "1.0.0-draft" },
+    "sourceTrace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["relativePath", "sessionRunId"],
+      "properties": {
+        "relativePath": {
+          "type": "string",
+          "description": "Path to trace JSON under .gluecharm/context/learnings/"
+        },
+        "sessionRunId": { "type": "string" }
+      }
+    },
+    "lessons": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "lessonId",
+          "category",
+          "statement",
+          "confidence",
+          "transferability",
+          "evidenceRefs"
+        ],
+        "properties": {
+          "lessonId": { "type": "string", "minLength": 1 },
+          "category": {
+            "type": "string",
+            "enum": [
+              "failureCorrection",
+              "nonObviousDecision",
+              "confirmedPattern",
+              "noise"
+            ]
+          },
+          "statement": { "type": "string", "minLength": 1 },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "transferability": {
+            "type": "string",
+            "enum": ["repo-specific", "pattern-likely"]
+          },
+          "evidenceRefs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["kind", "ref"],
+              "properties": {
+                "kind": {
+                  "type": "string",
+                  "enum": ["reasoningStep", "decision", "failure"]
+                },
+                "ref": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "summaryForHumans": { "type": "string" }
+  }
+}