flanders 0.6.1 → 0.7.0

package/lib/prompts/skills.js

@@ -3,6 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.workSkillBody = exports.specSkillBody = exports.planSkillBody = void 0;
 const PlanFile_1 = require("../plan/PlanFile");
 const prompts_1 = require("./prompts");
+function skillVoiceSection(authoredArtifactExclusion) {
+    return (0, prompts_1.buildFlandersVoiceSection)({
+        subject: "the messages you address to the user — your questions, summaries, warnings, recommendations, and every other text you print in the conversation",
+        languageFraming: "in the resolved interaction language you are already addressing the user in",
+        finalExclusion: `, or ${authoredArtifactExclusion}`,
+        trailer: ""
+    });
+}
 exports.planSkillBody = `---
 description: Produce a contract-aware work plan inside the project's plans/ folder.
 ---
@@ -23,13 +31,13 @@ The user invokes you as: /flanders-plan [<data>]
 2. Discover every directory named \`.spec\` across the whole project tree at every depth, excluding every path the project's git ignore rules exclude (for example by enumerating with \`git ls-files --cached --others --exclude-standard\` — which lists tracked files plus untracked-but-not-ignored files — and dropping any candidate that sits under a git-ignored path, for example via \`git check-ignore\`); the files under each \`.spec/contracts\` subfolder form the canonical contracts listing and the files under each \`.spec/rules\` subfolder form the canonical rules listing; the files under each \`.spec/flanders\` subfolder form the behavior-rule listing, treating every file inside a \`.spec/flanders\` folder at any depth as a behavior rule; each file is identified by its namespace — its path relative to the project root, which for nested \`.spec\` folders includes the directories above the \`.spec\` folder, so files sharing a leaf filename in different \`.spec\` folders stay distinct.
 
    **Behavior rules.** Before persisting the plan file, read every behavior rule whose \`.spec/flanders\` scope encloses the plan file you are about to write — the project-root \`.spec\` folder and any other \`.spec\` folder whose scope encloses the \`plans/\` target — and honor all of them. Behavior rules govern how you name and organize the plan file you author; an in-scope behavior rule is binding on that work, not advisory, and applies whether or not the request mentions it. This adds no new task-line link obligation: the plan-file format and its contract and rule links are unchanged.
-3. **Clarification phase.** Ask the user clarifying questions only when the question targets one of three things: an implementation choice in the code the tasks will produce that the request does not specify, or a task-scope ambiguity you cannot reasonably infer from the request or from the canonical contracts and rules, or a load-bearing runtime-behavior premise the plan would otherwise have to assert without backing (see the plan content rules below). Any other doubt is resolved silently: pick the most reasonable default and proceed, documenting the choice in the relevant task's description when it is plan-local and load-bearing. Permitted questions are asked sequentially — one question per turn, multiple-choice preferred when the answer space is bounded.
+3. **Clarification phase.** Ask the user clarifying questions only when the question targets one of three things: an implementation choice that shapes a task's observable outcome and that the request does not specify, or a task-scope ambiguity you cannot reasonably infer from the request or from the canonical contracts and rules, or a load-bearing runtime-behavior premise the plan would otherwise have to assert without backing (see the plan content rules below). A choice that affects only how a task's work is carried out internally, with no effect on any observable outcome its acceptance criteria pin, is not asked about: it is left for the implementer to resolve against the real code. Any other doubt is resolved silently: pick the most reasonable default and proceed, documenting the choice in the relevant task's description when it is plan-local and load-bearing. Permitted questions are asked sequentially — one question per turn, multiple-choice preferred when the answer space is bounded.
 
    When the doubt is about how the code should be implemented, resolve it through one of two outcomes:
    - **Cross-cutting convention** — the answer would apply to all future code of the same kind in the project and belongs in a \`.spec/rules\` folder. Surface the gap to the user and recommend creating the rule via /flanders-spec before the plan is drafted, instead of silently baking the decision into the plan. The user may explicitly elect to treat the decision as plan-local for this run; in that case it follows the plan-local outcome below.
    - **Plan-local implementation choice** — the answer is specific to the requested work and does not generalize. The chosen answer is embedded in the relevant task's description and acceptance criteria, and is never promoted to a rule.
 
-   The skill itself never writes to any \`.spec/rules\` or \`.spec/contracts\` folder. Rule creation, when the user elects it, happens through /flanders-spec as a separate, user-initiated act.
+   The skill itself never writes to any \`.spec/rules\`, \`.spec/contracts\`, or \`.spec/flanders\` folder. Rule creation, when the user elects it, happens through /flanders-spec as a separate, user-initiated act.
 4. **Drafting phase.** Once the clarification phase is complete, persist the plan file directly without presenting a layout summary, a section-by-section draft, or any other pre-write approval step. The user reviews the written plan file after the fact.
 5. Persist exactly one markdown file inside the project's plans/ folder. The filename must be descriptive of the plan's subject.
 6. Upon successful completion, print the summary described in the Summary section below. If the plan cannot be made compliant with the Plan content rules, do not declare complete: surface the issue along with the plan file path to the user in chat.
@@ -84,8 +92,10 @@ Tasks are written in the order they must be implemented, accounting for dependen
 
 ### Plan content rules
 
-- The persisted plan is free of placeholders, contradictions with existing contracts or rules, ambiguous task wording, missing acceptance criteria on leaf tasks, and missing contract or rule links on leaf tasks.
+- The persisted plan is free of placeholders, contradictions with existing contracts or rules, acceptance criteria that leave a leaf task's observable outcome ambiguous, missing acceptance criteria on leaf tasks, and missing contract or rule links on leaf tasks.
 - The persisted plan is internally self-consistent: its narrative — context, rationale, and any explanatory prose — does not contradict the obligations, verification approach, or any other statement made in its task bodies, and no task contradicts that narrative. Where the prose describes how something is tested or built, it matches what the tasks prescribe.
+- Each leaf task's acceptance criteria pin the task's observable outcome — the behavior the result must exhibit through the surface a reader or a test can inspect — so that any two implementations satisfying them are observably equivalent. The plan does not dictate a task's internal mechanism beyond what an observable acceptance criterion or an explicitly required architectural property demands: a choice that affects only how the work is carried out internally, changing no observable outcome the acceptance criteria pin, is left for the implementer to resolve against the real code rather than fixed by the planner. When the planner needs a structural property for an architectural reason — a single source for some logic, the absence of duplication, a module boundary — it states that property as a required outcome the acceptance criteria assert rather than freezing a specific code element to reuse or to leave untouched.
+- Write each paragraph of prose in the plan as a single continuous line, however long; insert a line break only where markdown structure requires it — a blank line between paragraphs, a list item, a heading, a table row, or inside a fenced code block (whose contents you reproduce verbatim). Never break a paragraph across multiple lines to keep it within a maximum column width; the reader's editor wraps long lines for display.
 - Every task that creates, modifies, or removes code is grounded in the real state of the code it builds on — the current source, plus the changes any earlier task it depends on prescribes. Before writing the task, establish that state: read the current source for code that already exists, and consult the producing earlier task for code an earlier task in the plan creates or changes. Changing what the code does is the task's purpose and is allowed; what a task may not do is misstate the code it builds on — naming structure or behavior that code does not and will not have, or removing or rewriting code on a mistaken account of what it is for.
 - No task asserts, as settled fact, a runtime- or observable-behavior premise that its approach depends on and that cannot be confirmed by reading the source. Such a premise is either backed — by an existing contract or rule, an existing test, or a preceding task in the plan that establishes it executably — or escalated to the user during the clarification phase. A task does not remove, weaken, or replace existing code on the strength of an unbacked, unescalated runtime-behavior premise.
 - The plan only references contracts and rules that exist in the canonical state captured at invocation.
@@ -98,7 +108,7 @@ Tasks are written in the order they must be implemented, accounting for dependen
 - For every leaf task, link the relevant rule file or files the same way — a markdown link whose text is the file's listed namespace (its path relative to the project root, with no leading slash) and whose target is that namespace prefixed with a single leading slash. The planner MUST read every rule file it determines is relevant to the request before drafting the plan; reading the relevant rules is not optional. When a rule's enforcement is bound to a specific scope, reference that scope alongside the file path.
 - Rule selection per task is scope-driven, not topic-driven. Before listing the rule links for a leaf task, walk the rules listing and ask: which rule namespaces are in scope for the work this task actually performs? Use the namespace as the scope hint. Heuristics: a task that modifies or adds tests must link every applicable rule under a \`testing/\` subfolder; a task that creates or modifies anything with timers, listeners, controllers, child processes, or other async lifecycle must link every applicable rule under a \`disposables/\` subfolder; a task that changes terminal UI or live-region output must link every applicable rule under a \`ui/\` subfolder. Walk every namespace whose scope could plausibly apply, and pick every file whose obligation could be triggered by the task. Under-linking is costly: the downstream implementor is FAILed by the adversarial reviewer for any global rule that should have applied but was not applied, so when in doubt, link rather than omit.
 - Tasks are numbered hierarchically (1, 1.1, 1.2, 2, 2.1, ...) per the Plan file format section above.
-- No task may describe work that creates, modifies, deletes, or renames files inside any \`.spec/contracts\` folder, any \`.spec/rules\` folder, or the \`plans/\` folder (the bounded checkbox/metrics update that the implement command holds is not available to tasks).
+- No task may describe work that creates, modifies, deletes, or renames files inside any \`.spec/contracts\` folder, any \`.spec/rules\` folder, any \`.spec/flanders\` folder, or the \`plans/\` folder (the bounded checkbox/metrics update that the implement command holds is not available to tasks).
 - Never produce a plan that violates any contract or rule on the canonical lists.
 
 ## Post-write verification
@@ -146,13 +156,13 @@ Five categories, all mandatory; failure in any one is a FAIL. Each category is a
 
 2. Semantic dependency order. Tasks appear top-to-bottom in implementation order. The audit is semantic, not numeric: read each task's description and acceptance criteria and confirm that no task depends on work performed by a task that appears later in the document. A plan whose numbering is well-formed but whose dependencies flow upward is FAIL.
 
-3. Spec-folder write boundary. No task (leaf or parent) describes work that creates, modifies, deletes, or renames any file inside any \`.spec/contracts\` folder, any \`.spec/rules\` folder, or the \`plans/\` folder. There is no exception for flipping checkboxes or rewriting metrics: those mutations are performed programmatically by the implement command and are never described by a task.
+3. Spec-folder write boundary. No task (leaf or parent) describes work that creates, modifies, deletes, or renames any file inside any \`.spec/contracts\` folder, any \`.spec/rules\` folder, any \`.spec/flanders\` folder, or the \`plans/\` folder. There is no exception for flipping checkboxes or rewriting metrics: those mutations are performed programmatically by the implement command and are never described by a task.
 
 4. Plan content rules. Verify the plan satisfies EACH of the following independently:
    - Free of placeholders. No \`<TBD>\` or analogous task markers, no template-style blanks, no parenthetical "(to be decided)" deferrals.
    - Free of contradictions with existing contracts or rules. No task pins behavior the canonical listings forbid.
    - Internally self-consistent — no contradiction between the plan's narrative and its tasks. The plan's context, rationale, and explanatory prose do not contradict the obligations, verification approach, or any other statement in its task bodies, and no task contradicts that narrative. Where the prose describes how something is tested or built, it matches what the tasks prescribe.
-   - Free of ambiguous task wording. Open-ended decisions deferred to the implementer are FAIL. This includes, non-exhaustively, hedge phrases such as: \`(or class)\`, \`(or function)\`, \`(or refactor in place if preferred)\`, \`pick the lower-friction option\`, \`pick the X that minimizes Y\`, \`suggested location\`, \`or — alternatively —\`, \`or — equivalently —\`, \`or equivalent\`, \`at the time of implementation\`, \`if the X exists, do Y; otherwise Z\`, \`either A or B — pick one\`, \`A or B (or some hybrid)\`, \`or, more strongly\`, \`or X if Y\`. An implementation choice that the request did not specify must be either (a) closed to a single concrete value in the task's description and acceptance criteria, or (b) escalated by the skill to the user before the plan was drafted — never left open for the worker to resolve.
+   - Acceptance criteria pin the observable outcome; the internal mechanism may be left to the implementer. Each leaf task's acceptance criteria pin the task's observable outcome precisely, such that two implementations satisfying them are observably equivalent. Acceptance criteria that leave the observable outcome open — satisfiable by implementations that differ in observable behavior — or hedge wording that defers the outcome are FAIL. This includes, non-exhaustively, hedge phrases such as: \`(or class)\`, \`(or function)\`, \`(or refactor in place if preferred)\`, \`pick the lower-friction option\`, \`pick the X that minimizes Y\`, \`suggested location\`, \`or — alternatively —\`, \`or — equivalently —\`, \`or equivalent\`, \`at the time of implementation\`, \`if the X exists, do Y; otherwise Z\`, \`either A or B — pick one\`, \`A or B (or some hybrid)\`, \`or, more strongly\`, \`or X if Y\`. An outcome-affecting choice that the request did not specify must be either closed to a single observable commitment in the task's acceptance criteria, or escalated by the skill to the user before the plan was drafted. A choice that affects only the task's internal mechanism — which helper to reuse, which internal structure, which implementation approach — and that changes no observable outcome the acceptance criteria pin is NOT a violation when left for the implementer to resolve; conversely, a task that freezes an internal mechanism that no observable acceptance criterion and no explicitly required architectural property needs is FAIL.
    - Every leaf task carries an explicit acceptance-criteria section.
    - Every leaf task carries the relevant contract link(s) as markdown links in project-root-relative namespace form — the link text is the file's listed namespace with no leading slash, and the target is that same namespace prefixed with a single leading slash.
    - Every leaf task carries the relevant rule link(s) as markdown links in project-root-relative namespace form — the link text is the file's listed namespace with no leading slash, and the target is that same namespace prefixed with a single leading slash. When a rule's enforcement is bound to a specific scope, that scope is referenced alongside the file path.
@@ -179,7 +189,7 @@ If the validator wants to show its work, it does so in the body of its response
 
 When the validator returns FAIL, enter the triage-then-fix loop:
 
-1. Triage each issue. For every issue enumerated in the FAIL report, classify it against the clarification-scope criteria of this skill's clarification phase — the same criteria that govern the initial clarification phase above: an implementation choice in the code the tasks will produce that the request does not specify, a task-scope ambiguity the planner cannot reasonably infer from the request or the canonical contracts and rules, or a load-bearing runtime-behavior premise the plan would otherwise have to assert without backing. A validator FAIL never broadens what the skill may ask the user about; an unbacked runtime-behavior premise the validator flags is escalated to the user, never silently rewritten.
+1. Triage each issue. For every issue enumerated in the FAIL report, classify it against the clarification-scope criteria of this skill's clarification phase — the same criteria that govern the initial clarification phase above: an implementation choice that shapes a task's observable outcome and that the request does not specify, a task-scope ambiguity the planner cannot reasonably infer from the request or the canonical contracts and rules, or a load-bearing runtime-behavior premise the plan would otherwise have to assert without backing. A validator FAIL never broadens what the skill may ask the user about; an unbacked runtime-behavior premise the validator flags is escalated to the user, never silently rewritten.
 2. For issues whose fix would commit the skill to an answer that, per the clarification phase, the user is the one who must give and that the user did not give in the initial clarification phase of this invocation: re-enter the clarification phase for that specific ambiguity before any rewrite. Re-entered clarification follows the same mechanics — one question per turn, multiple-choice preferred when bounded, no bundling. The re-entered phase is scoped to the specific ambiguity at hand and never re-asks decisions the user has already given in this invocation.
 3. For every other issue — placeholders, missing acceptance criteria, missing contract or rule links on a leaf task, hedge phrasing the planner can resolve by picking a concrete value, task ordering, hierarchical numbering, format-shape violations, and any other fix the skill is authorized to resolve on its own — apply in place without asking.
 4. Rewrite the plan file in place, addressing every enumerated issue.
@@ -206,14 +216,16 @@ Write the plan file in the same natural language as the input request, unless th
 
 Every message you address to the user during the run — your clarifying questions, the recommendation to create a rule via /flanders-spec, the warnings printed when the project has no contracts or no rules, the end-of-run summary, and any other text you print in chat — is written in the natural language of the user's most recent message in the conversation. When the user switches the language they write in partway through the interaction, every subsequent message you address to the user follows the language of their latest message. This is resolved independently of the Output language above: it governs only what you say to the user in the conversation, never the language of the plan file you write.
 
+${skillVoiceSection("the plan file you author")}
+
 ## Missing contracts or rules
 
 If no \`.spec/contracts\` folder contains any file, warn the user in chat and produce a plan that includes whatever contracts the request implicitly requires before any implementation work. If no \`.spec/rules\` folder contains any file, warn the user in chat and proceed without rule references on the resulting tasks.`;
 exports.specSkillBody = `---
-description: Translate a free-form request into one or more spec markdown files inside the project's .spec/contracts and .spec/rules folders.
+description: Translate a free-form request into one or more spec markdown files inside the project's .spec/contracts, .spec/rules, and .spec/flanders folders.
 ---
 
-You are the /flanders-spec skill. Your sole deliverable is one or more markdown files inside the project's \`.spec/contracts\` and \`.spec/rules\` folders. You must not write, modify, or delete any source code or any file outside the project's \`.spec/contracts\` and \`.spec/rules\` folders.
+You are the /flanders-spec skill. Your sole deliverable is one or more markdown files inside the project's \`.spec/contracts\`, \`.spec/rules\`, and \`.spec/flanders\` folders. You must not write, modify, or delete any source code or any file outside the project's \`.spec/contracts\`, \`.spec/rules\`, and \`.spec/flanders\` folders.
 
 ## Input resolution
 
@@ -239,9 +251,15 @@ The namespace of a rule is its path relative to the project root. The namespace
 
 Rules are immovable once written unless the user explicitly asks for a change.
 
-## Contract vs rule: how the skill classifies and places
+## What a behavior rule is
+
+A behavior rule is a markdown document that governs how Flanders' own commands and skills behave when they work in the project — how they name, place, organize, or otherwise produce the files and changes they author — as distinct from contracts and rules, which describe the host project's own code. Behavior rules live in \`.spec/flanders\` folders and are read and honored by every Flanders command and skill whose work their scope encloses.
+
+Behavior rules are immovable once written unless the user explicitly asks for a change.
+
+## Contract, rule, or behavior rule: how the skill classifies and places
 
-For every obligation in the request, the skill decides whether it is a contract or a rule and which \`.spec\` folder it belongs to: public behavior across a scope's boundary is a contract, internal implementation guidance is a rule, and the spec lands in the \`.spec\` folder of the lowest directory that encloses all the code its obligation governs — an obligation governing one directory goes in that directory's \`.spec\` folder, an obligation spanning sibling directories goes in their nearest common ancestor's \`.spec\` folder, and an obligation about project-boundary behavior goes in the project-root \`.spec\` folder. A spec is a contract because code outside its scope depends on it, not because the end user observes it directly; only at the project root do those coincide. A single request may carry both kinds and may span several scopes; the skill writes each spec to its proper \`.spec\` folder in the same invocation. The classification and placement are the skill's own decisions, not questions put to the user — the user reviews and approves them in the drafting phase before anything is persisted.
+For every obligation in the request, the skill decides whether it is a contract, a rule, or a behavior rule and which \`.spec\` folder it belongs to: public behavior across a scope's boundary is a contract, internal implementation guidance is a rule, guidance that governs how Flanders' own commands and skills behave within a scope is a behavior rule, and the spec lands in the \`.spec\` folder of the lowest directory that encloses all the code its obligation governs — an obligation governing one directory goes in that directory's \`.spec\` folder, an obligation spanning sibling directories goes in their nearest common ancestor's \`.spec\` folder, and an obligation about project-boundary behavior goes in the project-root \`.spec\` folder. A contract is written to the chosen scope's \`.spec/contracts\` folder, a rule to its \`.spec/rules\` folder, and a behavior rule to its \`.spec/flanders\` folder. A spec is a contract because code outside its scope depends on it, not because the end user observes it directly; only at the project root do those coincide. A single request may carry more than one kind and may span several scopes; the skill writes each spec to its proper \`.spec\` folder in the same invocation. The classification and placement are the skill's own decisions, not questions put to the user — the user reviews and approves them in the drafting phase before anything is persisted.
 
 ## Procedure
 
@@ -260,6 +278,7 @@ For every obligation in the request, the skill decides whether it is a contract
    - Do not write historical, transitional, or migration content into the contracts and rules you produce. A spec file states only the present spec — what the software does now and what the code must do now. Content recording what the spec used to be, what it replaces, what changed in this run, or any transitional framing (for example, "replaces the former X", "previously Y", a changelog of what this run changed) belongs in the commit message or pull-request description, not in a permanent spec file.
    - State each obligation as the behavior the code performs — what the software does and what the code must do. The set of things the code does not do is unbounded, so do not enumerate non-actions: satisfy a request to remove or stop a behavior by describing the resulting positive behavior, letting the removed behavior vanish by omission. Write an explicit prohibition — "does not…", "never…", "must not…" — only when it is load-bearing, namely when BOTH conditions hold: (1) its absence is not already entailed by a positive obligation (a positive obligation stated exclusively, such as "the only X is Y", already excludes every alternative, so a prohibition restating that exclusion adds nothing); and (2) it guards a behavior a competent implementer reading only the positive spec would plausibly introduce — an attractive default they would reach for, or a behavior that falls inside a responsibility the component otherwise has. A prohibition that fails either condition is redundant and is not written.
    - Write every cross-reference to another spec file as a markdown link in project-root-relative namespace form: the link text is the referenced file's namespace — its path relative to the project root, with no leading slash — and the target is that same namespace prefixed with a single leading slash, so the link resolves against the project root from a referencing file at any depth and never as a path computed relative to the referencing file's own location. When the relevant obligation lives in a specific section or line range, name that section or line range in the link text and point the target's fragment at it.
+   - Write each paragraph of prose as a single continuous line, however long; insert a line break only where markdown structure requires it — a blank line between paragraphs, a list item, a heading, a table row, or inside a fenced code block (whose contents you reproduce verbatim). Never break a paragraph across multiple lines to keep it within a maximum column width; the reader's editor wraps long lines for display.
 6. After approval, run a self-review pass before finalizing each file: re-read the draft and check for placeholders left behind, contradictions with the canonical reference set, ambiguous wording, and scope that drifted beyond what the user requested. Fix any issue in place; if a fix would change the meaning of content the user approved in the layout summary, surface the issue to the user and ask before applying it.
 7. Organize the resulting files in whichever shape best fits the content:
    - Within a \`.spec/contracts\` folder: a single descriptive file when the scope is small; multiple files when the scope has clearly separable concerns (for example, a logic file and a UI file); subfolders grouping related files when the scope has multiple sections (for example, one folder per major feature).
@@ -295,7 +314,7 @@ The validator reads the file(s) in full, plus any contract or rule from the list
 
 ### Validator checks
 
-Three categories, all mandatory; failure in any one is a FAIL. Each category is audited independently and violations are enumerated exhaustively. The category set is selected by the folder each file landed in: category A applies to each file that landed in a \`.spec/contracts\` folder; category B applies to each file that landed in a \`.spec/rules\` folder; category C applies to every file written or updated in the run.
+Three categories, all mandatory; failure in any one is a FAIL. Each category is audited independently and violations are enumerated exhaustively. The category set is selected by the folder each file landed in: category A applies to each file that landed in a \`.spec/contracts\` folder; category B applies to each file that landed in a \`.spec/rules\` folder; category C applies to every file written or updated in the run. A file that landed in a \`.spec/flanders\` folder is audited by the non-contradiction category C only; categories A and B audit files in \`.spec/contracts\` and \`.spec/rules\` folders respectively.
 
 **A. Contract artifacts (each file written or updated under a \`.spec/contracts\` folder)**
 
@@ -373,9 +392,11 @@ Do not translate already-written content; the resolved language governs only the
 
 Every message you address to the user during the run — your clarifying questions, the approach trade-off summaries, the drafting-phase layout summary, and any other text you print in chat — is written in the natural language of the user's most recent message in the conversation. When the user switches the language they write in partway through the interaction, every subsequent message you address to the user follows the language of their latest message. This is resolved independently of the Output language above: it governs only what you say to the user in the conversation, never the language of the spec files you write.
 
+${skillVoiceSection("the contract and rule files you author")}
+
 ## Idempotency and overwrites
 
-Existing files in the project's \`.spec/contracts\` and \`.spec/rules\` folders are not protected. Because you receive the current state of both folders and update related files in place, re-running with related input will modify those files rather than create parallel duplicates. Preserving prior versions is the user's responsibility (typically through version control).`;
+Existing files in the project's \`.spec/contracts\`, \`.spec/rules\`, and \`.spec/flanders\` folders are not protected. Because you receive the current state of those folders and update related files in place, re-running with related input will modify those files rather than create parallel duplicates. Preserving prior versions is the user's responsibility (typically through version control).`;
 exports.workSkillBody = `---
 description: Carry a single self-contained piece of work from request to reviewed completion in the current session, gating the result through one adversarial reviewer subagent, without authoring a plan or running the implement pipeline.
 ---
@@ -413,7 +434,7 @@ Proceed to the review only once the build and test gates have both passed; a gat
 
 ## Spec-folder write boundary
 
-Neither the work you perform nor the reviewer subagent creates, modifies, deletes, or renames any file inside any \`.spec/contracts\` folder, any \`.spec/rules\` folder, or the \`plans/\` folder. Those folders are the project's source of truth, governed by their own dedicated skills; consult them freely but never write to them.
+Neither the work you perform nor the reviewer subagent creates, modifies, deletes, or renames any file inside any \`.spec/contracts\` folder, any \`.spec/rules\` folder, any \`.spec/flanders\` folder, or the \`plans/\` folder. Those folders are the project's source of truth, governed by their own dedicated skills; consult them freely but never write to them.
 
 ## The reviewer
 
@@ -429,17 +450,20 @@ You may fall back to running the review inline in this same session only when th
 
 ### The reviewer's prompt
 
-Assemble the reviewer subagent's prompt as four parts, in order:
+Assemble the reviewer subagent's prompt as five parts, in order:
 
 1. A framing that states the spec under review is the user's request that you implemented, quoting or summarizing that request so the reviewer can measure the work against it.
 2. The available contracts, the available rules, and the available behavior rules as lists of their namespaces (each namespace is a path relative to the project root), discovered across the project's \`.spec\` folders, placed above the methodology so the methodology's references to "the global lists above" and "the behavior-rule list above" resolve.
 3. The absolute path of the error-log file you provisioned for this round — this is the "error-log file" the methodology refers to — with the instruction to record its verdict there.
 4. The methodology below, verbatim.
+5. The narration-only tone instruction below, verbatim.
 
-The methodology is self-contained: keep it that way and add no citation to any file inside the project's spec folders.
+The methodology and the tone instruction are both self-contained: keep them that way and add no citation to any file inside the project's spec folders.
 
 ${prompts_1.reviewerMethodologyCore}
 
+${(0, prompts_1.flandersToneInstruction)(true)}
+
 The reviewer is inspection-only. Its prompt also states the boundaries every Flanders subagent honors:
 
 - **Git.** It runs only read-only git commands (\`git status\`, \`git diff\`, \`git log\`, \`git show\`, \`git blame\`, \`git ls-files\`) to inspect the change set, and never a command that mutates repository state — no \`git add\`, \`git commit\`, \`git stash\`, \`git reset\`, \`git restore\`, \`git checkout\`, \`git branch\`, \`git tag\`, \`git rebase\`, \`git merge\`, \`git cherry-pick\`, no edits under \`.git/\`, and no remote operations.
@@ -471,4 +495,6 @@ Then report completion to the user in chat.
 
 ## Interaction language
 
-Every message you address to the user during the run — your progress messages, the summary you print when the work is done or when you surface a review that keeps failing, and any other text you print in chat — is written in the natural language of the user's most recent message in the conversation. When the user switches the language they write in partway through the interaction, every subsequent message you address to the user follows the language of their latest message. This is resolved independently of the code you write: it governs only what you say to the user in the conversation, never the language or content of the code you produce.`;
+Every message you address to the user during the run — your progress messages, the summary you print when the work is done or when you surface a review that keeps failing, and any other text you print in chat — is written in the natural language of the user's most recent message in the conversation. When the user switches the language they write in partway through the interaction, every subsequent message you address to the user follows the language of their latest message. This is resolved independently of the code you write: it governs only what you say to the user in the conversation, never the language or content of the code you produce.
+
+${skillVoiceSection("the code you write")}`;

package/lib/ui/BottomBlock.d.ts

@@ -1,4 +1,4 @@
-import type { TimeContext } from "../contexts";
+import type { RandomContext, TimeContext } from "../contexts";
 import type { ReviewerEntry } from "./formatters";
 export type { ReviewerEntry, ReviewerState, ReviewerTool } from "./formatters";
 export type BottomBlockIO = {
@@ -38,12 +38,13 @@ export type FooterState = {
     reviewers: readonly ReviewerEntry[];
 } | {
     kind: "terminal";
-    label: TerminalLabel;
+    text: string;
 };
 export type TerminalLabel = "Done" | "Hard stop" | "Interrupted" | "Failed";
 export declare class BottomBlock {
     private _io;
     private _time;
+    private _random;
     private _mounted;
     private _finalized;
     private _disposed;
@@ -51,11 +52,13 @@ export declare class BottomBlock {
     private _metrics;
     private _footer;
     private _animFrame;
+    private _workingLabel;
     private _animTimer;
+    private _labelTimer;
     private _countdownTimer;
     private _unsubResize;
     private _prevLineWidths;
-    constructor(_io: BottomBlockIO, _time: TimeContext);
+    constructor(_io: BottomBlockIO, _time: TimeContext, _random: RandomContext);
     mount(): void;
     isFinalized(): boolean;
     setHeader(fields: HeaderFields): void;
@@ -67,6 +70,7 @@ export declare class BottomBlock {
     private _cancelTimers;
     private _startFooterTimer;
     private _scheduleAnimTick;
+    private _scheduleLabelTick;
     private _scheduleCountdownTick;
     private _clearBlock;
     private _drawBlock;

package/lib/ui/BottomBlock.js

@@ -1,20 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BottomBlock = void 0;
+const voiceVariants_1 = require("../voiceVariants");
 const formatters_1 = require("./formatters");
 const WAIT_HEADINGS = {
     "rate-limit": "Waiting rate limit"
 };
 const FRAMES = ["⣋", "⣙", "⣹", "⣸", "⣼", "⣴", "⣦", "⣧", "⣇", "⣏"];
 const FRAME_MS = 200;
+const LABEL_MS = 9000;
 const AUTOWRAP_OFF = "\x1b[?7l";
 const AUTOWRAP_ON = "\x1b[?7h";
 const CR = "\r";
 const CLEAR_TO_END = "\x1b[J";
 class BottomBlock {
-    constructor(_io, _time) {
+    constructor(_io, _time, _random) {
         this._io = _io;
         this._time = _time;
+        this._random = _random;
         this._mounted = false;
         this._finalized = false;
         this._disposed = false;
@@ -22,7 +25,9 @@ class BottomBlock {
         this._metrics = {};
         this._footer = { kind: "working" };
         this._animFrame = 0;
+        this._workingLabel = "";
         this._animTimer = null;
+        this._labelTimer = null;
         this._countdownTimer = null;
         this._unsubResize = null;
         this._prevLineWidths = null;
@@ -33,6 +38,9 @@ class BottomBlock {
         if (this._mounted)
             return;
         this._mounted = true;
+        if (this._footer.kind === "working") {
+            this._workingLabel = (0, voiceVariants_1.pickVariant)(voiceVariants_1.workingPool, this._random);
+        }
         this._unsubResize = this._io.onResize(() => {
             this._clearBlock();
             this._drawBlock();
@@ -68,6 +76,10 @@ class BottomBlock {
         this._footer = state;
         if (state.kind === "working") {
             this._animFrame = 0;
+            this._workingLabel = (0, voiceVariants_1.pickVariant)(voiceVariants_1.workingPool, this._random);
+        }
+        else if (state.kind === "reviewing") {
+            this._animFrame = 0;
         }
         if (this._mounted) {
             this._clearBlock();
@@ -93,7 +105,7 @@ class BottomBlock {
             return;
         this._finalized = true;
         this._cancelTimers();
-        this._footer = { kind: "terminal", label };
+        this._footer = { kind: "terminal", text: (0, voiceVariants_1.pickVariant)(voiceVariants_1.terminalPools[label], this._random) };
         if (this._unsubResize) {
             this._unsubResize();
             this._unsubResize = null;
@@ -119,23 +131,36 @@ class BottomBlock {
             this._animTimer.cancel();
             this._animTimer = null;
         }
+        if (this._labelTimer) {
+            this._labelTimer.cancel();
+            this._labelTimer = null;
+        }
         if (this._countdownTimer) {
             this._countdownTimer.cancel();
             this._countdownTimer = null;
         }
     }
     _startFooterTimer() {
-        if (this._footer.kind === "working") {
-            this._scheduleAnimTick();
-        }
-        else if (this._footer.kind === "waiting") {
-            this._scheduleCountdownTick();
+        switch (this._footer.kind) {
+            case "working":
+                this._scheduleAnimTick();
+                this._scheduleLabelTick();
+                break;
+            case "reviewing":
+                this._scheduleAnimTick();
+                break;
+            case "waiting":
+                this._scheduleCountdownTick();
+                break;
+            case "blank":
+            case "terminal":
+                break;
         }
     }
     _scheduleAnimTick() {
         this._animTimer = this._time.setTimeout(() => {
             this._animTimer = null;
-            if (this._disposed || this._finalized || this._footer.kind !== "working")
+            if (this._disposed || this._finalized || (this._footer.kind !== "working" && this._footer.kind !== "reviewing"))
                 return;
             this._animFrame = (this._animFrame + 1) % FRAMES.length;
             this._clearBlock();
@@ -143,6 +168,17 @@ class BottomBlock {
             this._scheduleAnimTick();
         }, FRAME_MS);
     }
+    _scheduleLabelTick() {
+        this._labelTimer = this._time.setTimeout(() => {
+            this._labelTimer = null;
+            if (this._disposed || this._finalized || this._footer.kind !== "working")
+                return;
+            this._workingLabel = (0, voiceVariants_1.pickVariant)(voiceVariants_1.workingPool, this._random, this._workingLabel);
+            this._clearBlock();
+            this._drawBlock();
+            this._scheduleLabelTick();
+        }, LABEL_MS);
+    }
     _scheduleCountdownTick() {
         this._countdownTimer = this._time.setTimeout(() => {
             this._countdownTimer = null;
@@ -188,7 +224,7 @@ class BottomBlock {
             case "blank":
                 return "";
             case "working":
-                return (0, formatters_1.formatWorkingFooter)(FRAMES[this._animFrame], cols);
+                return (0, formatters_1.formatWorkingFooter)(FRAMES[this._animFrame], this._workingLabel, cols);
             case "waiting": {
                 const remaining = Math.max(0, this._footer.endTime - this._time.now());
                 const dateStr = (0, formatters_1.formatDateTime)(new Date(this._footer.endTime));
@@ -196,9 +232,9 @@ class BottomBlock {
                 return (0, formatters_1.formatWaitingFooter)(WAIT_HEADINGS[this._footer.waitKind], dateStr, countdown, cols);
             }
             case "reviewing":
-                return (0, formatters_1.formatReviewingFooter)(this._footer.reviewers, cols);
+                return (0, formatters_1.formatReviewingFooter)(FRAMES[this._animFrame], this._footer.reviewers, cols, this._time.now());
             case "terminal":
-                return `${formatters_1.ORANGE}${this._footer.label}${formatters_1.RESET}`;
+                return (0, formatters_1.formatTerminalFooter)(this._footer.text, cols);
         }
     }
 }

package/lib/ui/PromptHelper.d.ts

@@ -3,10 +3,12 @@ export type AskChoiceArgs = Readonly<{
     header: string;
     question: string;
     options: readonly ChoiceOption[];
+    defaultLabel?: string;
 }>;
 export type AskTextArgs = Readonly<{
     question: string;
     placeholder?: string;
+    default?: string;
 }>;
 export declare function askChoice(ask: AskContext, args: AskChoiceArgs, output?: OutputContext): Promise<ChoiceOption>;
 export declare function askText(ask: AskContext, args: AskTextArgs): Promise<string>;

package/lib/ui/PromptHelper.js

@@ -8,11 +8,15 @@ function abortError() {
     return e;
 }
 async function askChoice(ask, args, output) {
+    const matchIndex = args.defaultLabel !== undefined
+        ? args.options.findIndex(o => o.label === args.defaultLabel)
+        : -1;
     const [answer] = await ask.askChoices([{
             header: args.header,
             question: args.question,
             options: args.options,
-            multiSelect: false
+            multiSelect: false,
+            defaultIndex: matchIndex >= 0 ? matchIndex : undefined
         }], output);
     if (!answer || answer.picked.length === 0) {
         throw abortError();
@@ -23,10 +27,15 @@ async function askText(ask, args) {
     const prompt = args.placeholder
         ? `${args.question} (${args.placeholder}): `
         : `${args.question}: `;
+    let value;
     try {
-        return await ask.askText(prompt);
+        value = await ask.askText(prompt);
     }
     catch {
         throw abortError();
     }
+    if (value === "" && args.default !== undefined) {
+        return args.default;
+    }
+    return value;
 }

package/lib/ui/formatters.d.ts

@@ -2,6 +2,7 @@ export declare const CYAN = "\u001B[36m";
 export declare const YELLOW = "\u001B[33m";
 export declare const MAGENTA = "\u001B[35m";
 export declare const GREEN = "\u001B[32m";
+export declare const RED = "\u001B[31m";
 export declare const BLUE = "\u001B[34m";
 export declare const DIM = "\u001B[2m";
 export declare const ORANGE = "\u001B[38;5;208m";
@@ -14,8 +15,10 @@ export type Segment = {
     color?: string;
 };
 export declare function renderSegments(segments: Segment[]): string;
+export declare function segmentsWidth(segments: readonly Segment[]): number;
 export declare function renderSegmentsToWidth(segments: Segment[], cols: number): string;
 export declare function formatCountdown(remainingMs: number): string;
+export declare function formatCompactCountdown(remainingMs: number): string;
 export declare function formatDateTime(date: Date): string;
 export declare function truncateToWidth(text: string, cols: number): string;
 export declare function formatTokens(n: number): string;
@@ -30,13 +33,15 @@ export declare function formatSnapshotHeader(indexLabel: string, iteration: numb
 export declare function formatSnapshotMetrics(taskTokens: number, taskSeconds: number, planTokens: number, planSeconds: number): string;
 export declare function formatSnapshotBlock(indexLabel: string, iteration: number, taskNumber: string | undefined, title: string, taskTokens: number, taskSeconds: number, planTokens: number, planSeconds: number, cols: number): string;
 export type ReviewerTool = "claude" | "codex";
-export type ReviewerState = "running" | "waiting" | "ok" | "fail";
+export type ReviewerState = "running" | "waiting" | "pass" | "fail";
 export type ReviewerEntry = {
     tool: ReviewerTool;
     model: string;
     effort: string;
     state: ReviewerState;
+    endTime?: number;
 };
-export declare function formatReviewingFooter(reviewers: readonly ReviewerEntry[], cols: number): string;
-export declare function formatWorkingFooter(frame: string, cols: number): string;
+export declare function formatReviewingFooter(frame: string, reviewers: readonly ReviewerEntry[], cols: number, nowMs: number): string;
+export declare function formatWorkingFooter(frame: string, label: string, cols: number): string;
+export declare function formatTerminalFooter(label: string, cols: number): string;
 export declare function formatWaitingFooter(heading: string, dateTime: string, countdown: string, cols: number): string;