devflow-kit 3.4.0 → 3.6.0

package/dist/commands/dynamic-tickets.md

@@ -41,7 +41,7 @@ Spawn devflow agents with:
 agent("your prompt here", { agentType: "Code" })
 ```
 
-Valid `agentType` values: Code, Validate, Simplify, Scrutinize, Evaluate, Test, Review, Git, Synthesize, Knowledge, Design.
+Valid `agentType` values: Code, Fix, Validate, Polish, Harden, Evaluate, Test, Review, Git, Synthesize, Knowledge, Design.
 
 **OMIT `opts.model` whenever `agentType` is set.** The agent frontmatter carries its own model tier (Code→sonnet, Validate→haiku, Review→opus, etc.) and that tier is honored automatically. Passing `opts.model` overrides it — always a mistake.
 
@@ -65,7 +65,7 @@ The `budget` global governs depth. Scale Review agent roster and verification vo
 
 ### Handoff convention for sequential Code agents within a ticket
 
-When a ticket requires multiple sequential Code agent phases, each Code agent appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. It never rewrites an earlier section. The next Code agent reads, via HANDOFF_FILE input, only the section of the phase immediately before its own, not the whole file. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Code is authoritative, summaries are supplementary.
+When a ticket requires multiple sequential Code agent phases, each Code agent appends its own `## Phase {N} Implementation Summary` section, at most 8,192 bytes, to `{toplevel}/.devflow/docs/handoff-{branch_slug}.md` (branch-scoped to prevent concurrent session clobber), `{branch_slug}` being the ticket's branch name with every `/` replaced by `-`, and `{toplevel}` being `git rev-parse --show-toplevel` in the checkout the ticket's branch is in — never a subdirectory. It never rewrites an earlier section. The next Code agent reads, via HANDOFF_FILE input, only the section of the phase immediately before its own, not the whole file. PRIOR_PHASE_SUMMARY is the compact in-context form; the handoff file is the durable form that survives context compaction. Code is authoritative, summaries are supplementary.
 
 ### IRON RULE (LLM-vs-plumbing)
 
@@ -91,23 +91,25 @@ The accepted line is the only source of these values: the script alone folds the
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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`):
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
 git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
 ```
 
-Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
 
 1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
 2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
 3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
 
-This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 Before you author the workflow script, read `{ledger}/.devflow/learning/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
 
-The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into the prompts of the Code, Design, Knowledge, Review and Scrutinize agents, using the `devflow:apply-decisions` consumption algorithm (scan index → Read relevant entries → cite verbatim IDs in agent prompts). Those are the agent types above whose contract declares it; every other agent type gets no decisions context.
+The script body cannot perform this read — you (the main model) do it before authoring. Then inject the relevant DECISIONS_CONTEXT into the prompts of the Code, Fix, Design, Knowledge, Review and Harden agents, which follow `devflow:apply-decisions`. Those are the agent types above whose contract declares it; every other agent type gets no decisions context.
+
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice. The script carries one `DECISIONS_CONTEXT` for every agent, so cut it once, over the whole run.
 
 ---
 
@@ -121,11 +123,12 @@ The following agentType values are valid. Model tiers are shown for reference
 
 | agentType | Model tier | Role |
 |-----------|-----------|------|
-| Code | sonnet | Writes all code and all fixes — the ONLY agent that writes code |
+| Code | sonnet | Implements the plan and fixes review findings — the Code family is the ONLY one that writes code |
+| Fix | sonnet | Fixes the listed validation, alignment and QA failures — part of the Code family |
 | Validate | haiku | Build / typecheck / lint / test — fast correctness gate |
-| Simplify | sonnet | Reduces complexity, removes duplication, improves readability |
-| Scrutinize | opus | 9-pillar self-review — deep structural analysis |
-| Evaluate | opus | Plan-fidelity / alignment — "was the plan implemented correctly?" |
+| Polish | sonnet | Reduces complexity, removes duplication, improves readability |
+| Harden | opus | 9-pillar self-review — deep structural analysis |
+| Evaluate | sonnet | Plan-fidelity / alignment — "was the plan implemented correctly?" |
 | Test | sonnet | Scenario-based acceptance tests against acceptance criteria |
 | Review | opus | Focus-parameterized code review — spawn ONE agent() per focus area |
 | Git | haiku | Git operations — branches, commits, merges, worktree management |
@@ -135,7 +138,7 @@ The following agentType values are valid. Model tiers are shown for reference
 
 ### Agent caveats
 
-- **A Code agent writes every fix** — no other agent type writes code. Finding-verification uses adversarial Review agent-style passes (§6.3 of design doc). Risk-assessment and tech-debt routing live in the post-code pipeline + escalation doctrine.
+- **The Code family writes every fix** — Code for review findings, Fix for gate failures; no other agent type writes code. Finding-verification uses adversarial Review agent-style passes (§6.3 of design doc). Risk-assessment and tech-debt routing live in the post-code pipeline + escalation doctrine.
 - **Always omit `opts.model` with `agentType`.** Each agent honors its own frontmatter model tier; overriding it defeats the per-agent specialization.
 - **Review agents are focus-parameterized.** Each focus is a SEPARATE `agent()` call with `agentType: "Review"` and the focus baked into the prompt. Do NOT batch multiple focuses into one Review agent call — that defeats parallel specialization.
 - **Do not depend on agents enumerating their own skills.** Skills are loaded (spike F5 confirmed) but self-reporting is imperfect. Write agent prompts that give the agent full context directly.
@@ -227,8 +230,9 @@ const candidates = args.candidates || [];   // [{title, summary, wave, dependsOn
 const initiative = args.initiative || args[0] || "see task description";
 const constraints = args.constraints || "";
 const DECISIONS_CONTEXT = args.decisionsContext || "";   // injected before authoring
-const slug = args.slug || initiative.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
-const ts = new Date().toISOString().slice(0,16).replace(/[-:T]/g, (c) => c === 'T' ? '_' : c === ':' ? '' : c);
+const slug = args.slug || initiative.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 50).replace(/-+$/, '') || 'untitled';
+const now = new Date(), two = (n) => String(n).padStart(2, '0');
+const ts = `${now.getFullYear()}-${two(now.getMonth() + 1)}-${two(now.getDate())}_${two(now.getHours())}${two(now.getMinutes())}`;
 const ROOT = args.root;  // {worktree} from Pre-authoring setup: the checkout's toplevel, never cwd
 const OUTDIR = `${ROOT}/.devflow/docs/tickets/${slug}/${ts}`;
 
@@ -299,7 +303,7 @@ Write the amended ticket file to ${OUTDIR}/${a.title.toLowerCase().replace(/[^a-
 return phase("tracking-issue", () =>
   agent(`Write ticket files and a tracking-issue document for initiative: "${initiative}"
 
-For each ticket in the revised set, write a file to ${OUTDIR}/{slug}.md using the ticket_body_template structure:
+For each ticket in the revised set, write a file to ${OUTDIR}/{ticket-slug}.md using the ticket_body_template structure. {ticket-slug} is the ticket title run through title.toLowerCase().replace(/[^a-z0-9]+/g, '-') with nothing trimmed, the same rule the amend phase applied, so a ticket keeps the file name its amendment wrote:
 - Wave: N header
 - Depends on: list or "none"
 - Summary, Scope (In/Out + anti-features), Invariants, numbered Acceptance Criteria (at least one negative), Open Questions
@@ -645,7 +649,7 @@ Tracking issue → `{worktree}/.devflow/docs/tickets/{slug}/{ts}/tracking-issue.
 
 `{worktree}` is the docs root resolved in Pre-authoring setup (it honours `WORKTREE_PATH` when provided).
 
-Timestamps follow the devflow `YYYY-MM-DD_HHMM` convention (date and time separated by an underscore, e.g. `2026-06-12_1148`). The `ts` variable in the workflow script generates this format.
+Timestamps follow the devflow `YYYY-MM-DD_HHMM` convention in local time (date and time separated by an underscore, e.g. `2026-06-12_1148`). The `ts` variable in the workflow script generates this format.
 
 ---
 

package/dist/commands/explore.md

@@ -46,19 +46,19 @@ The accepted line is the only source of these values: the script alone folds the
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 
-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`):
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
 
 ```bash
 git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
 ```
 
-Line 1 is the checkout's toplevel, line 2 the repository's common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first of these that applies:
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
 
 1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
 2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
 3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
 
-This is the rule the learning hooks apply (D-LEDGER-MAIN-WORKTREE, D-PROMPT-ROOT), so you read the index the Learning agent writes.
+This is the rule the learning hooks apply, so you read the index the Curate agent writes.
 
 **Step 1 — Read the pre-rendered index:**
 
@@ -67,11 +67,15 @@ Attempt to read `{ledger}/.devflow/learning/index.md`.
 - If the file exists and contains non-empty content: use that content as `DECISIONS_CONTEXT`.
 - If the file is absent or empty: set `DECISIONS_CONTEXT` to `(none)`.
 
-The index is one direct file read, written at render time by `render-decisions.cjs` alongside `decisions.md`/`pitfalls.md` — no `.cjs` script runs here, and the index's own footer names the files that hold each entry's full body.
+The index is one direct file read, written at render time by `render-decisions.cjs` — no `.cjs` script runs here.
 
-**Step 2 — Apply decisions using `devflow:apply-decisions`:**
+**Step 2 — Slice the index, then hand it on:**
 
-When `DECISIONS_CONTEXT` is not `(none)`, follow `devflow:apply-decisions` to scan the index, identify plausibly-relevant entries, Read full entry bodies on demand, and cite verbatim IDs in downstream agent prompts and reasoning.
+When `DECISIONS_CONTEXT` is not `(none)`, hand it only to the agents whose contract declares it.
+
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
+
+Those agents follow `devflow:apply-decisions`. A host that uses the index in its own thread says so in its own step.
 
 The orchestrator uses `DECISIONS_CONTEXT` locally when framing exploration — prior decisions and pitfalls suggest specific areas to investigate. Follow `devflow:apply-decisions` to Read full entry bodies on demand. **Do NOT pass `DECISIONS_CONTEXT` to Explore sub-agents** — decisions context stays in the orchestrator, not in the investigation workers.
 
@@ -107,7 +111,7 @@ Ask each explorer for a final report of at most about 1,500 tokens: findings wit
 **Produces:** MERGED_FINDINGS
 **Requires:** EXPLORE_OUTPUT
 
-Spawn `Agent(subagent_type="Synthesize")` in `exploration` mode with combined findings:
+Spawn `Agent(subagent_type="Synthesize")` with the prompt line `Mode: exploration` first, then the combined findings:
 
 - Merge overlapping discoveries from parallel explorers
 - Resolve any contradictions between explorer findings
@@ -167,21 +171,17 @@ FEATURE_SLUG: {slug derived from primary changed directory, kebab-case}
 FEATURE_NAME: {human-readable name}
 DIRECTORIES: {list of primary directories touched by this workflow}
 FILES_CHANGED: {list of files changed}
-DECISIONS_CONTEXT: {DECISIONS_CONTEXT if available, else (none)}
+DECISIONS_CONTEXT: {the slice for these directories, else (none)}
 
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
-Then update the index cache by performing a read-modify-write on:
+Then update the index cache:
   {worktree}/.devflow/features/index.md
 
 Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
 
-If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
-
-The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
-
-After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+Then commit the two files as your Commit Protocol directs."
 ```
 
 **Step 4 — Surface an uncommitted knowledge base:**