@oscaner-skills/cdd-engine 4.6.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 +137 -22
- package/dist/face/preview.js +1 -1
- package/dist/face/route-render.js +1 -1
- package/dist/face/words.js +4 -4
- package/dist/render/brief.js +18 -8
- package/dist/render/issue-body.js +46 -0
- package/dist/render/templates.js +13 -4
- package/dist/session/dispatch-authority.js +179 -23
- package/dist/session/handoff-schema.js +8 -1
- package/dist/session/inflight.js +44 -18
- package/dist/session/ledger.js +143 -41
- package/dist/session/line-identity.js +3 -2
- package/dist/session/next.js +16 -5
- package/dist/session/preflight.js +5 -5
- package/dist/session/run.js +10 -8
- 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,14 +18,16 @@ 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";
|
|
25
|
+
import { BriefRenderer } from "../render/brief.js";
|
|
24
26
|
import { TemplateAssembler } from "../render/templates.js";
|
|
25
27
|
import { TargetFaceTable } from "../session/faces.js";
|
|
26
28
|
import { HandoffSchema } from "../session/handoff-schema.js";
|
|
27
29
|
import { InFlight } from "../session/inflight.js";
|
|
28
|
-
import { Ledger, RoundViolation, } from "../session/ledger.js";
|
|
30
|
+
import { Ledger, RoundRecords, RoundViolation, } from "../session/ledger.js";
|
|
29
31
|
import { RoundNaming } from "../session/round-naming.js";
|
|
30
32
|
import { PlanStructure } from "../session/run.js";
|
|
31
33
|
import { DISPATCH, HOSTS, HostDetect, REFS } from "./host.js";
|
|
@@ -39,6 +41,10 @@ const STDOUT_TAIL_MAX = 40;
|
|
|
39
41
|
* set or a task's `DependsOn` set moved inside the round (design spec §7.3). The
|
|
40
42
|
* vanished / unreadable document cases name their own damage instead. */
|
|
41
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");
|
|
42
48
|
/**
|
|
43
49
|
* CliLifecycle — the lifecycle's dispatch-seam production default (the split contract's
|
|
44
50
|
* lifecycle face; face/cli.ts re-exports it as HarnessDispatch so the composition
|
|
@@ -60,6 +66,9 @@ export class CliLifecycle {
|
|
|
60
66
|
#io;
|
|
61
67
|
#scene;
|
|
62
68
|
#reviews;
|
|
69
|
+
/** The brief projection face — the wave frame's reviewed-basis hash rides the same
|
|
70
|
+
* task-only assembly the ledger binds (one projection, two callers). */
|
|
71
|
+
#brief;
|
|
63
72
|
/** The single word table (the promotion WARN wording + its station) — one instance,
|
|
64
73
|
* injected at the composition root, so the lifecycle never re-types a user-facing
|
|
65
74
|
* line. */
|
|
@@ -68,6 +77,9 @@ export class CliLifecycle {
|
|
|
68
77
|
* frame derives here (the report/evidence/brief names + the family op), so the
|
|
69
78
|
* lifecycle and the dry-run preview name the same artifacts by one rule. */
|
|
70
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();
|
|
71
83
|
/** The handoff-schema face — stateless, one shared instance (the read-back
|
|
72
84
|
* validator + the injected prompt text). */
|
|
73
85
|
#handoffSchema = new HandoffSchema();
|
|
@@ -81,10 +93,11 @@ export class CliLifecycle {
|
|
|
81
93
|
* (`ProcessFacts.startOf`; injected by the tests to span a long session). */
|
|
82
94
|
#proc;
|
|
83
95
|
/** Whether this invocation asked to take over a dead holder's record (the
|
|
84
|
-
* `--
|
|
85
|
-
#
|
|
96
|
+
* `--recover` flag — the only takeover path). */
|
|
97
|
+
#recover;
|
|
86
98
|
/** The HEAD the current dispatch started from (null off a repo / before a spawn) —
|
|
87
|
-
* 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). */
|
|
88
101
|
#dispatchBase = null;
|
|
89
102
|
/** The commits added after `#dispatchBase` (computed once the child returned). */
|
|
90
103
|
#commitsSince = [];
|
|
@@ -108,9 +121,10 @@ export class CliLifecycle {
|
|
|
108
121
|
opts.inflight ?? new InFlight(opts.scene.workspace.root, opts.scene.workspace.slug);
|
|
109
122
|
this.#git = opts.git ?? new GitClient();
|
|
110
123
|
this.#proc = opts.proc ?? ProcessFacts;
|
|
111
|
-
this.#
|
|
124
|
+
this.#recover = opts.recover ?? false;
|
|
112
125
|
this.#sync = opts.sync ?? new Terminator();
|
|
113
126
|
this.#template = opts.template ?? new TemplateAssembler();
|
|
127
|
+
this.#brief = opts.brief ?? new BriefRenderer();
|
|
114
128
|
this.#words = opts.words ?? new Words();
|
|
115
129
|
this.#io = opts.io ?? {
|
|
116
130
|
stdout: (t) => process.stdout.write(t),
|
|
@@ -129,6 +143,65 @@ export class CliLifecycle {
|
|
|
129
143
|
step() {
|
|
130
144
|
return (frame) => this.#dispatch(frame);
|
|
131
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
|
+
}
|
|
132
205
|
/** One dispatch — the round's work, the observation facts every record carries (the
|
|
133
206
|
* dispatch baseline HEAD captured before the spawn, the dispatch-after
|
|
134
207
|
* `treeClean` observation) and the TERMINAL VERDICT the round is booked under
|
|
@@ -216,10 +289,14 @@ export class CliLifecycle {
|
|
|
216
289
|
],
|
|
217
290
|
};
|
|
218
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);
|
|
219
296
|
const violations = [
|
|
220
297
|
...(outcome.violations ?? []),
|
|
221
|
-
...(await this.#criterionViolations(frame, outcome)),
|
|
222
|
-
...
|
|
298
|
+
...(await this.#criterionViolations(frame, outcome, evidence)),
|
|
299
|
+
...evidence,
|
|
223
300
|
...this.#structureViolations(frame),
|
|
224
301
|
...logEntries,
|
|
225
302
|
];
|
|
@@ -232,8 +309,13 @@ export class CliLifecycle {
|
|
|
232
309
|
};
|
|
233
310
|
}
|
|
234
311
|
/** The verb's completion-criterion verdict as graded entries — the criterion's own
|
|
235
|
-
* hard violation plus its SOFT observations (design spec §3.2/§3.3).
|
|
236
|
-
|
|
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) {
|
|
237
319
|
const scene = this.#scene;
|
|
238
320
|
const judged = await CompletionCriteria.of(this.#opOf(frame)).judge({
|
|
239
321
|
record: this.#judgedRecordOf(frame, outcome),
|
|
@@ -243,12 +325,36 @@ export class CliLifecycle {
|
|
|
243
325
|
reviewsPath: this.#reviewsPath(frame),
|
|
244
326
|
git: this.#git,
|
|
245
327
|
repoRoot: scene.workspace.root.repoRoot,
|
|
328
|
+
emptyFileTasks: this.#emptyFileTasks(),
|
|
329
|
+
evidenceOk: evidence.length === 0,
|
|
246
330
|
});
|
|
247
331
|
return [
|
|
248
332
|
...(judged.violation === null ? [] : [judged.violation]),
|
|
249
333
|
...(judged.observations ?? []),
|
|
250
334
|
];
|
|
251
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
|
+
}
|
|
252
358
|
/** The round IDENTITY the criterion judges from — its op / cycle / attempt, the
|
|
253
359
|
* group baseline and the carrier path the round writes. Deliberately verdict-free:
|
|
254
360
|
* this judgment PRODUCES the verdict, so a verdict cell here would be a
|
|
@@ -376,7 +482,7 @@ export class CliLifecycle {
|
|
|
376
482
|
// A sibling dispatch that won the lock in between makes `acquire` throw
|
|
377
483
|
// `HoldingError` (carrying the holder's facts), which rides the CLI's held BLOCK.
|
|
378
484
|
this.#dispatchBase = await this.#git.head(this.#scene.workspace.root.repoRoot);
|
|
379
|
-
await this.#inflight.acquire(await this.#recordOf(frame), {
|
|
485
|
+
await this.#inflight.acquire(await this.#recordOf(frame), { recover: this.#recover });
|
|
380
486
|
// The round's own log file — created BEFORE the spawn (append stream open, zero
|
|
381
487
|
// bytes), so the channel exists from the dispatch's first millisecond. A create
|
|
382
488
|
// failure is a named soft observation and the round continues on the CPU leg
|
|
@@ -483,6 +589,7 @@ export class CliLifecycle {
|
|
|
483
589
|
attempt: frame.attempt ?? 1,
|
|
484
590
|
briefHash: this.#briefHashOf(frame),
|
|
485
591
|
plan: scene.planPath === null ? null : this.#rel(scene.planPath),
|
|
592
|
+
dispatchBase: this.#dispatchBase,
|
|
486
593
|
sampledAt: null,
|
|
487
594
|
verdict: null,
|
|
488
595
|
};
|
|
@@ -506,18 +613,20 @@ export class CliLifecycle {
|
|
|
506
613
|
return null;
|
|
507
614
|
}
|
|
508
615
|
}
|
|
509
|
-
/** The wave frame's
|
|
510
|
-
*
|
|
511
|
-
*
|
|
512
|
-
*
|
|
513
|
-
*
|
|
616
|
+
/** The wave frame's reviewed-basis hash at acquire time — `ReviewRefs.briefRevision`
|
|
617
|
+
* over the SAME task-only projection the ledger binds (`BriefRenderer#taskBody` of
|
|
618
|
+
* the plan for this wave's tasks — P29 §2.2, `## Constraints` excluded). Computed
|
|
619
|
+
* independently of the ledger's records, so a wave's FIRST dispatch (no
|
|
620
|
+
* `brief-revision` row yet) still carries the hash. Null off the wave face, on a
|
|
621
|
+
* plan-less scene and when the plan is unreadable. */
|
|
514
622
|
#briefHashOf(frame) {
|
|
515
623
|
const scene = this.#scene;
|
|
516
|
-
if (frame.type !== "wave" ||
|
|
624
|
+
if (frame.type !== "wave" || frame.target.kind !== "wave" || scene.planPath === null)
|
|
517
625
|
return null;
|
|
518
626
|
try {
|
|
519
|
-
const
|
|
520
|
-
|
|
627
|
+
const plan = readFileSync(scene.planPath, "utf8");
|
|
628
|
+
const body = this.#brief.taskBody(plan, frame.target.tasks);
|
|
629
|
+
return scene.ledger.refs().briefRevision(this.#rel(scene.planPath), body).brief_hash;
|
|
521
630
|
}
|
|
522
631
|
catch {
|
|
523
632
|
return null;
|
|
@@ -828,7 +937,7 @@ export class CliLifecycle {
|
|
|
828
937
|
const requester = FixDispositions.requesterInputOf(this.#scene.ledger.recordsOf(frame.key, frame.type), frame.round, this.#reviewsPath(frame), this.#repoRootValue().absolute);
|
|
829
938
|
if (requester.kind !== "read")
|
|
830
939
|
return undefined;
|
|
831
|
-
const counts = new FixDispositions().summaryOf(carrier, requester.
|
|
940
|
+
const counts = new FixDispositions().summaryOf(carrier, requester.findings);
|
|
832
941
|
return FIX_DISPOSITIONS_SUMMARY.replace("{fixed}", String(counts.fixed)).replace("{rejected}", String(counts.rejected));
|
|
833
942
|
}
|
|
834
943
|
/** The requesting review carrier's path — the fix round's `--reviews` input, or the
|
|
@@ -1069,10 +1178,16 @@ export class CliLifecycle {
|
|
|
1069
1178
|
}
|
|
1070
1179
|
return Object.keys(out).length > 0 ? out : undefined;
|
|
1071
1180
|
}
|
|
1072
|
-
/** The draft findings as
|
|
1073
|
-
*
|
|
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. */
|
|
1074
1186
|
#findingsList(findings) {
|
|
1075
|
-
|
|
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);
|
|
1076
1191
|
}
|
|
1077
1192
|
/** The same-command resume string — the crash record's `next`, mirroring the
|
|
1078
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)
|
|
@@ -81,7 +81,7 @@ export class RouteRenderer {
|
|
|
81
81
|
return this.#words.routeWord("done");
|
|
82
82
|
}
|
|
83
83
|
/** renderReason(hop) → the `reason:` VALUE of one derived NextHop — the named fact
|
|
84
|
-
* that selected the hop (one of the
|
|
84
|
+
* that selected the hop (one of the eight `NEXT_HOP_REASON` tokens), rendered as a
|
|
85
85
|
* row of its OWN so the dispatchable `next:` literal keeps its exact bytes. A
|
|
86
86
|
* hop-absent round renders no row at all: the caller gates on the SAME hop object
|
|
87
87
|
* its `next:` render reads, so the two rows can never disagree. The station word
|
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/brief.js
CHANGED
|
@@ -7,7 +7,9 @@
|
|
|
7
7
|
// the plan's `## Constraints` section (the complete plan mirror). The checkable
|
|
8
8
|
// gate blocks step surfaces that carry a step
|
|
9
9
|
// with no checkable clause; a requested task with no matching heading blocks the
|
|
10
|
-
// whole render (the group-level out-of-bounds contract).
|
|
10
|
+
// whole render (the group-level out-of-bounds contract). The task sections are
|
|
11
|
+
// also exposed alone (`taskBody`) — the wave's reviewed-basis projection (P29
|
|
12
|
+
// §2.2), so the child's bytes and the reopen fingerprint share one assembly.
|
|
11
13
|
import { PlanDocType } from "../contract/doc.js";
|
|
12
14
|
import { PlanTaskBlocksReader } from "../contract/task-blocks.js";
|
|
13
15
|
/**
|
|
@@ -54,19 +56,27 @@ export class BriefRenderer {
|
|
|
54
56
|
}
|
|
55
57
|
return { data, missing };
|
|
56
58
|
}
|
|
57
|
-
/**
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
|
|
59
|
+
/** The task-only projection — the wave's reviewed-basis content face: the requested
|
|
60
|
+
* `### Task N:` sections and nothing else. `render` appends the plan's
|
|
61
|
+
* `## Constraints` on top of this projection for the child; the reviewed-brief hash
|
|
62
|
+
* (`Ledger#briefRevision` / `#briefDrifted`) covers this projection alone (P29 §2.2
|
|
63
|
+
* — a Constraints reword is dispatch input, never a brief drift). One assembly,
|
|
64
|
+
* two consumers: zero second slicing logic. */
|
|
65
|
+
taskBody(planContent, tasks) {
|
|
61
66
|
const { data, missing } = this.extract(planContent, tasks);
|
|
62
67
|
if (missing.length > 0) {
|
|
63
68
|
throw new Error(`task${missing.length > 1 ? "s" : ""} ${missing.join(", ")} not found in the plan`);
|
|
64
69
|
}
|
|
65
70
|
const lines = planContent.split("\n");
|
|
66
|
-
|
|
71
|
+
return data.map((task) => this.#slice(lines, task.range)).join("\n\n");
|
|
72
|
+
}
|
|
73
|
+
/** Render the brief content — the task-only projection + the plan's `## Constraints`
|
|
74
|
+
* section (the complete plan mirror the child reads). Any requested task without a
|
|
75
|
+
* heading blocks the whole render (out-of-bounds). */
|
|
76
|
+
render(planContent, tasks) {
|
|
77
|
+
const body = this.taskBody(planContent, tasks);
|
|
67
78
|
const constraints = this.#reader.section(planContent, "Constraints");
|
|
68
|
-
|
|
69
|
-
return `${body}\n`;
|
|
79
|
+
return constraints === "" ? `${body}\n` : `${body}\n\n${constraints}\n`;
|
|
70
80
|
}
|
|
71
81
|
/** The AST-range slice of one task block — the block's own lines verbatim, its
|
|
72
82
|
* `####` children included (the retired `^#` scan cut a block at its first child
|