devflow-kit 3.1.0 → 3.3.0

package/dist/commands/plan.md

@@ -18,13 +18,19 @@ The orchestrator only spawns agents and gates — all analytical work is done by
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/plan`:
+What follows `/plan` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Opens with a candidate issue reference → issue mode (one candidate = single-ref, more than one = multi-issue)
 - Path to existing `.md` file → **error**: "Use /implement with plan documents"
 - Other text → feature description
 - Empty → use conversation context
 
-**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `$ARGUMENTS` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
+**Issue-reference grammar (L1 — command layer, permissive and provider-blind):** scan `COMMAND_INPUT` for candidate issue references — a `#`-prefixed token and a bare digit run are both candidates — and collect them in source order as the raw token list `ISSUE_REFS`. Forward that list to the Git agent **verbatim**: the command never renders, normalises, pads, strips or coerces a token, and never rules a candidate out. Under `github` a token matching `^#?[1-9][0-9]{0,8}$` **is** a reference and the Git agent renders it as `#{n}`.
 
 **A token of any other shape is neither coerced nor dropped silently — and no producer-side grammar check rejects it before the fetch.** Adjudication belongs to the operation that runs, and each one answers in its own Output block: `fetch-issue` strips a leading `#` and takes the text branch, so a non-numeric token is used as a **search term** and the operation returns the first open match or nothing; `fetch-issues-batch` resolves each token to an issue number, drops the ones it cannot resolve, and names them in `NOT_FOUND ({refs})` beside the issues it did fetch. Read the outcome from the operation that ran — a token's shape is a verdict nowhere, and there is nothing upstream holding it back.
 
@@ -62,7 +68,7 @@ Explore the user's intent through focused Socratic questioning before spawning a
 
 **Step 0 — Fetch issue(s)** (issue mode only; skip for feature-description and empty modes):
 
-- **Single-ref** (one candidate ref in `$ARGUMENTS`):
+- **Single-ref** (one candidate ref in `COMMAND_INPUT`):
 
   ```
   Agent(subagent_type="Git"):
@@ -106,8 +112,6 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 **Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
 **Requires:** CONFIRMED_SCOPE
 
-**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:software-design`, `devflow:security`, `devflow:design-review`. If a skill fails to load, continue without it.
-
 Spawn Skim agent for codebase context:
 
 ```
@@ -212,7 +216,7 @@ Pass `FEATURE_KNOWLEDGE` alongside `DECISIONS_CONTEXT` to Explore and Design age
 **Produces:** EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, DECISIONS_CONTEXT
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated."
+Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -355,7 +359,7 @@ User can:
 **Produces:** IMPL_EXPLORE_OUTPUTS
 **Requires:** SKIM_CONTEXT, ACCEPTED_SCOPE
 
-Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope:
+Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope. Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
 | Focus | Thoroughness | Find |
 |-------|-------------|------|
@@ -384,7 +388,7 @@ Combine into: patterns to follow, integration points, reusable code, edge cases"
 **Produces:** PLAN_OUTPUTS
 **Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS, DECISIONS_CONTEXT
 
-Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis:
+Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis. Ask each agent for a final report of at most about 1,500 tokens: the plan itself, not a restatement of the exploration.
 
 | Focus | Output |
 |-------|--------|
@@ -573,7 +577,7 @@ Spawn a Git agent with `OPERATION: ensure-traceable-issue`:
 ```
 Agent(subagent_type="Git"):
 "OPERATION: ensure-traceable-issue
-ISSUE_INPUT: {the raw candidate token from $ARGUMENTS if /plan was invoked with an issue reference, else omit}
+ISSUE_INPUT: {the raw candidate token from COMMAND_INPUT if /plan was invoked with an issue reference, else omit}
 TASK_DESCRIPTION: {Gate 0 confirmed scope — one-line title}
 INITIAL_REQUEST: {the Gate 0 confirmed scope statement}
 REQUIREMENTS: {discovered requirements summary from Phase 6 gap synthesis}

package/dist/commands/release.md

@@ -17,13 +17,19 @@ Release the project using adaptive learned configuration. On first run, scans th
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/release`:
+What follows `/release` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Explicit version: `v1.2.3` or `1.2.3`
 - Bump type: `patch`, `minor`, `major`
 - Flag: `--dry-run`
 - Empty: interactive mode (will ask for version)
 
-Parse from $ARGUMENTS:
+Parse from `COMMAND_INPUT`:
 - `VERSION`: explicit version string if present (strip leading `v`)
 - `BUMP_TYPE`: `patch | minor | major` if bump type provided
 - `DRY_RUN`: true if `--dry-run` present, false otherwise

package/dist/commands/research.md

@@ -16,7 +16,13 @@ Research a topic by spawning parallel Research agents across multiple research t
 
 ## Input
 
-`$ARGUMENTS` contains whatever follows `/research`:
+What follows `/research` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
 - Research question: "best caching strategies"
 - Comparison question: "compare React vs Svelte for our use case"
 - Empty: use conversation context
@@ -183,7 +189,7 @@ If external research was skipped due to tool unavailability: inform user.
 1. If `codebase` type was not in RESEARCH_PLAN → skip
 2. Check if matching feature knowledge already exists by reading `{worktree}/.devflow/features/index.md` (or globbing frontmatter if absent). If covered → skip
 3. Use AskUserQuestion: "No feature knowledge exists for {researched area}. Create one?"
-4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to load `devflow:feature-knowledge`, write `KNOWLEDGE.md`, and update `index.md` directly
+4. If user accepts: spawn `Agent(subagent_type="Knowledge")` with researched area context + worktree root, instructing it to write `KNOWLEDGE.md` and update `index.md` directly
 5. Set FEATURE_KNOWLEDGE_STATUS = created or skipped
 
 **Failure handling**: Non-blocking. If Knowledge agent fails, log and continue.

package/dist/commands/resolve.md

@@ -24,7 +24,7 @@ Process issues from code review reports: triage every issue through the blast-ra
 
 1. **Discover resolvable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
    - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
-   - See the `devflow:worktree-support` skill for the full 7-step algorithm and canonical protected branch list
+   - Invoke the `devflow:worktree-support` skill, then Read its `references/discovery.md` from the skill's base directory for the full 7-step algorithm; the canonical protected branch list stays in the skill
    - Additional filter: must have unresolved reviews (latest review directory has no `resolution-summary.md`)
 2. **If `--path` flag provided:** use only that worktree, skip discovery
    **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
@@ -302,8 +302,8 @@ For each batch, spawn Code agent with `OPERATION: issue-fix` and `PUSH: false`:
 
 ```
 Agent(subagent_type="Code"):
-"TASK_ID: resolve-{batch-id}
-OPERATION: issue-fix
+"OPERATION: issue-fix
+TASK_ID: resolve-{batch-id}
 ISSUES: {fix_now_issues_in_batch}
 SCOPE: {risk_tier_per_issue}
 PUSH: false
@@ -348,7 +348,8 @@ Agent(subagent_type="Simplify", run_in_background=false):
 "TASK_DESCRIPTION: Issue resolution fixes
 WORKTREE_PATH: {worktree_path}  (omit if cwd)
 FILES_CHANGED: {list of files modified by Code agents}
-Simplify and refine the fixes for clarity and consistency"
+Simplify and refine the fixes for clarity and consistency
+Commit any improvements with a conventional-commit message."
 ```
 
 ### Phase 7: Verification Gate
@@ -361,7 +362,7 @@ If no fixes were made (CODE_AGENT_RESULTS contains 0 commits) → set VERIFICATI
 Otherwise, spawn Validate agent:
 
 ```
-Agent(subagent_type="Validate", model="haiku"):
+Agent(subagent_type="Validate"):
 "FILES_CHANGED: {list of files from Code agent output}
 VALIDATION_SCOPE: full
 Run build, typecheck, lint, test. Report pass/fail with failure details."
@@ -376,8 +377,8 @@ Run build, typecheck, lint, test. Report pass/fail with failure details."
    - Spawn Code agent with fix context:
    ```
    Agent(subagent_type="Code"):
-   "TASK_ID: resolve-{batch-id}-valfix-{count}
-   OPERATION: validation-fix
+   "OPERATION: validation-fix
+   TASK_ID: resolve-{batch-id}-valfix-{count}
    VALIDATION_FAILURES: {parsed failures from Validate agent}
    SCOPE: Fix only the listed failures, no other changes
    PUSH: false
@@ -415,14 +416,24 @@ If `fork_no_push` is set → skip: "Cannot push to fork — skipping CI validati
 
 Otherwise, for each worktree with fixes:
 
-<!-- PATTERN: ci-status-gate — shared polling/classification/budget logic; context-specific preamble lives outside this block -->
-1. Spawn `Agent(subagent_type="Git")` with `OPERATION: check-ci-status` and `WORKTREE_PATH`.
+`PR_NUMBER` is the worktree's `pr_number` from Phase 0; when it is absent, skip: "No PR/CI configured, skipping CI validation."
+
+**Push first, outside the gate block.** The gate waits on the pushed head, so push once more with the gate's own command — never forced, and no retry:
+
+```bash
+git -C {worktree} push; echo "exit=$?"
+```
+
+Phase 7 has pushed already, so this is a no-op unless the head moved since. `exit=0` continues to the gate. Any other result records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and skips the wait for this worktree. Pass `WORKTREE_PATH: {worktree_path}` on the fix spawn below.
+
+<!-- PATTERN: ci-status-gate -->
+1. Wait: run `cd {worktree} && HEAD_SHA=$(git rev-parse HEAD) && node "$HOME/.devflow/scripts/ci-wait.cjs" --pr {PR_NUMBER} --head "$HEAD_SHA"` through the Bash tool with `timeout: 600000`. Each run is one wait of at most 570 seconds and prints one line, `CI <STATUS> pr=… head=… failing=… pending=… waited=…` (INDETERMINATE adds `reason=…`). A missing or unparseable line, a status outside the six below, or a non-zero exit is INDETERMINATE.
 2. **If PASSING** → proceed to next phase.
 3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to next phase.
-4. **If PENDING** → poll every 60 seconds (global budget, see step 7). Re-spawn Git agent each poll. If PASSING → proceed. If still PENDING after budget exhausted → report "CI still running — verify manually before merging" and proceed.
-5. **If INDETERMINATE** → poll as PENDING within the same budget. If still INDETERMINATE after budget exhausted → report "CI status unknown — verify manually before merging" and proceed.
-6. **If FAILING** → report failing checks. Spawn `Agent(subagent_type="Code")` with `COMPLIANCE_FRAMEWORKS` to fix CI failures based on check names and failure context. After fix, push and re-check. Max 2 fix attempts. If still failing → report failures and proceed.
-7. **Total budget**: max 10 polls and max 2 fix attempts across all check/fix cycles combined. If the budget is exhausted, report current status and proceed.
+4. **If PENDING** and fewer than 3 waits have run → wait again (step 1). After the third wait → report "CI still running — verify manually before merging" and proceed.
+5. **If INDETERMINATE** and fewer than 3 waits have run → wait again (step 1). After the third wait → report "CI status unknown — verify manually before merging" and proceed.
+6. **If FAILING** and fewer than 2 fixes have run → report the failing checks from the line. Spawn `Agent(subagent_type="Code")` whose prompt opens with `OPERATION: ci-fix`, with `COMPLIANCE_FRAMEWORKS`, `CI_FAILURES` and `PUSH: false`; `CI_FAILURES` holds the failing-check names from the line and nothing else, because the Code agent fetches the full names and reads the logs itself and this command reads none. After a fix, push with the command above and, if a wait remains, wait again (step 1); a failed push records `TRACEABILITY: DEGRADED (ci push failed)`, reports "CI status unknown — verify manually before merging" and stops waiting. After the second fix still FAILING → report the failing checks and proceed.
+7. **Budget**: at most 3 waits and 2 fixes in all, per worktree. When one is spent, report the current status and proceed.
 <!-- /PATTERN: ci-status-gate -->
 
 ### Phase 9: Manage Debt (Sequential)
@@ -455,7 +466,7 @@ After manage-debt completes:
 
 **Step 9b-0: Re-verify stale test-plan items**
 
-Run this step only when this run's Phase 7 push succeeded — the one way /resolve moves the PR head — and a PR is known; otherwise skip it and Step 9b-3, and record `STALE_REVERIFICATION` as `SKIPPED (head unchanged)`. Detection needs no Git agent: from the worktree root, run the evidence script, which re-derives every test-plan state at the new head and writes the stale TP lines whose text the PR's trusted evidence record vouches for:
+Run this step only when a push of this run succeeded — Phase 7's, or the push of Phase 8's gate — and a PR is known; otherwise skip it and Step 9b-3, and record `STALE_REVERIFICATION` as `SKIPPED (head unchanged)`. Detection needs no Git agent: from the worktree root, run the evidence script, which re-derives every test-plan state at the new head and writes the stale TP lines whose text the PR's trusted evidence record vouches for:
 
 ```bash
 cd {worktree} && node "$HOME/.devflow/scripts/verify-evidence.cjs" verify --pr {pr_number} --stale-out "{TARGET_DIR_REL}/stale-plan.md"; echo "exit=$?"
@@ -607,7 +618,7 @@ Final gate: {PASS | FAILED after N attempts}
 - Resolution comment: {POSTED | POSTED+TRUNCATED | SKIPPED (already posted) | SKIPPED (publication off) | SKIPPED (no PR) | DEGRADED (reason)}
 - Publication: {FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config) | STUB (visibility undeterminable) | STUB (evidence policy)}
 - Thread replies: {COMPLETE | PARTIAL | TRUNCATED | SKIPPED (reason) | DEGRADED (reason)}
-- Push: {pushed | skipped (no fixes) | skipped (cannot push to fork)}
+- Push: {pushed (Phase 7, a CI-fix push, or both) | skipped (no fixes) | skipped (cannot push to fork) | DEGRADED (ci push failed)}
 - Test-plan re-verification: {Test plan: n stale, m re-verified | SKIPPED (head unchanged) | DEGRADED (reason)}
 - Test-plan evidence: {the EVIDENCE line's VERIFIED-CI + ATTESTED-LOCAL / total, then the Body / Comment line | SKIPPED (reason) | DEGRADED (reason)}
 
@@ -648,7 +659,7 @@ If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine
 **Step 2 — Evaluate whether write-back is warranted:**
 
 Only proceed if **at least one** of these is true:
-- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
 - This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
 
 **Never spawn unconditionally.** If neither condition is met, skip write-back silently.
@@ -665,8 +676,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
@@ -720,7 +729,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 ├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code agent validation-fix loop ≤2
 │
 ├─ Phase 8: CI Status Gate (conditional — skipped if no fixes or verification FAILED)
-│  └─ Git agent (check-ci-status) → poll/fix loop
+│  └─ push, then ci-wait.cjs (inline, one wait ≤ 570 s) → Code agent on FAILING (3 waits + 2 fixes per worktree)
 │
 ├─ Phase 9: Git agent (manage-debt) — FIX_SEPARATE + TECH_DEBT → backfill Tracked={ISSUE_REF} (or TRACEABILITY: DEGRADED on failure)
 │  SEQUENTIAL across worktrees

package/dist/commands/self-review.md

@@ -14,7 +14,7 @@ Run Simplify agent and Scrutinize agent sequentially on changed files for post-i
 
 ### Phase 0: Context Gathering
 
-**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, HEAD_BEFORE
 
 Detect changed files and build context:
 
@@ -22,6 +22,7 @@ Detect changed files and build context:
 2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged
 3. If no changes found, report "No changes to review" and exit
 4. Build TASK_DESCRIPTION from recent commit messages or branch name
+5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Simplify runs — Phase 3 compares against it
 ### Load DECISIONS_CONTEXT
 
 The decisions ledger belongs to the repository, not to one checkout: in a linked worktree it lives in the main worktree, and a session started in a subdirectory reads the copy at the repository root. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
@@ -100,7 +101,7 @@ If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set `FE
 
 Pass `FEATURE_KNOWLEDGE` to Scrutinize agent.
 
-**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional)
+**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional), HEAD_BEFORE (40-hex SHA)
 
 ### Phase 1: Simplify agent (Code Refinement)
 
@@ -112,13 +113,14 @@ Spawn Simplify agent to refine code for clarity and consistency:
 Agent(subagent_type="Simplify", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
-Simplify and refine the code for clarity and consistency while preserving functionality."
+Simplify and refine the code for clarity and consistency while preserving functionality.
+Commit any improvements with a conventional-commit message."
 
 **Wait for completion.** Simplify agent commits changes directly.
 
 ### Phase 2: Scrutinize agent (9-Pillar Quality Gate)
 
-**Produces:** SCRUTINIZE_STATUS, SCRUTINIZE_CHANGES
+**Produces:** SCRUTINIZE_STATUS
 **Requires:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT
 
 Spawn Scrutinize agent for quality evaluation and fixing:
@@ -132,17 +134,19 @@ Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report.
 Follow devflow:apply-decisions to scan DECISIONS_CONTEXT and Read full ADR/PF bodies on demand. Skip if (none).
 Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
 
-**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED), changes_made (bool)
+**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED) from the `### Status` line
 
 ### Phase 3: Conditional Validation
 
 **Produces:** VALIDATION_RESULT
-**Requires:** SCRUTINIZE_CHANGES
+**Requires:** HEAD_BEFORE, SCRUTINIZE_STATUS
 
-If Scrutinize agent made changes (STATUS == FIXED):
+If STATUS is BLOCKED, skip this phase: the report (Phase 4) names the blocker.
+
+Run this phase only if HEAD moved — `git rev-parse HEAD` differs from `HEAD_BEFORE`, meaning Simplify or Scrutinize committed (Simplify alone counts, whatever Scrutinize's STATUS is). Otherwise skip it. Its scope is changed-only over what the two agents changed:
 
 Agent(subagent_type="Validate", run_in_background=false):
-"FILES_CHANGED: {scrutinize_modified_files}
+"FILES_CHANGED: {output of `git diff --name-only HEAD_BEFORE..HEAD`}
 VALIDATION_SCOPE: changed-only
 Run build, typecheck, lint, test on modified files"
 
@@ -208,7 +212,7 @@ If the settings line says `KNOWLEDGE=off`, skip write-back entirely. The machine
 **Step 2 — Evaluate whether write-back is warranted:**
 
 Only proceed if **at least one** of these is true:
-- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed).
+- This workflow changed files in a directory that is documented by an existing feature knowledge base (a documented area changed). Knowledge bases are written through at that point, never on a background schedule.
 - This workflow surfaced durable, cross-cutting knowledge about a codebase area that would help future agents working in the same area — patterns, anti-patterns, integration points, gotchas not visible from a single file read.
 
 **Never spawn unconditionally.** If neither condition is met, skip write-back silently.
@@ -225,8 +229,6 @@ DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
 DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
 
-Load the devflow:feature-knowledge skill and follow its authoring process.
-
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
@@ -254,6 +256,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │
 ├─ Phase 0: Context gathering
 │  ├─ Git diff for changed files
+│  ├─ Record HEAD_BEFORE
 │  └─ Read index.md → DECISIONS_CONTEXT
 │
 ├─ Phase 1: Simplify agent
@@ -263,7 +266,7 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │  └─ 9-pillar quality gate (may fix and commit)
 │
 ├─ Phase 3: Validate agent (conditional)
-│  └─ If Scrutinize agent made changes, verify tests pass
+│  └─ If HEAD moved since HEAD_BEFORE (Simplify or Scrutinize committed), changed-only Validate over HEAD_BEFORE..HEAD
 │
 └─ Phase 4: Report
    └─ Display summary with pillar status
@@ -282,6 +285,6 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 
 1. **Orchestration only** - Command spawns agents, doesn't do the work
 2. **Sequential execution** - Simplify agent must complete before Scrutinize agent
-3. **Validation gate** - If Scrutinize agent changes code, must pass validation
+3. **Validation gate** - If Simplify agent or Scrutinize agent committed, the changes must pass validation
 4. **Honest reporting** - Display actual agent outputs
 5. **Fail fast** - Stop on BLOCKED or validation failure

package/dist/core/agent-frontmatter.js

@@ -96,6 +96,31 @@ export function readFrontmatterModel(content) {
     const m = MODEL_RE.exec(parts.value.fmBody);
     return Ok(m ? m[1] : '');
 }
+// ---------------------------------------------------------------------------
+// readFrontmatterEffort
+// ---------------------------------------------------------------------------
+/**
+ * Read the `effort:` value from the first frontmatter block.
+ *
+ * D-SHIPPED-EFFORT: an agent's shipped effort is part of its shipped default,
+ * the same as its model, so the reader that answers "what did devflow ship?"
+ * must see both. This is the effort twin of readFrontmatterModel and has the
+ * same contract: it reads only the leading frontmatter block (an `effort:`
+ * line in the body is ignored), returns Ok('') when no `effort:` line exists,
+ * and returns an error for missing or unterminated frontmatter.
+ *
+ * The value is returned as written. Whether it is a valid effort level is the
+ * caller's decision (loadShippedAgentDefaults owns that check against
+ * EFFORT_LEVELS), so a typo in a shipped file is reported rather than hidden here.
+ */
+export function readFrontmatterEffort(content) {
+    const parts = parseFrontmatter(content);
+    if (!parts.ok)
+        return Err(parts.error);
+    const EFFORT_RE = /^effort:[ \t]*(.*?)[ \t]*$/m;
+    const m = EFFORT_RE.exec(parts.value.fmBody);
+    return Ok(m ? m[1] : '');
+}
 /**
  * Rewrite the `model:` and optionally `effort:` lines in the first
  * frontmatter block of `content`.