Small strengthenings of research subagents

.claude-plugin/marketplace.json

@@ -105,6 +105,13 @@
       "description": "Hierarchical microstructure knowledge base for trading venues: exchange mechanics, order books, auctions, Reg NMS, Chinese futures (CTP), feed handlers, execution models",
       "source": "./venue-expert",
       "skills": ["./"]
+    },
+    {
+      "name": "agentic-tdd",
+      "description": "Phase-based resumable agentic TDD loop (PLAN → LOOP → ASSESS → RELEASE) with a deterministic gate engine, protected test evidence, fresh-context falsification, and optional external challenges",
+      "source": "./agentic-tdd",
+      "skills": ["./"],
+      "commands": ["./commands/"]
     }
   ]
 }

.gitignore

@@ -1,2 +1,6 @@
 .claude/
 .tmp/
+.DS_Store
+.obsidian/
+/research/
+.tdd/

CLAUDE.md

@@ -70,6 +70,11 @@ Use the **venue-expert** skill for exchange-specific context. Invoke it when:
 - Debugging trading system issues (feed, order, session problems)
 - Needing venue mechanics: order types, matching rules, session times, data formats, regulatory quirks
 
+## Research Integrity
+
+- **Approval ≠ truth**: user approval sets objectives, budget, risk tolerance. It never upgrades the confidence of a factual claim — evidence does.
+- **Anti-ritual**: any "always X" default (Data Sentinel first, Double ML, fixed thresholds) may be skipped with a stated reason. Method follows the decision context: literature questions have no dataset; descriptive work needs no causal estimator.
+
 ## Testing
 - Tests will be specified when needed
 - Don't assume - ask if testing is required

README.md

@@ -283,6 +283,31 @@ arxiv_search "protein folding" --max-papers 5
 /plugin install arxiv-search@deevs-agent-system
 ```
 
+### agentic-tdd
+
+Phase-based, resumable agentic TDD workflow: `PLAN → LOOP → ASSESS → RELEASE`.
+
+**Core**: A zero-dependency gate engine (`core/scripts/tdd-engine.mjs`) validates every state transition, artifact hash, budget, and protected test file; the orchestrator spawns fresh-context role subagents (architect, logic-hunter, developer, tester-qa, release-reviewer, external-challenger) whose reports are schema-shaped, never prose-driven. Workflow state lives in the target repo under gitignored `.tdd/<feature>/` and is resumable from files alone.
+
+**Quick start**:
+```bash
+/tdd plan my-feature      # intake, contract, oracle, risks, frozen plan
+/tdd loop my-feature      # protected tests locked, then implementation
+/tdd assess my-feature    # fresh-context falsification on the exact candidate commit
+/tdd release my-feature   # mandatory fresh-context release reviewer
+/tdd status my-feature
+```
+
+**Use when**: correctness-critical features that justify contract-first TDD with protected evidence — especially stateful, concurrent, numerical, or latency-sensitive changes (`cpp-hft` profile).
+
+**Dependencies**: node >= 22, git. Canonical `core/` source lives in `deevs-pi-kit/skills/agentic-tdd/core/`; this copy is a byte-identical mirror.
+
+**Details**: [agentic-tdd/SKILL.md](agentic-tdd/SKILL.md)
+
+```bash
+/plugin install agentic-tdd@deevs-agent-system
+```
+
 ## Agent Color Scheme
 
 Universal color scheme across all agent plugins:

agentic-tdd/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: agentic-tdd
+description: Phase-based resumable agentic TDD loop (PLAN → LOOP → ASSESS → RELEASE) with protected test evidence, deterministic engine gates, fresh-context falsification, and optional external challenges. Use when the user asks for a tdd loop, agentic tdd, /tdd, protected tests, or to plan/implement/assess/release a feature under the TDD workflow.
+---
+
+# Agentic TDD (Claude Code shim)
+
+The runtime-agnostic workflow lives in `core/`. Read `core/ORCHESTRATOR.md` first and
+follow it; this shim only binds it to the Claude Code runtime.
+
+## Runtime bindings
+
+- **Engine**: `node <this-skill-dir>/core/scripts/tdd-engine.mjs <cmd> <feature> --root <target repo>`
+  via Bash (requires node >= 22 on PATH). Treat only its typed JSON output as
+  authoritative.
+- **Roles**: launch packets with the Agent tool (general-purpose, or a matching
+  specialist agent when available). Critique, tester-qa acceptance authoring, assess,
+  release-review, and challenge runs always start as fresh agents — never reuse the
+  implementing context to judge its own work. Apply `options.models.<step>` via the
+  Agent tool's model parameter. Launch independent perspectives in one message so they
+  run in parallel.
+- **Recurrence**: the main session drives the state machine — after each phase completes,
+  read `engine status` and dispatch the next phase until `CLOSED`, a `WAITING_FOR_USER_*`
+  state, or `BUDGET_EXHAUSTED`. Resume in a fresh session from `engine status` alone.
+
+## Boundaries
+
+- Never bypass the engine to edit `manifest.json` or protection state by hand.
+- Verdicts, transitions, and blockers come from engine enums and structured role
+  reports, never from prose.
+- This directory's `core/` is a byte-identical mirror; canonical source is
+  `deevs-pi-kit/skills/agentic-tdd/core/`. Edit there and copy.

agentic-tdd/commands/tdd.md

@@ -0,0 +1,19 @@
+---
+description: Drive the agentic TDD workflow (plan | loop | assess | release | challenge | status) for a feature
+argument-hint: <plan|loop|assess|release|challenge|status> <feature> [--resume | --from-finding ID | --amend ID]
+---
+
+Drive the agentic-tdd skill for: $ARGUMENTS
+
+1. Load the `agentic-tdd` skill and read its `core/ORCHESTRATOR.md`.
+2. Run `node <skill-dir>/core/scripts/tdd-engine.mjs status <feature> --root <repo>`.
+   If the feature is not initialized and the subcommand is `plan`, follow the
+   initialization protocol (ask the USER the batched init questions first).
+3. Validate that the requested subcommand matches an allowed transition from the current
+   engine state; if not, report the typed state and the legal next steps instead of
+   forcing it.
+4. Execute the matching phase file (`core/phases/`), honoring `--resume`,
+   `--from-finding`, and `--amend` by re-entering the owning phase with the referenced
+   finding attached.
+5. For `status`: print the engine status plus open questions, budgets, and the next
+   required command. Never mutate state from a status call.

agentic-tdd/core/ORCHESTRATOR.md

@@ -0,0 +1,137 @@
+# Agentic TDD Orchestrator
+
+You are the coordinator of a phase-based, resumable, artifact-driven TDD workflow:
+`PLAN → LOOP → ASSESS → RELEASE`, with optional external challenges after PLAN/LOOP/ASSESS.
+You preserve process integrity and advance the state machine. You never author the
+protected evidence that judges implementation work.
+
+All state lives in `.tdd/<feature>/` in the target repository (gitignored). Resume from
+files, never from conversation memory. The engine is the sole authority for state,
+transitions, hashes, budgets, and protection:
+
+```text
+ENGINE = <skill-dir>/core/scripts/tdd-engine.mjs
+node "$ENGINE" <command> <feature> [args] --root <target-repo>
+```
+
+| Command | Purpose |
+|---|---|
+| `init <feature> [--depth auto\|light\|full] [--domains cpp-hft] [--protection auto\|flags\|chmod\|none] [--challenges plan,loop,assess] [--test-command CMD] [--allow-dirty]` | scaffold `.tdd/<feature>/`, bind baseline commit |
+| `status <feature>` | typed state, allowed transitions, budgets, open questions, required checks |
+| `transition <feature> <STATE> [--result FILE]` | validated state change; every phase-exit edge accepts only its bound result phase+status, and `verify` runs inside |
+| `set-depth <feature> light\|full [--evidence NOTE]` | PLAN records the routing decision (PLANNING only) |
+| `freeze <feature> <phase> --files a,b,c` | hash-freeze phase artifacts (allowed only in the owning phase state) |
+| `protect <feature> <paths...>` / `unprotect <feature>` | lock/release protected files; unprotect only in CLOSED / RELEASE_BLOCKED |
+| `verify <feature>` | hashes, protected files, candidate tree; exit 2 on drift |
+| `run-check <feature> <check-id> [--cwd DIR] -- <argv...>` | engine-executed evidence: exit code, output hashes, bound to the candidate tree |
+| `assess-worktree <feature> [--remove]` | detached clean worktree at the exact candidate snapshot |
+| `challenge <prepare\|ingest\|dispose\|skip> <feature> <phase> [--response\|--file\|--reason]` | external-challenge lifecycle; gates block on pending challenges |
+| `question <open\|answer\|waive> <feature> ...` | typed user questions; blocking ones freeze checkpoints |
+| `review ingest <feature> --report FILE` | release reviewer report, bound to the candidate tree |
+| `waiver authorize <feature> --file FILE` | user-authorized waiver with future expiry |
+| `budget <feature> <counter>` / `grant <feature> <counter> --authorized-by WHO [--n N]` | consume / user-granted headroom |
+| `run <begin\|publish> <feature> <phase> [run-id]` | transactional `.partial` run directories |
+| `unlock <feature> [--stale\|--force]` | recover a crashed writer's lock |
+| `event <feature> <type> [--data JSON]` | append to the audit log |
+
+Every decision you make consumes typed engine output (states, codes, statuses) — never
+infer success from prose or file existence. Transitions self-verify: a tampered or
+drifted evidence chain fails the transition, not just the report. Phase artifacts and
+result files belong under `.tdd/<feature>/` (gitignored) — files written elsewhere become
+part of the candidate tree and will register as drift.
+
+## Candidate identity
+
+Reaching `CANDIDATE_READY` snapshots the exact worktree (tracked + untracked,
+`.gitignore` respected) into an engine-owned ref — no user-visible commit is created.
+All downstream evidence binds to that `candidate_tree`; any later change to the worktree
+fails `verify` until the state machine routes back through LOOP. Assessment SHOULD run
+in `assess-worktree` so leftover developer state cannot leak into evidence.
+
+## Initialization protocol
+
+Before `init`, investigate the repository, then ask the USER once, batched:
+
+1. **Optional steps**: which external challenges to enable (plan/loop/assess), and —
+   for full depth — mutation testing, fuzzing, performance protocol where relevant.
+   Challenges can also be invoked ad hoc at any boundary later.
+2. **Domains**: `--domains cpp-hft` loads `references/verification-matrix-cpp.md` and
+   adds sanitizer check obligations.
+3. **Models**: preferred model per optional/verification step, if the runtime supports
+   per-run model selection. Record in `options.models` (e.g. `{"challenge": "...", "assess": "..."}`)
+   and apply when spawning; note a deviation if the runtime cannot honor it.
+4. **Protection mode** if the default (`auto`) is unsuitable — immutable flags need root
+   on Linux; `chmod` is the portable fallback; hashes are always verified regardless.
+5. **Dirty worktree / test command** only if detection failed or the tree is dirty.
+
+Do NOT ask for light/full — depth starts `auto` and PLAN's intake determines it with
+evidence (`set-depth`), asking the USER only when routing needs an authority decision.
+
+## Phase dispatch
+
+Read the phase file for the current state, execute it, then transition:
+
+| State | File |
+|---|---|
+| NEW, PLANNING, PLAN_READY, WAITING_FOR_USER_PLAN | `phases/10-plan.md` |
+| PLAN_APPROVED, LOOP_RUNNING, BLOCKED_*, CANDIDATE_READY | `phases/20-loop.md` |
+| ASSESSING, CHANGES_REQUIRED, ASSESSMENT_READY, WAITING_FOR_USER_ASSESS | `phases/30-assess.md` |
+| ASSESSMENT_ACCEPTED, RELEASING, WAITING_FOR_USER_RELEASE, RELEASE_BLOCKED, CLOSED | `phases/40-release.md` |
+| any enabled challenge gate | `phases/90-external-challenge.md` |
+
+`BUDGET_EXHAUSTED` is an explicit stop: report which counter died and ask the USER for a
+grant or a route; never quietly continue.
+
+## Subagent packets
+
+Roles run as fresh-context subagents. A packet contains, in this order:
+
+1. the role card from `roles/` (verbatim);
+2. the frozen artifacts the role may read (paths, not transcripts);
+3. the concrete task and required output template from `templates/`;
+4. scope bounds: exact files/dirs, what not to inspect, bounded output.
+
+Rules:
+- Implementation (developer role) never sees or edits protected files; `protect` runs
+  before LOOP starts, on QA's acceptance tests **and** test-runner configs.
+- ASSESS and RELEASE roles start fresh and initially read-only; they receive frozen
+  artifacts and diffs, never the implementation transcript or confidence claims.
+- Independent critiques launch in parallel **before** implementation spend (cheap
+  falsification first, expensive compute second).
+- A candidate that survives repair is re-verified on the exact candidate commit — the
+  engine rejects stale assessments.
+
+## Evidence rules
+
+Priority: reproducible failing check > authoritative spec > frozen contract + validated
+oracle > production trace > exact code-path argument > model judgment > model consensus.
+Critical/major findings require a minimal counterexample or a discriminating check
+(`templates/finding.json`); otherwise they are non-blocking hypotheses.
+
+Deterministic verification runs through `run-check`, never as self-reported prose: the
+engine records exit codes and output hashes bound to the candidate tree, and the
+`ASSESSMENT_READY` gate requires passing bound records for every profile-required check
+id. Assessors interpret this evidence; they cannot manufacture it. Tests proposed during
+ASSESS are staged under `.tdd/<feature>/assess/<run>/proposed-tests/` and applied in the
+next LOOP round — the candidate tree stays immutable while it is being judged.
+
+## User authority
+
+Investigate repository evidence before asking. Batch questions with options,
+consequences, and a recommendation (`templates/question.json`), registered via
+`question open` — blocking classes freeze every checkpoint transition until
+`question answer` or `question waive` records the USER's decision. Budget grants and
+waivers likewise exist only as engine records with an `authorized-by`. Never ask the
+USER to resolve ordinary technical questions answerable from the repository.
+
+## Memory
+
+At PLAN start, read `.tdd/memory.jsonl` (if present) and surface relevant observations.
+At CLOSED, append 1–2 tagged observations: defect classes found, which control caught
+them, which control was dead weight. One JSON object per line:
+`{"ts": "...", "feature": "...", "tag": "...", "observation": "..."}`.
+
+## Git policy
+
+Follow `references/git-policy.md`. Never commit or push without explicit USER approval;
+commit only functional code changes — never `.tdd/`, plans, scratch files, or `git add -A`.

agentic-tdd/core/phases/10-plan.md

@@ -0,0 +1,63 @@
+# Phase: PLAN
+
+Define what correct behavior means, how the change fits the repository, how it will be
+falsified, and whether LIGHT or FULL depth is justified.
+
+## Enter
+
+`transition <feature> PLANNING`. Read `.tdd/memory.jsonl` and prior `decisions/` if present.
+
+## Steps
+
+1. **Engineering intake** — localize affected components and downstream consumers;
+   identify state ownership, temporal assumptions, concurrency, and hot-path impact;
+   find precedents, existing tests, oracles, and benchmark infrastructure. Determine
+   depth with evidence and record it: `engine set-depth <feature> light|full --evidence "..."`
+   (any high-risk dimension routes full: new domain semantics, statefulness, concurrency,
+   missing oracle, irreversibility, hot path, uncertain blast radius, weak production
+   detection). Ask the USER only when routing needs an authority decision. Write
+   `plan/vNNN/intake.json`.
+2. **Role briefs** — spawn fresh-context critiques in parallel (architect, logic-hunter,
+   tester-qa packets from `roles/`), full mode or where risk warrants. Architect: design,
+   seams, dependencies, rollout. Logic-hunter: contract (P, Q, invariants, violation
+   policy, tolerances), oracle candidates with provenance. Tester-qa: partitions,
+   adversarial cases, testability objections.
+3. **User-question gate** — after evidence gathering, batch blocking domain/policy
+   questions (`templates/question.json`) and register each via
+   `engine question open <feature> --file q.json`. Record answers with
+   `engine question answer <feature> <id> "<decision>"`. If any `BLOCKING_*` remains
+   unanswered: `transition WAITING_FOR_USER_PLAN` and stop — the engine refuses
+   `PLAN_READY` while blocking questions are open.
+4. **Synthesis and critique** — developer critiques feasibility and test seams;
+   tester-qa checks falsifiability; logic-hunter checks semantic coverage and oracle
+   domain; architect checks composition and downstream effects.
+5. **Gate** — `engine run begin <feature> plan` gives a transactional `vNNN.partial`
+   directory; write `plan.md`, `architecture.md`, `contract.json` (stable clause IDs),
+   `oracle.json` (provenance, independence, domain, exclusions), `risks.json`,
+   `test-plan.md`, `performance-plan.json` (hot path only), `result.json`; then
+   `engine run publish <feature> plan vNNN`.
+
+## Exit requirements
+
+Affected components enumerated with evidence; contract explicit (P/Q/invariants/violation
+policy/tolerances); oracle provenance recorded — for high-risk logic, two independent
+evidence sources; risks mapped to planned controls; QA has a path to discriminating
+tests; developer confirms seams are implementable; no blocking question open.
+
+Then:
+
+```text
+engine freeze <feature> plan --files .tdd/<feature>/plan/vNNN/contract.json,.tdd/<feature>/plan/vNNN/oracle.json,...
+engine transition <feature> PLAN_READY --result .tdd/<feature>/plan/vNNN/result.json
+```
+
+If `options.challenges.plan`: run `phases/90-external-challenge.md`, then
+`transition PLAN_APPROVED`. Otherwise `transition PLAN_APPROVED` directly (record the
+challenge as `not_invoked`).
+
+## Revision
+
+Amendments consume `budget <feature> planning_revisions` and produce a new
+`plan/vNNN`; downstream evidence bound to older versions is invalid. Statuses:
+`PLAN_READY | WAITING_FOR_USER | NEEDS_REPOSITORY_EVIDENCE | NEEDS_HUMAN_DOMAIN_INPUT |
+ESCALATE_FULL | BUDGET_EXHAUSTED`.