@curdx/flow 3.0.0 → 3.1.0

package/knowledge/atomic-commits.md

@@ -1,262 +0,0 @@
-# Atomic Commits — Atomic Commit Rules
-
-> One task, one commit. This is the iron rule for all execution agents in CurdX-Flow.
->
-> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/atomic-commits.md`.
-
----
-
-## Core Principle
-
-**One task = one commit = one rollback unit.**
-
-Why:
-- `git bisect` can pinpoint a problem to a specific task
-- `git revert <hash>` can undo a single task in isolation
-- PR review can walk through changes commit-by-commit
-- Downstream agents can trace "which AD / FR this change came from" via commit history
-
----
-
-## Commit Message Format (Conventional Commits + CurdX-Flow extensions)
-
-```
-<type>(<scope>): <summary>
-
-[body - explain why, not what]
-
-[footer - reference IDs]
-```
-
-### Type (required)
-
-| Type | Purpose | Example |
-|------|---------|---------|
-| `feat` | New feature | `feat(auth): add JWT refresh endpoint` |
-| `fix` | Bug fix | `fix(login): handle empty email case` |
-| `refactor` | Refactor (behavior unchanged) | `refactor(db): extract connection pool` |
-| `test` | Tests | `test(auth): red - add login validation tests` |
-| `docs` | Documentation | `docs(readme): add install instructions` |
-| `chore` | Misc (deps, config) | `chore(deps): upgrade bcrypt to 5.1.0` |
-| `perf` | Performance | `perf(query): cache user lookups` |
-| `style` | Formatting (no behavior change) | `style: fix indentation in auth module` |
-| `build` | Build config | `build(tsconfig): enable strict mode` |
-| `ci` | CI config | `ci(github): add test workflow` |
-
-### TDD phase markers (used in Phase 3)
-
-| Phase | Type + suffix | Example |
-|-------|--------------|---------|
-| RED | `test(scope): red - ...` | `test(auth): red - login validation` |
-| GREEN | `feat(scope): green - ...` | `feat(auth): green - satisfy login test` |
-| YELLOW | `refactor(scope): yellow - ...` | `refactor(auth): yellow - extract validator` |
-
-### Scope
-
-- Module name (`auth`, `db`, `ui`, `api`)
-- Or file name (without extension)
-- Or `(spec-name)` if spanning multiple modules
-
-### Summary
-
-- Imperative mood (`add`, `fix`, not `added`, `fixes`)
-- Lowercase start (unless a proper noun)
-- No trailing period
-- ≤ 70 characters
-
----
-
-## Body (optional but recommended)
-
-Explain **why**. Do not explain **what** (the diff shows what).
-
-```
-feat(auth): implement JWT refresh flow
-
-Tokens expire after 15 minutes. Without refresh, users get
-logged out mid-session. This adds a refresh endpoint that
-validates the refresh_token and issues a new access_token.
-
-Per AD-03: use rotating refresh tokens to mitigate theft.
-```
-
-Do NOT write:
-```
-feat(auth): implement JWT refresh flow
-
-Added refreshToken() function in auth.ts.
-Added POST /auth/refresh endpoint.
-Added tests for success and failure cases.
-```
-← the diff already shows this; it wastes commit message space.
-
----
-
-## Footer (reference IDs)
-
-CurdX-Flow extension: if a task references FR / AC / AD / D-NN, list them in the footer:
-
-```
-feat(auth): implement JWT refresh flow
-
-Refresh tokens rotate on each use, preventing replay attacks.
-
-Requirements: FR-03, AC-2.1
-Design: AD-03
-Decisions: D-07 (session storage strategy)
-Task: spec/auth-system/tasks.md#3.2
-```
-
-Fields:
-- `Requirements:` lists implemented FR / AC
-- `Design:` lists related AD
-- `Decisions:` lists referenced project-level decisions (D-NN)
-- `Task:` optional, points at the task definition location
-
----
-
-## Concrete Rules for Atomicity
-
-### 1. One commit does one thing
-
-✗ **Bad**:
-```
-feat: add login + fix typo + refactor db connection
-```
-
-✓ **Good** (split into 3 commits):
-```
-feat(auth): add login endpoint
-docs: fix typo in README
-refactor(db): extract connection factory
-```
-
-### 2. Do not mix "task code" and "cleanup"
-
-✗ **Bad**:
-```
-feat(auth): add JWT + remove unused imports in user.ts
-```
-
-✓ **Good**:
-```
-feat(auth): add JWT endpoint
-chore: remove unused imports in user.ts
-```
-
-### 3. Every commit must pass tests independently
-
-This is what makes `git bisect` work.
-
-- Do not commit "broken intermediate states"
-- Even WIP should build + test (even with few tests)
-- For a large change that truly must be split, use a feature branch and squash at the end
-
-### 4. The file change scope should match the commit message
-
-If the commit is `feat(auth): ...`, it should not include changes under `src/ui/`. Otherwise you actually did two things.
-
----
-
-## The flow-executor Agent's Commit Flow
-
-```bash
-# Step 1: git add only the files involved in the task
-git add src/auth/login.ts src/auth/login.test.ts
-
-# Step 2: check that staged diff matches the commit message
-git diff --cached --stat
-
-# Step 3: ensure no unexpected changes sneaked in
-# (if you see a file that shouldn't be there, git reset HEAD <file>)
-
-# Step 4: commit
-git commit -m "feat(auth): green - implement login endpoint
-
-Per AD-03, uses bcrypt for password hashing.
-
-Requirements: FR-01
-Design: AD-03
-"
-
-# Step 5: record the hash
-COMMIT_HASH=$(git rev-parse --short HEAD)
-echo "✓ Committed: $COMMIT_HASH"
-```
-
----
-
-## Forbidden Patterns
-
-### ✗ Giant commit
-```
-feat(auth): implement entire authentication system
-```
-Too large, cannot review, cannot bisect. Split into N small commits.
-
-### ✗ Hedging words
-```
-feat(auth): maybe fix login issue?
-```
-If unsure, do not commit yet. A commit is a definitive operation.
-
-### ✗ Meaningless commits
-```
-wip
-fix
-update
-```
-Future maintainers will curse you. At minimum write `wip(auth): placeholder for token refresh`.
-
-### ✗ `--amend` on a pushed commit
-```
-git commit --amend  # after push
-git push -f         # overwrite remote
-```
-Destroys shared history. Only amend local, unpushed commits.
-
-### ✗ Skipping hooks
-```
-git commit --no-verify
-```
-Unless the user explicitly requests it. Hooks exist for reasons (pre-commit lint, commit-msg check).
-
----
-
-## Relationship to PR Review
-
-PR review reads each commit's message.
-
-- Good commit message → reviewer finishes in 5 minutes
-- Bad commit message → reviewer either rubber-stamps or blocks without reading
-
-CurdX-Flow's review handoff expects atomic commits plus verification/review reports. Poor commit quality yields poor PR descriptions and weak release evidence.
-
----
-
-## Real Example (commit history for a full spec execution)
-
-```
-$ git log --oneline auth-system spec
-
-abc123f feat(auth): green - implement login endpoint (Requirements: FR-01)
-def456g feat(auth): green - implement password hashing (Design: AD-03)
-ghi789h test(auth): red - add login endpoint tests
-jkl012i test(auth): red - add password hash tests
-mno345j chore(deps): add bcrypt@5.1.0
-pqr678k docs(auth): add design.md for JWT authentication
-stu901l docs(auth): add requirements.md
-vwx234m docs(auth): add research.md (initial spec)
-```
-
-Reading this history, anyone can understand:
-- First came research → requirements → design (doc commits)
-- Then a dependency was added
-- Then TDD red (tests) → green (implementation)
-- Every step is atomic
-
-This is the quality CurdX-Flow demands.
-
----
-
-_CurdX-Flow internal rule. Violation counts as a flow-executor task failure._

package/knowledge/claude-code-runtime-contracts.md

@@ -1,240 +0,0 @@
-# Claude Code Runtime Contracts — CurDX-Flow Notes
-
-CurDX-Flow depends on Claude Code's plugin, hook, skill, and subagent runtime surfaces. This page records the operational contracts we rely on so agents and maintainers do not drift from the current official behavior.
-
-## Source of Truth
-
-- Official docs entry: `https://code.claude.com/docs/en/overview`
-- Runtime-specific pages to re-check when changing behavior:
-  - Hooks: `/docs/en/hooks`
-  - Subagents: `/docs/en/sub-agents`
-  - Skills: `/docs/en/skills`
-  - Commands: `/docs/en/commands`
-  - Plugins: `/docs/en/plugins`
-  - Settings: `/docs/en/settings`
-  - Plugin manifest reference: `/docs/en/plugins-reference`
-  - Output styles: `/docs/en/output-styles`
-  - Status line: `/docs/en/statusline`
-  - Plugin dependency constraints: `/docs/en/plugin-dependencies`
-  - Routines / scheduled tasks: `/docs/en/routines`, `/docs/en/scheduled-tasks`
-
-When a behavior is unclear, prefer the official docs and `claude plugin validate .` over inferred behavior from older examples.
-
-## Hook Output Rules
-
-- Standard plugin hooks live at `hooks/hooks.json` in the plugin root and are discovered automatically. Do not also set `plugin.json.hooks` to that same file; current Claude runtimes treat that as a duplicate load.
-- `SessionStart` context injection must use:
-  - `hookSpecificOutput.hookEventName = "SessionStart"`
-  - `hookSpecificOutput.additionalContext = "..."`
-- Persistent environment for later hook/script invocations must be written to `CLAUDE_ENV_FILE` as shell exports. Do not invent a JSON top-level `environmentVariables` field.
-- `Stop` / `SubagentStop` continuation blocking uses top-level `decision: "block"` plus `reason`.
-- `PreToolUse` denial uses `hookSpecificOutput.permissionDecision = "deny"` and `permissionDecisionReason`.
-- `PreToolUse` also supports `hookSpecificOutput.permissionDecision = "defer"` for deferred tool handling in `-p` / SDK-style flows; do not assume deny/allow are the only valid permission outcomes.
-- `PermissionDenied` can return `{ "retry": true }` to let Claude try a different approach after an auto-mode classifier denial.
-- Hooks must fail open when runtime prerequisites are missing (`python3`, malformed stdin JSON, absent `.flow/` state). The exception is an explicit, success-looking subagent completion with a missing required artifact.
-- Hook and monitor scripts must not assume the current working directory is the repo root. Official `CwdChanged` exists, and users often work from nested package/app directories, so CurDX-Flow runtime scripts should prefer `CLAUDE_PROJECT_DIR` and otherwise walk upward until they find the project `.flow/` root.
-- CurDX-Flow may use `CwdChanged` + `FileChanged` to maintain dynamic watch paths for `.flow/.active-spec`, the active spec `.state.json`, and `tasks.md`. Treat that watch layer as reactive context plumbing, not as a replacement for the monitor or disk-backed truth.
-- `TaskCreated` / `TaskCompleted` can be used as native-task-sync guardrails, but only for CurDX-shaped task subjects. Never let those hooks break unrelated user task-list workflows that happen outside an active CurDX spec.
-- `ConfigChange` can block project/local settings updates from taking effect in the running session. CurDX-Flow may use that to reject mid-execute changes that would disable hooks or reroute the main thread away from `flow-orchestrator`.
-- `TeammateIdle` has less context than `SubagentStop`, so CurDX-Flow should resolve `teammate_name -> agent_type` through `~/.claude/teams/<team-name>/config.json` before enforcing artifact gates for team-mode workers.
-
-## Subagent Artifact Discipline
-
-Subagents that produce long reports must write the artifact before producing the final assistant summary. The final summary should be short and point to the file path.
-
-Guarded artifact targets:
-
-| Agent | Expected artifact |
-| --- | --- |
-| `flow-researcher` | `.flow/specs/<active>/research.md` |
-| `flow-product-designer` | `.flow/specs/<active>/requirements.md` |
-| `flow-architect` | `.flow/specs/<active>/design.md` |
-| `flow-planner` | `.flow/specs/<active>/tasks.md` |
-| `flow-reviewer` | `.flow/specs/<active>/review-report.md` |
-| `flow-verifier` | `.flow/specs/<active>/verification-report.md` |
-| `flow-security-auditor` | `.flow/specs/<active>/security-audit.md` |
-| `flow-qa-engineer` | `.flow/specs/<active>/qa-report.md` |
-| `flow-edge-hunter` | `.flow/specs/<active>/edge-cases.md` |
-| `flow-adversary` | `.flow/specs/<active>/adversarial-review.md` |
-| `flow-ui-researcher` | `.flow/specs/<active>/ui-research.md` |
-| `flow-ux-designer` | `.flow/specs/<active>/ui-sketch/index.html` |
-| `flow-triage-analyst` | `.flow/_epics/<epic-name>/epic.md` |
-| `flow-brownfield-analyst` | `.flow/codebase-index.md` |
-
-`flow-executor` is marker-driven rather than report-driven: it must update task state and end with `TASK_COMPLETE: <task_id>` or `TASK_FAILED: <task_id>`.
-
-## Background Subagent Policy
-
-- Official background subagents keep the main conversation free while the worker runs, but any `AskUserQuestion` call inside that worker auto-denies instead of surfacing an interactive clarification prompt.
-- CurDX-Flow should therefore reserve `background: true` for agents that are:
-  - artifact-producing or evidence-gathering
-  - long-running enough to justify concurrency
-  - not dependent on `AskUserQuestion` for normal operation
-- Do not set `background: true` by default on `flow-executor`, `flow-debugger`, `flow-qa-engineer`, `flow-product-designer`, `flow-security-auditor`, `flow-triage-analyst`, or `flow-ux-designer` without a tighter clarification/permission contract.
-- If those same agent definitions are reused as teammates, `TeammateIdle` quality gates should reuse the same disk-artifact contract as subagent completion whenever the agent is artifact-bearing.
-
-## Agent Teams Compatibility
-
-- Official `agent-teams` behavior differs from regular subagent invocation in one critical way: when a subagent definition runs as a teammate, its `skills` and `mcpServers` frontmatter fields are not applied.
-- Team coordination tools remain available to teammates, but any agent that relies on a preloaded skill must also have access to the `Skill` tool so it can invoke that skill explicitly when used as a teammate.
-- A project file like `.claude/teams/teams.json` is not configuration. Official docs say team config lives under user scope, not project scope.
-
-## Skills and Frontmatter
-
-- Keep `SKILL.md` frontmatter minimal and schema-backed.
-- Use `description` for the concise trigger phrase; put longer trigger examples in `when_to_use`.
-- Use forked context and a named agent only when the skill's work benefits from isolation or a specialized role.
-- Avoid preloading broad tool access. Prefer the smallest useful tool set per skill/agent.
-- Do not make bundled skills or agents implicitly depend on runtime-gated tools such as `SendMessage`, `TeamCreate`, `TeamDelete`, or `ToolSearch` unless CurDX-Flow also ships the matching feature-flag/setup contract.
-- Interactive Claude sessions expose the Task tool family (`TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`) while headless / SDK flows use `TodoWrite`. Any CurDX native task-list sync must therefore be optional UX, not a correctness dependency.
-- Official interactive-mode docs also support `CLAUDE_CODE_TASK_LIST_ID` for sharing a native task list across sessions. CurDX-Flow may use that later as an optimization, but current execution must still recover correctly when the native task list changes or disappears.
-- If CurDX uses task lifecycle hooks, `TaskCreated` should reject orphan CurDX-native tasks that do not map to `tasks.md`, and `TaskCompleted` should reject UI completion that happens before `tasks.md` is updated.
-
-## Plugin Settings
-
-- Claude Code plugin-root `settings.json` currently supports only `agent` and `subagentStatusLine`.
-- CurDX-Flow ships both:
-  - `agent: "flow-orchestrator"` to route the main thread through the CurDX-Flow coordinator by default.
-- `subagentStatusLine`, pointing at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-statusline.sh`.
-- The status-line script must fail open on malformed input or missing `python3`; UI decoration must never break agent execution.
-- Plugin-root references must never traverse outside the plugin directory. Installed marketplace plugins run from Claude Code's plugin cache, so parent-directory references are invalid even if they work in a development checkout.
-- CurDX-Flow should not declare `plugin.json.hooks` while using the standard `hooks/hooks.json` location; keep the file on disk, let Claude discover it implicitly, and reserve `plugin.json.hooks` for non-default or additional hook files only.
-- If adding plugin settings, update `schemas/plugin-settings.schema.json`, `test/plugin-structure-contract.test.js`, `test/pack-tarball-smoke.test.js`, and `scripts/validate-plugin-contracts.mjs` in the same change.
-
-## Plugin Monitors and User Config
-
-- CurDX-Flow ships a plugin monitor at `${CLAUDE_PLUGIN_ROOT}/monitors/monitors.json` to surface `.flow` state changes back into the active Claude session.
-- Monitors run only when the Claude `Monitor` tool is available, and only in interactive CLI sessions.
-- The monitor must keep working even when Claude's cwd moves below the repo root; `.flow` discovery should be project-root aware rather than cwd-fragile.
-- CurDX-Flow `userConfig` values are exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>`.
-- Current runtime knobs:
-  - `autonomous_blocking`: lets users disable stop-hook continuation without editing plugin files.
-  - `daily_dependency_check`: silences or enables the once-per-day recommended-plugin reminder.
-  - `monitor_interval_seconds`: controls plugin monitor polling cadence.
-- `doctor` should explain both the machine-effective config value and the projected plugin subprocess env var for these knobs, since hook/monitor behavior depends on the env projection rather than direct JSON parsing.
-- Current `doctor` inspection includes file-based managed settings (`managed-settings.json` plus sorted `managed-settings.d/*.json` fragments) before local/project/user settings. It still cannot see server-managed settings, MDM/registry policy delivery, or one-off CLI overrides.
-
-## Plugin Dependency Constraints
-
-- Official dependency version constraints require upstream plugin release tags in the `{plugin-name}--v{version}` format.
-- Do not add a version constraint to the `context7-plugin` dependency unless the Upstash marketplace has matching `context7-plugin--v*` tags. Claude resolves plugin dependency ranges against `{plugin-name}--v*` tags; a semver range without those tags can disable dependency resolution and surface the installed plugin version as `unknown`.
-- Keep the CLI registry and `.claude-plugin/plugin.json` dependency entry aligned: Context7 remains a required companion plugin, while optional tools stay in `RECOMMENDED_PLUGINS`.
-
-## Shared Settings Guardrails
-
-- `.claude/settings.json` is a shared project surface. Keep machine-local scripts, secrets, and credential helpers out of it.
-- Official docs say these keys are ignored or not accepted at project scope and must live in user/local/managed settings instead:
-  - `autoMemoryDirectory`
-  - `autoMode`
-  - `useAutoModeDuringPlan`
-  - `permissions.skipDangerousModePermissionPrompt`
-  - `sshConfigs`
-  - `teammateMode` belongs in the global `~/.claude.json` config, not project `settings.json`.
-- Treat shared auto-approval settings as high risk:
-  - `enableAllProjectMcpServers`
-  - `enabledMcpjsonServers`
-- Treat shared hook and skill policy as behavior-changing:
-  - `disableSkillShellExecution: true` replaces inline shell output in project/plugin skills and commands with a disabled placeholder.
-  - Empty `allowedHttpHookUrls` blocks all HTTP hook targets.
-  - Empty `httpHookAllowedEnvVars` prevents HTTP hook header environment interpolation.
-- Treat shared `env` injection as behavior-changing when it flips Claude runtime modes:
-  - `CLAUDE_CODE_SIMPLE=1` puts Claude Code into bare/simple mode and disables hooks, skills, plugins, MCP discovery, auto memory, and `CLAUDE.md`.
-  - `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=1` keeps discovery enabled but swaps in the minimal Claude system prompt.
-  - `CLAUDE_CODE_EFFORT_LEVEL=low|medium` lowers reasoning for every collaborator session.
-  - `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` enables experimental teammate surfaces for every collaborator session.
-  - Provider-specific pinned model IDs (`ANTHROPIC_DEFAULT_*_MODEL`, `ANTHROPIC_CUSTOM_MODEL_OPTION`) should usually be paired with `_SUPPORTED_CAPABILITIES` so Claude keeps effort / thinking feature detection.
-  - In CI / headless runs, `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` makes marketplace plugins available before the first turn; otherwise they can install in the background and miss turn one.
-  - `CLAUDE_CODE_PLUGIN_SEED_DIR` is the official way to pre-populate marketplace plugins in containers and CI images.
-- Treat shared sandbox policy as runtime-sensitive:
-  - `sandbox.failIfUnavailable: true` can fail Claude Code startup on unsupported hosts.
-  - `sandbox.filesystem.denyRead` / `denyWrite` must not block `.flow`, `.git`, or the project root.
-  - Empty `sandbox.network.allowedDomains` blocks outbound network access for sandboxed commands.
-- Prefer `attribution` over deprecated `includeCoAuthoredBy`.
-- Treat shared runtime blockers as high risk for CurDX-Flow:
-  - `disableAllHooks: true` disables stop-hook recovery, artifact guards, and custom status lines.
-  - `agent: "<name>"` routes the main thread through a named subagent, replacing the normal CurDX-Flow prompt, tool surface, and model for the whole session.
-  - `permissions.defaultMode: "dontAsk"` can auto-deny clarification and Agent dispatch prompts.
-  - `permissions.deny` rules for `Agent`, `AskUserQuestion`, CurDX-Flow `flow-*` agents, or broad `Bash` / `Monitor` / `Read` / `Write` / `Edit` / `Grep` / `Glob` tools can make workflows fail.
-  - `availableModels` must include the portable `sonnet` and `opus` aliases used by bundled agents.
-  - Shared `effortLevel: "low"` or `"medium"` may underpower main-thread planning/review turns; prefer `high` / `xhigh` for CurDX-Flow-heavy projects.
-  - `CLAUDE_CODE_SIMPLE=1` in the launch environment is a hard runtime blocker for CurDX-Flow because Claude stops discovering plugin assets and `CLAUDE.md`.
-  - `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=1` in the launch environment is not a hard blocker, but it weakens the normal Claude Code system prompt CurDX-Flow expects.
-  - Provider-specific model IDs in `ANTHROPIC_DEFAULT_*_MODEL` or `ANTHROPIC_CUSTOM_MODEL_OPTION` can disable feature detection for effort and thinking unless the matching `_SUPPORTED_CAPABILITIES` env var is declared.
-  - In CI / `claude -p` runs that depend on marketplace plugins, missing `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` (or a seeded plugin cache via `CLAUDE_CODE_PLUGIN_SEED_DIR`) can leave plugins unavailable on the first turn.
-  - Prefer `claude --bare -p` for CI / scripted runs so hooks, skills, plugins, MCP discovery, auto memory, and `CLAUDE.md` do not vary by machine; add `--plugin-dir`, `--settings`, and `--mcp-config` explicitly when needed.
-  - Do not depend on interactive `/curdx-flow:*` slash commands in `claude -p`; scripted runs should ask for the desired outcome directly.
-  - `settings.json` does not accept `effortLevel: "max"`; official docs reserve `max` for session-only `/effort` (or `CLAUDE_CODE_EFFORT_LEVEL`), so do not commit it to shared project settings.
-  - `enabledPlugins` entries set to `false` for `curdx-flow@curdx-flow-marketplace` or required companion plugins override user-level installs in that project.
-
-## Browser and UI Verification
-
-For UI-facing acceptance criteria, code inspection and DOM unit tests are not sufficient evidence. Use `chrome-devtools` MCP when available to drive the real browser, capture screenshots, list console messages, and inspect network requests. If the MCP is unavailable, mark UI-facing acceptance criteria as unverified instead of silently passing them.
-
-
-## Reality Verification Contract
-
-For fix/debug/regression specs, green tests alone do not prove the user-visible problem was fixed. The workflow must preserve a BEFORE/AFTER evidence trail:
-
-1. BEFORE: record the original reproduction command, observed failure output, and timestamp in `.progress.md` before changing code.
-2. FIX: change the smallest root cause and run the task's Verify command.
-3. AFTER: rerun the original reproduction command and compare output against BEFORE.
-4. COMPLETE: write `Verified: Issue resolved` only when the original failure is gone.
-
-Planner duties:
-- Add a `VF` task for fix/debug specs unless `STATE.md` has an explicit D-NN waiver.
-- Treat missing `VF` coverage as a coverage-audit gap.
-
-Executor duties:
-- Do not mark `VF` complete unless `.progress.md` has the BEFORE/AFTER comparison.
-- Use the same reproduction command for AFTER unless a documented D-NN explains why the command changed.
-
-Verifier duties:
-- Mark fix/debug specs `PARTIAL` when BEFORE/AFTER evidence is missing, even if the normal test suite is green.
-
-## Task Split Contract
-
-When a task is too broad, under-specified, or unsafe to complete surgically, the executor must stop rather than expand scope. It returns `TASK_FAILED` with a split proposal containing at most 3 replacement tasks, each with `Do`, `Files`, `Done when`, `Verify`, and `Commit` fields.
-
-The coordinator or planner owns updates to `tasks.md`. An executor must not create new tasks and execute them in the same turn.
-
-## Failure Recovery Contract
-
-Execution failure recovery is ledger-first:
-
-- Default `manual` recovery blocks progress past `TASK_FAILED`; retry the first unchecked task after root-cause analysis.
-- `fix-task` recovery may create one targeted `[FIX <task_id>]` task immediately after the failed task, but only before execution resumes.
-- `.state.json` `execute_state.fix_task_map` records attempts, generated fix task ids, and the last error per original task.
-- `max_fix_tasks_per_original` is a hard ceiling, not a suggestion.
-
-Generated fix tasks must include `Do`, `Files`, `Done when`, `Verify`, and `Commit`. A recovery task that cannot name a verification command is not actionable and should stop for user input rather than guessing.
-
-## Stop-Hook Recovery Contract
-
-The stop-hook strategy must never trust one source of completion by itself:
-
-- `.state.json` tracks execution cursor and phase.
-- `tasks.md` is the task ledger; unchecked tasks mean work remains.
-- `ALL_TASKS_COMPLETE` is a signal, not proof.
-
-Completion requires both completed state and zero unchecked tasks. If they disagree, continue `tasks.md`'s unchecked tasks and do not add new tasks. When Claude Code sends `stop_hook_active=true`, allow stop to prevent recursive stop-hook loops; resume from persisted state on the next turn.
-
-## Status / Cancel Contract
-
-`/curdx-flow:status` is read-only. It must compare both machine state (`.state.json`) and human task ledger (`tasks.md`) before reporting health. If they disagree, report `NEEDS_ATTENTION` and give one concrete recovery command.
-
-`/curdx-flow:cancel` is non-destructive by default. It cancels execution state while preserving spec artifacts, progress, reports, and project-level `.flow` files. Deleting a spec requires both `--delete-spec` and `--yes`.
-
-If state JSON is corrupt, preserve it by renaming to `.state.json.corrupt.<timestamp>` rather than deleting it. Recovery commands should prefer `/curdx-flow:status` followed by `/curdx-flow:implement --strategy=subagent`.
-
-## Test Quality Contract
-
-Tests used as FR/AC evidence must exercise real behavior. Mock-only tests are not proof of implementation.
-
-Blocking evidence problems:
-- The test only asserts mock/spies were called.
-- The real module/function under test is not invoked.
-- The test is skipped, assertion-free, or would pass with an empty implementation.
-- Mock setup overwhelms behavioral assertions and no integration/e2e backup exists.
-- Stateful mocks are not cleaned up between tests.
-
-Mocks are acceptable for boundaries (network, payment provider, clock/randomness) when the assertion still verifies production logic. If a requirement is backed only by weak tests, `/curdx-flow:verify` and `/curdx-flow:review` must not return full PASS.