compound-workflow 1.0.1 → 1.1.0

package/README.md

@@ -62,10 +62,10 @@ flowchart LR
 | Step | Intent | Command | Output / note |
 |------|--------|---------|---------------|
 | Clarify what to build | Dialogue only; no code | `/workflow:brainstorm [topic]` | `docs/brainstorms/` |
-| Define how (fidelity + confidence) | Plan only; no code | `/workflow:plan [description or brainstorm path]` | `docs/plans/` |
-| Execute | File-based todos; risk-tier testing; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
-| Ready the queue | Priority and dependencies for pending todos | `/workflow:triage` | — |
-| Validate quality | Evidence-based review; no fixes by default | `/workflow:review [PR, branch, or current]` | pass / pass-with-notes / fail |
+| Define how (fidelity + confidence) | Plan only; no code; include agentic access + validation contract | `/workflow:plan [description or brainstorm path]` | `docs/plans/` |
+| Execute | File-based todos; risk-tier testing; evidence-backed completion; no auto-ship | `/workflow:work <plan-path>` | `todos/` |
+| Ready the queue | Priority/dependencies + executable agentic contract checks for pending todos | `/workflow:triage` | — |
+| Validate quality | Evidence-based review + agentic executability checks; no fixes by default | `/workflow:review [PR, branch, or current]` | pass / pass-with-notes / fail |
 | Capture learnings | One solution doc for future use | `/workflow:compound [context]` | `docs/solutions/` |
 | Log and improve | Session log + optional aggregate review | `/metrics` + `/assess weekly 7` (or monthly) | `docs/metrics/daily/`, weekly/monthly |
 
@@ -75,19 +75,19 @@ flowchart LR
 
 #### 2. Define how (plan)
 
-**Intent:** Plan only; no code; fidelity + confidence. **Command:** `/workflow:plan [description or brainstorm path]`. **Output:** `docs/plans/`.
+**Intent:** Plan only; no code; fidelity + confidence; include an agentic access + validation contract. **Command:** `/workflow:plan [description or brainstorm path]`. **Output:** `docs/plans/`.
 
 #### 3. Execute (work)
 
-**Intent:** File-based todos; risk-tier testing; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
+**Intent:** File-based todos; risk-tier testing; success-criteria evidence + quality gates before completion; no auto-ship. **Command:** `/workflow:work <plan-path>`. **Output:** `todos/`.
 
 #### 4. Ready the queue (triage)
 
-**Intent:** Priority and dependencies for pending todos. **Command:** `/workflow:triage`. **Output:** —.
+**Intent:** Priority/dependencies for pending todos and readiness checks for agentic executability. **Command:** `/workflow:triage`. **Output:** —.
 
 #### 5. Validate quality (review)
 
-**Intent:** Evidence-based review; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
+**Intent:** Evidence-based review + agentic validation coverage checks; no fixes by default. **Command:** `/workflow:review [PR|branch|current]`. **Output:** pass / pass-with-notes / fail.
 
 #### 6. Capture learnings (compound)
 
@@ -147,6 +147,10 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 - **Brainstorm and plan do not write code.** Output is documents only.
 
+- **Todo completion requires evidence:** acceptance/success criteria plus quality gates must be recorded before `complete`.
+
+- **Quality gate fallback:** if `lint_command` or `typecheck_command` is missing from repo config, workflow asks once for run-provided commands and continues only if they pass.
+
 - Add a separate shipping command if you want automated commit/PR and quality gates.
 
 ---
@@ -161,7 +165,7 @@ Full “when to use what” and reference standards: [src/AGENTS.md](src/AGENTS.
 
 ## Configuration and optional bits
 
-**Repo configuration:** Commands read a **Repo Config Block** (YAML) in `AGENTS.md` for `default_branch`, `dev_server_url`, `test_command`, etc. Run **`/install`** once; then edit `AGENTS.md` to set the Repo Config Block.
+**Repo configuration:** Commands read a **Repo Config Block** (YAML) in `AGENTS.md` for `default_branch`, `dev_server_url`, `test_command`, `lint_command`, `typecheck_command`, etc. Run **`/install`** once; then edit `AGENTS.md` to set the Repo Config Block.
 
 **agent-browser:** `/test-browser` uses the agent-browser CLI only. Install: `npm install -g agent-browser` then `agent-browser install`. See [src/.agents/commands/test-browser.md](src/.agents/commands/test-browser.md).
 

package/package.json

@@ -1 +1 @@
-{"name":"compound-workflow","version":"1.0.1","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}
+{"name":"compound-workflow","version":"1.1.0","description":"Clarify → plan → execute → verify → capture. One Install action for Cursor, Claude, and OpenCode.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/cjerochim/compound-workflow.git"},"bin":{"compound-workflow":"scripts/install-cli.mjs"},"files":["src","scripts",".cursor-plugin",".claude-plugin","skills"],"engines":{"node":">=18"},"devDependencies":{"@semantic-release/git":"^10.0.1","@semantic-release/npm":"^13.1.4","semantic-release":"^25.0.3"}}

package/scripts/install-cli.mjs

@@ -184,10 +184,29 @@ function hasCommand(cmd) {
 
 const SKILLS_SYMLINK_PATH = ".agents/compound-workflow-skills";
 
+function symlinkPointsTo(linkPath, expectedTargetAbs) {
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (!stat.isSymbolicLink()) return false;
+    const rawTarget = fs.readlinkSync(linkPath);
+    const linkTargetAbs = path.resolve(path.dirname(linkPath), rawTarget);
+    return realpathSafe(linkTargetAbs) === realpathSafe(expectedTargetAbs);
+  } catch {
+    return false;
+  }
+}
+
+function removePathIfExists(linkPath) {
+  try {
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  } catch {}
+}
+
 function ensureSkillsSymlink(targetRoot, dryRun) {
   const agentsDir = path.join(targetRoot, ".agents");
   const linkPath = path.join(agentsDir, "compound-workflow-skills");
   const targetRel = path.join("..", "node_modules", "compound-workflow", "src", ".agents", "skills");
+  const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
 
   if (dryRun) {
     console.log("[dry-run] Would create", SKILLS_SYMLINK_PATH, "symlink");
@@ -199,16 +218,15 @@ function ensureSkillsSymlink(targetRoot, dryRun) {
   let needCreate = true;
   try {
     const stat = fs.lstatSync(linkPath);
-    if (stat.isSymbolicLink()) {
-      fs.realpathSync(linkPath);
-      needCreate = false;
+    if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
+    else if (!stat.isSymbolicLink()) {
+      console.warn("Skipped", SKILLS_SYMLINK_PATH, "because it exists and is not a symlink");
+      return;
     }
   } catch (_) {}
 
   if (needCreate) {
-    try {
-      fs.unlinkSync(linkPath);
-    } catch (_) {}
+    removePathIfExists(linkPath);
     const type = process.platform === "win32" ? "dir" : "dir";
     fs.symlinkSync(targetRel, linkPath, type);
     console.log("Created", SKILLS_SYMLINK_PATH, "-> package skills");
@@ -223,6 +241,7 @@ function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, lab
 
   const linkPath = path.join(cursorDir, cursorSubdir);
   const targetRel = path.join("..", "node_modules", "compound-workflow", "src", ".agents", pkgSubdir);
+  const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
 
   if (dryRun) {
     console.log("[dry-run] Would create .cursor/" + cursorSubdir, "symlink (Cursor)");
@@ -232,16 +251,15 @@ function ensureCursorDirSymlink(targetRoot, cursorSubdir, pkgSubdir, dryRun, lab
   let needCreate = true;
   try {
     const stat = fs.lstatSync(linkPath);
-    if (stat.isSymbolicLink()) {
-      fs.realpathSync(linkPath);
-      needCreate = false;
+    if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
+    else if (!stat.isSymbolicLink()) {
+      console.warn("Skipped", ".cursor/" + cursorSubdir, "because it exists and is not a symlink");
+      return;
     }
   } catch (_) {}
 
   if (needCreate) {
-    try {
-      fs.unlinkSync(linkPath);
-    } catch (_) {}
+    removePathIfExists(linkPath);
     const type = process.platform === "win32" ? "dir" : "dir";
     fs.symlinkSync(targetRel, linkPath, type);
     console.log("Created", ".cursor/" + cursorSubdir, "->", label || pkgSubdir, "(Cursor)");
@@ -280,19 +298,19 @@ function ensureCursorSkills(targetRoot, dryRun) {
   for (const name of skillNames) {
     const linkPath = path.join(skillsDir, name);
     const targetRel = path.join("..", "..", "..", "node_modules", "compound-workflow", "src", ".agents", "skills", name);
+    const targetAbs = path.resolve(path.dirname(linkPath), targetRel);
     let needCreate = true;
     try {
       const stat = fs.lstatSync(linkPath);
-      if (stat.isSymbolicLink()) {
-        fs.realpathSync(linkPath);
-        needCreate = false;
+      if (stat.isSymbolicLink() && symlinkPointsTo(linkPath, targetAbs)) needCreate = false;
+      else if (!stat.isSymbolicLink()) {
+        console.warn("Skipped", ".cursor/skills/" + name, "because it exists and is not a symlink");
+        continue;
       }
     } catch (_) {}
 
     if (needCreate) {
-      try {
-        fs.unlinkSync(linkPath);
-      } catch (_) {}
+      removePathIfExists(linkPath);
       fs.symlinkSync(targetRel, linkPath, type);
       console.log("Created", ".cursor/skills/" + name, "-> package skill (Cursor)");
     }

package/src/.agents/commands/workflow/plan.md

@@ -147,6 +147,34 @@ Select one: `High | Medium | Low`
 
 If confidence is `Low`, ask 1-2 focused clarifying questions before finalizing the plan.
 
+#### Solution Scope (REQUIRED)
+
+Select one: `partial_fix | full_remediation | migration`
+
+- `partial_fix`: intentionally scoped fix with known follow-up gaps.
+- `full_remediation`: complete resolution for the defined problem boundary.
+- `migration`: phased or structural transition from an existing implementation/state to a new one.
+
+If unclear, ask one focused clarification before finalizing the plan.
+
+#### Spike Need Evaluation (REQUIRED for risky work)
+
+Determine whether spikes are needed before finalizing implementation structure.
+
+Risky work trigger set (extended):
+
+- Any high-risk domain trigger (security, payments, privacy, schema/data migrations or backfills, production infra/deployment risk, hard-to-reverse changes)
+- `confidence: low`
+- `solution_scope: migration`
+- Open questions that include implementation feasibility unknowns
+
+If risky work is detected:
+
+- Spike evaluation is mandatory.
+- Declare `spikes_needed: yes|no`.
+- If `spikes_needed: yes`, include explicit Spike Candidates with upfront dependency and priority modeling (see Step 3.5).
+- If `spikes_needed: no`, include a short rationale + risk mitigation note explaining why direct implementation is safe.
+
 #### Research Mode
 
 Decide whether to run external research.
@@ -170,6 +198,9 @@ Required announcement format:
 ```
 Fidelity selected: <Low|Medium|High>
 Confidence: <High|Medium|Low>
+Solution scope: <partial_fix|full_remediation|migration>
+Spike evaluation: required|not-required
+Spikes needed: yes|no|n/a
 
 Why this fidelity:
 1) ...
@@ -252,6 +283,50 @@ Think like a product manager - what would make this issue clear and actionable?
 - [ ] Gather supporting materials (error logs, screenshots, design mockups)
 - [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
 
+### 2.5. Solution Scope Contract (REQUIRED for all plans)
+
+Every plan MUST include an explicit scope contract so `/workflow:work` can enforce intent.
+
+Required contract fields:
+
+- `solution_scope`: one of `partial_fix | full_remediation | migration`
+- `completion_expectation`: explicit definition of done for this plan
+- `non_goals`: explicitly out of scope for this plan
+
+Rules:
+
+- If `solution_scope: partial_fix`, include a **Remaining Gaps** checklist (`- [ ]`) with expected follow-up work.
+- If `solution_scope: migration`, include migration strategy, rollout safety checks, and rollback triggers/steps.
+- If `solution_scope: full_remediation`, define the remediation boundary so completion is unambiguous.
+
+Placement:
+
+- Put `solution_scope` in frontmatter.
+- Put `completion_expectation` and `non_goals` in a dedicated section (recommended: `## Scope Contract`) in the plan body.
+
+### 2.6. Agentic Access & Validation Contract (REQUIRED for all plans)
+
+Every plan MUST include an explicit contract describing how an agent will execute and verify the work without hidden assumptions.
+
+Required fields (per implementation phase/checklist group):
+
+- `Access Preconditions`: required services, credentials, fixtures, feature flags, env vars
+- `Access Method`: how the agent obtains required access in this repo/runtime
+- `Validation Path`: concrete commands/routes/checks the agent can run
+- `Evidence Required`: exact outputs/artifacts/logs used to prove success criteria
+- `Quality Gates`: `test_command`, `lint_command`, `typecheck_command` (configured or run-provided)
+
+Rules:
+
+- If any required access dependency is unknown, add a Discussion Point or Spike Candidate so it is triaged before execution.
+- A plan is not execution-ready until this contract is present and actionable.
+- Avoid placeholders like "validate manually" without a concrete agent-runnable path.
+
+Placement:
+
+- Add a dedicated section in the plan body: `## Agentic Access & Validation Contract`.
+- Reference this section from implementation phases/todos so `/workflow:work` can enforce it directly.
+
 ### 3. Incorporate SpecFlow (if Step 1.7 ran)
 
 If SpecFlow was run in Step 1.7:
@@ -259,9 +334,9 @@ If SpecFlow was run in Step 1.7:
 - [ ] Review SpecFlow analysis results
 - [ ] Ensure any identified gaps or edge cases are reflected in the issue structure and acceptance criteria
 
-### 3.5. Discussion Points & Spike Candidates (REQUIRED when Open questions ≠ none)
+### 3.5. Discussion Points & Spike Candidates
 
-When you declared Open questions in Step 1.5 (other than "none"), the plan file MUST include one or both of these sections with checkboxes so `/workflow:work` and `file-todos` can create pending todos for triage:
+When you declared Open questions in Step 1.5 (other than "none"), and/or when risky-work spike evaluation requires spikes, the plan file MUST include one or both sections below with checkboxes so `/workflow:work` and `file-todos` can create pending todos for triage:
 
 - **## Discussion Points (resolve/decide)** — Decisions to make (no code). Use `- [ ]` items (e.g. "Decide: X or Y?", "Confirm constraint Z").
 - **## Spike Candidates (timeboxed)** — Timeboxed investigations to de-risk. Use `- [ ] Spike: <short description>` items.
@@ -270,10 +345,34 @@ Rules:
 
 - If an unknown blocks implementation feasibility, prefer listing it under **Spike Candidates**.
 - If confidence is `Low`, include at least one checkbox in one of these sections.
+- If risky-work spike evaluation declared `spikes_needed: yes`, include at least one Spike Candidate checkbox.
 - These sections may appear after the main implementation content (e.g. after Acceptance Criteria or References) or in a dedicated "Unknowns & decisions" area; ensure they are in the written plan file when Open questions exist.
 
+Required Spike Candidate metadata (per candidate, documented directly under each checkbox item):
+
+- `Initial priority: p1|p2|p3`
+- `Depends on: <issue ids or none>`
+- `Unblocks: <build todo(s) or plan section(s)>`
+- `Timebox: <duration>`
+- `Deliverable: <options/recommendation/next build todos>`
+- `Parallelizable: yes|no`
+
+If a spike unblocks implementation work, mark it as a blocking spike in the candidate text so triage/work can front-load it.
+
 **When presenting Discussion Points (to the user or during triage):** (1) List a **concise numbered summary** of the points. (2) Walk through **each point one by one**; for each, discuss and align with the user; only then move on. Do not resolve all points in one turn.
 
+Example Spike Candidate:
+
+```markdown
+- [ ] Spike: Validate tenant-safe migration sequence for billing events
+  - Initial priority: p1
+  - Depends on: none
+  - Unblocks: "Implement migration executor + backfill safety checks"
+  - Timebox: 4h
+  - Deliverable: 3 options + recommendation + follow-up build todos
+  - Parallelizable: yes
+```
+
 ### 4. Choose Implementation Detail Level
 
 Select how comprehensive you want the issue to be. Fidelity should drive this choice.
@@ -307,12 +406,24 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
+solution_scope: [partial_fix|full_remediation|migration]
 ---
 
 # [Issue Title]
 
 [Brief problem/feature description]
 
+## Scope Contract
+
+- Completion expectation: [explicit done definition]
+- Non-goals:
+  - [out of scope item 1]
+  - [out of scope item 2]
+
+### Remaining Gaps (required if solution_scope = partial_fix)
+
+- [ ] [gap to handle later]
+
 ## Constraints
 
 [Key constraints (technical, scope, or policy)]
@@ -339,6 +450,17 @@ date: YYYY-MM-DD
 - [ ] How to verify requirement 1
 - [ ] How to verify requirement 2
 
+## Agentic Access & Validation Contract
+
+- Access Preconditions: [services/fixtures/env needed]
+- Access Method: [how agent gets access in this repo]
+- Validation Path: [commands/routes/checks]
+- Evidence Required: [logs/output/artifacts]
+- Quality Gates:
+  - test: [command]
+  - lint: [command or "ask once if not configured"]
+  - typecheck: [command or "ask once if not configured"]
+
 ## References
 
 - Related issue: #[issue_number]
@@ -367,6 +489,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
+solution_scope: [partial_fix|full_remediation|migration]
 ---
 
 # [Issue Title]
@@ -375,6 +498,17 @@ date: YYYY-MM-DD
 
 [Comprehensive description]
 
+## Scope Contract
+
+- Completion expectation: [explicit done definition]
+- Non-goals:
+  - [out of scope item 1]
+  - [out of scope item 2]
+
+### Remaining Gaps (required if solution_scope = partial_fix)
+
+- [ ] [gap to handle later]
+
 ## Problem Statement / Motivation
 
 [Why this matters]
@@ -417,6 +551,17 @@ date: YYYY-MM-DD
 
 [What to monitor; how to test and validate]
 
+## Agentic Access & Validation Contract
+
+- Access Preconditions: [services/fixtures/env needed]
+- Access Method: [how agent gets access in this repo]
+- Validation Path: [commands/routes/checks]
+- Evidence Required: [logs/output/artifacts]
+- Quality Gates:
+  - test: [command]
+  - lint: [command or "ask once if not configured"]
+  - typecheck: [command or "ask once if not configured"]
+
 ## References & Research
 
 - Similar implementations: [file_path:line_number]
@@ -446,6 +591,7 @@ title: [Issue Title]
 type: [feat|fix|refactor]
 status: active
 date: YYYY-MM-DD
+solution_scope: [partial_fix|full_remediation|migration]
 ---
 
 # [Issue Title]
@@ -454,6 +600,17 @@ date: YYYY-MM-DD
 
 [Executive summary]
 
+## Scope Contract
+
+- Completion expectation: [explicit done definition]
+- Non-goals:
+  - [out of scope item 1]
+  - [out of scope item 2]
+
+### Remaining Gaps (required if solution_scope = partial_fix)
+
+- [ ] [gap to handle later]
+
 ## Problem Statement
 
 [Detailed problem analysis]
@@ -542,6 +699,17 @@ date: YYYY-MM-DD
 
 [Test scenarios by dimension: env, role, data, edge cases]
 
+## Agentic Access & Validation Contract
+
+- Access Preconditions: [services/fixtures/env needed]
+- Access Method: [how agent gets access in this repo]
+- Validation Path: [commands/routes/checks]
+- Evidence Required: [logs/output/artifacts]
+- Quality Gates:
+  - test: [command]
+  - lint: [command or "ask once if not configured"]
+  - typecheck: [command or "ask once if not configured"]
+
 ## Resource Requirements
 
 [Team, time, infrastructure needs]
@@ -634,6 +802,12 @@ Apply best practices for clarity and actionability, making the issue easy to sca
 - [ ] Title is searchable and descriptive
 - [ ] Labels accurately categorize the issue
 - [ ] All template sections are complete
+- [ ] `solution_scope`, completion expectation, and non-goals are explicitly documented
+- [ ] `## Agentic Access & Validation Contract` is present and executable (no hidden/manual-only steps)
+- [ ] If `solution_scope = partial_fix`, Remaining Gaps checklist is present and actionable
+- [ ] If `solution_scope = migration`, migration safety checks + rollback triggers are specified
+- [ ] If risky-work triggers apply, Spike Evaluation is present with `spikes_needed: yes|no`
+- [ ] If `spikes_needed = yes`, each spike candidate has priority/dependency/timebox/deliverable/parallelizable metadata
 - [ ] Links and references are working
 - [ ] Acceptance criteria are measurable
 - [ ] Add names of files in pseudo code examples and todo lists
@@ -651,14 +825,19 @@ Write the complete plan file to `docs/plans/YYYY-MM-DD-<type>-<slug>-plan.md`. T
 
 **When Open questions were declared (Step 1.5):** The written plan MUST include at least one of: `## Discussion Points (resolve/decide)` with `- [ ]` items, or `## Spike Candidates (timeboxed)` with `- [ ] Spike: ...` items. If confidence is `Low`, at least one checkbox is required in one of these sections. This ensures `file-todos` can create pending discussion/spike todos for `/workflow:triage`.
 
+**When risky-work Spike Evaluation declared `spikes_needed: yes`:** The written plan MUST include `## Spike Candidates (timeboxed)` with at least one spike checkbox and required per-candidate metadata (`Initial priority`, `Depends on`, `Unblocks`, `Timebox`, `Deliverable`, `Parallelizable`) so ordering can be defined in plan, confirmed in triage, and enforced in work.
+
+**Execution-readiness gate:** If the written plan is missing the required `## Agentic Access & Validation Contract`, do not mark it as ready for `/workflow:work`; fix the plan first.
+
 Confirm: "Plan written to docs/plans/[filename]"
 
-**Non-interactive mode:** When the invocation is non-interactive (e.g., `workflow:plan` run by automation, CI, or with an explicit non-interactive flag/convention), skip AskQuestion calls and do not present Post-Generation Options. For determinism, the repo should define the flag or convention (e.g., in `AGENTS.md` Repo Config Block or a documented env var). Still **declare** Fidelity, Confidence, Research mode, and Open questions in the required announcement format before writing the plan. Use these defaults when user input is unavailable: fidelity = Medium, confidence = Medium, research mode = local + external for Medium/High risk topics else local only. Proceed directly to writing the plan file and then exit or return the plan path as output.
+**Non-interactive mode:** When the invocation is non-interactive (e.g., `workflow:plan` run by automation, CI, or with an explicit non-interactive flag/convention), skip AskQuestion calls and do not present Post-Generation Options. For determinism, the repo should define the flag or convention (e.g., in `AGENTS.md` Repo Config Block or a documented env var). Still **declare** Fidelity, Confidence, Solution scope, Spike evaluation, Spikes needed, Research mode, and Open questions in the required announcement format before writing the plan. Use these defaults when user input is unavailable: fidelity = Medium, confidence = Medium, solution_scope = full_remediation, spike evaluation = not-required unless risky-work triggers are present, spikes needed = n/a when spike evaluation is not required, research mode = local + external for Medium/High risk topics else local only. Proceed directly to writing the plan file and then exit or return the plan path as output.
 
 **Required in plan frontmatter:** Add these fields to the plan file:
 
 - `fidelity: low|medium|high`
 - `confidence: high|medium|low`
+- `solution_scope: partial_fix|full_remediation|migration`
 
 ## Output Format
 

package/src/.agents/commands/workflow/review.md

@@ -35,6 +35,7 @@ If empty, default to `current`.
 2. Resolve:
    - `default_branch` (fallback: `main`, then `master`)
    - `lint_command` (used in Phase 3)
+   - `typecheck_command` (used in Phase 3)
 
 State what you resolved or assumed.
 
@@ -43,13 +44,42 @@ State what you resolved or assumed.
 1. Determine target type from `$ARGUMENTS`: PR/URL, branch name, or `current`.
 2. If reviewing a PR and `gh` is available:
    - Fetch title/body/files via `gh pr view --json`
-   - Checkout the branch (direct checkout or via worktree)
+   - Resolve target branch metadata before selecting isolation context
 3. If target is a branch (not current):
-   - Ensure you are on the correct branch, or offer a worktree via `skill: git-worktree`
-4. If you are not on the target branch and user requested that target, offer a worktree via `skill: git-worktree`.
+   - Resolve isolation context before running review passes
+4. If you are not on the target branch and user requested that target, do not continue until isolation preflight is complete.
 
 Prefer reviewing the currently checked-out branch. Only switch branches or create worktrees when the user explicitly requests a different target.
 
+### Phase 1.5: Isolation Preflight Gate (HARD GATE for non-current targets)
+
+No diff analysis, lint, or reviewer-agent passes may run before this gate passes for non-current targets.
+
+Policy:
+
+- Target `current`: gate passes immediately on current checkout.
+- Target PR/branch not currently checked out:
+  - Default path: use `skill: git-worktree` for isolated review context.
+  - Opt-out path: explicit user confirmation to review without worktree, then switch to the requested non-default branch context.
+
+Gate completion record (REQUIRED for non-current targets):
+
+- `target_type: pr|branch|current`
+- `isolation_mode: worktree|direct-checkout`
+- `review_context_path` (worktree path) or `review_branch` (direct checkout)
+- `gate_status: passed`
+
+Never run non-current review from the default branch checkout without completing this gate.
+
+### Phase 1.6: Preflight Violation Recovery (REQUIRED)
+
+If review activity started before the isolation gate was complete:
+
+- Disclose the violation.
+- Stop analysis immediately.
+- Return to Phase 1.5 and complete the gate.
+- Resume only after `gate_status: passed`.
+
 Protected artifacts:
 
 - Never suggest deleting or ignoring `docs/plans/` or `docs/solutions/`.
@@ -71,6 +101,13 @@ Protected artifacts:
 
 - `Task learnings-researcher(<target context>)` (related prior solutions)
 - `Task lint(<changed files context>)` only if `lint_command` is configured in the Repo Config Block
+- Verify agentic executability from plan/todo artifacts when available:
+  - access prerequisites are explicit
+  - validation commands are explicit and reproducible
+  - success-criteria evidence is traceable in todo Work Logs
+- For type-checking coverage:
+  - if `typecheck_command` is configured, run it (or verify recent evidence if command execution is not feasible in this context)
+  - if not configured, report "typecheck command not configured" as a note and recommend adding it to Repo Config Block
 
 **Conditional passes** (run when they apply):
 
@@ -83,6 +120,7 @@ Then perform the main review synthesis across:
 - change summary (surface area, high-risk files)
 - correctness
 - tests/verification adequacy
+- agentic validation adequacy (can another agent execute and verify deterministically?)
 - risk and failure modes
 - operational considerations (monitoring, rollback)
 - readability/maintainability
@@ -98,6 +136,10 @@ Provide:
   - evidence (file references or commands/output)
   - recommended action (concise)
 - What ran vs skipped (selected agents/passes)
+- Validation coverage summary:
+  - tests: pass|fail|not-run
+  - lint: pass|fail|not-configured|not-run
+  - typecheck: pass|fail|not-configured|not-run
 
 ### Phase 5: Handoff Options
 

package/src/.agents/commands/workflow/triage.md

@@ -32,15 +32,24 @@ This command does not implement fixes. It approves and organizes work so `/workf
    - set `priority` (`p1|p2|p3`)
    - set `dependencies` (issue_ids)
    - ensure Acceptance Criteria is testable
+   - ensure the todo includes an explicit `Agentic Execution Contract`:
+     - access preconditions
+     - validation commands/routes/checks
+     - evidence expectations
+     - quality gate commands (`test`, `lint`, `typecheck`)
+   - if lint/typecheck commands are missing in repo config, mark Recommended Action with "ask once for run-provided commands before completion"
    - add/update tags for searchability
    - **When multiple todos have `tags: [discussion]`:** (1) List a **concise numbered summary** of the discussion points. (2) Walk through **each point one by one**; for each, discuss and align with the user before approving or deferring; only then move on. Do not resolve all discussion points in one turn.
    - **If the todo has `tags: [discussion]`:** Recommended Action must state the concrete decision task (what info is needed, who decides, done-when). Approve only when the outcome is a clear, executable decision task; otherwise defer.
-   - **If the todo has `tags: [spike]`:** Recommended Action must include a timebox and deliverable (e.g. "2–4h spike; deliver: options + recommendation + next build todos"). Set `dependencies` so that any build todos that depend on this spike's outcome list this todo's `issue_id`; when approving, ensure dependent build todos remain blocked until the spike is complete (they depend on the spike's `issue_id`). Approve only when the spike scope and deliverable are clear; otherwise defer.
+   - **If the todo has `tags: [spike]`:** Recommended Action must include a timebox and deliverable (e.g. "2–4h spike; deliver: options + recommendation + next build todos"). Confirm or adjust plan-provided spike metadata (initial priority, depends_on, unblocks, parallelizable). Set `dependencies` so that any build todos that depend on this spike's outcome list this todo's `issue_id`; when approving, ensure dependent build todos remain blocked until the spike is complete (they depend on the spike's `issue_id`). Approve only when the spike scope and deliverable are clear; otherwise defer.
+   - **Blocking spikes first:** If a spike unblocks downstream build todos, prioritize approving that spike before its dependents. Do not approve dependent build todos as executable ahead of unresolved blocking spikes.
+   - **Parallel spike readiness:** If multiple spike todos are independent (no dependency edges between them), they may be approved together for parallel execution.
 3. Decision:
-   - **approve now** -> rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready`
+   - **approve now** -> rename `*-pending-*` -> `*-ready-*` and set frontmatter `status: ready` (only when Acceptance Criteria and Agentic Execution Contract are executable)
    - **defer** -> rename `*-pending-*` -> `*-deferred-*` and set frontmatter `status: deferred` (keep priority, typically `p3`). Ensure Recommended Action, Findings, and Work Log have enough context for future reference. Deferred items are not executed until re-triaged to `ready`.
+   - **blocked follow-up** -> when work returns a blocked todo, keep it as `pending` (rename from `*-ready-*` when needed), add `tags: [blocker]`, and require blocker options + recommendation in Work Log before re-approval.
 4. Output:
-   - list approved `ready` todos (unblocked first)
+   - list approved `ready` todos (blocking spikes first, then other unblocked items)
    - list remaining pending todos
    - list deferred todos (parked for reference; not in executable queue)
    - list blocked todos with missing dependencies

package/src/.agents/commands/workflow/work.md

@@ -64,6 +64,7 @@ The input must be a plan file path.
    - `test_command`
    - `test_fast_command` (optional)
    - `lint_command` (optional)
+   - `typecheck_command` (optional)
    - `format_command` (optional)
 
    If not present, ask once for the project's test command and suggest adding it to `AGENTS.md`.
@@ -88,20 +89,59 @@ The input must be a plan file path.
    - Prefer `test_command` and optional `test_fast_command` from `AGENTS.md`.
    - If missing, ask once for the repo's test command and suggest adding it to `AGENTS.md`.
 
-2. **Setup Environment**
+1.6. **Agentic Access + Validation Preflight (HARD GATE)**
+
+   Before any implementation commands:
+
+   - Verify each `ready` todo has an executable Agentic Execution Contract:
+     - access preconditions are explicit
+     - validation path is explicit (commands/routes/checks)
+     - evidence expectations are explicit
+     - quality gate commands are explicit or marked for ask-once fallback
+   - If a todo lacks this contract, move it to `pending` for triage before coding.
+
+   Ask-once fallback policy for missing lint/typecheck config:
+
+   - If `lint_command` and/or `typecheck_command` is missing from `AGENTS.md`, ask once in this run for run-provided commands.
+   - Record run-provided commands in the first active todo Work Log entry.
+   - Continue only when provided commands run successfully.
+   - If commands are not provided or fail, do not mark related todos complete.
+
+1.75. **Resolve Plan Scope Contract (REQUIRED)**
+
+   Before any environment setup or implementation, resolve the plan's scope contract:
+
+   - `solution_scope`: `partial_fix | full_remediation | migration`
+   - `completion_expectation`: explicit definition of done
+   - `non_goals`: explicitly out of scope
+
+   If any scope-contract field is missing:
+
+   - Pause execution and ask the user to update the plan via `/workflow:plan`, or provide explicit values now.
+   - Record the resolved values in the first todo Work Log entry before coding.
+
+   Scope implications:
+
+   - `partial_fix`: maintain an explicit remaining-gaps list while executing.
+   - `migration`: identify migration verification + rollback checks before executing todos.
+   - `full_remediation`: complete all known gaps in the scoped area before completion.
+
+2. **Setup Environment (HARD GATE)**
 
    Determine how to isolate the work for this plan.
 
-   Default: use a worktree (recommended). The user may opt out.
+   No implementation commands or code edits may run before this gate passes.
+
+   Default: use a worktree. Opt-out requires explicit user confirmation.
 
    1) Resolve your current branch (this is the default worktree base):
 
    - If you are already on a branch that clearly matches this plan, continue.
    - Otherwise, continue anyway — the current active branch remains the reference/base for a new worktree unless the user explicitly requests a different base.
 
-   2) Ask the user (opt-out prompt):
+   2) Ask the user (required decision prompt):
 
-   - "Use a worktree for this work? (default: Yes; recommended for isolation)"
+   - "Use a worktree for this work? (default: Yes; required unless you explicitly opt out)"
    - Options:
      - Yes (worktree)
      - No (stay in current checkout; create/switch to a feature branch)
@@ -127,7 +167,24 @@ The input must be a plan file path.
 
    4) If worktree is not chosen (opt-out):
 
+   - Require explicit user confirmation of the opt-out.
    - Create or switch to a feature branch (never work directly on the default branch).
+   - Record the execution branch in a visible place.
+
+   Gate completion record (REQUIRED before Phase 2):
+
+   - `worktree_decision: yes|no`
+   - `worktree_path: <path>` when yes, else `execution_branch: <branch>`
+   - `gate_status: passed`
+
+2.5. **Preflight Violation Recovery (REQUIRED)**
+
+   If implementation starts before the hard gate above is completed:
+
+   - Immediately disclose the violation.
+   - Stop all implementation actions.
+   - Return to Step 2 and complete the gate record.
+   - Resume only after `gate_status: passed`.
 
 3. **Create Todo List**
 
@@ -171,13 +228,19 @@ The input must be a plan file path.
 
 1. **Task Execution Loop**
 
-   **When a worktree was created for this run:** All implementation edits (file reads/writes) and all terminal commands (run tests, install, lint, etc.) MUST be performed with the worktree directory as the working context: use the worktree path for file paths and set terminal cwd to the worktree root. Do not make code changes in the main repo checkout.
+   All implementation edits (file reads/writes) and all terminal commands (run tests, install, lint, etc.) MUST use the execution context resolved in Step 2.
+
+   - If `worktree_decision: yes`: use the worktree path for file paths and set terminal cwd to the worktree root. Do not make code changes in the main repo checkout.
+   - If `worktree_decision: no`: use the recorded execution branch context only (never default branch).
 
    Todo selection rules (default):
 
    - Consider only `todos/*-ready-*.md` items. Do not execute `pending` or `deferred` todos.
    - Skip blocked todos:
      - blocked if `dependencies` is non-empty and any dependency does not have a corresponding `*-complete-*.md` file.
+   - Prioritize blocking spikes first:
+     - if a ready spike todo unblocks downstream implementation todos, execute that spike before dependent build todos.
+     - independent ready spikes may run in parallel when environment/worktree setup supports it.
    - Prioritize by priority then id:
      - `p1` before `p2` before `p3`
      - lower `issue_id` first
@@ -230,6 +293,7 @@ The input must be a plan file path.
       - tests run
       - results
       - next steps
+      - status context (`ready`, `pending`, `complete`)
 
     Discovery + scope changes (ask each time):
 
@@ -243,11 +307,14 @@ The input must be a plan file path.
 
    **Validation Gate (per todo)**
 
-   Before marking a todo complete, you MUST prove the acceptance criteria are met.
+   Before marking a todo complete, you MUST prove acceptance/success criteria are met.
 
    For each todo:
-   - Re-state the acceptance criteria being validated (1–3 bullets)
+   - Re-state the acceptance/success criteria being validated (1–3 bullets)
    - Run the smallest verification that proves it (tests, command output, UI check)
+   - Run lint/typecheck quality gates for changed scope:
+     - `lint_command` when configured, else run the ask-once run-provided lint command
+     - `typecheck_command` when configured, else run the ask-once run-provided typecheck command
    - Record evidence in the todo Work Log:
      - commands run + results
      - files changed (paths)
@@ -257,6 +324,10 @@ The input must be a plan file path.
    - stop and fix immediately, or
    - if blocked, follow the Blocker Protocol.
 
+   Scope contract checks:
+   - If `solution_scope: partial_fix`, update remaining gaps in todo Work Log as they are discovered.
+   - If `solution_scope: migration`, record migration validation evidence and rollback readiness evidence before marking migration todos complete.
+
    **Blocker Protocol (pause implementation)**
 
    Trigger: you cannot proceed safely due to ambiguity, missing info, failing approach, or environment/tooling issue.
@@ -265,6 +336,7 @@ The input must be a plan file path.
    - Pause implementation. Do not “push through” with guesses.
    - Timebox investigation to reach options (not a full rewrite).
    - Produce at least 3 viable options.
+   - Immediately move the active todo back to `pending`, add/ensure `tags: [blocker]`, and record blocker status in Work Log.
 
    Output format (always):
    - Blocker summary (1–2 sentences)
@@ -277,6 +349,7 @@ The input must be a plan file path.
    - Convert the decision into explicit todos (implementation/investigation/deferral).
    - If the chosen option is to run a timeboxed investigation or prototype, follow the **Spike Protocol** below.
    - Record the decision + rationale in the todo Work Log.
+   - Re-approve the todo through `/workflow:triage` before returning it to `ready`.
 
    **Spike Protocol (allocate a spike)**
 
@@ -284,9 +357,9 @@ The input must be a plan file path.
 
    Steps:
 
-   1. **Spike todo:** Create a new `todos/*-pending-*.md` todo tagged `tags: [spike]` (or convert the current blocked todo to a spike todo). Fill Problem Statement, Proposed Solutions (options), and Acceptance Criteria (deliverable). If triage has not been run, recommend `/workflow:triage` to approve the spike and set timebox + deliverable; then treat the spike as `ready` once approved.
+   1. **Spike todo:** Create a new `todos/*-pending-*.md` todo tagged `tags: [spike]` (or convert the current blocked todo to a spike todo). Fill Problem Statement, Proposed Solutions (options), and Acceptance Criteria (deliverable). Carry forward any plan metadata (initial priority, depends_on, unblocks, parallelizable). If triage has not been run, recommend `/workflow:triage` to approve the spike and set timebox + deliverable; then treat the spike as `ready` once approved.
    2. **Isolated execution:** Recommend a dedicated spike worktree. Use `skill: git-worktree` with branch name `spike/<todo_id>-<slug>` (e.g. `spike/003-auth-approach`). Run worktree bootstrap per the git-worktree skill. Execute the spike in that worktree so build work is not mixed with exploration.
-   3. **Research subagents (per spike):** Run in parallel when useful:
+   3. **Research subagents (per spike):** Run mandatory baseline research in parallel:
       - Always (when agents exist): Task repo-research-analyst(context), Task learnings-researcher(context)
       - Conditional: Task framework-docs-researcher(topic), Task best-practices-researcher(topic), Task git-history-analyzer(context) when touching existing behavior or framework choices
    4. **Spike deliverable (required in spike todo Work Log):**
@@ -294,7 +367,7 @@ The input must be a plan file path.
       - Recommendation (one option + why)
       - Concrete next steps: create or update build todos (or plan checkbox to flip) so the main plan can proceed
       - **Should we compound this?** yes/no + one-line why (if yes, recommend `/workflow:compound` with spike context after the spike is complete)
-   5. **Multiple spikes:** If there are N approved spike todos and they are independent, create N worktrees (one per spike, under configured `worktree_dir`). Run one spike per worktree; when the environment supports multiple agents, spikes may run in parallel.
+   5. **Multiple spikes:** If there are N approved spike todos and they are independent, create N worktrees (one per spike, under configured `worktree_dir`). Run one spike per worktree; when the environment supports multiple agents, spikes may run in parallel. If spikes have dependency edges, execute them in dependency order.
    6. **After spike completion:** Mark the spike todo complete (`*-complete-*.md`). If the deliverable said "compound: yes", recommend running `/workflow:compound` with the spike context so the learning is captured in `docs/solutions/` with `tags: [..., spike]`.
 
  2. **Follow Existing Patterns**
@@ -343,9 +416,13 @@ The input must be a plan file path.
    - `test_command` (required when available)
    - `test_fast_command` (optional)
    - `lint_command` (optional)
+   - `typecheck_command` (optional)
    - `format_command` (optional)
 
-   If `test_command` is not configured, ask once for the project's test command and suggest adding it to `AGENTS.md`.
+   Ask-once fallback:
+
+   - If `test_command` is not configured, ask once for the project's test command and suggest adding it to `AGENTS.md`.
+   - If `lint_command` or `typecheck_command` is not configured, ask once for run-provided commands and use them for this run.
 
 2. **Consider Reviewer Agents** (Optional)
 
@@ -358,10 +435,14 @@ The input must be a plan file path.
 3. **Final Validation**
    - All todo files created for this plan are marked complete
    - All tests pass
-   - Linting/formatting checks pass (if configured)
+   - Linting/typechecking/formatting checks pass (configured or run-provided via ask-once fallback)
    - Code follows existing patterns
    - UI validation completed (if applicable)
    - No console errors or warnings
+   - Scope contract satisfied:
+     - `partial_fix`: remaining gaps are materialized as `pending` or `deferred` todos before completion
+     - `migration`: migration verification and rollback checks are documented as passing
+     - `full_remediation`: scoped remediation goals are complete per `completion_expectation`
 
 4. **Update Plan Status**
 
@@ -409,7 +490,7 @@ If the user wants to ship (commits/PR/screenshots), handle that as a separate ex
 
 - Follow existing patterns
 - Write tests for new code
-- Run linting/formatting as configured in `AGENTS.md`
+- Run linting/typechecking/formatting as configured in `AGENTS.md` (or run-provided via ask-once fallback)
 - Use reviewer agents for complex/risky changes only
 
 ### Ship Complete Features
@@ -423,11 +504,14 @@ If the user wants to ship (commits/PR/screenshots), handle that as a separate ex
 Before marking work complete, verify:
 
 - [ ] All clarifying questions asked and answered
+- [ ] Hard gate completed before implementation (`worktree_decision`, execution context, `gate_status: passed`)
 - [ ] All todo files created for this plan are marked complete
 - [ ] Tests pass (run `test_command`)
-- [ ] Linting/formatting passes (run `lint_command` / `format_command` if configured)
+- [ ] Linting/typechecking/formatting passes (run `lint_command` / `typecheck_command` / `format_command`; ask once if lint/typecheck is not configured)
 - [ ] Code follows existing patterns
 - [ ] UI validation completed (if applicable; use `/test-browser` when useful)
+- [ ] Scope contract satisfied (`solution_scope`, `completion_expectation`, `non_goals`)
+- [ ] For `partial_fix`, unresolved work is captured as `pending/deferred` todos
 - [ ] If shipping is requested, capture any required artifacts (screenshots, release notes) per repo conventions
 
 ## When to Use Reviewer Agents
@@ -446,6 +530,7 @@ For most features: tests + linting + following patterns is sufficient.
 
 - **Analysis paralysis** - Don't overthink, read the plan and execute
 - **Skipping clarifying questions** - Ask now, not after building wrong thing
+- **Skipping the worktree hard gate** - No implementation before Step 2 gate passes
 - **Ignoring plan references** - The plan has links for a reason
 - **Testing at the end** - Test continuously or suffer later
 - **Forgetting todo updates** - Update todo files and plan checkboxes or lose track of progress

package/src/.agents/skills/file-todos/SKILL.md

@@ -63,6 +63,7 @@ Required sections:
 - Findings
 - Proposed Solutions
 - Recommended Action
+- Agentic Execution Contract
 - Acceptance Criteria
 - Work Log
 
@@ -80,6 +81,8 @@ dependencies: ["001"]     # issue_ids this is blocked by
 
 **Deferred:** Items with `status: deferred` are not planned for the current development cycle. Keep Problem Statement, Findings, and Work Log so the item can be re-triaged or picked up later. Only `*-ready-*.md` todos are executed; `pending` and `deferred` are non-executable.
 
+**Blocker handling:** Do not introduce a new `blocked` status. When execution is blocked, move the todo from `ready` back to `pending`, add `tags: [blocker]`, and record options + recommendation in Work Log before triage re-approval.
+
 ## Common Workflows
 
 ### Create a New Todo
@@ -117,16 +120,23 @@ Default mapping rules:
    - include the plan path in `Resources`
    - include a "Plan checkbox" pointer when derived from a checkbox (exact text)
    - otherwise include a short "Plan section" pointer (heading name or anchor)
+   - include an `Agentic Execution Contract` with access preconditions, validation commands, evidence expectations, and quality gate commands
    - write Acceptance Criteria that is testable
 6. **Discussion Points and Spike Candidates:** If the plan has sections `## Discussion Points (resolve/decide)` or `## Spike Candidates (timeboxed)`:
    - Checkboxes under **Discussion Points** → create `todos/*-pending-*.md` with `tags: [discussion]` and `status: pending`.
    - Checkboxes under **Spike Candidates** (including items like `- [ ] Spike: ...`) → create `todos/*-pending-*.md` with `tags: [spike]` and `status: pending`.
+   - For each spike candidate, carry plan metadata into the todo when present:
+     - `Initial priority` -> todo `priority` (initial value; triage may adjust)
+     - `Depends on` -> todo `dependencies` when issue ids are known; otherwise keep as a note in `Recommended Action`
+     - `Unblocks` -> include in `Recommended Action` so triage/work can front-load blocking spikes
+     - `Timebox`, `Deliverable`, `Parallelizable` -> copy into `Recommended Action` or `Findings`
    - These items require triage before execution; do not default them to `ready` unless the plan is explicitly approved and triage has been run.
 
 Status and priority defaults:
 
 - `status`: `ready` when the plan is approved and the todo is not from Discussion Points or Spike Candidates; otherwise `pending`. Todos with `tags: [discussion]` or `tags: [spike]` default to `pending`.
 - `priority`: `p2` unless clearly urgent/high-risk
+- If a spike is marked as unblocking implementation work, default initial priority to `p1` when no explicit priority is provided.
 
 Dependencies:
 
@@ -144,6 +154,9 @@ Plan sync expectations:
    - read Problem Statement + Findings
    - choose a recommended action
    - set priority and dependencies
+   - verify `Agentic Execution Contract` is executable (no hidden/manual-only prerequisite)
+   - if lint/typecheck commands are not configured in AGENTS, set triage note: "ask once for run-provided lint/typecheck commands before completion"
+   - for `tags: [spike]`, confirm/adjust carried plan metadata (`Initial priority`, `Depends on`, `Unblocks`, `Timebox`, `Deliverable`, `Parallelizable`)
 3. Decision:
    - **Approve:** rename `*-pending-*` -> `*-ready-*`, set frontmatter `status: ready`
    - **Defer:** rename `*-pending-*` -> `*-deferred-*`, set frontmatter `status: deferred` (typically `p3`). Keep Work Log/Findings so the item is referenceable later; it will not appear in the executable queue until re-triaged to `ready`.
@@ -160,16 +173,21 @@ Consider only `*-ready-*.md` todos. Ignore `pending` and `deferred`.
 3. Update the Work Log each session with:
    - actions (file references + commands)
    - tests run
+   - lint/typecheck commands run (configured or run-provided)
    - results
    - learnings
+   - status context (`ready`, `pending`, `complete`)
 4. Check off Acceptance Criteria as you complete items.
 
 ### Complete a Todo
 
 1. Verify all acceptance criteria are checked.
-2. Add a final Work Log entry.
-3. Rename `*-ready-*` -> `*-complete-*`.
-4. Update frontmatter `status: ready` -> `status: complete`.
+2. Verify success criteria evidence is recorded in Work Log (commands + outputs/artifacts).
+3. Verify lint/typecheck evidence is recorded (configured commands or run-provided commands for this run).
+4. If blocked, move todo back to `pending`, add/ensure `tags: [blocker]`, and record options + recommendation before triage.
+5. Add a final Work Log entry.
+6. Rename `*-ready-*` -> `*-complete-*`.
+7. Update frontmatter `status: ready` -> `status: complete`.
 
 ## Distinctions
 

package/src/.agents/skills/file-todos/assets/todo-template.md

@@ -61,6 +61,17 @@ Risk: Low / Medium / High
 
 To be filled during triage. Clear, actionable plan for resolving this todo.
 
+## Agentic Execution Contract
+
+- Access Preconditions: <services, credentials, fixtures, flags, env>
+- Access Method: <how the agent gets access in this repo/runtime>
+- Validation Commands: <commands/routes/checks>
+- Evidence Targets: <logs/output/artifacts that prove success>
+- Quality Gate Commands:
+  - Test: <command>
+  - Lint: <command or "ask once if not configured">
+  - Typecheck: <command or "ask once if not configured">
+
 ## Technical Details
 
 Affected files, related components, data changes, or architectural considerations.
@@ -79,6 +90,8 @@ Testable checklist items for verifying completion.
 
 - [ ] Acceptance criteria item 1
 - [ ] Acceptance criteria item 2
+- [ ] Success criteria evidence captured in Work Log
+- [ ] Lint and typecheck evidence captured (configured or run-provided)
 
 ## Work Log
 
@@ -92,11 +105,19 @@ Actions:
 - Changes made (include file references)
 - Commands executed
 - Tests run
+- Quality gates run (lint/typecheck)
+- Status transition (`ready` -> `pending` with `tags: [blocker]` when blocked, or `ready` -> `complete` when done)
 
 Learnings:
 - What worked / what didn't
 - Key insights
 
+Blocker Decision (only when blocked):
+- Blocker summary:
+- Constraints discovered:
+- Options considered (>=3):
+- Recommendation:
+
 ---
 
 (Add more entries as work progresses)

package/src/AGENTS.md

@@ -53,7 +53,14 @@ Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:
 - **Brainstorm = WHAT, Plan = HOW.** `/workflow:plan` must not re-litigate decisions already captured in `docs/brainstorms/`.
 - **Local grounding is mandatory.** Every plan must cite at least 1–3 internal file path/line refs (existing patterns) and any relevant `docs/solutions/**` learnings.
 - **Fidelity + confidence are required declarations** in every plan file: always output the Fidelity/Confidence/Research-mode block; the chosen template must include the required sections for that fidelity (Low/Medium/High).
+- **Solution scope contract is mandatory in every plan.** Plans must declare `solution_scope` (`partial_fix|full_remediation|migration`) plus explicit completion expectation and non-goals so `/workflow:work` can enforce intent.
 - **SpecFlow is a validation gate, not a rewrite engine.** High fidelity required; Medium recommended; Low optional. Output must translate into acceptance criteria/edge cases, not new scope.
+- **Isolation preflight is a hard gate.** `/workflow:work` must complete and record worktree/isolation preflight before any implementation commands. `/workflow:review` must do the same for non-current PR/branch targets before analysis.
+- **Spike governance is explicit and ordered.** Risky plans must evaluate spike need, spike candidates must declare initial priority/dependencies/unblocks/timebox/deliverable, triage confirms those assumptions, and `/workflow:work` executes blocking spikes before dependent build todos.
+- **Agentic access/testability is mandatory in planning.** Every plan must include an executable access + validation contract so work/review can run deterministically.
+- **Todo completion requires evidence.** A todo may move to `complete` only after success criteria evidence and quality gate evidence are recorded in Work Log.
+- **Blockers change todo state immediately.** Blocked work must move from `ready` back to `pending` with `tags: [blocker]` and an options+recommendation decision record.
+- **Quality gates are enforced with ask-once fallback.** If `lint_command` or `typecheck_command` is missing, ask once per run and continue only when commands are provided and pass.
 - **Skills are invoked only by trigger.** `document-review` only when user selects "Review and refine" (or explicit request); guardrail skills (PII/financial/audit/data) only when the feature touches that domain.
 - **No new files/directories by default** beyond `docs/plans/...` for planning output.
 - **Plan file is the artifact.** Post-generation options are actions on the artifact; they do not change the workflow shape.
@@ -65,6 +72,7 @@ Use the canonical command names (`/workflow:plan`, `/workflow:work`, `/workflow:
 
 - `Fidelity selected`: `Low | Medium | High`
 - `Confidence`: `High | Medium | Low`
+- `solution_scope`: `partial_fix | full_remediation | migration`
 - Why this fidelity (2-4 reasons)
 - Research mode used (`local only` or `local + external`)
 - Open questions (if any)
@@ -106,6 +114,7 @@ Suggested keys (examples):
 - `test_command: npm test`
 - `test_fast_command: npm test -- --watch=false --runInBand`
 - `lint_command: npm run lint`
+- `typecheck_command: npm run typecheck`
 - `format_command: npm run format`
 - `project_tracker: github` (or `linear`)
 - `worktree_dir: .worktrees` (optional; where worktrees are created)
@@ -123,6 +132,7 @@ dev_server_url: http://localhost:3000
 test_command: npm test
 test_fast_command: npm test -- --watch=false
 lint_command: npm run lint
+typecheck_command: npm run typecheck
 format_command: npm run format
 project_tracker: github
 worktree_dir: .worktrees