flanders 0.10.0 → 0.11.0

package/README.md

@@ -68,7 +68,7 @@ Flanders installs at one of two scopes, chosen with a pair of mutually exclusive
 
 ### What it writes
 
-For each AI tool you select for skills, `install` writes one skill artifact per Flanders skill (`/flanders-spec`, `/flanders-plan`, and `/flanders-work`) into that tool's skill folder for the chosen scope:
+For each AI tool you select for skills, `install` writes one skill artifact per Flanders skill (`/flanders-spec`, `/flanders-plan`, `/flanders-work`, and `/flanders-hard-stop-review`) into that tool's skill folder for the chosen scope:
 
 | Tool | Project scope | Global scope |
 | --- | --- | --- |
@@ -137,7 +137,7 @@ Updated the lib and itching for the freshest skills, neighbor? Just run:
 flanders update
 ```
 
-`update` takes no flags. It scans the four skill destinations `install` writes to — Claude Code's `.claude/skills/` and `~/.claude/skills/`, and Codex CLI's `.codex/prompts/` and `~/.codex/prompts/` — and wherever it finds at least one Flanders skill artifact already in place, it rewrites the full `/flanders-spec`, `/flanders-plan`, and `/flanders-work` trio there with the current version. A destination where no Flanders skill artifact is present is left untouched, so `update` refreshes the installations you already have and never creates one where you had none.
+`update` takes no flags. It scans the four skill destinations `install` writes to — Claude Code's `.claude/skills/` and `~/.claude/skills/`, and Codex CLI's `.codex/prompts/` and `~/.codex/prompts/` — and wherever it finds at least one Flanders skill artifact already in place, it rewrites the full `/flanders-spec`, `/flanders-plan`, `/flanders-work`, and `/flanders-hard-stop-review` set there with the current version. A destination where no Flanders skill artifact is present is left untouched, so `update` refreshes the installations you already have and never creates one where you had none.
 
 ## Configuration
 
@@ -152,26 +152,32 @@ When a command reads the configuration, a project-scope `.flanders/` always take
 
 ## Usage
 
-With Flanders installed, here's how to put it to work — running plans from the CLI and shaping them with the three skills.
+With Flanders installed, here's how to put it to work — running plans from the CLI and shaping them with the four skills.
 
-### The three skills
+### The four skills
 
 - **`/flanders-spec`** — turns a free-form request into your contracts, rules, and behavior rules, written into the `.spec/contracts`, `.spec/rules`, and `.spec/flanders` folders.
 - **`/flanders-plan`** — derives a single, ordered, specification-aware work plan from your request.
 - **`/flanders-work`** — implements a small, self-contained request directly and gates it through build, test, and a single adversarial review, all in one invocation — no plan file and no commit.
+- **`/flanders-hard-stop-review`** — diagnoses an `implement` hard stop from its preserved temporary folder and recommends how to relaunch `implement` so the stuck task finishes instead of stopping again.
 
-Each skill takes the same optional `<data>` argument:
+The first three skills take the same optional `<data>` argument, and `/flanders-hard-stop-review` takes one too:
 
 ```
 /flanders-spec [<data>]
 /flanders-plan [<data>]
 /flanders-work [<data>]
+/flanders-hard-stop-review [<data>]
 ```
 
+For `/flanders-spec`, `/flanders-plan`, and `/flanders-work`, `<data>` is your request:
+
 - Omit it, and the skill takes your request straight from the conversation.
 - Give it a path to an existing file, and the skill reads that file as the input.
 - Give it any other text, and the skill uses that text verbatim.
 
+For `/flanders-hard-stop-review`, `<data>` is the path of the preserved hard-stop temporary folder to diagnose — omit it, and the skill takes that path from the conversation.
+
 ### Implementing a plan
 
 ```sh
@@ -254,4 +260,4 @@ It won't leave you guessing, though. Flanders prints an error that names the tas
 
 Inside you'll find the sessions from every attempt on the task: the worker's output, the build and test output, each reviewer's output, and the `error.log` that briefed the final iteration. It's the whole story of what was tried and where each go-round fell short.
 
-And here's the neighborly part — you don't have to untangle it all yourself. Hand that folder to your AI coding tool and just ask it to review the folder and tell you why the run failed. It'll read back through the sessions and walk you through what went wrong, so you can mend the spec, the plan, or the task and send Flanders off to try again.
+And here's the neighborly part — you don't have to untangle it all yourself. Invoke **`/flanders-hard-stop-review`** in your AI coding tool and hand it that folder's path, and it reads back through the sessions, tells you why the run failed, and recommends how to relaunch `implement` so the stuck task finishes this time — mending the spec or the plan, or simply running it again.

package/lib/commands/Implement.d.ts

@@ -40,8 +40,9 @@ export declare class Implement {
     private _currentIteration;
     private _currentTask;
     private _taskStartedAt;
-    private _taskRateLimitMs;
+    private _taskExcludedMs;
     private _taskRateLimitStartedAt;
+    private _reviewPauseStartedAt;
     private _taskTokens;
     private _otherTasksSeconds;
     private _runPromise;
@@ -64,6 +65,8 @@ export declare class Implement {
     private _setReviewerState;
     private _setReviewerWaiting;
     private _writeReviewerEntry;
+    private _syncReviewPause;
+    private _endReviewPause;
     private _renderReviewingFooter;
     private _setReviewerLogicalStatus;
     private _evaluateReviewRoundCompletion;

package/lib/commands/Implement.js

@@ -85,8 +85,9 @@ class Implement {
         this._currentIteration = 0;
         this._currentTask = null;
         this._taskStartedAt = 0;
-        this._taskRateLimitMs = 0;
+        this._taskExcludedMs = 0;
         this._taskRateLimitStartedAt = null;
+        this._reviewPauseStartedAt = null;
         this._taskTokens = { it: 0, ot: 0 };
         this._otherTasksSeconds = 0;
         this._runPromise = this._run(rawArgs);
@@ -271,7 +272,7 @@ class Implement {
         });
     }
     _activeSeconds() {
-        return Math.max(0, Math.floor((this._contexts.time.now() - this._taskStartedAt - this._taskRateLimitMs) / 1000));
+        return Math.max(0, Math.floor((this._contexts.time.now() - this._taskStartedAt - this._taskExcludedMs) / 1000));
     }
     async _persistMetrics(plan, line) {
         try {
@@ -285,7 +286,7 @@ class Implement {
         if (!this._currentTask || this._taskRateLimitStartedAt !== null)
             return;
         const planTotals = plan.planTotals();
-        const anchorMs = this._taskStartedAt + this._taskRateLimitMs;
+        const anchorMs = this._taskStartedAt + this._taskExcludedMs;
         this._block.setMetrics({
             task: { tokens: this._taskTokens.it + this._taskTokens.ot, anchorMs, baseSeconds: 0 },
             plan: { tokens: planTotals.it + planTotals.ot, anchorMs, baseSeconds: this._otherTasksSeconds }
@@ -306,8 +307,9 @@ class Implement {
         this._currentWorkerSessionId = null;
         this._workerSessionTokens = { inputTokens: 0, outputTokens: 0 };
         this._taskStartedAt = this._contexts.time.now();
-        this._taskRateLimitMs = 0;
+        this._taskExcludedMs = 0;
         this._taskRateLimitStartedAt = null;
+        this._reviewPauseStartedAt = null;
         this._taskTokens = { it: 0, ot: 0 };
         this._otherTasksSeconds = plan.planTotals().t - task.metrics.t;
         this._updateMetrics(plan);
@@ -515,8 +517,23 @@ class Implement {
             next.endTime = endTime;
         }
         this._reviewerStates[reviewerIdx] = next;
+        this._syncReviewPause();
         this._renderReviewingFooter();
     }
+    _syncReviewPause() {
+        if (this._reviewerStates.some(r => r.state === "running")) {
+            this._endReviewPause();
+        }
+        else {
+            this._reviewPauseStartedAt = this._contexts.time.now();
+        }
+    }
+    _endReviewPause() {
+        if (this._reviewPauseStartedAt !== null) {
+            this._taskExcludedMs += this._contexts.time.now() - this._reviewPauseStartedAt;
+            this._reviewPauseStartedAt = null;
+        }
+    }
     _renderReviewingFooter() {
         if (!this._block || this._block.isFinalized() || !this._reviewerStates)
             return;
@@ -570,6 +587,7 @@ class Implement {
             }
         }));
         await Promise.all(launches);
+        this._endReviewPause();
         if (this._disposed) {
             return false;
         }
@@ -709,7 +727,7 @@ class Implement {
             },
             onLongWaitEnd: () => {
                 if (this._taskRateLimitStartedAt !== null) {
-                    this._taskRateLimitMs += this._contexts.time.now() - this._taskRateLimitStartedAt;
+                    this._taskExcludedMs += this._contexts.time.now() - this._taskRateLimitStartedAt;
                     this._taskRateLimitStartedAt = null;
                 }
                 if (this._disposed)

package/lib/commands/skillArtifacts.js

@@ -10,7 +10,8 @@ const skills_1 = require("../prompts/skills");
 exports.SKILLS = [
     { name: "flanders-spec", body: skills_1.specSkillBody },
     { name: "flanders-plan", body: skills_1.planSkillBody },
-    { name: "flanders-work", body: skills_1.workSkillBody }
+    { name: "flanders-work", body: skills_1.workSkillBody },
+    { name: "flanders-hard-stop-review", body: skills_1.hardStopReviewSkillBody }
 ];
 const CLAUDE_SKILLS_SUBDIR = ".claude/skills";
 const CODEX_PROMPTS_SUBDIR = ".codex/prompts";
@@ -38,7 +39,7 @@ function stripYamlFrontmatter(body) {
     }
     return body.slice(closerIndex + "\n---\n".length);
 }
-async function writeDirectorySkillTrio(fs, scopeRoot, tool, isDisposed) {
+async function writeDirectorySkillArtifacts(fs, scopeRoot, tool, isDisposed) {
     const skillsRoot = (0, fsUtils_1.joinPath)(scopeRoot, CLAUDE_SKILLS_SUBDIR);
     const writtenPaths = [];
     for (const skill of exports.SKILLS) {
@@ -93,5 +94,5 @@ async function writeSkillArtifacts(fs, scopeRoot, tool, isDisposed) {
         }
         return { ok: true, writtenPaths };
     }
-    return writeDirectorySkillTrio(fs, scopeRoot, tool, isDisposed);
+    return writeDirectorySkillArtifacts(fs, scopeRoot, tool, isDisposed);
 }

package/lib/prompts/skills.d.ts

@@ -1,3 +1,4 @@
 export declare const planSkillBody: string;
 export declare const specSkillBody: string;
 export declare const workSkillBody: string;
+export declare const hardStopReviewSkillBody: string;

package/lib/prompts/skills.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.workSkillBody = exports.specSkillBody = exports.planSkillBody = void 0;
+exports.hardStopReviewSkillBody = exports.workSkillBody = exports.specSkillBody = exports.planSkillBody = void 0;
 const PlanFile_1 = require("../plan/PlanFile");
 const prompts_1 = require("./prompts");
 function skillVoiceSection(authoredArtifactExclusion) {
@@ -38,7 +38,7 @@ The user invokes you as: /flanders-plan [<data>]
 
    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.
+5. Persist exactly one markdown file inside the project's plans/ folder. The filename is \`YYYY-MM-DD_HH.MM-<descriptive-subject>.md\`: a generation-timestamp prefix — a four-digit year, a two-digit month, and a two-digit day joined by \`-\`, then a single \`_\`, then a two-digit hour on a 24-hour clock and a two-digit minute joined by \`.\`, then a single \`-\` — immediately followed by a subject descriptive of the plan's content. The timestamp is the machine's local date and time at the moment the plan file is generated, and every numeric component is zero-padded to its fixed width, so the prefix always has the same length and plan files sort chronologically by name.
 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.
 
 ## Plan file format
@@ -500,3 +500,52 @@ Then report completion to the user in chat.
 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")}`;
+exports.hardStopReviewSkillBody = `---
+description: Diagnose a hard stop of the implement command and recommend how to relaunch it so the same task completes.
+---
+
+You are the /flanders-hard-stop-review skill. When \`flanders implement\` exceeds its per-task iteration cap it ends the run, preserves its temporary folder on disk, and points the user at that folder. You diagnose why the hard-stopped task never reached a clean iteration and recommend the concrete action that lets \`implement\` be relaunched so the task completes instead of stopping again.
+
+## Input resolution
+
+The user invokes you as: /flanders-hard-stop-review [<data>]
+
+\`<data>\` is the filesystem path of the preserved hard-stop temporary folder — the path the hard stop printed. When \`<data>\` is supplied, it names the folder you analyze. When \`<data>\` is omitted, take that path from the conversation.
+
+## Behavior
+
+Your work is read-only, drawing only on the preserved hard-stop temporary folder, the plan file, and the project's spec corpus — not the AI tools' own session transcripts.
+
+1. **Read the preserved evidence.** Read the preserved hard-stop temporary folder: its per-iteration worker, build, test, and reviewer output logs, its briefing \`error.log\`, and its consolidated \`spec.md\`, together with each per-reviewer folder's \`error.log\`. From that evidence identify the task that hard-stopped — its plan-file line number and title — and the plan file the run was implementing.
+
+2. **Ground the analysis in the project's specs.** Read the identified plan file and the contracts and rules the hard-stopped task references, consulting the wider spec corpus as far as the diagnosis needs.
+
+3. **Classify the hard stop.** Examine how the iterations progressed — what each iteration changed and how the recorded failures evolved from one iteration to the next — and classify the hard stop as one of two cases:
+   - The task made real progress across iterations, so the hard stop reflects a task larger than the iteration cap can finish or a transient failure, and a fresh run or a smaller task would carry it through.
+   - The iterations circled the same unresolved failure with no net progress — a loop — driven by a cause the next run must remove first: a contradictory or ambiguous contract or rule, an acceptance criterion no implementation can satisfy as written, a task premise about runtime behavior the code does not bear out, a task scoped too large or ordered ahead of a dependency it needs, or a review that keeps re-failing the change for the same reason.
+
+4. **Map the cause to the action that removes it:**
+   - Re-run \`flanders implement\` unchanged, when the failure was transient or the task was progressing and needs only a fresh iteration budget. The per-task iteration cap is a fixed five and is not configurable, so the remedy for a task that needs more attempts is a fresh run — which resets the per-task iteration counter to zero — or a task split into smaller tasks, and never a raised cap.
+   - Revise the plan through \`/flanders-plan\`: split the hard-stopped task into smaller tasks, correct acceptance criteria or a task premise the iterations proved wrong, or reorder the task against the dependency it needs.
+   - Fix the spec through \`/flanders-spec\`: resolve the contradictory or ambiguous contract or rule that left the task unsatisfiable.
+   - A combination of the above, when the evidence shows more than one cause.
+
+5. **Present your root-cause finding and recommendation in chat.**
+
+## Recommending and launching the next step
+
+After presenting the diagnosis, ask the user which skill to launch to carry out the recommendation: \`/flanders-spec\`, \`/flanders-plan\`, or neither. Recommend the skill the action you selected in step 4 points to. When the user chooses one, launch it in the same session with no \`<data>\` argument. It takes the diagnosis from the conversation and operates under its own write boundary; yours remains read-only. When the recommended fix is to re-run \`implement\` unchanged, state the \`flanders implement\` command for the user to run and launch nothing. When the user declines, end the run.
+
+## Write boundary
+
+You create, modify, delete, and rename no file of your own: not code, not a plan file, and no file inside any \`.spec/contracts\`, \`.spec/rules\`, or \`.spec/flanders\` folder. Every file change happens only through a skill you launch, under that skill's own write authority.
+
+## Interaction language
+
+Every message you address to the user during the run 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.
+
+${(0, prompts_1.buildFlandersVoiceSection)({
+    subject: "the messages you address to the user",
+    languageFraming: "the resolved interaction language you are addressing the user in",
+    finalExclusion: ""
+})}`;

package/lib/ui/BottomBlock.js

@@ -76,8 +76,11 @@ class BottomBlock {
         if (this._disposed || this._finalized)
             return;
         this._cancelTimers();
-        if (state.kind === "waiting") {
-            this._metricsPausedAtMs = this._time.now();
+        const paused = state.kind === "waiting" || (state.kind === "reviewing" && !state.reviewers.some(r => r.state === "running"));
+        if (paused) {
+            if (this._metricsPausedAtMs === null) {
+                this._metricsPausedAtMs = this._time.now();
+            }
         }
         else if (this._metricsPausedAtMs !== null) {
             this._metricsPauseAccumMs += this._time.now() - this._metricsPausedAtMs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flanders",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Flanders never breaks a rule",
   "main": "lib/",
   "types": "lib/types",