@oscaner-skills/cdd-engine 4.7.0 → 4.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/contract/completion-criterion.js +179 -57
- package/dist/contract/declare.js +4 -1
- package/dist/contract/invariants.js +95 -19
- package/dist/contract/rules.js +19 -5
- package/dist/contract/task-blocks.js +46 -0
- package/dist/face/cli.js +92 -7
- package/dist/face/declare.js +5 -9
- package/dist/face/lifecycle.js +122 -14
- package/dist/face/preview.js +1 -1
- package/dist/face/words.js +4 -4
- package/dist/render/templates.js +13 -4
- package/dist/session/dispatch-authority.js +58 -10
- package/dist/session/handoff-schema.js +8 -1
- package/dist/session/inflight.js +44 -18
- package/dist/session/ledger.js +50 -3
- package/dist/session/preflight.js +5 -5
- package/package.json +1 -1
|
@@ -33,6 +33,15 @@ export class PlanTaskBlocksReader {
|
|
|
33
33
|
static STEP_LINE = TaskBlockGrammar.STEP_LINE;
|
|
34
34
|
/** The `— checkable:` clause separator. */
|
|
35
35
|
static CHECKABLE = TaskBlockGrammar.CHECKABLE;
|
|
36
|
+
/** The placeholder spellings a `Files` value line may carry INSTEAD of a path — the
|
|
37
|
+
* wave's "this task changes no file" declaration: a blank value, the bare `none`
|
|
38
|
+
* and the parenthetical `(none)`. Matched case-insensitively on the trimmed,
|
|
39
|
+
* bullet- and label-stripped remainder, and token by token for a quoted one. */
|
|
40
|
+
static FILE_PLACEHOLDERS = new Set(["", "none", "(none)"]);
|
|
41
|
+
/** The optional line label a `Files` row may carry (`- Modify: …` · `- Test: …`) —
|
|
42
|
+
* stripped so the value's own token is what remains; a line without one keeps its
|
|
43
|
+
* whole remainder. */
|
|
44
|
+
static FILE_ROW_LABEL = /^[A-Za-z][\w ()/.+-]*?:\s+/;
|
|
36
45
|
/** A dependency id token — the declared `DependsOn id` value domain (the SAME
|
|
37
46
|
* source string the registry element carries). */
|
|
38
47
|
static ID_TOKEN = new RegExp(TASK_ID_VALUE_PATTERN);
|
|
@@ -62,4 +71,41 @@ export class PlanTaskBlocksReader {
|
|
|
62
71
|
section(content, heading) {
|
|
63
72
|
return MarkdownTree.parse(content).sectionText(heading);
|
|
64
73
|
}
|
|
74
|
+
/** The path tokens one block's `Files` declaration names — the read face behind the
|
|
75
|
+
* implement criterion's verification-wave cell (P30 §2.4). An empty result is a
|
|
76
|
+
* REAL claim ("this task changes no file"), so the read fails SAFE: an absent
|
|
77
|
+
* section, a blank value, a bare bullet and the `(none)` placeholder declare zero
|
|
78
|
+
* paths, while an unrecognized remainder is returned as one token — text this
|
|
79
|
+
* reader does not understand never reads as "no paths". */
|
|
80
|
+
filePathsOf(block) {
|
|
81
|
+
const field = block.fields.find((entry) => entry.key === "Files");
|
|
82
|
+
if (field === undefined)
|
|
83
|
+
return [];
|
|
84
|
+
const tokens = [];
|
|
85
|
+
for (const line of field.lines) {
|
|
86
|
+
for (const token of PlanTaskBlocksReader.#fileTokensOf(line))
|
|
87
|
+
tokens.push(token);
|
|
88
|
+
}
|
|
89
|
+
return tokens;
|
|
90
|
+
}
|
|
91
|
+
/** One `Files` value line's tokens — the quoted spans when the line quotes its paths
|
|
92
|
+
* (the plan convention), else the whole stripped remainder. The bullet marker is
|
|
93
|
+
* stripped with its trailing whitespace OR at the line's end, so a bare `-` bullet
|
|
94
|
+
* (a row that declares no path at all) reads as an empty value. */
|
|
95
|
+
static #fileTokensOf(line) {
|
|
96
|
+
const remainder = line
|
|
97
|
+
.replace(/^[-*+](?:\s+|$)/, "")
|
|
98
|
+
.replace(PlanTaskBlocksReader.FILE_ROW_LABEL, "")
|
|
99
|
+
.trim();
|
|
100
|
+
if (PlanTaskBlocksReader.FILE_PLACEHOLDERS.has(remainder.toLowerCase()))
|
|
101
|
+
return [];
|
|
102
|
+
const spans = [...remainder.matchAll(/`([^`]+)`/g)]
|
|
103
|
+
.map((match) => (match[1] ?? "").trim())
|
|
104
|
+
.filter((token) => token.length > 0);
|
|
105
|
+
// A line that quotes its paths declares exactly those; a quoted placeholder
|
|
106
|
+
// (`` `(none)` ``) declares none of them.
|
|
107
|
+
if (spans.length === 0)
|
|
108
|
+
return [remainder];
|
|
109
|
+
return spans.filter((token) => !PlanTaskBlocksReader.FILE_PLACEHOLDERS.has(token.toLowerCase()));
|
|
110
|
+
}
|
|
65
111
|
}
|
package/dist/face/cli.js
CHANGED
|
@@ -82,6 +82,11 @@ import { CommandTreeBuilder } from "./projection.js";
|
|
|
82
82
|
import { Terminator } from "./termination.js";
|
|
83
83
|
import { Words } from "./words.js";
|
|
84
84
|
export { CliLifecycle as HarnessDispatch } from "./lifecycle.js";
|
|
85
|
+
/** The `--recover` double-gap refusal (P30 §2.1③) — NEITHER leg holds: no stale
|
|
86
|
+
* in-flight record stands on this tree, and the line is not at drift ∧ pending-fix.
|
|
87
|
+
* The command dispatches nothing: a flag that silently degrades into an ordinary
|
|
88
|
+
* dispatch is exactly the silent fallback §2.1③ forbids. */
|
|
89
|
+
const RECOVER_NOTHING = "--recover has nothing to take over and nothing to reopen — no stale in-flight record stands on this tree (①), and this line is not at drift ∧ pending-fix (②); nothing was dispatched";
|
|
85
90
|
/**
|
|
86
91
|
* The Cli — the command face's parse/run surface over the assembled object graph.
|
|
87
92
|
* runArgv() parses through the commander program and rejects unknown flags (the
|
|
@@ -516,7 +521,7 @@ export class Cli {
|
|
|
516
521
|
// The explicit takeover flag — VOID under --dry-run: the preview face never
|
|
517
522
|
// acquires, so a takeover there would have no write channel at all. The
|
|
518
523
|
// preview still judges the same gate, sees the same holder facts, and exits 1.
|
|
519
|
-
|
|
524
|
+
recover: !parsed.dryRun && parsed.args.recover === "true",
|
|
520
525
|
});
|
|
521
526
|
// The per-invocation batch cursor: the in-memory done set mirrors the on-disk
|
|
522
527
|
// ledger's closed waves (the C5 closure single face) — NOT a "every non-group
|
|
@@ -546,6 +551,20 @@ export class Cli {
|
|
|
546
551
|
scene.state.markDone(id);
|
|
547
552
|
}
|
|
548
553
|
const expected = verb === "implement" ? "implement" : verb === "fix" ? "fix" : scene.face.product.reviewLead;
|
|
554
|
+
// THE `--recover` judgment (P30 §2.1①–③), at the composition root and BEFORE the
|
|
555
|
+
// dispatch verdict: the takeover lands first, the supersede stamp second and the
|
|
556
|
+
// `N+1` review dispatch third — the order is fixed HERE, never inside `step()`.
|
|
557
|
+
// A STRUCTURE refusal keeps its own face: the recovery legs are skipped, so a dirty
|
|
558
|
+
// tree or a live holder is never displaced by an argument.
|
|
559
|
+
const recovery = !parsed.dryRun &&
|
|
560
|
+
parsed.args.recover === "true" &&
|
|
561
|
+
this.#authority.structureRefusal(preflight) === null
|
|
562
|
+
? await this.#recoverRun(verb, type, scene, parsed, inflight)
|
|
563
|
+
: null;
|
|
564
|
+
if (recovery !== null && recovery.kind === "blocked") {
|
|
565
|
+
this.#io.stderr(`${this.#words.station("blocked")} ${recovery.message}\n`);
|
|
566
|
+
return 1;
|
|
567
|
+
}
|
|
549
568
|
// THE dispatch verdict (P27 §2.2) — ONE authority over the three legs, in
|
|
550
569
|
// priority order: the structure leg (the pre-flight verdict just judged), the
|
|
551
570
|
// upstream station leg, then this line's own phase. A refusal is ONE verdict —
|
|
@@ -615,7 +634,7 @@ export class Cli {
|
|
|
615
634
|
if (!parsed.dryRun && type === "wave" && scene.planText !== null)
|
|
616
635
|
scene.briefPath = this.#gate.renderBrief(scene, parsed);
|
|
617
636
|
const statuses = [];
|
|
618
|
-
const dispatch = this.#dispatchOf(scene, parsed);
|
|
637
|
+
const dispatch = await this.#dispatchOf(scene, parsed, recovery?.harness ?? null);
|
|
619
638
|
const run = new Lifecycle({
|
|
620
639
|
face: scene.face,
|
|
621
640
|
state: scene.state,
|
|
@@ -755,10 +774,77 @@ export class Cli {
|
|
|
755
774
|
* retired synthetic approval (`() => ({ status: "APPROVED", findings: [] })`)
|
|
756
775
|
* has no remaining caller: a preview books no round and fabricates no
|
|
757
776
|
* conclusion. */
|
|
758
|
-
#dispatchOf(scene, parsed) {
|
|
777
|
+
async #dispatchOf(scene, parsed, recovered = null) {
|
|
759
778
|
if (this.#dispatch !== null)
|
|
760
779
|
return this.#dispatch;
|
|
761
|
-
const harness =
|
|
780
|
+
const harness = recovered ?? this.#lifecycleOf(scene, parsed);
|
|
781
|
+
// The abort fold already ran at the composition root's `--recover` judgment
|
|
782
|
+
// (`#recoverRun`) when a harness was handed in; the injected/default face keeps
|
|
783
|
+
// its own fold here, so the takeover always precedes this dispatch's own record.
|
|
784
|
+
if (recovered === null && !parsed.dryRun && parsed.args.recover === "true") {
|
|
785
|
+
await harness.foldAbort();
|
|
786
|
+
}
|
|
787
|
+
return harness.step();
|
|
788
|
+
}
|
|
789
|
+
/** The `--recover` judgment (spec §2.1①–③) — the two legs, judged in order and
|
|
790
|
+
* allowed to stack:
|
|
791
|
+
* ① the ABORT leg — a stale in-flight record is taken over and, when it still
|
|
792
|
+
* names the killed round, folded into the ledger (`foldAbort`);
|
|
793
|
+
* ② the REOPEN leg — `review` on a doc / branch line only, at drift ∧ pending-fix,
|
|
794
|
+
* with no round in flight: the old review is stamped `supersededBy` and the
|
|
795
|
+
* dispatch that follows allocates `N+1`;
|
|
796
|
+
* ③ neither → the double-gap BLOCKED, naming both missing conditions, and no
|
|
797
|
+
* dispatch at all.
|
|
798
|
+
* The ORDER is the ruling (§2.1④): the abort fold first, the stamp second, the
|
|
799
|
+
* `N+1` dispatch third — it lives here, not in `step()`'s internals. `fix --recover`
|
|
800
|
+
* and `implement --recover` take leg ① only (never a reopen), wave lines likewise
|
|
801
|
+
* (their reopen face stays P29's brief-drift). */
|
|
802
|
+
async #recoverRun(verb, type, scene, parsed, inflight) {
|
|
803
|
+
const harness = this.#lifecycleOf(scene, parsed);
|
|
804
|
+
const stale = (await inflight.staleState()) !== null;
|
|
805
|
+
if (stale)
|
|
806
|
+
await harness.foldAbort();
|
|
807
|
+
const reopened = await this.#reopenLeg(verb, type, scene, inflight);
|
|
808
|
+
if (stale || reopened)
|
|
809
|
+
return { kind: "allowed", harness };
|
|
810
|
+
return { kind: "blocked", message: RECOVER_NOTHING };
|
|
811
|
+
}
|
|
812
|
+
/** The reopen leg (spec §2.3) — its three conditions judged here, and the stamp
|
|
813
|
+
* written when all hold: ① `reviewGate` open (the doc drifted), ② a fix still owed
|
|
814
|
+
* (`pendingFix`), ③ no round in flight (a live holder was refused upstream; a stale
|
|
815
|
+
* one was already taken over). Trigger face pinned: `review` on a doc / branch line
|
|
816
|
+
* ONLY — `fix` / `implement` and the wave line never reopen. Returns whether the
|
|
817
|
+
* supersede stamp landed. */
|
|
818
|
+
async #reopenLeg(verb, type, scene, inflight) {
|
|
819
|
+
if (verb !== "review")
|
|
820
|
+
return false;
|
|
821
|
+
if (type !== "branch" && !TargetFaceTable.isDocShape(type))
|
|
822
|
+
return false;
|
|
823
|
+
const identity = this.#gate.lineIdentity(scene);
|
|
824
|
+
if (identity.key === null || identity.doc === null)
|
|
825
|
+
return false;
|
|
826
|
+
const state = await inflight.inspect();
|
|
827
|
+
if (state.kind !== "absent" || existsSync(inflight.lockPath()))
|
|
828
|
+
return false;
|
|
829
|
+
const ledger = scene.ledger;
|
|
830
|
+
if (ledger.reviewGate(identity.key, identity.doc, type).kind !== "open")
|
|
831
|
+
return false;
|
|
832
|
+
if (!ledger.pendingFix(identity.key, type))
|
|
833
|
+
return false;
|
|
834
|
+
const completed = ledger.completedCycles(identity.key, "review", type);
|
|
835
|
+
if (completed.length === 0)
|
|
836
|
+
return false;
|
|
837
|
+
// The next review cycle is the latest completed review's + 1 — allocated BEFORE
|
|
838
|
+
// the stamp lands (the spec's fixed action order), and it is exactly the cycle the
|
|
839
|
+
// following dispatch allocates (the register's cycle count is unchanged by a stamp).
|
|
840
|
+
const latest = Math.max(...completed);
|
|
841
|
+
return ledger.supersedeReview(identity.key, type, latest, latest + 1);
|
|
842
|
+
}
|
|
843
|
+
/** The invocation's lifecycle harness — the production dispatch face, held by the
|
|
844
|
+
* composition root so the abort fold can ride the SAME instance that dispatches
|
|
845
|
+
* (the takeover precedes the stamp, spec §2.1④). */
|
|
846
|
+
#lifecycleOf(scene, parsed) {
|
|
847
|
+
return new CliLifecycle({
|
|
762
848
|
env: process.env,
|
|
763
849
|
sync: this.#sync,
|
|
764
850
|
template: this.#template,
|
|
@@ -774,11 +860,10 @@ export class Cli {
|
|
|
774
860
|
overallLink: scene.overallLink,
|
|
775
861
|
},
|
|
776
862
|
reviews: parsed.paths.reviews,
|
|
777
|
-
// The explicit takeover flag (`--
|
|
863
|
+
// The explicit takeover flag (`--recover`): the ONLY path that displaces a
|
|
778
864
|
// standing in-flight record — and only when its holder is dead.
|
|
779
|
-
|
|
865
|
+
recover: parsed.args.recover === "true",
|
|
780
866
|
});
|
|
781
|
-
return harness.step();
|
|
782
867
|
}
|
|
783
868
|
/** The branch scope anchor (BASE_BRANCH) — the base artifact's branch name read
|
|
784
869
|
* from the line's own workspace (`base.json`, the same `base get` source the CLI
|
package/dist/face/declare.js
CHANGED
|
@@ -60,8 +60,8 @@ export const ARGV_CHANNEL = {
|
|
|
60
60
|
help: "the base artifact's source channel",
|
|
61
61
|
},
|
|
62
62
|
force: { flag: "--force", type: "bool", help: "override the existing base artifact" },
|
|
63
|
-
|
|
64
|
-
flag: "--
|
|
63
|
+
recover: {
|
|
64
|
+
flag: "--recover",
|
|
65
65
|
type: "bool",
|
|
66
66
|
help: "take over a standing in-flight record whose holder is dead (the only takeover path)",
|
|
67
67
|
},
|
|
@@ -146,11 +146,7 @@ export const CLI_COMMANDS = [
|
|
|
146
146
|
name: "implement",
|
|
147
147
|
description: `run the task implement phase — at most ${MAX_TASKS_PER_WAVE} tasks per wave`,
|
|
148
148
|
example: `cdd implement --tasks 1,2 --plan ${ENGINE_DOC_ROOTS.plans}/p3.md`,
|
|
149
|
-
keys: [
|
|
150
|
-
{ key: "tasks", required: true },
|
|
151
|
-
{ key: "plan", required: true },
|
|
152
|
-
{ key: "stealStale" },
|
|
153
|
-
],
|
|
149
|
+
keys: [{ key: "tasks", required: true }, { key: "plan", required: true }, { key: "recover" }],
|
|
154
150
|
},
|
|
155
151
|
{
|
|
156
152
|
name: "review",
|
|
@@ -162,7 +158,7 @@ export const CLI_COMMANDS = [
|
|
|
162
158
|
{ key: "plan" },
|
|
163
159
|
{ key: "spec" },
|
|
164
160
|
{ key: "round" },
|
|
165
|
-
{ key: "
|
|
161
|
+
{ key: "recover" },
|
|
166
162
|
],
|
|
167
163
|
},
|
|
168
164
|
{
|
|
@@ -175,7 +171,7 @@ export const CLI_COMMANDS = [
|
|
|
175
171
|
{ key: "reviews" },
|
|
176
172
|
{ key: "spec" },
|
|
177
173
|
{ key: "plan" },
|
|
178
|
-
{ key: "
|
|
174
|
+
{ key: "recover" },
|
|
179
175
|
],
|
|
180
176
|
},
|
|
181
177
|
{
|
package/dist/face/lifecycle.js
CHANGED
|
@@ -18,6 +18,7 @@ import { existsSync, readFileSync } from "node:fs";
|
|
|
18
18
|
import process from "node:process";
|
|
19
19
|
import { printParseErrorCode } from "jsonc-parser";
|
|
20
20
|
import { CompletionCriteria, FixDispositions } from "../contract/completion-criterion.js";
|
|
21
|
+
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
21
22
|
import { GitClient } from "../infra/git.js";
|
|
22
23
|
import { ProcessFacts } from "../infra/proc.js";
|
|
23
24
|
import { RoundLog } from "../infra/round-log.js";
|
|
@@ -26,7 +27,7 @@ import { TemplateAssembler } from "../render/templates.js";
|
|
|
26
27
|
import { TargetFaceTable } from "../session/faces.js";
|
|
27
28
|
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
28
29
|
import { InFlight } from "../session/inflight.js";
|
|
29
|
-
import { Ledger, RoundViolation, } from "../session/ledger.js";
|
|
30
|
+
import { Ledger, RoundRecords, RoundViolation, } from "../session/ledger.js";
|
|
30
31
|
import { RoundNaming } from "../session/round-naming.js";
|
|
31
32
|
import { PlanStructure } from "../session/run.js";
|
|
32
33
|
import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
|
|
@@ -40,6 +41,10 @@ const STDOUT_TAIL_MAX = 40;
|
|
|
40
41
|
* set or a task's `DependsOn` set moved inside the round (design spec §7.3). The
|
|
41
42
|
* vanished / unreadable document cases name their own damage instead. */
|
|
42
43
|
const STRUCTURE_CHANGED = "the plan's structure changed inside this round (the Task id set or a task's DependsOn set) — the structure face belongs to the orchestrator and lands as its own commit";
|
|
44
|
+
/** The abort fold's ONE hard entry (spec §2.2) — the killed round's grade, cause
|
|
45
|
+
* (`interrupted`, the vocabulary's new literal) and prose. One entry, one cause: the
|
|
46
|
+
* fold records WHY the round has no conclusion, never a second diagnosis. */
|
|
47
|
+
const ABORT_INTERRUPTED = RoundViolation.hard("the dispatch was interrupted outside the engine — its in-flight record named a dead holder at takeover, so the round concluded nothing (the same command re-offers it)", "interrupted");
|
|
43
48
|
/**
|
|
44
49
|
* CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
|
|
45
50
|
* lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
|
|
@@ -72,6 +77,9 @@ export class CliLifecycle {
|
|
|
72
77
|
* frame derives here (the report/evidence/brief names + the family op), so the
|
|
73
78
|
* lifecycle and the dry-run preview name the same artifacts by one rule. */
|
|
74
79
|
#naming;
|
|
80
|
+
/** The plan's task-block read face — the `Files` declaration the implement
|
|
81
|
+
* criterion's verification cell derives from (P30 §2.4). */
|
|
82
|
+
#blocks = new PlanTaskBlocksReader();
|
|
75
83
|
/** The handoff-schema face — stateless, one shared instance (the read-back
|
|
76
84
|
* validator + the injected prompt text). */
|
|
77
85
|
#handoffSchema = new HandoffSchema();
|
|
@@ -85,10 +93,11 @@ export class CliLifecycle {
|
|
|
85
93
|
* (`ProcessFacts.startOf`; injected by the tests to span a long session). */
|
|
86
94
|
#proc;
|
|
87
95
|
/** Whether this invocation asked to take over a dead holder's record (the
|
|
88
|
-
* `--
|
|
89
|
-
#
|
|
96
|
+
* `--recover` flag — the only takeover path). */
|
|
97
|
+
#recover;
|
|
90
98
|
/** The HEAD the current dispatch started from (null off a repo / before a spawn) —
|
|
91
|
-
* the postmortem baseline of `commitsSince
|
|
99
|
+
* the postmortem baseline of `commitsSince` AND the in-flight record's
|
|
100
|
+
* `dispatchBase` cell (the killed round's group baseline a takeover restores, §2.2). */
|
|
92
101
|
#dispatchBase = null;
|
|
93
102
|
/** The commits added after `#dispatchBase` (computed once the child returned). */
|
|
94
103
|
#commitsSince = [];
|
|
@@ -112,7 +121,7 @@ export class CliLifecycle {
|
|
|
112
121
|
opts.inflight ?? new InFlight(opts.scene.workspace.root, opts.scene.workspace.slug);
|
|
113
122
|
this.#git = opts.git ?? new GitClient();
|
|
114
123
|
this.#proc = opts.proc ?? ProcessFacts;
|
|
115
|
-
this.#
|
|
124
|
+
this.#recover = opts.recover ?? false;
|
|
116
125
|
this.#sync = opts.sync ?? new Terminator();
|
|
117
126
|
this.#template = opts.template ?? new TemplateAssembler();
|
|
118
127
|
this.#brief = opts.brief ?? new BriefRenderer();
|
|
@@ -134,6 +143,65 @@ export class CliLifecycle {
|
|
|
134
143
|
step() {
|
|
135
144
|
return (frame) => this.#dispatch(frame);
|
|
136
145
|
}
|
|
146
|
+
/** The `--recover` abort leg (spec §2.1①/§2.2) — take over a stale in-flight record
|
|
147
|
+
* and, when the record can still name the killed round, fold that round into the
|
|
148
|
+
* ledger as an abort: `targetAction: false` plus ONE hard `interrupted` entry, the
|
|
149
|
+
* record's own cycle / attempt / `dispatchBase`. The group baseline therefore returns
|
|
150
|
+
* to before the killed round, so a recovery commit lands inside the next dispatch's
|
|
151
|
+
* window instead of being invisible.
|
|
152
|
+
*
|
|
153
|
+
* The three stale morphologies are judged HERE, exactly as `acquire({ recover })`
|
|
154
|
+
* judges them: a dead holder's readable record, a corrupt record with a leftover
|
|
155
|
+
* lock, a lock with no record behind it. Only the first carries a record back, so
|
|
156
|
+
* only it is booked — the other two have no op / cycle / baseline to read, and an
|
|
157
|
+
* invented identity is worse than no record (zero invention, same discipline as the
|
|
158
|
+
* `treeClean` pin below). A live holder is never displaced.
|
|
159
|
+
*
|
|
160
|
+
* Writes NO `crash-*.json` and promotes no draft: the crash record is the death face's
|
|
161
|
+
* (`#reject`), and this is the postmortem fold of a dispatch killed outside the
|
|
162
|
+
* engine — the two paths never mix. Returns whether an abort record was written. */
|
|
163
|
+
async foldAbort() {
|
|
164
|
+
const stale = await this.#inflight.staleState();
|
|
165
|
+
if (stale === null)
|
|
166
|
+
return false;
|
|
167
|
+
if (stale.kind === "held") {
|
|
168
|
+
const record = await this.#inflight.steal(InFlight.STEAL_REASON.deadHolder);
|
|
169
|
+
return record === null ? false : this.#bookAbort(record);
|
|
170
|
+
}
|
|
171
|
+
// The two record-less morphologies: the takeover is the whole effect (no op /
|
|
172
|
+
// cycle / baseline is readable, and an invented identity would be worse).
|
|
173
|
+
await this.#inflight.steal(stale.kind === "corrupt"
|
|
174
|
+
? InFlight.STEAL_REASON.corruptRecord
|
|
175
|
+
: InFlight.STEAL_REASON.lockOnly);
|
|
176
|
+
return false;
|
|
177
|
+
}
|
|
178
|
+
/** Book one taken-over record as the killed round's abort fact — the cells are the
|
|
179
|
+
* record's OWN (op from its phase through the ledger's one mode mapping, cycle /
|
|
180
|
+
* attempt / baseline verbatim). `treeClean` is pinned TRUE explicitly: the fold makes
|
|
181
|
+
* no dispatch-after observation, so leaving the ledger's default to be re-read would
|
|
182
|
+
* let two implementations book different facts (`#softOf` folds
|
|
183
|
+
* `treeClean === false` into a dirty-tree observation).
|
|
184
|
+
*
|
|
185
|
+
* A record that cannot name its whole identity — the row key, the op, the cycle or the
|
|
186
|
+
* attempt — is NOT booked: the takeover happens, and no identity is made up for it. An
|
|
187
|
+
* allocated cycle or a defaulted attempt would be invented facts, and either could
|
|
188
|
+
* overwrite a real round's record on the same `(op, cycle, attempt)`. */
|
|
189
|
+
#bookAbort(record) {
|
|
190
|
+
const op = RoundRecords.opOf(record.phase ?? "");
|
|
191
|
+
const { wave: key, cycle, attempt } = record;
|
|
192
|
+
if (op === null || key === null || cycle === null || attempt === null)
|
|
193
|
+
return false;
|
|
194
|
+
this.#scene.ledger.recordRound(key, {
|
|
195
|
+
op,
|
|
196
|
+
cycle,
|
|
197
|
+
attempt,
|
|
198
|
+
dispatchBase: record.dispatchBase,
|
|
199
|
+
verdict: { treeClean: true, targetAction: false },
|
|
200
|
+
violations: [ABORT_INTERRUPTED],
|
|
201
|
+
carrierPath: null,
|
|
202
|
+
}, "wave");
|
|
203
|
+
return true;
|
|
204
|
+
}
|
|
137
205
|
/** One dispatch — the round's work, the observation facts every record carries (the
|
|
138
206
|
* dispatch baseline HEAD captured before the spawn, the dispatch-after
|
|
139
207
|
* `treeClean` observation) and the TERMINAL VERDICT the round is booked under
|
|
@@ -221,10 +289,14 @@ export class CliLifecycle {
|
|
|
221
289
|
],
|
|
222
290
|
};
|
|
223
291
|
}
|
|
292
|
+
// The evidence gate is judged ONCE: its graded entries ride the verdict AND its
|
|
293
|
+
// result feeds the criterion's read-only `evidenceOk` cell (P30 §2.4) — the round
|
|
294
|
+
// pays for one evidence read, never two.
|
|
295
|
+
const evidence = this.#evidenceViolations(frame);
|
|
224
296
|
const violations = [
|
|
225
297
|
...(outcome.violations ?? []),
|
|
226
|
-
...(await this.#criterionViolations(frame, outcome)),
|
|
227
|
-
...
|
|
298
|
+
...(await this.#criterionViolations(frame, outcome, evidence)),
|
|
299
|
+
...evidence,
|
|
228
300
|
...this.#structureViolations(frame),
|
|
229
301
|
...logEntries,
|
|
230
302
|
];
|
|
@@ -237,8 +309,13 @@ export class CliLifecycle {
|
|
|
237
309
|
};
|
|
238
310
|
}
|
|
239
311
|
/** The verb's completion-criterion verdict as graded entries — the criterion's own
|
|
240
|
-
* hard violation plus its SOFT observations (design spec §3.2/§3.3).
|
|
241
|
-
|
|
312
|
+
* hard violation plus its SOFT observations (design spec §3.2/§3.3).
|
|
313
|
+
*
|
|
314
|
+
* The verification cells (P30 §2.4) are filled HERE, the single point: the wave's
|
|
315
|
+
* empty-`Files` task ids come from the plan document the dispatch already reads
|
|
316
|
+
* (`#emptyFileTasks`), and `evidenceOk` is the evidence judgment the round already
|
|
317
|
+
* ran — the gate's own result, never a second disk read. */
|
|
318
|
+
async #criterionViolations(frame, outcome, evidence) {
|
|
242
319
|
const scene = this.#scene;
|
|
243
320
|
const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
|
|
244
321
|
record: this.#judgedRecordOf(frame, outcome),
|
|
@@ -248,12 +325,36 @@ export class CliLifecycle {
|
|
|
248
325
|
reviewsPath: this.#reviewsPath(frame),
|
|
249
326
|
git: this.#git,
|
|
250
327
|
repoRoot: scene.workspace.root.repoRoot,
|
|
328
|
+
emptyFileTasks: this.#emptyFileTasks(),
|
|
329
|
+
evidenceOk: evidence.length === 0,
|
|
251
330
|
});
|
|
252
331
|
return [
|
|
253
332
|
...(judged.violation === null ? [] : [judged.violation]),
|
|
254
333
|
...(judged.observations ?? []),
|
|
255
334
|
];
|
|
256
335
|
}
|
|
336
|
+
/** The plan tasks whose `Files` declaration names no path — the verification-wave
|
|
337
|
+
* cell. The PLAN document is the only source (never the diff): an absent plan, a
|
|
338
|
+
* plan path pointing at no document or an unreadable one declares no empty row, so
|
|
339
|
+
* a wave can never read as verification on a plan this dispatch could not see. */
|
|
340
|
+
#emptyFileTasks() {
|
|
341
|
+
const planPath = this.#scene.planPath;
|
|
342
|
+
if (planPath === null)
|
|
343
|
+
return new Set();
|
|
344
|
+
let content;
|
|
345
|
+
try {
|
|
346
|
+
content = readFileSync(planPath, "utf8");
|
|
347
|
+
}
|
|
348
|
+
catch {
|
|
349
|
+
return new Set();
|
|
350
|
+
}
|
|
351
|
+
const empty = new Set();
|
|
352
|
+
for (const block of this.#blocks.parse(content)) {
|
|
353
|
+
if (this.#blocks.filePathsOf(block).length === 0)
|
|
354
|
+
empty.add(block.id);
|
|
355
|
+
}
|
|
356
|
+
return empty;
|
|
357
|
+
}
|
|
257
358
|
/** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
|
|
258
359
|
* group baseline and the carrier path the round writes. Deliberately verdict-free:
|
|
259
360
|
* this judgment PRODUCES the verdict, so a verdict cell here would be a
|
|
@@ -381,7 +482,7 @@ export class CliLifecycle {
|
|
|
381
482
|
// A sibling dispatch that won the lock in between makes `acquire` throw
|
|
382
483
|
// `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
|
|
383
484
|
this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
|
|
384
|
-
await this.#inflight.acquire(await this.#recordOf(frame), {
|
|
485
|
+
await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
|
|
385
486
|
// The round's own log file — created BEFORE the spawn (append stream open, zero
|
|
386
487
|
// bytes), so the channel exists from the dispatch's first millisecond. A create
|
|
387
488
|
// failure is a named soft observation and the round continues on the CPU leg
|
|
@@ -488,6 +589,7 @@ export class CliLifecycle {
|
|
|
488
589
|
attempt: frame.attempt ?? 1,
|
|
489
590
|
briefHash: this.#briefHashOf(frame),
|
|
490
591
|
plan: scene.planPath === null ? null : this.#rel(scene.planPath),
|
|
592
|
+
dispatchBase: this.#dispatchBase,
|
|
491
593
|
sampledAt: null,
|
|
492
594
|
verdict: null,
|
|
493
595
|
};
|
|
@@ -835,7 +937,7 @@ export class CliLifecycle {
|
|
|
835
937
|
const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
|
|
836
938
|
if (requester.kind !== "read")
|
|
837
939
|
return undefined;
|
|
838
|
-
const counts = new FixDispositions().summaryOf(carrier, requester.
|
|
940
|
+
const counts = new FixDispositions().summaryOf(carrier, requester.findings);
|
|
839
941
|
return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
|
|
840
942
|
}
|
|
841
943
|
/** The requesting review carrier's path — the fix round's `--reviews` input, or the
|
|
@@ -1076,10 +1178,16 @@ export class CliLifecycle {
|
|
|
1076
1178
|
}
|
|
1077
1179
|
return Object.keys(out).length > 0 ? out : undefined;
|
|
1078
1180
|
}
|
|
1079
|
-
/** The draft findings as
|
|
1080
|
-
*
|
|
1181
|
+
/** The draft findings as the carrier's list — the child's rows kept VERBATIM except
|
|
1182
|
+
* for the ONE engine-owned column: `id`, stamped from the carrier position (`F1`,
|
|
1183
|
+
* `F2` …) and overwriting whatever the child wrote (P30 §2.5 — the disposition
|
|
1184
|
+
* primary key belongs to the engine, never to the audited prose). This is the only
|
|
1185
|
+
* write point of a finding id in the engine. */
|
|
1081
1186
|
#findingsList(findings) {
|
|
1082
|
-
|
|
1187
|
+
const rows = Array.isArray(findings) ? findings : [];
|
|
1188
|
+
return rows.map((row, index) => typeof row === "object" && row !== null && !Array.isArray(row)
|
|
1189
|
+
? { ...row, id: `F${index + 1}` }
|
|
1190
|
+
: row);
|
|
1083
1191
|
}
|
|
1084
1192
|
/** The same-command resume string — the crash record's `next`, mirroring the
|
|
1085
1193
|
* CLI's dispatchable form of this frame (re-run the same command per the BLOCKED
|
package/dist/face/preview.js
CHANGED
|
@@ -69,7 +69,7 @@ export class Preview {
|
|
|
69
69
|
/** The read-only held block — the in-flight gate REFUSED this dispatch: the preview
|
|
70
70
|
* renders the gate's own holder facts as a `lock:` row (the dead holder carries the
|
|
71
71
|
* takeover hint), exits 1 at the caller, and touches nothing: no acquire, no steal,
|
|
72
|
-
* no release. The `--
|
|
72
|
+
* no release. The `--recover` flag has no write channel here. */
|
|
73
73
|
heldBlock(verb, state) {
|
|
74
74
|
const lines = [`cdd ${verb}: preview (no repo changes)`, ` lock: ${this.#lockValueOf(state)}`];
|
|
75
75
|
if (state.kind === "held" && !state.alive)
|
package/dist/face/words.js
CHANGED
|
@@ -113,7 +113,7 @@ export const CAPSULE_WORDS = {
|
|
|
113
113
|
inFlight: {
|
|
114
114
|
free: "free — no dispatch holds this tree",
|
|
115
115
|
held: "held — pid {pid}",
|
|
116
|
-
stale: "stale holder — pid {pid} (re-run with --
|
|
116
|
+
stale: "stale holder — pid {pid} (re-run with --recover to take over)",
|
|
117
117
|
corruptLocked: "unreadable record — lock on disk",
|
|
118
118
|
corruptUnlocked: "unreadable record — no lock behind",
|
|
119
119
|
},
|
|
@@ -133,9 +133,9 @@ export const CAPSULE_WORDS = {
|
|
|
133
133
|
* corrupt shapes and the three canonical recovery sentences. */
|
|
134
134
|
inFlight: {
|
|
135
135
|
held: "a dispatch is already in flight — pid {pid} · command: {command} · started: {startedAt} · running for {uptime} · wave: {wave} · slug: {slug}",
|
|
136
|
-
stealable: "the holding process is gone — re-run the same command with --
|
|
137
|
-
corruptLocked: "the in-flight record is unreadable and its lock is still on disk — re-run with --
|
|
138
|
-
corruptUnlocked: "the in-flight record is unreadable and no lock is left behind — re-run with --
|
|
136
|
+
stealable: "the holding process is gone — re-run the same command with --recover to take the in-flight record over",
|
|
137
|
+
corruptLocked: "the in-flight record is unreadable and its lock is still on disk — re-run with --recover to take it over",
|
|
138
|
+
corruptUnlocked: "the in-flight record is unreadable and no lock is left behind — re-run with --recover to take it over",
|
|
139
139
|
lockHeld: "held by pid {pid} · command: {command} · started: {startedAt} · wave: {wave} · slug: {slug}",
|
|
140
140
|
lockOnly: "held by an unreadable in-flight record — the lock is still on disk",
|
|
141
141
|
free: "free — no dispatch holds this tree",
|
package/dist/render/templates.js
CHANGED
|
@@ -121,7 +121,7 @@ const FIX_SHELL = [
|
|
|
121
121
|
WORK_CAPABILITY,
|
|
122
122
|
...FIX_TYPED_INSTRUCTIONS,
|
|
123
123
|
"**fix:** read `INPUT_REVIEWS` (open findings) + the plan context (`INPUT_WAVE_BRIEF` on a wave line — the complete plan mirror; `INPUT_PLAN` on the plan/branch lines — the plan document; `INPUT_SPEC` on the spec line — the spec document). Fix ALL findings (blocker/warn/nit), verifying against `INPUT_REVIEWS` none remain open. Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; draft write failure → `status: BLOCKED`; retry = full re-run (idempotent).",
|
|
124
|
-
'**Dispositions:** every requested finding needs a disposition keyed by its
|
|
124
|
+
'**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
|
|
125
125
|
EVIDENCE_ITEM,
|
|
126
126
|
...LICENSE_ITEMS,
|
|
127
127
|
// T5 (v0.3) — The work plane's ONE strict-schema sentence: every top-level draft
|
|
@@ -144,7 +144,9 @@ const DOCS_FIX_SHELL = [
|
|
|
144
144
|
...FRAME_ITEMS,
|
|
145
145
|
WORK_CAPABILITY,
|
|
146
146
|
"**docs-fix:** apply `INPUT_REVIEWS` (all severities) directly to the judged doc — `INPUT_PLAN` on a plan-doc line, `INPUT_SPEC` on a spec-doc line — removing fixed findings; record the path in `artifacts.doc` and report the round in `status` (APPROVED once every finding is applied, else BLOCKED + the reason in `notes`). Fix + write the draft at `OUTPUT_HANDOFF` per `## Handoff schema` in one process; retry = full re-run (idempotent).",
|
|
147
|
-
|
|
147
|
+
"**Change-history rows:** a new `## Change history` row bumps the front-matter `version:` in the same edit — the header version is the lineage's newest numeric version, and the two can never disagree.",
|
|
148
|
+
"**Table cells:** never hard-wrap a table cell — a wrapped continuation parses as a row whose cell count disagrees with the header, and the lineage row it was meant to be stops registering.",
|
|
149
|
+
'**Dispositions:** every requested finding needs a disposition keyed by its `id` exactly as the requesting carrier prints it (`F1`, `F2`, … — the summary is description only), valued `{ "status": "fixed" | "rejected", "reason"?: "…" }` — a missing or mis-keyed disposition fails the round.',
|
|
148
150
|
...LICENSE_ITEMS,
|
|
149
151
|
// The generic strict-schema sentence — the SAME one the work shells carry: the
|
|
150
152
|
// injected declaration is the draft's single field source, zero per-mode field
|
|
@@ -267,6 +269,13 @@ export const reviewGuideOf = (key) => {
|
|
|
267
269
|
const text = REVIEW_BODY_TEXT[key];
|
|
268
270
|
return SEVERITY_RUBRIC.replaceAll(SEVERITY_RUBRIC_SLOTS.artifact, text.artifact).replaceAll(SEVERITY_RUBRIC_SLOTS.audience, text.audience);
|
|
269
271
|
};
|
|
272
|
+
/** The closed-wave discipline's ONE sentence (P30 §2.7) — the document review axes'
|
|
273
|
+
* shared body: a finding on an already-closed task block's content face is answered
|
|
274
|
+
* by the document, never by moving the work. Both document criteria bodies select
|
|
275
|
+
* it, so the duty cannot fork between the plan variant and the spec shapes; the
|
|
276
|
+
* engine routes nothing on it (no finding classification, no dispatch branch) — it is
|
|
277
|
+
* prompt text, judged by the reviewer. */
|
|
278
|
+
export const CLOSED_WAVE_DISCIPLINE = "Closed waves are history: a finding on the content face of an already-closed task block is answered by amending the document to align with the delivered split — never by carrying work into or out of a closed task, and a finding that would rewrite the historical split is not raised.";
|
|
270
279
|
/** The spec-shaped documents' narrative criteria body — the phase-spec line's URC
|
|
271
280
|
* + its program-conformance clause, the ONE body both spec-shaped target rows
|
|
272
281
|
* select (the filled rubric is what differs per row). The charter's own criteria
|
|
@@ -276,7 +285,7 @@ export const reviewGuideOf = (key) => {
|
|
|
276
285
|
* today's tree happens to have: a line number is not a pin, a prose count is the
|
|
277
286
|
* guard's business, and a present-tense description of today's shape belongs to the
|
|
278
287
|
* plan. Nothing gates the writing moment — the review is where a violation surfaces. */
|
|
279
|
-
const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${guide}`;
|
|
288
|
+
const docNarrativeAxes = (guide) => `Follow URC: single-cycle, lens-tagged findings (completeness/consistency/clarity) + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin by module path + symbol name — a line number is not a pin; a count ("N places" · "N rows" · "N modules") must be stated as pinned by the named guard or test; a present-tense description of today's shape belongs to the plan — in a design spec a measurement input is a lens-tagged finding unless restated as a condition that must hold — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding + program conformance — judge the phase against its parent overall at \`INPUT_OVERALL\` (the charter its \`program:\` names): the phase must sit inside the scope the overall's Phase inventory registered for it, and a phase that reaches beyond it is a completeness finding. ${CLOSED_WAVE_DISCIPLINE} ${guide}`;
|
|
280
289
|
/** The charter's criteria body — the six things a program charter owns, and only
|
|
281
290
|
* those. It carries none of the implementation-face evidence duty the narrative
|
|
282
291
|
* body carries (running the repository's commands, pinning every claim): a charter
|
|
@@ -306,7 +315,7 @@ export const REVIEWS = {
|
|
|
306
315
|
},
|
|
307
316
|
plan: {
|
|
308
317
|
lensEnum: ["completeness", "decomposition", "buildability"],
|
|
309
|
-
axesGuide: `Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at \`INPUT_SPEC\` (the plan's \`spec\` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding. ${reviewGuideOf("plan")}`,
|
|
318
|
+
axesGuide: `Follow URC: single-cycle, lens-tagged findings (completeness/decomposition/buildability) + spec conformance — the plan is judged against its design spec at \`INPUT_SPEC\` (the plan's \`spec\` front-matter target): every spec requirement must map to a task, and a spec requirement with no owning task is a completeness finding + the writing-plans self-check + verification evidence — the reviewer runs the repository's typecheck and test commands and self-reports the dual evidence + Claimed→pin: every behavior claim (usage-line attribution · semantic contract · byte face) must cite a colocated pin (path:line + the assertion face) — the review checks every claim against its pin, claim by claim; a pinless claim is a lens-tagged finding. ${CLOSED_WAVE_DISCIPLINE} ${reviewGuideOf("plan")}`,
|
|
310
319
|
},
|
|
311
320
|
};
|
|
312
321
|
/** The criteria-body selection — the ONE target → criteria map. Four targets select
|