@chenmk/superflow 0.3.0 → 0.5.0

package/assets/skills-en/superflow-pipeline/SKILL.md

@@ -5,6 +5,13 @@ description: Use when a user asks for the SuperBridge Flow, SDD, OpenSpec, requi
 
 # SuperBridge Flow Pipeline
 
+When maintaining Superflow CLI itself, first read repository-root
+`docs/superflow-cli-design-principles.en.md` and
+`docs/superflow-cli-evaluation-framework.en.md`; managed-work changes also read
+the managed constitution and protocol. Identify the owner layer before editing,
+then record baseline, hypothesis, scenario, result, and rollback condition under
+the unified evaluation framework.
+
 ## Role
 
 This is the main router and stateful workflow orchestrator for SuperBridge Flow.
@@ -19,6 +26,96 @@ other:
 - Handoff files and state files are the memory boundary. Do not rely on chat
   memory after compaction.
 
+## Managed Work And Dual-Agent Closure
+
+When the Superflow MCP is installed for the host Agent, prefer
+`superflow_managed_start/status/wait/message/submit_review` instead of manually
+spawning `superflow pipeline` from chat. MCP tasks are always `external_host`:
+the current host keeps the user conversation and reviews directly, while the
+background service starts only the peer executor. Never spawn a nested
+supervisor CLI. Wait with `superflow_managed_wait` locally instead of spending
+model turns on periodic status checks. Use the CLI equivalent below only when
+MCP is unavailable.
+Call `superflow_managed_runtime` before task creation. If its fingerprint is
+stale, require a Host restart and never start a new validation task through the
+pre-install MCP process.
+
+When the user says to use Superflow for managed delivery and provides an
+implementation prompt, change directory, or direct task, use built-in managed
+mode. Do not require the user to name `superflow-pipeline`, roles, or CLI flags:
+
+Before start, perform one Host semantic routing step. Docs-only requests stop
+after autonomous document review and Coding Ready without a managed Task. A
+user-approved change/prompt is frozen from its original path. Only a bounded
+verbal request enters minimal or standard directly. Direction-changing API,
+data, concurrency, cross-repository, or owner choices return to
+clarification/documents; Runner regexes and Executor improvisation do not decide them.
+
+```bash
+superflow pipeline "<implementation prompt, change directory, or direct task>" --managed --project "<project root>" \
+  --supervisor current --executor peer --language en
+```
+
+`current/peer` resolves the host automatically: a Codex host drives Claude and a
+Claude host drives Codex. Ambiguous environments fail closed and require explicit
+roles. The background service
+invokes only the executor; the current host agent performs the read-only review
+without spawning another copy of itself. After executor delivery, read
+`host-review-N.md`, write the structured review JSON, then resume with
+`--resume-task <task-id> --submit-host-review <json>`. Losing the follower does
+not stop the task. Read `references/managed-work.md` before dispatch.
+
+Managed delivery uses the lower-cost executor for implementation and validation;
+the more expensive host only freezes the goal, supervises, and reviews delivery
+quality. The host must not code, build, start, test, or manage executor processes.
+When the task reaches `external_supervisor_review_required`, review, submit, and
+resume automatically in the same turn; it must not stop and wait for manual user handoff.
+Only an owner decision, unavailable external authority, or final Git approval may
+interrupt the user.
+
+Hard gates:
+
+- Use a fresh short session for every execution and repair call. Hand off through
+  the current workspace, frozen prompt, persisted result, and findings; keep old
+  session IDs only for audit and never resume a long session indefinitely.
+- The first invocation must receive the frozen task prompt automatically. Every
+  later invocation must first receive and read a condensed handoff containing at
+  least the prompt path/hash, task progress, local pending work, external
+  prerequisites, all current findings, diff stat, and recent report. Old and new
+  sessions both treat the handoff and current workspace as authoritative.
+- In `external_host` mode the current agent reviews; the service must not spawn a
+  nested Codex or Claude CLI for the supervisor role.
+- Host conversation and review do not count as background Agent invocations;
+  only real executor calls consume the execution budget.
+- Task contract, event journal, review results, and evidence are authoritative.
+- Maximum 5 reviews, 7 executor calls, and 12 total agent calls.
+- Revalidate the frozen contract and hard limits on every start or resume. Engineering work cannot enter review with only one verification category.
+- Resolve a change directory through `.sdd/state.yaml` `implementation_prompt`, reject `tasks.md` as an execution entry, and freeze one prompt snapshot plus SHA-256 for both agents.
+- Supervisor is read-only; executor cannot edit `.superflow/tasks` or commit/push/publish.
+- Frozen requirements, designs, prompts, handoffs, rules, and task facts are
+  immutable protected inputs. Tasks and test reports are retained progress
+  evidence that may be updated but not deleted. Executor cleans runtime and
+  workspace-temporary resources and keeps delivery artifacts and protected
+  contracts for Host review.
+- Never use pkill, killall, a bare kill, port/name-only cleanup, or rm -rf
+  without owner-helper verification. Native hooks block before mutation and
+  preflight/final gates verify every Host.
+- A passing run enters `environment_validation_blocked`, `local_delivery_ready`, or `release_ready`; Git always requires user approval.
+- Default MCP waits to a 240-second Host-compatible transport window. On window
+  expiry, immediately continue only from returned `latestSequence`; do not call
+  status, read full events, or restart Executor. Hosts with longer tool limits may
+  explicitly request up to twelve hours; semantic supervision runs only for attention.
+- When the user names a task-prompt document, pass its original path to start and verify the frozen SHA-256; never replace it with a host summary.
+- Page/permission changes require frontend startup and real-browser E2E; cross-stack API changes require both backend and frontend contract tests.
+- `superflow-managed-work-check.mjs` must pass before delivery-ready status.
+- Record the single delivery-ready event only after the integrity script passes.
+- After the managed command returns a terminal state, read the task report and summarize it to the user instead of returning only a task ID.
+- Freeze the selected language into the task contract. Executor and reviewer prompts, resumed rounds, journals, reports, notifications, and errors must inherit that language without switching mid-run.
+- Claude Executor long sessions use early auto-compaction by default, while
+  explicit user environment values win. Reload the frozen prompt and handoff after
+  compaction. Final `result.usage` is authoritative; a large value alone does not
+  prove Runner double counting.
+
 ## Phase Order
 
 Always route work through this order unless the task is explicitly a tweak or
@@ -27,6 +124,10 @@ hotfix:
 1. clarify: ingest requirements one feature at a time, freeze scope, and produce
    source-ingestion, feature gates, inventory, UI/API gaps, and freeze review.
 2. docs: generate OpenSpec/SDD contract artifacts and the first handoff package.
+   Before closing docs, run source-backed requirement review, repair blocking
+   findings, resolve all source investigations, owner decisions, and implementation-affecting
+   external contracts, then record `requirement-review.md`. Naming or assigning a blocker does
+   not close it.
 3. design: let Superpowers produce source-level technical design from the frozen
    contract and codebase evidence.
 4. implement: generate implementation prompts, execution plans, worktree/port
@@ -43,6 +144,8 @@ hotfix:
   use `superflow-clarify` in embedded deep-clarification mode. This is a mode
   inside the normal clarify phase, not a separate command the user must remember.
 - New or unclear requirement: use superflow-clarify.
+- Requirement review, reverse review, omission search, design challenge,
+  testability review, or over-design review: use superflow-requirement-review.
 - Confirmed requirement needing full docs: use openspec-propose, then
   superflow-docs.
 - Contract docs exist and code-level HOW is needed: use superflow-design.
@@ -79,6 +182,39 @@ When the router selects embedded deep clarification, follow these rules inside
 
 ## Required Artifacts
 
+### Source Fact Freeze And Question Eligibility (Blocking)
+
+- When a full workflow involves existing behavior, DB/table relationships,
+  cross-repository impact, or a real entry, docs must include
+  `source-code-audit.md` with: `Business conclusion | understand-anything
+locator | Data model | All writers | Real user entry | Current callers |
+Legacy conflict | DB check required | Conclusion level | owner decision`.
+- understand-anything is a locator, not the final source of truth. Classify
+  evidence as `current`, `legacy`, `unmounted`, `data-model-only`,
+  `owner-confirmed`, or `blocked`.
+- If `List`, `orderIds`, `batchInsert`, or a one-to-many model conflicts with a
+  single-item real entry, complete a Conflict Audit instead of inferring current
+  product behavior from the data structure.
+- Before asking the user, search source, Mapper/SQL, frontend/mini-program/H5
+  callers, sibling repositories, and read-only DB data when needed. Do not turn
+  repository-verifiable facts into clarification questions.
+
+### Canonical OpenSpec Change Directory (Blocking)
+
+- Superflow must use the OpenSpec CLI single-level layout:
+  `openspec/changes/<change-name>/`.
+- The release version belongs in the change name, not an intermediate
+  directory. Encode `v1.1.1` as `v1-1-1-<feature-slug>` and never create
+  `changes/v1.1.1/<feature-slug>/`.
+- Keep exactly one physical directory for each change. Do not create a
+  compatibility symlink, copied directory, or second canonical document tree.
+- Run `openspec new change <change-name>` first, then reuse that same physical
+  directory for status, instructions, strict validation, state, handoff, and
+  every Superflow guard.
+- If a nested version directory or symlinked change is found, stop document
+  generation, migrate it to one flat physical directory, and rerun
+  `openspec validate <change-name> --strict`.
+
 For a full change, the docs phase must create or refresh:
 
 - proposal.md
@@ -91,6 +227,7 @@ For a full change, the docs phase must create or refresh:
 - review-checklist.md
 - sdd-quality-gate.md
 - test-report.md
+- source-code-audit.md when the source fact gate is triggered
 - .sdd/state.yaml
 - .sdd/handoff/sdd-context.md
 - .sdd/handoff/sdd-context.json
@@ -124,6 +261,58 @@ Rules:
 
 ## Decision Points
 
+## Autonomous Document Delivery Closure
+
+A full-workflow docs Agent must not equate a successful keyword/file guard with
+100% implementation readiness. Before developer handoff, record at least three
+independent review lenses against the same current handoff hash in
+`.sdd/reviews/document-review.json`:
+
+1. `source-contract`: source, cross-repo callers, contracts, and real entries;
+2. `architecture-minimality`: ownership, reuse, simplest design, failure owner,
+   and overdesign;
+3. `e2e-environment`: startup order, configured environment, simulators,
+   automation, DB/log assertions, and cleanup.
+
+The Agent resolves every source/config/log/probe-discoverable gap itself. Only
+business-owner decisions, unavailable credentials/authority, or external
+resources may remain in `openOwnerDecisions`, and they are asked as one final
+batch. Open findings mean `BLOCKED_FOR_OWNER_BATCH`, never 100%.
+
+Explore the configured environment during docs and record
+`.sdd/readiness/environment.json`. Only fail-safe `file`, `directory`,
+`executable`, `tcp`, and `http` probes are allowed. Never print credentials or
+write production data. Respect the declared local/dev/test scope instead of
+requiring a remote environment by default. Use
+`superflow.environment-readiness.v2` to freeze the application location,
+`local-isolated/shared-dev/shared-test/mixed` dependency policy, config sources,
+allowed/forbidden overrides, and a `contractRef` for every probe. Reachability
+alone is not an environment execution contract.
+
+Cross-service, cross-repo, device, MQ, callback, scheduler, state-machine,
+compensation, or three-plus-module logic declares `complex_logic: true` or
+`mermaid: required` in `.openspec.yaml` and includes both a Mermaid
+`sequenceDiagram` and a `flowchart`/`stateDiagram` showing failure exits,
+compensation owner, and forbidden fallback.
+
+Run `superflow check <change> --level coding-ready` after all prompts are ready.
+It validates YAML, OpenSpec, docs/design/implement, every prompt and exact link,
+review receipts, environment probes, and Mermaid diagrams, then writes a receipt
+bound to the current handoff hash. Never delegate a failed implement gate to the
+developer Agent.
+
+## Cross-System Failure Ownership And Compensation Boundary
+
+Record `Failure signal | Interpreter | Compensation owner | Retry allowed? |
+Idempotency basis | Accepted race window | Extreme fallback | Owner approval`.
+When the caller receives an explicit failure and owns refund/cancel/state
+compensation, the downstream adapter defaults to `Fail-fast + Fail-closed +
+At-most-once + Caller-owned compensation`: no transparent retry, reroute,
+resend, or guessed success. Accept a bounded false-negative window when duplicate
+side effects are more harmful. Additional fallback requires explicit owner
+approval and a proven idempotency basis, collected with other owner-only
+questions in one final batch.
+
 Record irreversible or ambiguous decisions in references/decision-point.md
 format. Do not store decisions only in chat memory.
 
@@ -139,6 +328,9 @@ Decision points include:
 
 ## Quality Gates
 
+The machine-readable review, environment, Mermaid, and Coding Ready contracts
+are defined in `references/document-readiness.md`.
+
 The workflow must preserve these gates:
 
 - API-first contract freeze before implementation.
@@ -160,6 +352,13 @@ The workflow must preserve these gates:
 - Architecture boundary and call-direction analysis for multi-repo, service,
   SDK, MQ, scheduler, callback, gateway, adapter, device, or third-party flows.
 - SQL risk review before implementation for DB changes.
+- Frozen release SQL before source design for DB changes. `release-sql.md` must
+  declare `database_change: true`, an exact placeholder-free
+  `target_sql_path`, `copy_policy: verbatim`, and the normalized SQL payload
+  `sql_sha256`, with exactly one complete executable SQL block containing the
+  required prechecks, DDL/DML, migration, and post-verification. Implementation
+  agents may only copy the block verbatim and verify the hash; any SQL design
+  omission returns to docs and requires a refreshed handoff.
 - Real-entry acceptance for integration, device, callback, payment, client, or
   cross-system flows. Mock-only is never real integration.
 - Delivery completeness: runtime code changes must update the relevant task
@@ -178,6 +377,9 @@ Implementation prompts must require:
 - worktree and port plan for parallel work;
 - real-entry validation commands from tests.md;
 - DB SELECT or SHOW CREATE checks when persisted state is touched;
+- `release-sql.md`, its exact target path, verbatim-copy rule, and SHA-256 when
+  the change touches schema or data migration; prompts must never ask an
+  implementation agent to author or append SQL;
 - log checks and error checks;
 - superflow-verify-integration and superflow-delivery-check before completion;
 - a report format that distinguishes Passed, Partially verified, and Blocked.

package/assets/skills-en/superflow-pipeline/references/batch-prompt-template.md

@@ -21,6 +21,10 @@ review-checklist.md, sdd-quality-gate.md, test-report.md, and technical design.
 
 - Follow OpenSpec/SDD for WHAT and contract.
 - Follow Superpowers technical design for source-level HOW.
+- For database changes, read `release-sql.md`, copy its single SQL block
+  verbatim to the exact `target_sql_path`, and verify `sql_sha256`. Never
+  author, append, reorder, split, or optimize SQL during implementation. Return
+  omissions to docs and refresh the handoff.
 - Do not change forbidden files or root aggregate docs from a worker batch.
 - Use TDD: record RED failure before GREEN success.
 - Do not mark mock-only or unit-only evidence as real integration.

package/assets/skills-en/superflow-pipeline/references/document-readiness.md

@@ -0,0 +1,125 @@
+# Document Delivery Readiness Contract
+
+## Applicability
+
+Declare applicability in `.openspec.yaml`. Keyword scans may suggest a risk but
+must not override an explicit, source-backed decision.
+
+```yaml
+schema: superflow/v1
+applicability:
+  cross_repo: true
+  complex_logic: true
+  mermaid: required
+  environment: required
+  database: false
+  external_config: false
+  concurrency: false
+  money: false
+```
+
+`money: false` means this change does not alter money calculation, rounding,
+allocation, or financial display. It is not a bypass when source impact proves
+that money behavior changes.
+
+## Three-Review Receipt
+
+Path: `.sdd/reviews/document-review.json`
+
+```json
+{
+  "schemaVersion": "superflow.document-review.v1",
+  "handoffHash": "<current 64-character handoff hash>",
+  "verdict": "PASS",
+  "openOwnerDecisions": [],
+  "rounds": [
+    { "round": 1, "lens": "source-contract", "inputHash": "<same hash>", "findings": [] },
+    { "round": 2, "lens": "architecture-minimality", "inputHash": "<same hash>", "findings": [] },
+    { "round": 3, "lens": "e2e-environment", "inputHash": "<same hash>", "findings": [] }
+  ]
+}
+```
+
+Do not delete findings. After repair, retain them with `"status": "closed"`,
+evidence, and the closure location. Every round is rechecked against the current
+hash; a PASS for an old hash is invalid.
+
+## Environment Preflight
+
+Path: `.sdd/readiness/environment.json`
+
+```json
+{
+  "schemaVersion": "superflow.environment-readiness.v2",
+  "handoffHash": "<current hash>",
+  "scope": "local-dev",
+  "overall": "READY",
+  "ownerHelpRequired": [],
+  "executionContract": {
+    "applicationLocation": "local",
+    "dependencyPolicy": "shared-dev",
+    "allowLocalProvisioning": false,
+    "allowRemoteDevDependencies": true,
+    "allowedOverrides": ["server.port"],
+    "forbiddenOverrides": ["spring.datasource.url"],
+    "services": [
+      {
+        "id": "service-a",
+        "configSource": { "type": "bundled-profile", "ref": "application-prod.yml" },
+        "startupCommandSource": "tests.md#startup"
+      }
+    ],
+    "dependencies": [
+      {
+        "id": "redis",
+        "kind": "redis",
+        "provisioning": "shared-dev",
+        "configSource": { "type": "bundled-profile", "ref": "application-prod.yml#spring.redis" }
+      }
+    ]
+  },
+  "checks": [
+    { "id": "service-config", "type": "file", "target": "../../../service-a/application-prod.yml", "contractRef": "service:service-a", "status": "READY" },
+    { "id": "redis", "type": "tcp", "host": "redis.dev.internal", "port": 6379, "contractRef": "dependency:redis", "status": "READY" }
+  ]
+}
+```
+
+Supported checks are `file`, `directory`, `executable`, `tcp`, and `http`.
+Never embed credentials or tokens in URLs. Production writes and DB/Redis/MQ
+mutations are not preflight operations.
+
+`executionContract` is the single environment source of truth. Freeze the
+application location, dependency policy, local-provisioning and shared-dev
+permissions, allowed/forbidden overrides, and the config source for every
+service and dependency. `configSource.type` is one of `bundled-profile`,
+`external-file`, `environment`, `cli-override`, or `generated-fixture`.
+Do not mix `local-isolated`, `shared-dev`, and `shared-test`; use `mixed` and
+declare each dependency's `provisioning` when mixing is intentional. Every
+service and dependency needs a matching `contractRef` probe. Legacy v1 reports
+prove reachability only and cannot satisfy Coding Ready.
+
+## Complex Diagrams
+
+When `cross_repo` or `complex_logic` is true, include a Mermaid
+`sequenceDiagram` for the real call and a `flowchart` or `stateDiagram` for
+branches, compensation owner, and forbidden fallback.
+
+## Coding Ready
+
+```bash
+superflow check <change> --level docs
+superflow check <change> --level coding-ready
+```
+
+The second command writes `.sdd/readiness/coding-ready.json`. Any SDD document
+or handoff-hash change invalidates the old receipt. A developer Agent may only
+receive a change with a current receipt.
+
+## Cross-System Failure Ownership
+
+Record `Failure signal | Interpreter | Compensation owner | Retry allowed? |
+Idempotency basis | Accepted race window | Extreme fallback | Owner approval`.
+Default to fail-fast, fail-closed, at-most-once, and caller-owned compensation.
+Retry, reroute, resend, or distributed compensation requires explicit owner
+approval and a proven idempotency basis.

package/assets/skills-en/superflow-pipeline/references/document-templates.md

@@ -22,11 +22,26 @@
 - Source-of-truth contracts
 - Architecture boundary
 - Data model
+- Minimal Design Review: reuse evidence, necessity, simplest implementation,
+  removed/rejected complexity, and blockers
+- Count every new table, field, API, service, cache, async flow, scheduled job,
+  and compatibility layer; remove items without evidence
+- New-item counts: tables 0; fields 0; APIs 0; services/components 0; caches 0; MQ/events 0; scheduled jobs 0; compatibility layers 0. Replace each count.
 - Field semantics
 - Write/read loop
 - No-fallback decisions
 - Superpowers technical design handoff
 
+## release-sql.md (required for database changes)
+
+- Front matter: `database_change: true`, exact `target_sql_path`,
+  `copy_policy: verbatim`, and normalized payload `sql_sha256`
+- Exactly one complete executable `sql` block with required prechecks,
+  DDL/DML, migration, and post-verification
+- No placeholder path or deferred SQL design
+- Implementation agents only copy the block verbatim and verify the hash;
+  omissions return to docs
+
 ## tests.md
 
 - Case ID

package/assets/skills-en/superflow-pipeline/references/feature-gated-workflow.md

@@ -11,7 +11,14 @@ requests. Process one feature at a time.
 - ui-contract.md: screen field to API/DTO/DB/test mapping.
 - gap-analysis.md: unknowns, contradictions, and owner decisions.
 - spec-freeze-review.md: final frozen scope and excluded items.
+- source-code-audit.md: source fact freeze card, evidence classifications,
+  conflict audit, and question eligibility gate.
 
 ## Gate
 
 Do not generate full OpenSpec docs until the target feature is frozen.
+For existing-system work, understand-anything is locator evidence only. Confirm
+current behavior from source, Mapper/SQL, real callers, and read-only DB data
+when needed. Classify current versus legacy/unmounted/data-model-only paths and
+audit any List/orderIds/batchInsert/one-to-many signal that conflicts with a
+single-item real entry before asking an owner question.

package/assets/skills-en/superflow-pipeline/references/implementation-prompt-template.md

@@ -17,6 +17,13 @@ the new hash before continuing.
 OpenSpec/SDD is canonical for requirements, API, DB, SQL, tests, and acceptance.
 Superpowers technical design is canonical for source-level HOW and execution.
 
+For a database change, SQL is already frozen in
+[release-sql.md](../release-sql.md). The implementation agent may only copy its
+single SQL block verbatim to the exact `target_sql_path`, normalize line endings
+to LF with one trailing newline, and verify `sql_sha256`. Do not add, remove,
+reorder, split, or optimize SQL. Any omission returns to docs and requires a
+refreshed handoff; never design SQL inside the implementation prompt.
+
 ## Required Preflight
 
 - Real entry located.

package/assets/skills-en/superflow-pipeline/references/managed-work.md

@@ -0,0 +1,184 @@
+# Managed Work Rules
+
+## Design-constitution gate
+
+Before changing Superflow managed work itself, read
+`docs/managed-work-design-principles.en.md` and
+`docs/managed-agent-protocol.en.md` completely. Before delivery, walk through
+the constitution's mandatory change-review checklist and state whether the
+change alters any principle.
+
+Runner and scripts decide deterministic facts. Agents decide correctness,
+reasonableness, risk, and evidence sufficiency. Scripts must not replace
+semantic review with regexes, and Agents must not take ownership of hashes,
+schemas, counters, or state transitions. A new long-term rule first updates the
+Chinese and English constitutions, protocol, and tests.
+
+Managed orchestration owns only dual-Agent dispatch, frozen context, state,
+waiting, evidence, and review loops. API, database, concurrency, transaction,
+and test design belongs to `api.md`, `design.md`, `tests.md`, and source-level
+technical design. Executor prompts inherit rather than redesign. Audit every
+managed-prompt change against this boundary.
+
+Managed work is built into `superflow-pipeline`. The user only says to use
+Superflow and provides an implementation prompt, change directory, or direct
+task. Direct tasks receive a minimal contract. SDD work freezes the generated
+implementation prompt and never substitutes `tasks.md` for the execution prompt.
+
+Before start, the Host routes by input maturity: docs-only work stops at Coding
+Ready without a managed Task; a user-approved change/prompt is frozen directly;
+a bounded verbal task uses minimal or standard. If a verbal request has a
+direction-changing API, data, concurrency, cross-repository, or owner choice,
+return to clarification/documents instead of letting Runner regexes or Executor
+improvisation replace Host judgment.
+
+When MCP is installed, the current host must prefer the `superflow_managed_*`
+tools for submission, waiting, user guidance, and review submission. MCP is a
+channel to the local state machine rather than a third model. Direct host review
+is the only supported mode, preventing a nested supervisor CLI from duplicating
+context, tokens, and review time.
+
+When MCP is unavailable, dispatch through:
+
+```bash
+superflow pipeline "<implementation-prompt|change-dir|task>" --managed --project "<root>" \
+  --supervisor current --executor peer --language <en|zh>
+```
+
+`current/peer` resolves the host and its counterpart automatically. If host
+detection is ambiguous, pass explicit `codex/claude` roles instead of guessing.
+Legacy contracts with missing or retired supervision settings are migrated to
+direct host review on resume. No entry point may spawn a background supervisor
+CLI.
+Keep a single foreground `pipeline`/`resume` waiter so the CLI reads local state;
+never spend host model turns periodically invoking `superflow status`.
+In MCP mode,
+`superflow_managed_wait(taskId, afterSequence, timeoutSeconds=240)` defaults to
+a Host-compatible transport window below common 300-second tool limits. Hosts
+that support longer calls may explicitly request up to 43200 seconds. An active
+request exposes stages and healthy checkpoints through standard MCP progress
+notifications without waking the Host model. One healthy or idle checkpoint does
+not complete wait; two consecutive checkpoints without an effective milestone
+return attention. Ordinary window expiry immediately continues wait from the
+compact snapshot's `latestSequence`, without status or Executor restart. Call
+`superflow_managed_status` for full evidence only when the state requires Host
+attention.
+
+After executor delivery, the task enters `external_supervisor_review_required`.
+The current host reads `host-review-N.md`, writes the review JSON, and resumes:
+
+```bash
+superflow pipeline --resume-task <task-id> --submit-host-review <review.json>
+```
+
+Hard gates:
+
+- Claim the 5/7/12 budgets before an Agent call. The default Executor circuit
+  also stops at two million cumulative token units. Provider-dollar accounting
+  is not comparable, so the default has no USD circuit and Claude receives no
+  `--max-budget-usd`.
+- Freeze the selected language into the contract; prompts, journals, reports, notifications, errors, and resumed rounds must use that same language.
+- Revalidate the frozen contract hash, non-overridable permissions, and 5/7/12 hard limits on every start and resume. Fail closed if persisted contract data changed.
+- Runner uses filesystem snapshots for non-Git workspace changes. Executors must
+  never run `git init` for diff, preflight, or delivery, and must not create or
+  replace `.git`; repository-identity changes during a task still fail closed.
+- The context manifest marks frozen requirements, designs, prompts, handoffs,
+  rules, and task facts as `immutable`, and task/test-report progress evidence
+  as `retain`. Immutable entries are read-only; retained entries may be updated
+  but never deleted. Native hooks block before mutation and every Host is still
+  verified by preflight/final gates.
+- Cleanup separates runtime, workspace-temporary, delivery-artifacts, and
+  protected-contracts. Executor cleans only the first two and retains source,
+  SQL, tests, reports, and frozen contracts for Host review. Never use pkill,
+  killall, a bare kill, port/name-only cleanup, or rm -rf without owner-helper verification.
+- Resolve change directories through `.sdd/state.yaml` `implementation_prompt`; treat `tasks.md` as a checklist only. Copy the prompt into a managed snapshot and freeze its SHA-256 for both agents.
+- The first executor invocation automatically uses the frozen prompt as its task entry.
+- For real-runtime work, the first prompt requires a repository-owned,
+  one-command, repeatable, failure-safe, portable acceptance entry covering
+  preflight, setup, build, startup, real calls, assertions, and cleanup,
+  including the success path and one representative setup/verification failure
+  cleanup with final zero residue. The Host reviews all properties together.
+- Call the MCP runtime handshake before start. An installed-runtime change makes
+  the stale MCP fail closed before persistence and requires a Host restart.
+  Persist verbose logs and print bounded summaries and failure tails only.
+- Verification has three levels: repairs use change-scoped checks; engineering/SDD
+  defaults to task-level real acceptance; only an explicit frozen prompt, an owner
+  helper/managed-orchestration change, or a new custom cleanup primitive uses
+  framework certification. The frozen contract may raise but never silently lower
+  the level, and historical evidence reruns only when the diff/finding invalidates it.
+- A normal real-runtime Host review checks task PID/start-fingerprint binding,
+  deletion gates, one representative setup/assertion failure cleanup, and final
+  zero residue. Distinct business deletion paths and affected/cross-service
+  repositories still receive their own proof. It must not rerun shared-helper PID-reuse, non-owner, forged-state,
+  and every-signal disaster suites for each business task. Reuse the helper directly
+  through a configurable path instead of copying a cleanup framework. Record Host
+  usage or an explicit unavailable reason.
+- Pass neither `--max-turns` nor `--max-budget-usd` to a Claude Executor. Do not
+  split normal work by a fixed tool-step count or an inaccurate provider-dollar
+  estimate. The defaults stop after 60 minutes with no output or a two-hour
+  single-invocation deadline; repeated provider failures, token/invocation
+  budgets, safety boundaries, and user pause still stop execution.
+- Claude Executor defaults to the official
+  `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000` and
+  `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` settings for earlier long-session
+  compaction; explicit user values win. It reloads the frozen prompt and handoff
+  after compaction, and final `result.usage` is authoritative for the invocation.
+- Network errors, closed connections, timeouts, and provider overloads share one
+  consecutive-failure counter and must open the circuit on the third failure;
+  only a complete Agent response resets it. Transient 429/529/overloaded calls
+  and connection refused/reset/close or socket failures confirmed before an Agent
+  response may be credited; permission, token-plan, quota, and billing failures
+  are not, and none may bypass the three-failure circuit.
+- Keep the first invocation in one continuous session. Create a new session for
+  review repair or abnormal recovery and retain old IDs for audit; never guess
+  with `--last` or `--continue`. Generate `executor-handoff-N.md` for later
+  invocations with the prompt hash, task progress, local pending work, external
+  prerequisites, all findings, diff stat, and recent report. A new session must
+  read it and verify against the current workspace.
+- Write safely discovered Java, Maven, Node, and npm executable paths into the
+  first executor policy so the Agent does not waste tool calls rediscovering the
+  basic toolchain.
+- Handoff includes exact applicable rule files and a deterministic delivery
+  preflight. Executor runs it before returning and fixes line width, whitespace,
+  task checkboxes, and missing reports in the same session.
+- The current host performs review in `external_host` mode; the background
+  service must not spawn a nested supervisor CLI.
+- Treat `progress.jsonl`, the task contract, review results, and evidence as truth.
+- Executor cannot edit managed state or commit, push, publish, deploy, or bypass sandbox.
+- Supervisor cannot modify target files.
+- Invalid JSON, missing session IDs, and review-time workspace drift block pass. Absence checks use `assertion: negative` to express an expected exit 1/2 without guessing from command names or prose.
+- Expected-failure and fault-injection checks must use a parent command that
+  asserts the child's non-zero outcome and itself exits 0. Raw non-zero outcomes
+  stay in logs. Invalid negative evidence goes directly to Host review and never
+  triggers a full Executor invocation merely to rewrite JSON.
+- Engineering and SDD tasks need successful command evidence from at least two categories among build, test, and runtime/real invocation. Compile-only or unit-test-only delivery cannot enter formal review.
+- Run `superflow-managed-work-check.mjs <root> <task-id>` before delivery-ready.
+- `tasks.md` recognizes only local_required, environment_required, and release_required; untagged work is local. The Runner derives baseline evidence from the checklist, real workspace changes, test report, and successful commands. Executors add taskEvidence only for tasks that need distinct evidence.
+- The Runner merges the complete changedFiles set and stores structured command categories. The same mechanical rejection gets one automatic repair, with at most two automatic repairs overall, then the current host reviews it. Three or more permission denials in one invocation suppress another executor retry.
+- The Runner inherits valid startup, HTTP, test, and build commands across executor results. When the Host confirms complete historical evidence and only current structured metadata is invalid, it passes and promotes the artifact with an audit event instead of asking the Executor to rerun the environment or rewrite JSON.
+- When successful Spring Boot evidence already covers startup, real HTTP/runtime,
+  and evidence paths, and only the `invocation` category is missing, this is
+  verification-category ambiguity. Runner escalates directly to Host; after a
+  pass it promotes with an audit event instead of launching a full Executor for
+  metadata repair.
+- The Runner deterministically removes blank structured-array entries. A read-only
+  inspection with exit 1/2 that explicitly reports no process, listener,
+  container, or residue is a successful empty result; neither case launches the
+  Executor for metadata repair.
+- Status separates physical calls, infrastructure credits, and effective
+  development calls. Provider switches resume through
+  `--provider-switched <reason>`, and stage changes notify the Host conversation
+  without waking it for ordinary heartbeat.
+- Page/permission changes require frontend startup and Playwright/Cypress real-browser E2E. Cross-stack API changes require backend Controller and frontend request contracts plus an API-export snapshot.
+- Append the single `run.delivery_ready` event only after the integrity script passes. On failure, require human attention without leaving false delivery-ready evidence.
+- A passing run enters a three-stage source/environment/release state and still requires explicit Git approval.
+
+## Recovery
+
+After a background failure, recover from the task contract, event journal, run
+state, and latest checks. Old session IDs are audit records, not recovery
+dependencies. Plain `--resume-task` for a healthy `running` task is safe attach
+and continued wait only: it cannot reset state or budgets or launch another
+Executor. Only a recorded PID proven dead enters stale recovery; a missing PID
+fails closed into attach-and-wait. An active MCP wait's progress notifications
+are request-scoped, not autonomous callbacks after the Host turn ends.