@dombaras/agent-harness 0.1.1 → 0.1.2

package/README.md

@@ -66,17 +66,23 @@ hardcoding domain assumptions.
 - Personas also carry mechanical guardrails in frontmatter:
   - thinkers (`planner`, `product-manager`) → `permission: { edit: deny, bash: deny }`
   - `qa-architect`, `handoff` → `permission: { bash: deny }`
+  - code personas (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
+    `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
+    `diagnostics-expert`) → `permission.edit` allows everything EXCEPT
+    `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` (governance
+    and harness files are read-only), plus `bash: allow`
   - deterministic personas → `temperature: 0.1`
   - all personas → a `steps:` cap (cost ceiling)
   - `planner`, `handoff` → `hidden: true`
 - `.agents/skills/*/SKILL.md` carries a `model:` label only (informational).
 - `npx @dombaras/agent-harness list` prints the persona → model mapping.
 - `npm run test:dispatch` mechanically verifies model pins against
-  `scripts/qa/models.allowlist.txt`.
+  `scripts/qa/models.allowlist.txt` and that `model-routing.md` does not name a
+  stale model no longer pinned anywhere (doc↔config drift).
 
 ## QA gates
 
-- `npm run test:dispatch` — persona model-pin preflight + persona↔skill parity.
+- `npm run test:dispatch` — persona model-pin preflight + persona↔skill parity + model-routing↔pin drift check.
 - `npm run test:governance` — session wrap-up dispatch-log enforcement.
 - `node scripts/qa/check-qa-scripts.js` — warns (or `--strict` fails) when the
   DoD-referenced runtime QA tiers aren't wired into `package.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
   "bin": {
     "agent-harness": "bin/agent-harness.js"

package/templates/.agents/AGENTS.md

@@ -38,7 +38,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - **Delegate Big Searches**: Use the `explore` subagent for broad multi-file exploration.
 - **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/`; read the relevant memory files before starting.
 - **Locations Map**: Read `.agents/memory/locations.md` first — it is the canonical index of sessions, logs, docs, and data. Never re-hunt for a path.
-- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch independent subagents in parallel.
+- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch subagents in parallel only when their work is disjoint (see below).
   - **Persona map**:
     | Work area | Persona |
     |---|---|
@@ -57,6 +57,10 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     | Session wrap-up / handoff | `handoff` |
   - **Waivers** (the only way to skip a persona): a persona may be skipped only when (a) the change is fully covered by an automated gate on push or in the QA tiers, AND (b) the skip is pre-audited in `.agents/memory/` with a cited pointer. Log every waiver as `waived: <persona>` with `reason: <gate|pointer>`.
   - **Dispatch failure ladder** (never silent): retry once (resume the same `task_id`); if it still fails, do the work inline and log `degraded: <persona> model: <reason>`; never silently skip.
+  - **Bound every dispatch (task spec)** — never hand a persona a bare metric ("get under N lines", "type everything"). Each dispatch prompt carries: `Objective` (one deliverable) → `Owned files` (exact paths) → `Read-only files` → `Shared contracts (owns|consumes)` → `Done = <gate command + observable metric>` → `Out-of-scope`.
+  - **Parallel = disjoint** — run personas in parallel only when their owned files AND shared contracts are disjoint; otherwise serialize, with the shared-contract owner dispatched first.
+  - **Orchestrator acceptance gate** — after a persona reports done, re-run the gate yourself (`tsc --noEmit`, `npm run lint:hooks`, `npm run test:quick`) and grep the metric before integrating or committing. A subagent's `Evidence` is a claim, not proof.
+  - **No suppression shortcuts** — never accept (or produce) file-level `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore` to hit a metric. Suppressions are line-level only and each carries a reason — a file-level disable is a rules violation, not a fix.
 - **Synchronous Terminal Commands**: Prefer sync one-shot commands (build/test/lint) that return inline, over background servers/watchers.
 - **No Output Bloat**: Never paste large files/diffs into chat; apply edits with the edit tool, never print a code block of a change.
 - **Right-Size the QA Tier**: Never run the full regression suite for a CSS/copy tweak.
@@ -88,6 +92,7 @@ Every completed task passes this gate, in order:
    - [ ] RTL traced if layout touched; logical properties used.
    - [ ] Cross-screen audit if a new UX pattern was introduced.
    - [ ] No modified file over ~500 lines without extracting components.
+   - [ ] No blanket file-level `eslint-disable`/`@ts-nocheck`/`@ts-ignore` suppressions (line-level only, each with a reason).
 1. **QA tier** — `qa-architect` picks the tier (and authors progression tests); `qa-runner` executes and makes it pass (§6).
 2. **Security check** — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
 3. **Commit** — concise `feat:` / `fix:` / `refactor:` message.

package/templates/.agents/memory/model-routing.md

@@ -27,6 +27,11 @@ frontmatter:
 - **Thinkers** (`planner`, `product-manager`) have `permission: { edit: deny, bash: deny }`.
 - **`qa-architect`** has `permission: { bash: deny }` (authors tests, never runs).
 - **`handoff`** has `permission: { bash: deny }`.
+- **Code personas** (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
+  `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
+  `diagnostics-expert`) allow `edit` everywhere except governance/harness paths
+  — `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` are denied —
+  so out-of-scope edits are blocked mechanically, not just by prose.
 - **Deterministic personas** (`planner`, `qa-architect`, `qa-runner`, `handoff`,
   `diagnostics-expert`) pin `temperature: 0.1`.
 - **`steps:`** caps iterations per persona (cost ceiling).
@@ -50,7 +55,8 @@ Every subagent must return a single final message with, in order:
 ## Gates
 
 - `npm run test:dispatch` — `scripts/qa/check-dispatch-config.js` verifies model
-  pins, persona↔skill parity, and the output-contract marker.
+  pins, persona↔skill parity, the output-contract marker, and that this doc does
+  not name a concrete model no longer pinned anywhere (doc↔config drift).
 - `npm run test:governance` — `scripts/qa/governance.js` enforces the wrap-up
   dispatch log.
 - `scripts/qa/check-qa-scripts.js` — verifies the DoD-referenced QA tier scripts

package/templates/.agents/rules/00-operating.md

@@ -4,8 +4,11 @@ Always in effect. Full detail lives in `.agents/AGENTS.md`; read it before non-t
 
 ## Step Zero — subagent dispatch gate (non-negotiable)
 
-Before reading or editing any file for a task, dispatch the relevant personas via the `task` tool — each runs on its own `model:` (`.opencode/agents/<name>.md`). Dispatch independent subagents in parallel; serialize only on dependencies. Keep only coordination/mechanical work (reads, git, commits) on the main model.
+Before reading or editing any file for a task, dispatch the relevant personas via the `task` tool — each runs on its own `model:` (`.opencode/agents/<name>.md`). Keep only coordination/mechanical work (reads, git, commits) on the main model.
 
+- **Bound every task before dispatching.** No persona gets a bare metric ("get under N lines", "type everything"). Each dispatch prompt carries a task spec: `Objective` (one deliverable) → `Owned files` (exact paths) → `Read-only files` → `Shared contracts (owns|consumes)` → `Done = <gate command + observable metric>` → `Out-of-scope`.
+- **Parallel = disjoint.** Dispatch two personas in parallel only when their owned files AND shared contracts are disjoint; otherwise serialize and put the shared-contract owner first.
+- **Accept, don't trust.** After a code persona reports done, the orchestrator re-runs the gate itself (`tsc --noEmit`, `lint:hooks`, `test:quick`) and greps the metric before integrating — a subagent's `Evidence` is a claim, not proof.
 - Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
 - Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
 - Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in `.agents/memory/handoff.md`.

package/templates/.agents/skills/frontend-engineer/SKILL.md

@@ -57,6 +57,7 @@ Whenever you are writing frontend code or dealing with build errors, you MUST st
 - **500-Line Rule**: No single `.tsx` screen file should exceed ~500 lines. If it does, extract logically distinct sections (modals, list items, action handlers, sub-views) into separate component files in a co-located directory (e.g., `mobile/components/transactions/`). "Extract" means MOVE code into typed modules — never minify/compress JSX onto single lines to dodge the count, never swap real types for `any`, and never add `.d.ts` overrides or inline `require()` to silence tsc.
 - **Before adding code to a file that already exceeds 500 lines**: STOP. Refactor first, then add. Never grow a monolith.
 - **One component = one responsibility**: A screen file should orchestrate layout and state. Rendering logic for individual cards, list items, modals, or drawers should be in dedicated components.
+- **No suppression shortcuts**: never silence lint/type errors with file-level `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore` to hit a metric. Suppressions are line-level only, and each must carry a reason.
 
 ## Frontend Quality Exit Checklist
 Before declaring any UI work done, verify:

package/templates/.agents/skills/mobile-engineer/SKILL.md

@@ -38,3 +38,7 @@ You own the native React Native layer and its gotchas — not shared web UI (tha
   config, handoff, other screens) to satisfy a metric.
 - **Verify before done**: run `tsc --noEmit`, `npm run lint:hooks`, `npm run test:quick`
   yourself and report the observed output — never claim success you did not run.
+- **No suppression shortcuts**: never silence the gate with a file-level
+  `/* eslint-disable */`, `@ts-nocheck`, or `@ts-ignore`. Suppressions are
+  line-level only and each carries a reason — a file-level disable to hit a
+  metric is a rules violation, not a fix.

package/templates/.agents/skills/planner/SKILL.md

@@ -10,9 +10,20 @@ You decompose the task and produce the dispatch plan the orchestrator executes.
 
 ## Output contract (always return)
 
-1. **Dispatch plan** — ordered list of `persona → model → exact prompt scope → dependencies`.
-2. **Parallel batches** — group independent dispatches to run concurrently (one message, multiple `task` calls).
-3. **Orchestrator-only work** — glue/mechanical steps (reads, git, commits, final integration) kept on the main model.
+Never hand a persona a bare metric ("get under N lines", "type everything"). If a
+task cannot be bounded by the spec below, split it further or flag it — do not
+dispatch it broad.
+
+1. **Dispatch plan** — ordered list of entries, each with:
+   - `persona → model`
+   - **Objective** — one sentence naming a single deliverable.
+   - **Owned files** — exact paths this persona may edit.
+   - **Read-only files** — explicit out-of-scope paths (governance, memory, skills, other screens).
+   - **Shared contracts** — for each shared module/type: `owns` or `consumes` (exactly one owner per contract).
+   - **Done =** — the exact gate command(s) + observable metric (e.g. `tsc --noEmit` clean, `\bany\b` count 0), so success is verifiable, not self-reported.
+   - **Dependencies** — which other dispatch, if any, must complete first.
+2. **Parallel batches** — group only DISJOINT entries (disjoint owned files AND disjoint shared contracts). Serialize personas that would touch the same files or emit the same shared contract; put the contract owner first.
+3. **Orchestrator-only work** — glue/mechanical steps (reads, git, commits, final integration, acceptance re-verification) kept on the main model.
 4. **Risk flags** — any ambiguity that needs the user before proceeding.
 
 ## Rules

package/templates/.opencode/agents/data-engineer.md

@@ -3,6 +3,15 @@ description: Use for catalog/data ingestion and entity resolution — external-s
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Data Engineer. Read and follow the complete persona instructions in `.agents/skills/data-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/devops-engineer.md

@@ -3,6 +3,15 @@ description: Use for deployment, CI/CD, cron/scheduling, env & secrets managemen
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} DevOps Engineer. Read and follow the complete persona instructions in `.agents/skills/devops-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/diagnostics-expert.md

@@ -4,6 +4,15 @@ mode: subagent
 model: opencode/deepseek-v4-pro
 temperature: 0.1
 steps: 30
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Diagnostics Expert. Read and follow the complete persona instructions in `.agents/skills/diagnostics-expert/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/frontend-engineer.md

@@ -3,6 +3,15 @@ description: Use when writing or fixing web React / Next.js / Tailwind / shadcn
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Frontend Engineer. Read and follow the complete persona instructions in `.agents/skills/frontend-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/mobile-engineer.md

@@ -3,6 +3,15 @@ description: Use when writing or fixing Expo / React Native native code — nati
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Mobile Engineer. Read and follow the complete persona instructions in `.agents/skills/mobile-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/security-engineer.md

@@ -3,6 +3,15 @@ description: Use when a change touches auth, secrets, input validation, external
 mode: subagent
 model: opencode/deepseek-v4-pro
 steps: 30
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} Security Engineer. Read and follow the complete persona instructions in `.agents/skills/security-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/system-architect.md

@@ -3,6 +3,15 @@ description: Use when changing the Prisma schema, data model, multi-tenant bound
 mode: subagent
 model: opencode/deepseek-v4-pro
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} System Architect. Read and follow the complete persona instructions in `.agents/skills/system-architect/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/ui-designer.md

@@ -3,6 +3,15 @@ description: Use when designing the visual system — design tokens, theming, an
 mode: subagent
 model: opencode/gpt-5.6-luna
 steps: 40
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash:
+    "*": allow
 ---
 
 You are the {{PROJECT_NAME}} UI Designer. Read and follow the complete persona instructions in `.agents/skills/ui-designer/SKILL.md`, then carry out the task.

package/templates/scripts/qa/check-dispatch-config.js

@@ -12,6 +12,8 @@
  *   3. Every agent body carries the output-contract marker (Result / Evidence /
  *      Deferred & risks) so subagents return a consistent report shape.
  *   4. `opencode.json` main `model` + `small_model` are also real provider IDs.
+ *   5. `.agents/memory/model-routing.md` does not name a concrete model that is
+ *      no longer pinned by any agent or opencode.json (doc↔config drift).
  *
  * Allowlist refresh (only when the provider adds/removes models):
  *   npx opencode models > scripts/qa/models.allowlist.txt
@@ -62,7 +64,12 @@ function frontmatterModel(file) {
   return modelLine.replace(/^model:\s*/i, "").trim();
 }
 
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 // 1. every agent file exists, pins a real model, references a real skill
+const agentModels = new Set();
 const agentNames = fs
   .readdirSync(agentsDir)
   .filter((f) => f.endsWith(".md"))
@@ -72,6 +79,7 @@ for (const f of agentNames) {
   const name = f.replace(/\.md$/, "");
   const file = path.join(agentsDir, f);
   const model = frontmatterModel(file);
+  if (model) agentModels.add(model);
   const body = fs.readFileSync(file, "utf8");
   const skillMd = path.join(skillsDir, name, "SKILL.md");
   if (!model) fail(`agent ${f}: missing frontmatter model: (all agents must pin a model)`);
@@ -95,16 +103,40 @@ if (skillNames.join("|") === [...agentNames].map((f) => f.replace(/\.md$/, "")).
   pass(`persona parity: ${agentNames.length} agents == ${skillNames.length} skills`);
 
 // 3. opencode.json main + small model are real provider IDs
+const configModels = new Set();
 if (fs.existsSync(opencodeJson)) {
   const cfg = JSON.parse(fs.readFileSync(opencodeJson, "utf8"));
   for (const key of ["model", "small_model"]) {
     const v = cfg[key];
+    if (v) configModels.add(v);
     if (!v) warn(`opencode.json: no \`${key}\` set`);
     else if (allowlist.has(v)) pass(`opencode.json ${key} \`${v}\` is a real provider model`);
     else fail(`opencode.json ${key} \`${v}\` NOT in provider allowlist`);
   }
 } else warn("opencode.json not found (skip)");
 
+// 4. model-routing.md ↔ model: pin consistency (doc↔config drift)
+const usedModels = new Set([...agentModels, ...configModels]);
+const modelRoutingFile = path.join(root, ".agents", "memory", "model-routing.md");
+if (fs.existsSync(modelRoutingFile)) {
+  const doc = fs.readFileSync(modelRoutingFile, "utf8");
+  const modelPattern = [...allowlist].map(escapeRe).join("|");
+  const mentioned = new Set();
+  const re = new RegExp(modelPattern, "g");
+  let m;
+  while ((m = re.exec(doc)) !== null) mentioned.add(m[0]);
+  if (mentioned.size === 0) {
+    pass("model-routing.md names no concrete model IDs (tier policy only) — nothing to cross-check");
+  } else {
+    for (const mid of mentioned) {
+      if (usedModels.has(mid)) pass(`model-routing.md \`${mid}\` matches an actual pin`);
+      else fail(`model-routing.md references \`${mid}\` but no agent/config pins it (doc↔config drift)`);
+    }
+  }
+} else {
+  warn("model-routing.md not found (skip doc↔config drift check)");
+}
+
 console.log(
   `\nRESULT: ${agentNames.length} agents checked \u2014 ` +
     (failures.length ? `${failures.length} FAILURE(S)` : "0 failures") +