opensquid 0.5.395

package/packs/builtin/task-spec-author/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: task-spec-author
+description: 'Author task specs that ship at high compression. Use when the user wants to add a new task to docs/tasks/, extend an existing track, or create a new track spec file. Applies the standardized 11-field template (persona-specific skills + 7-phase workflow + concrete code shapes + acceptance criteria) that empirically ships 10–15× faster than minimal specs by eliminating implementation drift.'
+---
+
+# Task Spec Author
+
+You're authoring a task spec destined for `docs/tasks/<track>.md` in the loop planning repo (or equivalent task-spec location). The spec is a contract for future implementation — a subagent reading any task block should have zero guesswork about what to do.
+
+**Why this discipline matters:** detailed specs have empirically compressed 14–15 working days of typical implementation into ~10.6 wall-clock hours (~13× compression on the opensquid 8-phase refactor, 2026-05-19 → 2026-05-20). The mechanism: subagents given persona-specific skills + concrete 7-phase steps + real code shapes don't burn cycles exploring or asking — they execute. The cost of detail upfront (~30–60 min per task) is paid back many times over in avoided rework cycles.
+
+## When to use this skill
+
+Trigger phrases include:
+
+- "add a task for X"
+- "spec out the work for Y"
+- "create a new track for Z"
+- "author task specs"
+- "extend docs/tasks/ with..."
+- "write up the implementation plan for..."
+
+Do NOT use this skill for:
+
+- Memory entries (use the auto-memory system in CLAUDE.md)
+- Slash commands or runtime skills (those have separate formats)
+- One-off implementation notes (this is for tracked, multi-phase work)
+- ADRs / design docs (those go in `docs/`, not `docs/tasks/`)
+
+## The 11-field task template (fixed order)
+
+Every task block follows this template in this order:
+
+````markdown
+### Task <ID>: <name>
+
+**Required skills:** [2–5 from skills-catalog.md]
+**Deliverable:** [one sentence]
+**Depends on:** [task IDs or markdown links to other phase files]
+
+**Files affected:**
+
+- `path/to/file.ts` (new) — role
+- `other/file.ts` (modify) — what changes
+
+**Key code shapes:**
+
+```<lang>
+// real TS / YAML / SQL — never pseudocode
+```
+````
+
+**Test fixtures:**
+
+- Input X → expected Y
+- Input A → expected B
+- Edge case: empty input → expected behavior
+
+**Acceptance criteria:**
+
+- [ ] specific condition 1
+- [ ] specific condition 2
+
+**Risk callouts:**
+
+- gotcha 1
+- gotcha 2
+
+**References:**
+
+- URL or path
+
+**Verification commands:**
+
+```bash
+pnpm typecheck
+pnpm vitest run path/to/test
+```
+
+**7-phase steps:**
+
+1. **pre-research:** [specific files, URLs, questions]
+2. **learn:** [specific output deliverable]
+3. **code:** [specific files + module structure]
+4. **test:** [specific test names + cases]
+5. **audit:** [specific quality gates]
+6. **post-research:** [specific external sources]
+7. **fix:** [what audit + post-research feedback gets applied]
+
+```
+
+The order is load-bearing — readers scan top-down. Skills line first lets a subagent know which persona to embody before reading further.
+
+## Field-by-field discipline
+
+### Required skills (2–5 entries)
+
+**Granularity rule:** library/package or research-domain level. NOT generic categories.
+
+Wrong (generic):
+```
+
+**Required skills:** TypeScript expert; Testing expert
+
+```
+
+Right (persona-specific):
+```
+
+**Required skills:** Zod schema design expert (zod npm package, TS); TypeScript discriminated union design expert; Audit / code review expert; Architectural design expert
+
+```
+
+Mix two types:
+- **Library/package** experts: `chokidar npm package expert`, `lru-cache npm package expert`, `Zod schema design expert (zod npm package, TS)`, `commander v12 CLI argument parsing expert`
+- **Research-domain** experts: `Audit / code review expert`, `Architectural design expert`, `Security capability model expert`, `Performance / overhead analysis expert`, `Two-stage validation gate design expert`
+
+The persona IS the embodied expertise. Mix both kinds so the subagent knows the right library AND the right thinking discipline.
+
+If a skill isn't in `skills-catalog.md` yet, **add it** (see "Skills catalog extension" below).
+
+### Deliverable (one sentence)
+
+The shipped artifact. Concrete and observable.
+
+Wrong: "Improve the runtime"
+Right: "`src/runtime/types.ts` Event union has 8 variants (4 existing + 4 new); skill schema accepts `triggers:` block; evaluator filters rules by event kind; all Phase 1–7 tests still pass."
+
+### Depends on
+
+Task IDs OR markdown links to other phase files. Every dependency must be resolvable.
+
+Wrong: "Depends on Phase 1"
+Right: "Depends on [AUTO.1](automation.md#task-auto1-widen-event-union-...), [phase-7-wedge-gate.md](phase-7-wedge-gate.md) (capture.ts + promote.ts)"
+
+### Files affected
+
+Manifest of every file the task creates or modifies, with role.
+
+```
+
+- `src/runtime/types.ts` (modify) — extend Event union with 4 new variants
+- `src/runtime/types.test.ts` (new) — round-trip tests per variant
+- `package.json` (modify) — add `chokidar: ^3.6.0` dependency
+
+````
+
+Catches scope creep. If you're touching 10 files, the task is too big — split it.
+
+### Key code shapes
+
+**Real code, not pseudocode.** The shapes are paste-and-adapt scaffolding for the implementing subagent. Show:
+- Type signatures
+- Function shapes (impl body can be `/* ... */`)
+- YAML schemas
+- SQL DDL
+
+Wrong (pseudocode):
+```typescript
+// somewhere, somehow, parse the cron expression and validate it
+function parseCron(input: string): CronResult { /* magic */ }
+````
+
+Right (real shape):
+
+```typescript
+import { CronExpressionParser } from 'cron-parser';
+
+export interface CronResult {
+  cron: string;
+  next: Date;
+  timezone: string;
+}
+
+export function parseCron(input: string, tz: string = 'UTC'): CronResult {
+  const expr = CronExpressionParser.parse(input, { tz });
+  return { cron: input, next: expr.next().toDate(), timezone: tz };
+}
+```
+
+If the spec's signatures differ from the design doc, **the design doc wins** — file an issue rather than diverging silently.
+
+### Test fixtures
+
+Concrete input → expected output. Treat as the floor: add to them; don't shrink them.
+
+Format:
+
+```
+- Input: X → expected: Y
+- Input: edge case A → expected: B
+- Input: malformed payload → expected: ZodError citing the variant
+```
+
+Include happy path + at least one error path + at least one edge case.
+
+### Acceptance criteria
+
+Checklist that the audit phase verifies explicitly. Specific, not vague.
+
+Wrong: "Code works correctly"
+Right:
+
+```
+- [ ] Event union exports 8 variants (4 old + 4 new)
+- [ ] Each new variant has Zod schema + TS type via `z.infer`
+- [ ] Skill schema accepts `triggers:` block; default fills `[{kind: 'tool_call'}]`
+- [ ] `pnpm typecheck` exits zero
+- [ ] `pnpm vitest run src/runtime/types.test.ts` passes ≥ 5 new tests
+```
+
+### Risk callouts (optional but valuable for foundation/security tasks)
+
+Specific gotchas that have bitten or will bite. Each should be actionable.
+
+Wrong: "Be careful with concurrency"
+Right: "Discriminated unions in Zod require `z.literal(<value>)` on the discriminator — `z.string()` breaks narrowing silently."
+
+For foundation tasks (event unions, type definitions), security tasks (capability gates, auth), and performance-critical tasks (checkpointing, caching), always include 3–5 risk callouts. Cheap CLI wrappers and doc tasks can skip this field.
+
+### References
+
+URLs, file paths, memory entries. Anything the implementer should read.
+
+```
+- `src/runtime/types.ts` lines 52–84 — current Event union
+- `docs/opensquid-real-design.md` §"Event union"
+- Zod discriminated-union docs: https://zod.dev/?id=discriminated-unions
+- Memory: `feedback_user_authored_lessons_immune`
+```
+
+### Verification commands
+
+Bash commands the implementer runs to verify the task is done. Treat exit codes as gates; never proceed to commit on red.
+
+```bash
+cd /Users/slee/projects/opensquid
+pnpm typecheck
+pnpm vitest run src/runtime/types.test.ts
+pnpm build
+```
+
+CI invokes the same set — that's the contract.
+
+### 7-phase steps
+
+The non-negotiable structural lock. Every task lists all seven phases with concrete actions per phase, even if a phase is trivial.
+
+The seven phases:
+
+1. **pre-research** — read existing code, study docs, lock the approach BEFORE writing
+2. **learn** — synthesize what to build (the "spec output" of pre-research)
+3. **code** — write the implementation
+4. **test** — write + run tests
+5. **audit** — quality gates (file size, idioms, no fail-open, exhaustiveness)
+6. **post-research** — compare against external sources, competitor patterns
+7. **fix** — apply audit + post-research feedback
+
+Each phase entry is a SPECIFIC action, not a generic verb.
+
+Wrong (vague):
+
+```
+1. **pre-research:** Read the relevant code.
+2. **learn:** Figure out what to build.
+3. **code:** Implement it.
+```
+
+Right (specific):
+
+```
+1. **pre-research:** Re-read `src/runtime/types.ts` lines 52–84 (current Event union). Re-read `src/runtime/evaluator.ts` to enumerate every `switch (event.kind)` site. Read Zod discriminated-union docs.
+2. **learn:** Lock the new event variants' payload fields. Lock `triggers:` block default = `[{kind: 'tool_call'}]`.
+3. **code:** Add 4 z.object schemas + TS types. Extend Event union. Add `triggers:` block to skill schema. Update evaluator filter. Add TS exhaustiveness checks at every switch.
+```
+
+The audit phase is the one most often skipped under momentum pressure. **Never skip it** — retroactive audits have empirically surfaced 13+ critical findings on prior tracks. Specs that have a clear `audit:` action save downstream cycles.
+
+## Skills catalog extension
+
+If a task needs a persona-skill not in `skills-catalog.md`:
+
+1. Add an entry to the catalog in the appropriate category (Language/Architectural/Schema/Testing/MCP/Storage/Channels/Secrets/CLI/Cross-platform/Domain-specific/Automation/Durable/Security/Observability/Cost/Wedge/Performance)
+2. Format: `- **<Persona name>** — <one-line scope: library name, key concepts, gotchas>`
+3. Match the granularity of existing entries (library + concepts, not just library name)
+
+Example new entry:
+
+```markdown
+- **chokidar npm package expert** — `chokidar` file system watcher, `awaitWriteFinish`, polling fallback, FSEvents quirks, ignored globs
+```
+
+Adding to the catalog is part of the spec authoring task — don't ship task specs that reference catalog entries that don't exist.
+
+## File location + naming
+
+Specs live in:
+
+```
+/Users/slee/projects/loop/.claude/worktrees/<branch>/docs/tasks/<track>.md
+```
+
+Track file naming:
+
+- Phase files: `phase-<N>-<slug>.md` (e.g. `phase-1-runtime.md`)
+- Cross-cutting tracks: `cross-<area>.md` or just `<area>.md` (e.g. `cross-llm-call-modes.md`, `automation.md`, `scheduling.md`)
+- Specialty: `personal-pack.md`, `release.md`
+
+Task IDs:
+
+- Phase tasks: `<phase>.<index>` (e.g. `1.7`, `2.4`)
+- Cross-cutting: `<ABBREV>.<index>` (e.g. `AUTO.1`, `SCHED.3`, `UI.1`, `CLI.5`)
+- Keep IDs stable once shipped — don't renumber, even when inserting tasks
+
+## Track file structure (top of file)
+
+Every track file opens with a header block before any task entries:
+
+```markdown
+# <Track name>
+
+**Scope:** Per `docs/<design-doc>.md` §"<section>". One-paragraph description of what this track delivers + why it exists.
+**Relationship to phases:** Which phases/tracks this depends on. Which tasks are keystones.
+**Tasks:** N (<ID-low> through <ID-high>)
+**Specialist skills referenced:** see [`skills-catalog.md`](skills-catalog.md). New entries added in this track: <list any new persona-skills added>.
+**Cross-references:** [other-track.md](other-track.md) (why); [phase-X.md](phase-X.md) (why).
+
+---
+```
+
+Then the task entries follow, separated by `---` between tasks.
+
+## Worked example (compact)
+
+A task in the canonical form:
+
+````markdown
+### Task EXAMPLE.1: Add request ID propagation to MCP server
+
+**Required skills:** MCP SDK expert (@modelcontextprotocol/sdk npm package, TS); TypeScript ESM module design expert; Architectural design expert
+**Deliverable:** Every inbound MCP request generates or propagates a `requestId`; downstream logs + tool responses include it; round-trip test verifies propagation.
+**Depends on:** [Task 1.8](phase-1-runtime.md#task-18-mcp-server-entry--5-read-only-tools)
+
+**Files affected:**
+
+- `src/mcp/server.ts` (modify) — add request-id middleware
+- `src/mcp/request_id.ts` (new) — generation + extraction helpers
+- `src/mcp/request_id.test.ts` (new)
+
+**Key code shapes:**
+
+```typescript
+// src/mcp/request_id.ts
+import { randomUUID } from 'node:crypto';
+
+export function ensureRequestId(headers: Record<string, unknown>): string {
+  const existing = headers['x-request-id'];
+  if (typeof existing === 'string' && existing.length > 0) return existing;
+  return randomUUID();
+}
+```
+````
+
+**Test fixtures:**
+
+- Input: headers without `x-request-id` → returns generated UUID v4
+- Input: headers with `x-request-id: "abc-123"` → returns `"abc-123"` unchanged
+- Input: headers with empty string `x-request-id` → returns generated UUID
+
+**Acceptance criteria:**
+
+- [ ] `ensureRequestId` returns existing id if present, else generates
+- [ ] MCP server wraps every request with the id in context
+- [ ] Tool responses include `requestId` in metadata
+- [ ] `pnpm vitest run src/mcp/request_id.test.ts` passes ≥ 3 tests
+
+**Risk callouts:**
+
+- MCP SDK 1.29.0 middleware hook signature differs from 1.28 — verify against current version
+- Empty string id should fail the "existing" check, not propagate
+
+**References:**
+
+- MCP SDK middleware docs: https://github.com/modelcontextprotocol/typescript-sdk
+
+**Verification commands:**
+
+```bash
+pnpm typecheck
+pnpm vitest run src/mcp/request_id.test.ts
+```
+
+**7-phase steps:**
+
+1. **pre-research:** Read `src/mcp/server.ts` to find the middleware insertion point. Read MCP SDK 1.29.0 middleware docs to confirm signature.
+2. **learn:** Lock generation strategy (UUID v4 via node:crypto, no external dep).
+3. **code:** Implement `ensureRequestId` + middleware wrapper. Inject into server.ts.
+4. **test:** Three input fixtures. Run vitest.
+5. **audit:** Empty-string case handled. No PII in request ID. File size ≤ 80 LOC.
+6. **post-research:** Compare against gRPC's `x-correlation-id` conventions.
+7. **fix:** Tighten naming if conventions differ.
+
+```
+
+Note: this is a deliberately small task to show the format compactly. Real foundation/security/performance tasks should be denser in code shapes + risk callouts + 7-phase specificity.
+
+## Verification checklist before shipping a spec
+
+Before committing a new task or track file:
+
+- [ ] Every task has all 11 fields (risk callouts optional for thin tasks)
+- [ ] Every `Required skills` entry resolves in `skills-catalog.md` (or has been added)
+- [ ] Every `Depends on` reference is a valid task ID or working markdown link
+- [ ] Every `Files affected` row has new/modify + role
+- [ ] Every `Key code shapes` block is real code (not pseudocode)
+- [ ] Every 7-phase step is specific (names files, URLs, locks decisions)
+- [ ] Track file has the header block (Scope + Relationship + Tasks count + Skills reference + Cross-references)
+- [ ] README.md task-index updated with the new track + total task count
+- [ ] No engine-vocabulary leak in tasks that touch substrate-side code
+
+## Common pitfalls
+
+- **Generic skill assignments.** "TypeScript expert" doesn't tell a subagent which persona to embody. Specify library + concepts.
+- **Pseudocode in key code shapes.** The shapes are paste-and-adapt — pseudocode forces the subagent to redesign rather than implement.
+- **Skipping risk callouts on foundation tasks.** Saves 5 minutes now, costs 5 hours of rework later.
+- **Vague 7-phase steps.** "Read the docs" is worthless. "Read commander v12 docs at https://... — focus on subcommand action chaining" is actionable.
+- **Forgetting to extend skills-catalog.** Catalog entries are a dependency; task specs that reference missing entries fail to brief subagents.
+- **Letting task count drift.** README.md task index is the source of truth — every new task increments the total. Update both.
+- **Mixing scopes in one task.** If you find yourself writing "and also" in the deliverable, split into two tasks.
+- **Skipping the audit phase action.** The phase is non-negotiable; specify what audit gate applies (file size, no fail-open, exhaustiveness, license check, engine-vocabulary scan).
+
+## What makes a track keystone vs follower
+
+Foundation tasks (event unions, type definitions, schema migrations, security gates, perf-critical paths) carry the highest detail bar. Their downstream tasks depend on them; a bad design ripples.
+
+Follower tasks (thin CLI wrappers, doc regeneration, simple migrations) carry standard detail. Don't over-engineer them — but never skip the 11 fields entirely.
+
+The marginal value of detail is highest for keystone tasks and lowest for follower tasks. Spend authoring time accordingly.
+
+## Cross-cutting reminders (apply to every task)
+
+These come from the loop project's `docs/tasks/README.md` "Cross-cutting notes" section and should not be duplicated in each task block — but the spec author should verify the task respects them:
+
+- TaskCreate before logging the first phase
+- Log all seven phases (never skip audit)
+- File-size discipline (no monoliths)
+- Engine-vocabulary discipline (substrate types only in substrate code)
+- License discipline (no AGPL/GPL/SSPL)
+- Model-neutral architecture (LLM calls via aliases, no model names in source)
+- Auto-commit each verified slice (PATCH bump per slice)
+- No silent fail-open (validate at load, notify, pause)
+- User-authored lessons are eviction-immune
+- Pre-push checklist (typecheck + prettier + lint + test + build, in opensquid)
+- Verify CI after every push
+
+These are the cross-cutting contract a task ships into. The spec doesn't restate them — but if the task's design violates one (e.g. introduces silent fail-open, or names a model in source), surface it as a risk callout.
+
+## Output
+
+After authoring a track file or extending an existing one:
+
+1. Confirm the task IDs and count are stable
+2. List the new persona-skills added to skills-catalog.md (if any)
+3. Update `docs/tasks/README.md` task-index row + total count
+4. Commit as one logical slice (`docs: tasks/ — <track> spec authoring (N tasks)`)
+5. Report: how many tasks added, total now, which keystone tasks anchor downstream work
+
+If the user said "spec out X tasks" — author + commit. Don't ask "shall I commit?" — the auto-commit rule applies.
+```

package/packs/builtin/task-spec-author/manifest.yaml

@@ -0,0 +1,41 @@
+# task-spec-author — opensquid built-in PROFESSION pack wrapping the
+# task-spec-author format authority.
+#
+# The format authority itself lives at ~/.claude/skills/task-spec-author/
+# (Claude Code skill, 432 LOC SKILL.md + 114 LOC skills-catalog.md). This
+# pack provides the OPENSQUID-side handle: when scope-architect's chain-handoff
+# emits a directive with `next_action.profession: task-spec-author`, the agent
+# resolves the profession by reading this pack's `team.yaml` role + the
+# bundled SKILL.md format authority, then spawns a subagent applying both.
+#
+# Promoted per T-DISCIPLINE-PIPELINE-COMPLETION DPC.1 (2026-05-30). The CC
+# skill stays at its CC location for the format-authority + skills-catalog
+# discipline; this pack is the opensquid-side reference that makes the
+# profession addressable from chain-handoff directives.
+#
+# Ships in the npm package; opt-in via active.json:
+#
+#   { "packs": ["scope-architect", "task-spec-author"] }
+#
+# `evolves: false` — task-spec-author's format authority is locked content
+# (the 11-field template + 7-phase steps + persona-skills catalog), not a
+# wedge-gate-mutable rule set.
+name: task-spec-author
+version: 0.1.0
+scope: universal
+# GF.1 (F1) — a PROFESSION pack. Without this the manifest defaults to `usage: active`,
+# so `loadPack` skips its team.yaml and `resolveProfessionDirective` rejects the
+# coding-flow `handoff-research-to-spec` directive `wrong-usage` and drops it — the
+# SCOPE→AUTHOR handoff, the spine of the 3-stage flow, never fires. Mirrors
+# scope-architect/manifest.yaml `usage: both`.
+usage: profession
+goal: produce verified 11-field task specs from intent + pre-research
+description: |
+  Profession pack wrapping the task-spec-author format authority. Has no
+  `rules` of its own (validatePackFunctions is a no-op for profession packs;
+  the discipline lives in the bundled SKILL.md + skills-catalog.md format
+  reference). Loaded when chain-handoff-research-to-spec directive emits
+  `next_action.profession: task-spec-author` — the agent spawns a subagent
+  with this pack's team-role and the bundled SKILL.md as its system-prompt
+  addendum, runs the spec-authoring, returns the produced docs/tasks/T-*.md.
+evolves: false

package/packs/builtin/task-spec-author/skills-catalog.md

@@ -0,0 +1,115 @@
+# Skills catalog
+
+Persona-specific skills referenced by `docs/tasks/*.md` track specs in the loop planning repo. Each entry follows `library + concepts + gotchas` granularity — generic categories ("TypeScript expert", "Testing expert") are not acceptable; the persona must point at concrete libraries / domains the implementer must already know.
+
+Entries are categorized so spec authors can scan by area. When adding a new persona, drop it in the closest category — create a new category only when 2+ entries would land in it.
+
+---
+
+## Language / Module structure
+
+- **TypeScript ESM module design expert** — Node ESM (`type: "module"`), `.js` extension in import specifiers, top-level `await`, barrel re-exports, ESM ↔ CJS interop gotchas
+- **TypeScript discriminated union design expert** — `z.literal` discriminators, exhaustiveness via `never`, `as const` narrowing, no-fail-open at switches
+- **TypeScript compiler API expert** — `typescript` npm package, `ts.createSourceFile(name, text, ts.ScriptTarget.Latest, /*setParentNodes*/ true)`, `ts.forEachChild` recursive visitor, type guards (`ts.isCallExpression`, `ts.isPropertyAccessExpression`, `ts.isIdentifier`), `ts.SyntaxKind` enum, `SourceFile.getLineAndCharacterOfPosition(pos)` for human-readable positions (1-indexed line in display), JSDoc trivia stripped by default (the parser DOESN'T emit comment nodes — perfect for "real call site" detection), no need to add `typescript` as a runtime dep (it's already a devDependency in opensquid)
+- **Rust async expert (tokio)** — `tokio::spawn`, `tokio::net`, async traits, `Arc<Mutex>` vs message passing, cancellation safety, runtime feature flags
+- **Quarantine archaeology expert** — reading pre-reset code in `src.legacy/`, mapping symbols to current architecture, separating "still useful" from "obsolete", git-blame-driven recovery
+
+## Schema / Validation
+
+- **Zod schema design expert** — `zod` npm package, discriminated unions, `z.infer`, `.brand`, narrowing patterns, `safeParse` vs `parse`, error shape preservation
+- **JSON Schema / Ajv expert** — Draft 2020-12, `ajv` npm package, schema bundling, `$ref` resolution, custom keywords, oneOf vs anyOf vs allOf semantics
+- **YAML schema design expert** — `yaml` npm package, anchors + aliases pitfalls, bundled schemas, editor-friendly key ordering, forgiving validation patterns
+
+## Architecture / Audit
+
+- **Architectural design expert** — boundary discipline, substrate vs consumer separation, dependency direction, file-size enforcement, async vs sync surface choice
+- **Architectural-invariant test design expert** — production-grade enforcement of architectural decisions via test (single-caller invariants, layer-boundary invariants, "no caller in X may call Y" rules); the source-grep vs AST-walk trade-off (grep matches strings in JSDoc/comments — fragile; AST-walk parses the real call graph — ~100ms per file but robust); test placement convention (name the file after the invariant — e.g. `appendturn_sole_caller.test.ts` — not as a dumping-ground `architecture.test.ts`); INCLUDE-and-assert-location pattern (count == 1 AND location == expected) vs EXCLUDE-and-count (looser, passes at count==0); failure-message discipline (cite the offender file + line so triage is one-step + suggest the fix path); stale-FIXME-as-drift discipline (FIXMEs describing already-shipped work are documentation drift — recharacterize as architectural-contract JSDoc, don't delete the prose); the "JSDoc IS the architecture doc" principle — a separate architecture.md drifts; per-class JSDoc is the canonical statement
+- **Audit / code review expert** — fail-open detection, file-size discipline, idiom-check, no-`console.log`, no-`process.exit` outside CLI, license-grep, engine-vocabulary leak
+- **Two-stage validation gate design expert** — capture-stage user validation + promotion-stage outcome validation; eviction immunity invariants; block-only-testable patterns
+- **Tool-sequence FSM design expert** — Letta-style finite-state-machine over agent tool-call sequences ("after X tool, next tool must be Y or Z") adapted for opensquid via `session_tool_history` primitive + Stop-hook + exit-2 retry-loop pattern; heuristic-detection limitations (regex-only consumption check is imperfect — false-negatives slip drift through, false-positives cost a recovery turn); the ~1s visible-flash trade-off (Claude Code has no PreAssistantMessage hook, so Stop+exit-2 fires AFTER prose is emitted); plugin-vs-direct-install Stop hook split (GitHub issue #10412 — plugin Stop hooks halt, direct `.claude/hooks/` Stop hooks loop); when to pair with `destination_check` rule for LLM-judged consumption detection vs deterministic-heuristic-only
+- **Security capability model expert** — capability-grant patterns, denylist sealing, override env vars, audit log row shape, blast-radius reasoning, sandbox depth/step caps, proto-pollution defense via `Object.hasOwn`, allow-list discipline, fail-closed error paths
+- **Performance / overhead analysis expert** — hot-path branch cost, cold-start vs warm-path, allocation budgets, fs-read budgets per hook fire, microsecond-class budgets
+- **TypeScript exhaustiveness checking expert** — discriminated-union switches with `never` default, `as const` narrowing, no-fail-open at every switch, `assertNever(x: never): never` helper pattern
+- **Regression testing expert** — preserve every test in a contract suite, identify the single justified rewrite, audit-grep for orphan symbols, behavior-change documentation in CHANGELOG
+
+## Parser / Interpreter / DSL
+
+- **chevrotain npm package expert** — `chevrotain` v11 (pin against opensquid Node 20+), `createToken` token primitives, `Lexer`, `CstParser` LL(k) grammar DSL, perf-guide singleton-parser pattern, longest-match token ordering (multi-char operators first), `performSelfAnalysis()` lock against left-recursion, error recovery, `getBaseCstVisitorConstructor()` for CST→AST
+- **Tree-walking interpreter design expert** — AST node dispatch via discriminated union, scope binding via `Map<string, unknown>`, short-circuit evaluation for `&&`/`||`, sandbox primitives (depth-cap, step-cap, prototype-pollution defense via `Object.hasOwn`), error class hierarchy (`InterpreterLimitError` / `InterpreterRuntimeError`), strict vs loose equality semantics
+- **CST→AST visitor pattern expert** — chevrotain `BaseCstVisitor` subclassing, `validateVisitor()` lock against typo'd method names, position-preserving lowering (chevrotain token `startOffset` → AST `offset` field), left-fold associativity for `MANY`-produced rhs sequences, exhaustive node-kind dispatch
+- **TypeScript function allow-list design expert** — frozen `Record<string, FnHandler>` map via `Object.freeze`, no spread / no late mutation invariant, audit-grep for `FUNCTIONS\[` assignment, 5-point expansion checklist (cite-skill / pure / attack-surface / coercion-table / test-gate), JSDoc coercion tables
+- **ReDoS mitigation expert** — catastrophic backtracking patterns (`(a+)+$`-class), V8 RegExp engine pathologies, comparable-project landscape (Cerbos Go regexp, Cloudflare re2-wasm, OPA Rego), threat-model scoping by trust boundary (first-party vs third-party pack ecosystem), node `vm` module rejection (CVE-2023-29017 / VM2)
+- **re2-wasm npm package expert** — `re2-wasm` / `node-re2` / `re2js` package landscape + maintenance verification, `new RE2(pattern).test(s)` API, PCRE-subset that RE2 rejects (backreferences `\1`, lookarounds `(?=...)`/`(?<=...)`, possessive quantifiers `a++`), WASM cold-start (~50ms), bundle-size delta (~250KB)
+
+## MCP / Tool servers
+
+- **MCP SDK expert (`@modelcontextprotocol/sdk` npm package, TS)** — `Server` + `ListToolsRequestSchema` + `CallToolRequestSchema`, `StdioServerTransport`, version handshake, `zodToJsonSchema` integration, read-only-by-default tool design
+- **MCP write-tool design expert** — idempotency keys, side-effect surface (storage row inserts vs in-memory state), dispatcher-bypass auditing, harness re-prompt safety, capability gating on write tools
+- **JSON-RPC 2.0 over stdio expert** — line-delimited framing, request/response id pairing, error code conventions (-32700..-32603 reserved, -32000..-32099 custom), `id: null` notification edge cases
+- **loop-engine JSON-RPC client expert** — `EngineClient` wrapper from `src/engine/client.ts`, custom `ENGINE_ERROR` codes (-32000..-32004), `ManifestAssembleParams` side-effect quirks, LOOP_HOME pinning, stderr drain
+
+## Storage / RAG / Embeddings
+
+- **lru-cache npm package expert** — `lru-cache` v11 (already a dep in opensquid at `package.json:69`), `max` sizing, `get`/`set` API, `cache.size` property (not method) in v11, `cache.max` read-only, `clear()` for hot-reload paths, manual hit/miss counting (v11 doesn't expose counters by default)
+- **libsql migration expert** — `@libsql/client` npm package, schema migrations via `db.execute(...)` + version pragma, idempotent ingest (`INSERT OR IGNORE`, `UNIQUE` constraints), scope tagging, Turso remote URL vs local file URL
+- **Turso replication / cloud sync expert** — embedded replica + remote URL pattern, LWW per-row conflict policy, scope-keyed selective sync, replication interval tuning, opt-in config surface, sensitive-row exclusion
+- **Vector search / RRF expert** — Reciprocal Rank Fusion (RRF_K=60 industry default), hybrid semantic + text fusion, score normalization caveats, top-k vs candidate-set sizing
+- **Qwen3 embedder integration expert** — Qwen3-Embedding-4B via Ollama (`http://localhost:11434/api/embed`), 2560-dim vector shape, batch vs per-call cost, fallback-on-Ollama-down patterns
+- **HNSW persistence + cold-start expert** — `hnsw_rs` crate, rehydrate-on-start patterns, status-aware failure surface, `HNSW_MAX_ELEMENTS` caps, .vec sidecar discipline
+
+## Hooks / Harness integration
+
+- **Claude Code hooks expert** — `~/.claude/settings.json` hooks contract, `SessionStart`/`SessionEnd`/`Stop`/`PreToolUse`/`UserPromptSubmit` event shapes, stdin JSON payload, stderr-for-drift convention, exit-code semantics (0=allow, 2=block), `bin` entry vs inline `node` command, fail-open invariant
+- **System integration test / CI fixtures expert** — spawning bin entries with constructed stdin in CI, exit-code + stdout + stderr assertions, no-op detection via observable side effect, fixture stability across Node versions
+- **harness Monitor stream-source expert** — authoring a long-running command for the Claude Code `Monitor` tool (`persistent: true`): one stdout LINE = one in-chat event, events arrive on their own schedule (NOT user replies), child-side buffering is the #1 gotcha (a Node child `process.stdout.write(line + '\n')` per event flushes per call — no `stdbuf` needed, unlike piped C stdio), graceful run-forever (no exit), the session-scoped lifecycle limitation (dies at session end → agent re-starts at session start); contrast with cron/interval polling (`CronCreate`/`ScheduleWakeup`) which this explicitly replaces
+
+## CLI / UX
+
+- **commander v12 CLI argument parsing expert** — `commander` npm package v12, subcommand action chaining, `parseAsync`, `--help` output discipline, error exit codes
+- **CLI + UX expert** — clear `--help` strings, idempotent verbs, dry-run flags, `--yes` confirmation policy, TTY-vs-non-TTY behavior, exit-code conventions
+
+## Cross-platform / Lifecycle
+
+- **Unix domain socket singleton design expert** — `node:net` + `tokio::net::UnixListener`, path-byte limits (macOS 104, Linux 108), stale-socket cleanup, `proper-lockfile` serialization, `detached + stdio:'ignore'` patterns
+- **Subprocess lifecycle expert** — `node:child_process.spawn`, stderr drain, SIGTERM → SIGKILL escalation, pidfile patterns, detached daemon survival across parent exit
+- **opensquid hook-bin fast-path expert** — the four universal hook bins (`pre-tool-use.ts`, `user-prompt-submit.ts`, `stop.ts`, `session-end.ts`) at `src/runtime/hooks/`: their unconditional sequence (parse → side-effect writes → `loadActivePacks` → `buildRegistry` → `dispatchEvent`); where the idle-skip slot is (AFTER existing side effects to preserve observable behavior, BEFORE `loadActivePacks` to avoid the cost); the stat-based liveness probe pattern (cheap `fs.stat` on `automation.flag` + `active-task.json`); when to short-circuit vs always-run (state-transitioning tools like `TaskCreate`/`TaskUpdate` must NEVER skip dispatch since they may write the active-task signal); fail-open discipline at the fast-path boundary (stat-error of unknown kind → assume engaged, run the dispatcher — never silently swallow a gate by exiting early); shared regex constants kept in sync with personal-pack rules via a SUPERSET discipline (false-positive = cheap pack load; false-negative = missed gate)
+- **session-liveness probe expert** — answering "is this session-id plausible RIGHT NOW?" from filesystem evidence alone: stat-based freshness checks on session-state files (`<home>/sessions/<id>/active-task.json` and `state/tool-ledger.json`), mtime threshold semantics (default ~30min, env-configurable), `--force` escape hatch for first-fire-before-any-hook scenarios, fail-loud-not-silent when a CLI is about to write state to an implausible session-id (the cross-process-coordination failure mode behind silent-gate-disablement); contrast with active-task-presence checks (which answer "is a task loaded?", not "is the session itself alive?")
+- **cross-platform app-config path resolution expert** — locating per-host config files across macOS/Windows/Linux: macOS `~/Library/Application Support/<App>/`, Windows `%APPDATA%\<App>\`, Linux `~/.config/<App>/` (XDG); `process.platform` branching, `homedir()` + `env.APPDATA` fallbacks, `path.join` (never string concat); "app installed?" detection via parent-dir existence (create file only if dir exists, skip otherwise — don't fabricate an app's config tree)
+- **chokidar file-tail / append-stream expert** — `chokidar` npm package (already an opensquid dep, see `src/runtime/agent_bridge/transport_bridge.ts`): watching an append-only JSONL file that may not exist yet (fires `add` on creation, `change` on append), `{ ignoreInitial: true }` for new-only (the `tail -n 0 -F` equivalent — skip backlog), `awaitWriteFinish: { stabilityThreshold, pollInterval }` to coalesce partial-write events, byte-offset + leftover-buffer pattern for reading only appended bytes (stat size vs lastOffset; size < offset ⇒ truncation/rotation reset), partial-trailing-line carry across events; FSEvents quirks on macOS, polling fallback
+
+## Domain-specific (opensquid runtime)
+
+- **Pack / cartridge loader expert** — `src/cartridge/`, manifest.yaml schema, preload vs lazy load, scope hierarchy (user / project / skill / global / team)
+- **opensquid pack loader expert** — `src/packs/loader.ts` + `src/packs/yaml.ts` (`parseYamlFile` error formatter at lines 86-93), schema-failure surfacing with source path, load-time vs eval-time validation timing, Zod field-path threading
+- **opensquid pack-format expert** — `packs/builtin/` directory structure, `manifest.yaml` + `SKILL.md` + fixtures layout, `# Example — not load-bearing` header convention, BEFORE.md/SKILL.md/manifest.yaml triple-file pedagogical pattern
+- **Evaluator + rule process expert** — `src/runtime/evaluator.ts` unified rule + checkpoint + memo paths, `ProcessStep[]` interpreter, durable wrap + memo wrap order, no-eval policy, `verdict` primitive semantics
+- **opensquid runtime evaluator integration expert** — `src/runtime/evaluator.ts` unified rule + checkpoint + memo paths, `evalCondition` delegate boundary, header-docstring discipline, no-eval policy, regex-constant deletion targets (`EQ_PATTERN`/`BARE_PATTERN`/`NUM_CMP_PATTERN`/`BOOL_CMP_PATTERN`/`STR_PATH_EQ_PATTERN`)
+- **Recall-injection / context-pre-prepend expert** — `UserPromptSubmit` hook pattern, top-K recall selection, system-reminder framing, configurable per-codex thresholds, token-budget guards
+- **opensquid skill.yaml author expert** — authoring `skills/<name>/skill.yaml` against `schemas/skill.schema.json`: `track_check` vs `destination_check` rules, `ProcessStep` chains (`call`/`args`/`as`/`if`/`on_empty`), `when_to_load` triggers (`event_type` / `tool_match`), `if:` clause authoring against the frozen 5-function allow-list (`len`/`contains`/`startsWith`/`endsWith`/`match`), `parseExpression()` pre-write validation discipline, verdict-level selection (`pass`/`block`/`warn`/`surface`), copy-precedent from `workflow`/`git`/`d9-guard` skills, no-agent-loop constraint (skills emit verdicts, never orchestrate)
+- **opensquid chain-state machine expert** — the per-session chain state machine at `~/.opensquid/sessions/<id>/chain-state.json`: 7 stages (`idle → scoping → researched → spec_authored → tasks_loaded → phases_in_flight → phases_complete`), idempotent same-stage writes, append-only `history` audit trail, enrichment fields (`pre_research_path`, `spec_path`, `task_ids`) that accumulate across transitions, the writer-distribution pattern (5 transition points: UserPromptSubmit scope-intent, PreToolUse for research/spec/TaskCreate, log_phase MCP tool), session-scoped lifecycle (`SessionEnd` clears), session_state.ts-style helper pattern (`transitionChainStage` / `readChainState` / `readChainStage` / `clearChainState`), no-throw read posture (absent/malformed ⇒ null ⇒ caller defaults to `'idle'`); contrast with the active-task signal (single value, no history) — chain-state is a multi-stage progression with audit
+- **opensquid directive verdict / structured-protocol expert** — the `level: 'directive'` extension to the `Verdict` schema: `next_action: { skill?, tool?, args?, rationale }` shape (skill XOR tool, args is arbitrary JSON, rationale is mandatory and human-readable), the dispatcher aggregation pattern (mirrors `contextInjections: string[]` for `directives: Directive[]`), the UserPromptSubmit envelope serialization (`additionalContext` carries a fenced JSON block with a clear marker `⛔ DIRECTIVE` so the agent's reader surfaces it AND a future enforcer can parse it without re-parsing English), the no-agent-loop invariant (opensquid still does NOT invoke the named skill — it emits a structured recommendation; the agent dispatches), the coexistence semantics with `block` verdicts (block wins on exitCode 2; directives still ride through on stdout so the next-prompt context carries both); copies the `inject_context` aggregation precedent at `src/runtime/hooks/dispatch.ts:202-214` but with stronger typing
+- **opensquid dispatcher-boundary integration expert** — adding a new gate at the dispatcher's per-skill walk boundary (`src/runtime/hooks/dispatch.ts` between `matchesEvent(...)` and `for (const rule of skill.rules)`): per-fire caching of disk-derived state (one stat per session-scoped file across N skills' precondition evaluations — the cache key is `(sessionId, fire-id)`); fail-open in the engaged direction (ENOENT = absent, any other error = assume present, run the rules); the load-bearing distinction from rule-level `if: auto.value == true` guards (dispatcher-boundary is ONE eval per skill, rule-level is one eval per `process` step); AND-semantics for the new field (every entry must hold; an empty list trivially holds; back-compat with every existing skill); the migration arithmetic — hoisting a skill's leading `is_automation_mode` call into `requires:` saves both that primitive call AND every subsequent step's `if: auto.value == true` guard re-evaluation; integration with the existing trigger filter + `unloads_when` gates (the new boundary slots BETWEEN them); contrast with the hook-bin fast-path (bin-level, all-or-nothing; this is per-skill, declarative)
+- **opensquid agent-bridge daemon expert** — the WAB warm-agent-chat-bridge (`src/runtime/agent_bridge/`): `daemon.ts` (long-running process; PID lock `~/.opensquid/agent-bridge.lock`; per-project chokidar inbox watcher; api-mode lazily constructs the Anthropic SDK client, subscription-mode materializes `~/.opensquid/agent-bridge/mcp-config.json` + spawns Claude with subscription auth, NO ANTHROPIC_API_KEY/metered cost), `transport_bridge.ts` (inbox JSONL → typed events), `dispatcher.ts` (`ChatDispatcher.handleInbound` → batch/coalesce → `runAgentTurn` (api) | `runAgentTurnSubscription` (subscription) → `onReply`; `projectUuidBySlug` mapping), `agent_loop.ts` (`runAgentTurn` — full Anthropic Messages API turn, tool-use loop ≤8, prompt-cache, persisted history via `session_manager.ts`), CLI `agent-bridge {start|stop|status|restart|run-foreground}` (`resolveProjectUuidFromEnv` → cwd-walk); the daemon is autonomous + project-scoped — distinct from the harness-Monitor `chat watch` path which pushes into one live interactive session
+- **opensquid MCP setup-wizard / config-writer expert** — `src/setup/cli/mcp.ts` (`runMcpWizard` testable core; `--dry-run`/`--opensquid-root`/`--no-detect-project-cleanup` flags; injectable `McpCliDeps` for tests) + `src/setup/wizard/mcp-writer.ts` (`writeOpensquidMcp(configPath, repoRoot)` — PATH-generic, not Code-specific; `buildDesiredEntries(root)` = the two server entries → `dist/mcp/server.js` + `dist/mcp/chat-bridge-server.js`; `projectOpensquidMcp` merge that PRESERVES every non-`mcpServers` key via spread round-trip; `'@opensquid': true` marker for idempotent re-run + scoped upgrade; `.bak` snapshot before mutation); the writer works on ANY host config file with the `{mcpServers:{}}` shape (Claude Code `~/.claude.json`, Claude Desktop, Cursor) — host knowledge is just the path
+- **opensquid function primitive author expert** — authoring `src/functions/<name>.ts` primitives: `FunctionDef<TArgs,TResult>` shape (`name`/`argSchema` Zod `.strict()`/`durable`/`memoizable`/`costEstimateMs`/`execute`), `Result<T,FunctionError>` no-throw error model (`ok`/`err` from `../runtime/result.js`), `EvalCtx` access (`event`/`event.cwd`/`bindings`/`sessionId`), read-only vs side-effecting discipline, registration in `buildRegistry()` (`src/runtime/bootstrap.ts`), distinction from the frozen `if:` 5-function allow-list (primitives are `call:`-able, NOT `if:` functions)
+- **opensquid active-task lifecycle expert** — the `active-task.json` signal (`~/.opensquid/sessions/<id>/active-task.json` = `{id,subject,started_at}` | absent) per the unified-evaluator design: written on TaskCreate/TaskUpdate(in_progress), cleared on completed, archived at SessionEnd (rule #16); the harness-TaskCreate vs `mcp__opensquid__TaskCreate` distinction (opensquid must write its own signal); the d9-guard.sh anti-pattern (reading tasks from Stop stdin, which CC doesn't populate); the gate-reads-it / writer-writes-it coupling that the G-track severed; fail-closed-not-open on a missing/malformed signal
+- **loop-engine RPC handler author expert (Rust)** — adding a JSON-RPC method to `engine/src/serve.rs`: the `match method { "memory.create" => … }` dispatch arm pattern, `#[derive(Deserialize)]` param structs, `DispatchError::InvalidParams`, threading the dispatch context deps (`storage`/`llm`/`embedder`/`vector_index`), wrapping an existing `engine::memory::*` library fn (NOT reimplementing), `serde_json::json!` result shaping; the engine pre-push gate (fmt + clippy -D warnings + public-api snapshot + nightly + test) — a new public RPC shifts the public-api snapshot, update deliberately; engine-vocabulary discipline (substrate types only, no consumer concepts)
+- **memory-compression lifecycle expert** — `engine/src/engine/memory/{compress,lifecycle,cycle,store}.rs`: `compress(window, config) -> Mc` (detail→gist LLM summary), `derived_from` predecessor chains + `mem-c-<hex>` ids, citation transfer (`consumed_by_user_lessons = Σ predecessors`), `recompute_citation_counts` / `get_by_id_chasing_derived_from` (citations survive predecessor deletion), cycle/depth guards (max 16), recursive compression; the append-only + user-immunity invariant (`delete(force)` refuses engine-initiated deletes of user-cited memories); the LOCKED policy (D2) — predecessor deletion is the verified, satisfaction-gated, immunity-safe TERMINAL step, never automatic; recall-replay as the compression-quality gate
+- **opensquid skill-lifecycle expert** — the skill load/unload machinery: `unloads_when` (skill field, `types.ts`), `tick.ts` (`createTick`/`advanceTick`/`resetTick` — `prompt_submit` bumps `turnsSinceActivation`, `stop`/`session_end` latch `taskCompleted`/`sessionEnded`, `tool_call` no-op), `unload_conditions.ts` (`shouldUnload` OR-walk over `UnloadCondition` = `active_task_completes`|`session_ends`|`idle_n_turns:n`; `TickState` shape), `pinned_skills.ts` (universal+preload = pinned/resident, exempt from unload; dynamic = unloadable); the "Phase 4 wiring" gap (machinery has ZERO live call sites — `shouldUnload`/`advanceTick` never called by the dispatcher); per-PROCESS persistence requirement (hooks are separate processes, so tick state lives in `session_state.ts` like the tool-ledger, NOT an in-memory Map); the recall-load side (`recall_pre_inject.ts`) is SEPARATE + out of scope (per-turn-fresh `additionalContext`, harness-owned window — not accumulated)
+- **LLM-classifier integration expert** — `llm_classify` primitive (`src/functions/llm.ts`): args `{model(alias), prompt, allowed_labels, timeout_ms?}`, returns one label or `'UNCERTAIN'`, `durable+memoizable` `costEstimateMs:3000`; model-neutral alias resolution (`fast_classifier`, never literal model names); cheap-first composition (gate the LLM step behind a deterministic `if:` so it only fires on a pre-filter hit — zero per-turn cost); fail-quiet on `UNCERTAIN`; the regex-pre-filter → `llm_classify` → `verdict` single-rule pattern (d9-guard / pause-prompt-extended precedent)
+
+## Migration / Cleanup
+
+- **Auto-memory migration expert** — `~/.claude/projects/<slug>/memory/*.md` reader, frontmatter extraction, idempotent ingest via stable external_id, scope mapping (`scope=user` default), dry-run + diff surfaces
+- **Quarantine cleanup expert** — safe deletion of unimported code, import-graph traversal (`tsc --noEmit` + `eslint-plugin-import` unused detection), `git rm` discipline, per-file commit rationale, rollback safety via single-commit chunks
+
+## Documentation / Pedagogy
+
+- **Technical writing expert (developer docs)** — reference-doc structure (operator tables, function tables, gotchas), runnable code samples (extract + verify via parser), cross-link discipline, tone matched to comparable projects (Cerbos conditions, OPA Rego, GitHub Actions expressions), keep-a-changelog CHANGELOG conventions
+- **Pedagogical example design expert** — before/after compression demos (BEFORE.md prose vs YAML compressed form), real-vs-toy scenario selection, fixture/expected-output pairing in `fixtures/` subdirs, operator-family variety across examples (logical / regex / indexing), `# Example — not load-bearing` header to prevent calcification
+
+## Cross-cutting (every track touches these)
+
+- **Engine-vocabulary discipline expert** — substrate types stay at substrate boundary, no `Authorship` / `BlockReason` / `PromotionConfig` leak into user-facing strings or MCP descriptions
+- **Pre-push checklist expert** — opensquid: typecheck + lint + format:check + test + build; engine: fmt + clippy + public-api +nightly + test; gate enforcement before commit
+- **Testing + build expert** — `vitest`, fixture discipline, skip-if-no-binary patterns for live integration, `pnpm build` clean, no leaked test artifacts