@massa-ai/cursor-plugin 1.6.0

package/skills/massa-ai/references/furps/checklist.md

@@ -0,0 +1,92 @@
+# FURPS+ Refinement Checklist
+
+Use this reference from `workflows/refinement/furps-refinement.md` when analyzing a PRD and/or ADR against the FURPS+ quality model. One `furps-analyst` sub-agent loads only its assigned dimension section; the main agent loads the full file only when synthesizing or when no dimension split is used.
+
+## Source
+
+FURPS+ — a requirements/quality classification from the Rational Unified Process (RUP). The five core categories are Functionality, Usability, Reliability, Performance, Supportability; the "+" adds Design, Implementation, Interface, and Physical requirements. Source reference: QualidadeBR, "FURPS+", 2008 (https://qualidadebr.wordpress.com/2008/07/10/furps/), derived from RUP / Rational Library / Peter Eeles (IBM Rational).
+
+## Status rubric (every check item)
+
+| Status | Meaning |
+|---|---|
+| covered | Requirement/decision is explicitly present, source-backed, and unambiguous |
+| partial | Present but incomplete, vague, or missing a non-trivial sub-aspect |
+| missing | Absent from the document; execution would have to assume or invent it |
+| unclear | Present but contradictory, unverifiable, or without an owner |
+
+Every item must record: status, evidence (quote or "absent"), and the output section it feeds (Open Questions / Suggestions / Insights / Risks / DoR-gaps). `missing` and `unclear` always produce at least one `FR-<letter>-<N>` finding; `partial` produces a finding when the gap is non-trivial.
+
+## Dimension: F — Functionality
+
+Functional aspects of the software and compliance with specified requirements.
+
+- **F1 Functional completeness & compliance** — Are all required capabilities and flows present, and do they comply with the specified requirements? covered = every capability listed with acceptance criteria; missing = capabilities referenced but not defined. Feeds: Risks, DoR-gaps.
+- **F2 Components** — Are components/services and their responsibilities, boundaries, and contracts defined? covered = decomposition + ownership + contracts; partial = components named without boundaries. Feeds: Suggestions, Insights.
+- **F3 Error flows** — Are error states, exception paths, failure handling, and input validation defined per flow? covered = per-flow error taxonomy + user-facing messages; missing = happy-path only. Feeds: Risks, Open Questions.
+- **F4 Data integrity & validation** — Validation rules, constraints, idempotency, persistence correctness. Feeds: Risks.
+- **F5 Interoperability & contracts** — External API/system contracts, backward/forward compatibility. Feeds: Risks, DoR-gaps.
+- **F6 Edge cases & boundaries** — Identified and handled? Feeds: Open Questions, Risks.
+- **F7 Security-relevant functional requirements** — authn/authz/access-control flows (cross-ref, not duplicating security-audit). Feeds: Risks.
+
+## Dimension: U — Usability
+
+User-interface quality: error prevention, aesthetics, help/docs, consistency/standards.
+
+- **U1 Error prevention** — Does the design prevent user errors (destructive-action confirmations, validation messages, undo)? Cross-ref F3. Feeds: Suggestions.
+- **U2 Aesthetics & design consistency.** Feeds: Suggestions.
+- **U3 Help & documentation** — user-facing docs/help planned? Feeds: DoR-gaps.
+- **U4 Consistency & standards** — design-system adherence, patterns. Feeds: Suggestions.
+- **U5 Accessibility (a11y)** — WCAG, contrast, keyboard, screen-reader. Feeds: Risks, DoR-gaps.
+- **U6 Internationalization/localization (i18n/l10n).** Feeds: DoR-gaps.
+- **U7 Onboarding & learnability.** Feeds: Suggestions.
+
+## Dimension: R — Reliability
+
+Integrity, compliance, interoperability: failure frequency/severity, recoverability, predictability, accuracy, MTBF.
+
+- **R1 Failure frequency & severity** — assumptions stated? Feeds: Risks.
+- **R2 Recoverability** — retry, idempotency, rollback, compensation. Feeds: Risks.
+- **R3 Predictability** — determinism, race conditions, ordering. Feeds: Risks.
+- **R4 Accuracy & precision** — guarantees stated? Feeds: Open Questions.
+- **R5 MTBF / availability / SLO targets.** Feeds: DoR-gaps, Risks.
+- **R6 Data-loss prevention** — backups, disaster recovery. Feeds: Risks.
+- **R7 Graceful degradation** under partial failure. Feeds: Suggestions.
+
+## Dimension: P — Performance
+
+Response time, memory, CPU, load capacity, availability.
+
+- **P1 Response-time targets / SLOs.** Feeds: DoR-gaps.
+- **P2 Memory-consumption bounds.** Feeds: Risks.
+- **P3 CPU utilization.** Feeds: Risks.
+- **P4 Load capacity / throughput / concurrency.** Feeds: DoR-gaps.
+- **P5 Scalability under load** (horizontal/vertical). Feeds: Suggestions.
+- **P6 Startup/warm-up, cold-start.** Feeds: Risks.
+- **P7 Resource quotas/limits.** Feeds: DoR-gaps.
+
+## Dimension: S — Supportability
+
+Testability, adaptability, maintainability, compatibility, configurability, installability, scalability, localizability.
+
+- **S1 Testability** — strategy, seams, fixtures, coverage targets. Feeds: DoR-gaps.
+- **S2 Maintainability** — modularity, coupling, readability, changeability. Feeds: Suggestions, Insights.
+- **S3 Adaptability/flexibility/extensibility.** Feeds: Suggestions.
+- **S4 Compatibility** (backward/forward, browser/OS/device). Feeds: Risks.
+- **S5 Configurability** (feature flags, env config). Feeds: Suggestions.
+- **S6 Installability/deployability/operability.** Feeds: DoR-gaps.
+- **S7 Observability** — logging, metrics, tracing, alerting, runbooks. Feeds: Risks, DoR-gaps.
+- **S8 Localizability** (cross-ref U6). Feeds: DoR-gaps.
+
+## Dimension: X — FURPS+ Extensions
+
+Non-functional requirements beyond the five core ("+").
+
+- **X1 Design requirements/constraints** — languages, frameworks, tools, libraries, process. Feeds: Insights, Risks.
+- **X2 Implementation requirements** — mandatory standards, DB integrity policies, resource limits, operating environments. Feeds: Risks, DoR-gaps.
+- **X3 Interface requirements** — UI/system interface specs. Feeds: Open Questions.
+- **X4 Physical requirements** — hardware, device, network constraints. Feeds: Risks.
+
+## Cross-dimension note
+
+Some concerns span dimensions (e.g., error flows touch F3+R2+U1; components touch F2+S2). A `furps-analyst` may flag a cross-dimension concern in its findings, but must not expand its scope into another dimension. The main agent deduplicates and reconciles cross-dimension concerns during synthesis.

package/skills/massa-ai/references/furps/intake.md

@@ -0,0 +1,104 @@
+# FURPS+ Refinement Intake & Sub-agent Packet Contract
+
+Use this reference from `workflows/refinement/furps-refinement.md` during intake and before dispatching sub-agents. It defines source detection, DoR sourcing, the context-firewall, the bounded document packet, and the sub-agent packet contracts.
+
+## Source-type detection
+
+Detect the input source and resolve it before analysis:
+
+| Signal | Source type | Resolution |
+|---|---|---|
+| File path or glob | file | Read via file tool; apply context-firewall for large files |
+| Pasted text / inline block | text | Use directly; record as "pasted text" |
+| Jira issue key (`ABCD-123`) or URL | Jira | Atlassian MCP capability discovery (read-only) |
+| Confluence page URL | Confluence | Atlassian MCP capability discovery (read-only) |
+| Ambiguous / missing | — | Ask the user once for a concrete source (graceful degradation) |
+
+A run may combine sources (e.g., a Jira PRD epic + a Confluence ADR). Record every source and its timestamp.
+
+## Atlassian MCP (read-only capability discovery)
+
+This workflow only reads from Atlassian; it never creates issues or pages. Reuse the capability-discovery pattern from `references/ticket/atlassian-fix.md`:
+
+1. Inspect currently callable tools.
+2. Identify Atlassian MCP operations by capability and schema, not by provider-specific function name. Needed capabilities: Jira issue retrieval and Confluence page retrieval.
+3. Preflight availability. If no matching capability exists, fall back to file/text and state the skipped source.
+
+Do not assemble Jira/Confluence REST calls outside the MCP, and do not use the Jira CLI or browser automation as a fallback. If the MCP is absent, ask the user for the content as file/text.
+
+## Definition of Ready (DoR) sourcing
+
+DoR is optional context used to grade coverage. Resolve in order:
+
+1. DoR supplied explicitly in the input (file/text/inline).
+2. DoR referenced in Jira/Confluence (e.g., a DoR field or linked Confluence page) via Atlassian MCP.
+3. Built-in fallback DoR (below).
+
+If no DoR is available, use the built-in fallback and mark every DoR-gap finding with "no DoR supplied — fallback used". Never imply a DoR was applied when it was not.
+
+### Built-in fallback DoR
+
+- Clear problem statement and business value
+- Acceptance criteria (testable, unambiguous)
+- Scope boundaries and explicit out-of-scope
+- Identified dependencies and assumptions
+- Non-functional requirements (performance/reliability/security/usability) stated
+- Success metrics / measurable outcomes
+- Priority and ownership assigned
+- Open questions and risks documented
+
+## Context-firewall
+
+Before dispatching sub-agents, bound the document:
+
+- Carry section summaries plus pointers, not full raw text, when the document exceeds context-firewall thresholds.
+- Each sub-agent receives only its dimension's checklist section plus the relevant document sections plus DoR plus the Fool summary.
+- Sub-agents must summarize verbose content and return evidence/findings only, never raw dumps.
+
+## Bounded document packet
+
+The main agent builds one packet reused across sub-agents:
+
+- `projectId`, parent `workflowSessionId`
+- document sections (or summaries) with stable section IDs for citations
+- DoR criteria (resolved source)
+- recalled facts (budgeted `recall`): prior ADRs, accepted decisions, patterns
+- input source plus evidence timestamp
+- exclusions: out-of-scope dimensions and sibling-workflow targets
+
+## Sub-agent packet contracts
+
+### plan-critic (The Fool) — evidence_audit
+
+- role: `plan-critic`; mode: `evidence_audit`
+- purpose: grade whether the PRD/ADR claims are source-backed, complete, falsifiable
+- scope: the document as the challenged thesis
+- permissions: read-only
+- inputs: document packet, DoR, recalled facts
+- sensors: source-location proof for each claim; absent-claim detection
+- output: Fool critique contract (mode, steelmanned thesis, 3-5 challenges, severity, affected section, evidence gap, required revision, confidence impact, next step)
+- firewall: summarize the document; no raw dumps
+- memory: suggest only
+
+### plan-critic (The Fool) — pre_mortem
+
+- role: `plan-critic`; mode: `pre_mortem`
+- purpose: anticipate execution-phase failures of the proposed solution
+- inputs: document packet, DoR, recalled facts, AND the evidence_audit summary
+- output: Fool critique contract, focused on failure narratives
+- otherwise identical to evidence_audit
+
+Dispatch `pre_mortem` after `evidence_audit` returns, so it can build on identified gaps.
+
+### furps-analyst — one per dimension (F, U, R, P, S, X)
+
+- role: `furps-analyst`; dimension: `<letter>`
+- purpose: analyze one FURPS+ dimension against its checklist section
+- scope: the assigned dimension's check items only
+- permissions: read-only
+- inputs: document packet, DoR, the Fool summary, the dimension's `checklist.md` section
+- sensors: quote/section citation per check item; absent-claim detection
+- output: per check-item status (`covered|partial|missing|unclear`) plus `FR-<letter>-<N>` findings plus contributions to Open Questions / Suggestions / Insights / Risks / DoR-gaps
+- firewall: summarize the document; no raw dumps
+- memory: suggest only
+- parallelism: all six dispatch in parallel; batch if a concurrency cap applies

package/skills/massa-ai/references/furps/report-contract.md

@@ -0,0 +1,140 @@
+# FURPS+ Refinement Report Contract
+
+Use this reference from `workflows/refinement/furps-refinement.md` before writing the final report. It extends the shared `references/audit-report-io.md` single-lens contract with FURPS-specific sections and the required refinement outputs (open questions, suggestions, insights, risks, DoR coverage gaps).
+
+## Report path
+
+```text
+audits/refinement/<YYYY-MM-DD furps-refinement>.md
+```
+
+Use the local current date. Create `audits/refinement/` when missing. Same-day same-target collisions use `-2`, `-3`; never silently overwrite a different run.
+
+## Plan Mode save rule
+
+In Plan Mode, do not write the report file. Return the proposed canonical path and the complete report content. In Default mode, write the canonical report.
+
+## Report schema
+
+```md
+# FURPS+ Refinement Report
+
+Date: <YYYY-MM-DD>
+Workflow: furps-refinement
+ProjectId: <projectId>
+WorkflowSessionId: <furps-refinement-[entity]>
+Target: <PRD/ADR title or id>
+Target Focus: <file path, Jira key, Confluence URL, or "pasted text">
+Scope: <PRD | ADR | PRD+ADR>
+Input Source: <file | text | Jira:<key> | Confluence:<url>>
+DoR Source: <file | Jira | Confluence | built-in fallback | none>
+Source Evidence Timestamp: <YYYY-MM-DD HH:MM local, or unavailable>
+The Fool Validation: <modes run, compact summary, gating decision>
+
+## Executive Summary
+
+<one-paragraph readiness verdict; counts by severity; whether DoR is satisfied>
+
+## The Fool Pre-Validation
+
+<evidence_audit findings + pre_mortem findings; source-confidence gaps; execution-phase failure assumptions; the gating decision (proceed / proceed-with-caveats / paused)>
+
+## Functionality (F)
+
+<per check-item status; FR-F-<N> findings>
+
+## Usability (U)
+
+<… FR-U-<N>>
+
+## Reliability (R)
+
+<… FR-R-<N>>
+
+## Performance (P)
+
+<… FR-P-<N>>
+
+## Supportability (S)
+
+<… FR-S-<N>>
+
+## FURPS+ Extensions (X)
+
+<Design / Implementation / Interface / Physical; FR-X-<N>>
+
+## Open Questions
+
+<numbered unresolved questions for stakeholders>
+
+## Suggestions
+
+<prioritized concrete improvements>
+
+## Insights
+
+<non-obvious learnings or patterns surfaced>
+
+## Risks
+
+<severity-ordered; each with impact and mitigation>
+
+## Definition of Ready — Coverage Gaps
+
+<DoR criteria not satisfied by the document; if no DoR was supplied, state the built-in fallback used and list fallback gaps>
+
+## Ruled-Out Candidates
+
+<plausible concerns disproved by evidence, or "None">
+
+## Scope And Evidence
+
+<inputs inspected, DoR source, commands/searches, skipped checks, residual risk>
+
+## Verification/Test Fidelity Checklist
+
+| Item | Evidence |
+|---|---|
+| Deterministic sensor | <command, static scan, artifact inspection, or not available with reason> |
+| Result | <pass, fail, not run, or not applicable> |
+| Coverage target | <FR ID, no-finding claim, check item, or validation asset> |
+| Validation assets protected | <tests, specs, fixtures, acceptance criteria, or none> |
+| Skipped-check reason | <none or allowed reason> |
+| Execution handoff | <verification command/artifact for every actionable finding> |
+
+## Execution Handoff
+
+<ordered actionable FR-* IDs, dependencies, and suggested next workflow (e.g., spec-driven to fill gaps, requirements-audit after implementation, adr/rfc for open decisions)>
+```
+
+## Finding fields
+
+Every finding uses the prefix `FR-<letter>-<N>` where `<letter>` is `F|U|R|P|S|X`.
+
+```md
+### FR-<letter>-<N>: <short title>
+
+Dimension: F | U | R | P | S | X
+Severity: critical | high | medium | low
+Confidence: high | medium | low
+Check Item: <checklist item ID, e.g. F3>
+Status: covered | partial | missing | unclear
+Location: <PRD/ADR section or quote, or n/a>
+Evidence: <concrete quote or documented absence>
+Impact: <risk or cost if unaddressed>
+Simplest Fix Direction: <smallest sufficient change>
+Verification Suggestion: <deterministic command, test, or artifact check>
+```
+
+If a required field is unknown, write `Unknown` and explain the evidence gap. Execution treats unknown required fields as a stop condition unless the user explicitly accepts the risk after revalidation.
+
+## Severity rules
+
+- `critical`: blocks release, causes data loss, breaks auth/privacy, or invalidates core value.
+- `high`: missing/contradictory core requirement, major compatibility break, or a gap that will surface as an execution-phase failure.
+- `medium`: incomplete edge case, unclear acceptance gap, recoverable mismatch, or missing docs/test around a requirement.
+- `low`: minor ambiguity, wording mismatch, low-impact gap, or weakly supported concern.
+
+## Confidence
+
+`high` = source-backed by an explicit quote; `medium` = inferred from context; `low` = plausible but unverified. Low-confidence suspects stay in Scope And Evidence unless the user explicitly asks to investigate.

package/skills/massa-ai/references/hook-enforcement.md

@@ -0,0 +1,137 @@
+# Hook Enforcement
+
+Maps the runtime hook layer (`scripts/hooks/`, `hooks/hooks.json`) to massa-ai
+workflows and references, and documents the massa-ai dual-write/tag contract.
+Hooks **enforce** existing references and the gate the router already selected;
+they never re-author policy and never re-route. One canonical location per rule.
+
+## Platform Scoping
+
+The full hook graph installs for **Claude Code, Codex, and Cursor**. OpenCode has
+no hook model and keeps the `AGENTS.md` bootstrap only. The installer
+(`scripts/agent_integrations.py`) preserves unrelated user hooks on install and
+uninstall via managed-command tracking.
+
+Platform hook formats differ; the installer translates one canonical graph
+(`hooks/hooks.json`, PascalCase events) into each platform's native shape:
+
+| Platform | Format | Event names | Matcher notes |
+|---|---|---|---|
+| Claude Code | nested `settings.json` `hooks.<Event>[{matcher, hooks:[{type,command}]}]` | `PreToolUse`, `PostToolUse`, `Stop`, `PreCompact`, `SessionStart` (PascalCase) | `Edit\|Write` |
+| Codex | nested `hooks.json` (same shape as Claude) | same PascalCase events | same as Claude |
+| Cursor | flat `hooks.json` `hooks.<event>[{command, matcher?}]` | `preToolUse`, `postToolUse`, `stop`, `preCompact`, `sessionStart` (camelCase) | tool names differ: `Edit` → `Write` (no Edit tool in Cursor) |
+
+Blocking semantics: Claude and Codex honor the `{"decision":"block","reason"}`
+JSON output. Cursor's flat protocol differs; blocking hooks (`gateguard`,
+`config_protection`) still run and nudge, but Cursor's denial is best-effort.
+The non-blocking hooks (observe, context_monitor, suggest_compact,
+continuous_learning_evaluate, precompact_save_state, stop_evidence_gate) work
+identically across all three platforms (read stdin JSON, emit JSON, stderr
+nudge, exit 0).
+
+## Environment Flags
+
+| Flag | Values | Effect |
+|---|---|---|
+| `MASSA_AI_HOOK_PROFILE` | `minimal` \| `standard` \| `strict` | `minimal`: only blocking safety hooks (gateguard, config_protection). `standard` (default): blocking + nudges + observation + stop gate as nudge. `strict`: stop gate blocks once per session to force acknowledgment. |
+| `MASSA_AI_DISABLED_HOOKS` | comma-separated hook names | Skip named hooks entirely. |
+
+Every hook exits 0 on bad stdin or non-critical error. Blocking hooks are
+<200 ms and make no network calls. Observation hooks are non-blocking.
+
+## Hooks → Enforced Reference
+
+| Hook | Event | Enforces |
+|---|---|---|
+| `stop_evidence_gate.py` | Stop | `references/evidence-gate.md` |
+| `continuous_learning_evaluate.py` | Stop | `references/lessons.md`, `scripts/lessons.py` |
+| `precompact_save_state.py` | PreCompact | `workflows/long-session.md`, `references/context-firewall.md` |
+| `suggest_compact.py` | PreToolUse(Edit\|Write) | `references/context-firewall.md` (compaction boundary) |
+| `gateguard_fact_force.py` | PreToolUse(Edit) | `references/context-firewall.md` (investigate-before-edit) |
+| `config_protection.py` | PreToolUse(Edit\|Write) | `references/verification-ladder.md` (scope) |
+| `observe_runner.py` | PostToolUse | `references/lessons.md` (observation buffer) |
+| `context_monitor.py` | PostToolUse | `references/verification-ladder.md` (task sizing/scope) |
+
+## Workflow-Aware Stop Gate
+
+`stop_evidence_gate.py` reads the active `workflow` from `.specs/project/STATE.md`
+and selects the workflow-specific gate. When `workflow` is unset or STATE is
+absent, it falls back to the flat evidence matrix (graceful degradation).
+
+| Workflow | `stop_evidence_gate` applies |
+|---|---|
+| `architecture-fix` | verification-fix gate (`references/verification-ladder.md`) |
+| `bugs-fix` | verification-fix gate |
+| `code-quality-fix` | verification-fix gate |
+| `implementation-fix` | verification-fix gate |
+| `maestro-fix` | verification-fix gate |
+| `mobile-figma-fix` | verification-fix gate |
+| `requirements-fix` | verification-fix gate |
+| `security-fix` | verification-fix gate |
+| `tests-fix` | verification-fix gate |
+| `spec-driven` | `validation.md` verdict = Pass; 3-iteration cap |
+| `debug` | reproduction no longer fails |
+| `feature` | lite evidence matrix (`references/evidence-gate.md`) |
+| `refactor` | lite evidence matrix |
+| `exploration` | no-mutation gate (read-only invariant) |
+| `architecture-audit` | flat evidence matrix |
+| `bugs-audit` | flat evidence matrix |
+| `code-quality-audit` | flat evidence matrix |
+| `implementation-audit` | flat evidence matrix |
+| `maestro-audit` | flat evidence matrix |
+| `mobile-figma-audit` | flat evidence matrix |
+| `requirements-audit` | flat evidence matrix |
+| `security-audit` | flat evidence matrix |
+| `tests-audit` | flat evidence matrix |
+| `furps-refinement` | flat evidence matrix (findings-only; report written + DoR coverage gaps listed) |
+| `adr` | flat evidence matrix |
+| `commit` | flat evidence matrix |
+| `design` | flat evidence matrix |
+| `general` | flat evidence matrix |
+| `long-session` | flat evidence matrix |
+| `maestro` | flat evidence matrix |
+| `onboarding` | flat evidence matrix |
+| `rfc` | flat evidence matrix |
+| `tdd` | flat evidence matrix |
+| `the-fool` | flat evidence matrix |
+| `ticket` | flat evidence matrix |
+
+## massa-ai Dual-Write / Tag Contract
+
+The continuous-learning loop writes two stores, not one:
+
+- `lessons.py add` / `import` — deterministic grounded file store
+  (`.specs/lessons.json`); refuses ungrounded lessons; promotion/quarantine.
+- `remember` — durable memory, best-effort via REST (`MASSA_AI_API_URL`),
+  file-only fallback when REST is unavailable.
+
+**Type:** always `pattern` (lessons are procedural knowledge) or `decision`
+(when a lesson captures a chosen trade-off). `procedural` is a **tag**, never a
+type — massa-ai supports only `critical | conversation | code | decision | pattern`
+(`references/mcp-tools.md`).
+
+**Tags:** every massa-ai lesson write carries the full massa-ai persistence
+contract: `project:<projectId>`, `session:<workflowSessionId>`,
+`workflow:<type>`, `entity:<name>`, `memory:procedural`. This puts lessons in
+the same recall namespace as massa-ai decisions/patterns, so future
+`recall` surfaces them at Specify/Design.
+
+`PreCompact` (`precompact_save_state.py`) writes a massa-ai `critical` memory
+tagged `memory:working` for the active objective + exact next step before the
+window compacts; file-only fallback when REST is unavailable.
+
+## No SessionStart Recall Duplication
+
+massa-ai's router already runs budgeted `recall` on startup. The hook
+layer adds **no** competing SessionStart recall. The installer keeps the
+existing SessionStart bootstrap (which transports `AGENTS.md` policy); memory
+recall stays owned by the router.
+
+## Graceful Degradation
+
+| Failure | Behavior |
+|---|---|
+| massa-ai REST unavailable | lesson still lands in `lessons.json`; skipped memory write logged to `scripts/hooks-state/skip.log` |
+| `.specs/STATE.md` absent / workflow unset | stop gate falls back to flat matrix |
+| bad / malformed stdin | hook exits 0, never blocks |
+| hook non-critical error | exit 0, approve, log skip |

package/skills/massa-ai/references/implementation-delivery.md

@@ -0,0 +1,101 @@
+# Implementation Delivery Protocol
+
+Use this reference in every implementation workflow, before the first repository
+mutation. It defines how verified work leaves the agent's hands: isolated in a
+worktree, committed atomically, pushed, proposed as a pull request, watched
+through CI, repaired if red — and merged only after the user says so.
+
+Read-only workflows (`*-audit`, `exploration`, `the-fool`) never load this file.
+They do not mutate, so they have nothing to deliver.
+
+## Principle
+
+Work that is not isolated, not pushed, and not tested by CI is not delivered —
+it is a local opinion. The protocol turns "I finished" into "CI agrees, and a
+human chose to merge it".
+
+## The Chain
+
+| # | Stage | Command | On failure |
+| --- | --- | --- | --- |
+| 0 | Preflight | `git rev-parse --is-inside-work-tree`; `command -v gh`; `gh auth status` | Record which capabilities are absent and select the degraded path below |
+| 1 | Isolate | `git fetch origin <base> && git worktree add -b <type>/<slug> <path> origin/<base>` | Branch name taken → suffix `-2`. Worktree path taken → reuse it only if its branch matches |
+| 2 | Implement | one task → gate → `git commit` | Gate red → fix before committing. Never commit through a failing gate |
+| 3 | Push | `git push -u origin <type>/<slug>` | Rejected non-fast-forward → `git fetch` + rebase, never force-push a shared branch |
+| 4 | Propose | `gh pr create --base <base> --title <t> --body <b>` | `gh` absent/unauthenticated → degraded path |
+| 5 | Watch | `gh pr checks --watch` | No checks configured → say so; do not claim CI passed |
+| 6 | Repair | fix on the branch, commit, return to stage 5 | Capped at 3 iterations, then stop as `Blocked` |
+| 7 | **Ask** | report the PR URL and the green check list, then **stop** | — |
+
+### Stage 1 — worktree isolation is mandatory
+
+Every implementation task runs in its own git worktree. There is **no size
+exemption**: a one-line typo fix is isolated exactly like a twelve-file feature.
+The reason is that the exemption, not the ceremony, is what costs time —
+"this one is too small to isolate" is the judgment call that puts half-finished
+work on a shared branch.
+
+The only two legal skip reasons:
+
+1. The target is not a git repository.
+2. The user explicitly declined isolation for this task.
+
+Record the skip reason verbatim in the completion report. Any other reason is a
+protocol violation, not a shortcut.
+
+Set up the worktree's dependencies before the first gate — a fresh worktree has
+no `node_modules`, no `dist`, and no `.env`. A gate that fails only because the
+worktree was never provisioned is an environment failure; say so rather than
+reporting it as a code failure.
+
+### Stage 2 — one commit per task
+
+Commit message content, staging rules, audit-report exclusions, and Jira
+prefixes are owned by `workflows/commit.md`. Do not restate them here; invoke
+that workflow. This reference owns only the cadence: **one atomic commit per
+completed task, after its gate passes.** Never batch tasks into one commit and
+never commit a task whose gate is red.
+
+### Stage 7 — merge is never automatic
+
+Do not run `gh pr merge` without explicit user approval given in the current
+session. Approval for one PR does not carry to the next. When CI is green,
+report:
+
+- the PR URL,
+- the check names that passed,
+- what is still unverified (skipped jobs, absent checks),
+
+then stop and ask. If the user approves, merge with the repository's configured
+strategy and delete the branch. If the repository auto-releases on merge, say so
+in the same message — the user is approving a release, not just a merge.
+
+## Degraded Paths
+
+| Missing capability | Behavior |
+| --- | --- |
+| `gh` not installed or not authenticated | Run stages 0–3, then stop. Report the pushed branch and the exact `gh pr create` command the user can run. Record `pr: skipped — gh unavailable` |
+| No remote configured | Run stages 0–2. Report local commits and the branch name. Record `push: skipped — no remote` |
+| Not a git repository | Run stage 2's gate discipline only. Record `isolation: skipped — not a repository` |
+| Repository has no CI | Run stages 0–4, then stop at stage 7 with `ci: no checks configured` |
+| CI is red after 3 repair iterations | Stop as `Blocked`. Preserve the failing check output and the hypotheses already ruled out; do not merge, do not disable the check |
+
+A skipped stage is always reported. Silence reads as success, and a stage that
+silently did not run is worse than one that loudly failed.
+
+## Anti-Patterns
+
+- Committing directly to `main` or the default branch.
+- Force-pushing a branch that has an open PR.
+- Weakening, skipping, or deleting a test to turn CI green — see
+  `references/root-cause-scripts.md` when a check keeps failing.
+- Merging because CI passed. CI passing is the precondition for asking, not the
+  approval itself.
+- Reporting "done" while the branch is unpushed.
+
+## Completion Evidence
+
+The delivery section of the Evidence Gate reports, in one block: worktree path,
+branch, commit hashes with their tasks, PR URL, CI verdict per check, repair
+iterations used, skipped stages with reasons, and the merge decision (approved,
+declined, or awaiting the user).