@abelxiaoxing/cadence 2.0.50 → 2.1.1

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.
@@ -20,7 +20,12 @@ import {
20
20
 
21
21
  export const WORKFLOW_LIMITS = {
22
22
  tasks: 16,
23
- parallel: 2,
23
+ /** Assignments one run may list in all, counting those its revisions added
24
+ * and those they superseded. */
25
+ route: 48,
26
+ /** Questions one research run may carry. How many run at once is the
27
+ * owner's execution limit (`parallelLimit`), not a property of the plan. */
28
+ questions: 8,
24
29
  checks: 16,
25
30
  bytes: 256 * 1024,
26
31
  // Read budgets, never a lifetime cap on retained runs.
@@ -34,17 +39,40 @@ export interface WorkflowCheck {
34
39
  command: string;
35
40
  timeoutMs?: number;
36
41
  }
42
+ /** Something a worker should read before it starts: a project document (and
43
+ * optionally one section of it) or a recorded investigation, with the reason. */
44
+ export type WorkflowReading =
45
+ | { path: string; section?: string; reason: string }
46
+ | { research: string; reason: string };
37
47
  export interface WorkflowTask {
38
48
  id: string;
39
49
  title: string;
40
50
  instructions: string;
41
51
  writes: string[];
42
52
  after: string[];
53
+ /** Version 3: what this assignment reads first. */
54
+ reads?: WorkflowReading[];
55
+ }
56
+ /** Version 3: what the owner may do on its own after approval, beyond revising
57
+ * the route, the assignments and their write scope. */
58
+ export interface WorkflowPolicy {
59
+ /** Whether a revision may add dependency-installation setup commands. */
60
+ installs: boolean;
43
61
  }
44
62
  export interface WorkflowPlan {
45
- /** Version 2 admits adaptive delivery; absent versions are retained, readonly plans. */
46
- version?: 2;
63
+ /** Version 3 admits self-revising delivery. Version 2 (adaptive delivery in a
64
+ * fixed write scope) and unversioned plans are retained and readonly. */
65
+ version?: 2 | 3;
66
+ /** Version 2 only: approved documentation write paths. */
47
67
  knowledge?: string[];
68
+ /** Version 3: what the coordinator decided on the user's behalf; approval
69
+ * confirms these with the goal, decisions and acceptance. */
70
+ assumptions?: string;
71
+ /** Version 3: existing project documents this delivery may update. */
72
+ documents?: string[];
73
+ /** Version 3: what the independent review reads first. */
74
+ reviewReads?: WorkflowReading[];
75
+ policy?: WorkflowPolicy;
48
76
  goal: string;
49
77
  design: string;
50
78
  decisions: string;
@@ -78,11 +106,29 @@ export interface AcceptanceRecord {
78
106
  contextDigest: string;
79
107
  checks: string[];
80
108
  review: string;
109
+ /** Among `checks`, those a recorded deviation set aside; they failed. */
110
+ waived?: string[];
111
+ }
112
+ /** The worktree of one assignment that ran beside others: created from the
113
+ * candidate's commit, committed by the owner and picked onto the candidate. */
114
+ export interface DeliveryArtifact {
115
+ /** The assignment it belongs to. */
116
+ id: string;
117
+ path: string;
118
+ /** The candidate commit it was created from. */
119
+ base: string;
120
+ /** Its last commit recorded by the owner. */
121
+ head: string;
122
+ /** The candidate commit its work became, once integrated. */
123
+ applied: string | null;
124
+ state: "preparing" | "ready" | "removed" | "retained";
81
125
  }
82
126
  export interface DeliveryObservation {
83
127
  binding: DeliveryBinding;
84
128
  taskBranch: string;
85
129
  worktreeRoot: string;
130
+ /** Child worktrees of assignments that ran side by side, in creation order. */
131
+ artifacts?: DeliveryArtifact[];
86
132
  preparation: "pending" | "ready" | "unknown";
87
133
  workspace: {
88
134
  head: string;
@@ -165,10 +211,48 @@ export interface WorkflowStep {
165
211
  exitCode: number | null;
166
212
  truncated: boolean;
167
213
  }
214
+ /** An acceptance item or decision the delivery could not meet as written, and
215
+ * what it delivered instead. The independent review confirms each one. */
216
+ export interface WorkflowDeviation {
217
+ revision: number;
218
+ item: string;
219
+ reason: string;
220
+ delivered: string;
221
+ /** Declared acceptance checks set aside because of it. */
222
+ waives: string[];
223
+ }
224
+ /** Deviations one run may record. */
225
+ export const WORKFLOW_DEVIATIONS = 16;
226
+ export const WORKFLOW_TASK_STATES = [
227
+ "queued",
228
+ "running",
229
+ "completed",
230
+ "failed",
231
+ "superseded",
232
+ ] as const;
233
+ /** Where one assignment of the current route stands. `completed` means its
234
+ * work is in the candidate; `superseded` means a plan revision dropped it
235
+ * before it started. */
236
+ export interface WorkflowTaskState {
237
+ id: string;
238
+ title: string;
239
+ after: string[];
240
+ state: (typeof WORKFLOW_TASK_STATES)[number];
241
+ /** The plan revision that last changed this assignment (added, rewrote or
242
+ * superseded it); absent for one that stands as the agreement wrote it. */
243
+ revision?: number;
244
+ }
168
245
  export interface WorkflowRun {
169
246
  /** New runs retain older step pages separately; this is a view offset, not eviction. */
170
247
  stepsBefore?: number;
171
248
  revision?: number;
249
+ /** Repository paths that revisions brought into the write scope after approval. */
250
+ scope?: string[];
251
+ /** Where this delivery departs from the agreement, in recorded order. */
252
+ deviations?: WorkflowDeviation[];
253
+ /** The current route: the agreement's assignments as revisions left them,
254
+ * and where each stands. */
255
+ tasks?: WorkflowTaskState[];
172
256
  verification?: { id: string; source: string; steps: string[] };
173
257
  delivery?: DeliveryObservation;
174
258
  execution?: ExecutionContext;
@@ -264,6 +348,8 @@ const taskId = (v: unknown, strict = false) => {
264
348
  throw new Error("Invalid task id");
265
349
  return s;
266
350
  };
351
+ /** The identity a new assignment may take. */
352
+ export const workflowTaskId = (v: unknown) => taskId(v, true);
267
353
  export function decodeWorkflowCheck(v: unknown): WorkflowCheck {
268
354
  const o = closed(v, [
269
355
  "name",
@@ -323,24 +409,46 @@ export function decodeWorkflowPlan(
323
409
  "Publish a new delivery agreement; retained fixed-pipeline plans are readonly",
324
410
  );
325
411
  canonicalJson(v, WORKFLOW_LIMITS.bytes);
326
- if (modern && (v as { version?: unknown }).version !== 2)
412
+ const version = modern ? (v as { version?: unknown }).version : undefined;
413
+ if (modern && version !== 2 && version !== 3)
327
414
  throw new Error("Unsupported delivery agreement version");
415
+ const current = version === 3;
416
+ if (strict && !current)
417
+ throw new Error(
418
+ "Publish a new delivery agreement; earlier agreements are readonly",
419
+ );
328
420
  const o = closed(v, [
329
421
  "goal",
330
422
  "design",
331
423
  "decisions",
332
424
  "acceptance",
333
- ...(modern
334
- ? ["version", "knowledge"]
335
- : ["projectContext", "repairAttempts"]),
425
+ ...(current
426
+ ? ["version", "assumptions", "documents", "reviewReads", "policy"]
427
+ : modern
428
+ ? ["version", "knowledge"]
429
+ : ["projectContext", "repairAttempts"]),
336
430
  "tasks",
337
431
  "checks",
338
432
  "setup",
339
433
  "baselineChecks",
340
434
  "delivery",
341
435
  ]);
436
+ const documentation = (value: unknown) =>
437
+ list(value, 16, (entry) => {
438
+ const path = workflowPath(entry, strict);
439
+ if (!path.endsWith(".md"))
440
+ throw new Error("Documentation targets must be Markdown files");
441
+ return path;
442
+ });
342
443
  const tasks = list(o.tasks, WORKFLOW_LIMITS.tasks, (value) => {
343
- const t = closed(value, ["id", "title", "instructions", "writes", "after"]);
444
+ const t = closed(value, [
445
+ "id",
446
+ "title",
447
+ "instructions",
448
+ "writes",
449
+ "after",
450
+ ...(current ? ["reads"] : []),
451
+ ]);
344
452
  return {
345
453
  id: taskId(t.id, strict),
346
454
  title: text(t.title, 256, true),
@@ -349,6 +457,7 @@ export function decodeWorkflowPlan(
349
457
  after: list(t.after, WORKFLOW_LIMITS.tasks, (id: unknown) =>
350
458
  taskId(id, strict),
351
459
  ),
460
+ ...(current ? { reads: decodeWorkflowReadings(t.reads, strict) } : {}),
352
461
  };
353
462
  });
354
463
  if (
@@ -388,20 +497,22 @@ export function decodeWorkflowPlan(
388
497
  design: text(o.design, 32768, true),
389
498
  decisions: text(o.decisions, 16384),
390
499
  acceptance: text(o.acceptance, 16384, true),
391
- ...(modern
500
+ ...(current
392
501
  ? {
393
- version: 2 as const,
394
- knowledge: list(o.knowledge, 16, (v) => {
395
- const path = workflowPath(v, strict);
396
- if (!path.endsWith(".md"))
397
- throw new Error("Knowledge targets must be Markdown files");
398
- return path;
399
- }),
502
+ version: 3 as const,
503
+ assumptions: text(o.assumptions, 16384),
504
+ documents: documentation(o.documents),
505
+ reviewReads: decodeWorkflowReadings(o.reviewReads, strict),
506
+ policy: {
507
+ installs: bool(closed(o.policy, ["installs"]).installs),
508
+ },
400
509
  }
401
- : {
402
- projectContext: text(o.projectContext, 16384),
403
- repairAttempts: integer(o.repairAttempts, 0, 2),
404
- }),
510
+ : modern
511
+ ? { version: 2 as const, knowledge: documentation(o.knowledge) }
512
+ : {
513
+ projectContext: text(o.projectContext, 16384),
514
+ repairAttempts: integer(o.repairAttempts, 0, 2),
515
+ }),
405
516
  tasks,
406
517
  checks,
407
518
  setup: list(o.setup, 4, decodeWorkflowCheck),
@@ -419,7 +530,12 @@ export function decodeWorkflowPlan(
419
530
  result.design,
420
531
  result.decisions,
421
532
  result.acceptance,
533
+ result.assumptions ?? "",
422
534
  result.projectContext ?? "",
535
+ ...[
536
+ ...(result.reviewReads ?? []),
537
+ ...result.tasks.flatMap((t) => t.reads ?? []),
538
+ ].flatMap((r) => [r.reason, "section" in r ? (r.section ?? "") : ""]),
423
539
  ...result.tasks.flatMap((t) => [t.title, t.instructions]),
424
540
  ...[...result.checks, ...result.setup, ...result.baselineChecks].flatMap(
425
541
  (c) => [c.name, c.command],
@@ -436,15 +552,64 @@ export function decodeWorkflowPlan(
436
552
  throw new Error("Plan contains invisible terminal controls");
437
553
  return result;
438
554
  }
439
- /** The immutable permission/verification boundary, independent of internal route revisions. */
555
+ /** Existing project documents the agreement allows this delivery to update. */
556
+ export function workflowDocuments(p: WorkflowPlan): string[] {
557
+ return p.documents ?? p.knowledge ?? [];
558
+ }
559
+ /** The write scope the agreement starts from. A version-3 run may extend it
560
+ * inside the repository boundary (`workflowBoundary`); earlier versions never. */
440
561
  export function workflowWrites(p: WorkflowPlan): string[] {
441
562
  return [
442
- ...new Set([...p.tasks.flatMap((t) => t.writes), ...(p.knowledge ?? [])]),
563
+ ...new Set([...p.tasks.flatMap((t) => t.writes), ...workflowDocuments(p)]),
443
564
  ];
444
565
  }
566
+ /** Whether a revision may bring this path into a run's write scope: a plain
567
+ * repository path that names no credential, key or private-state file. */
568
+ export function workflowBoundary(path: string): boolean {
569
+ try {
570
+ if (workflowPath(path, true) !== path) return false;
571
+ } catch {
572
+ return false;
573
+ }
574
+ return !path
575
+ .split("/")
576
+ .some(
577
+ (name) =>
578
+ /^\.(?:ssh|aws|azure|gnupg|kube|npmrc|pypirc|netrc|pi)$/iu.test(name) ||
579
+ /^(?:auth|models|credentials|service-account)\.json$/iu.test(name) ||
580
+ /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.|$)/iu.test(name) ||
581
+ /\.(?:pem|key|p12|pfx)$/iu.test(name),
582
+ );
583
+ }
584
+ function decodeWorkflowReadings(
585
+ value: unknown,
586
+ strict: boolean,
587
+ ): WorkflowReading[] {
588
+ return list(value, 16, (entry): WorkflowReading => {
589
+ if (Object.hasOwn((entry ?? {}) as object, "research")) {
590
+ const r = closed(entry, ["research", "reason"]);
591
+ return {
592
+ research: decodeId(r.research),
593
+ reason: text(r.reason, 512, true),
594
+ };
595
+ }
596
+ const r = closed(entry, [
597
+ "path",
598
+ ...(Object.hasOwn((entry ?? {}) as object, "section") ? ["section"] : []),
599
+ "reason",
600
+ ]);
601
+ return {
602
+ path: workflowPath(r.path, strict),
603
+ ...(r.section === undefined
604
+ ? {}
605
+ : { section: text(r.section, 256, true) }),
606
+ reason: text(r.reason, 512, true),
607
+ };
608
+ });
609
+ }
445
610
  export function workflowContext(p: WorkflowPlan): string {
446
611
  return text(
447
- `# ${p.goal}\n\nInitial route (adapt within the approved boundary): ${p.design}\n\nExplicit decisions and non-goals: ${p.decisions}\n\nImmutable acceptance: ${p.acceptance}`,
612
+ `# ${p.goal}\n\nInitial route (${p.version === 3 ? "the owner may revise it" : "adapt within the approved boundary"}): ${p.design}\n\nExplicit decisions and non-goals: ${p.decisions}${p.assumptions ? `\n\nAssumptions confirmed with the agreement: ${p.assumptions}` : ""}\n\nAcceptance: ${p.acceptance}`,
448
613
  32768,
449
614
  true,
450
615
  );
@@ -504,6 +669,9 @@ export function decodeDeliveryObservation(value: unknown): DeliveryObservation {
504
669
  "binding",
505
670
  "taskBranch",
506
671
  "worktreeRoot",
672
+ ...(Object.hasOwn((value ?? {}) as object, "artifacts")
673
+ ? ["artifacts"]
674
+ : []),
507
675
  "preparation",
508
676
  "workspace",
509
677
  "candidate",
@@ -523,6 +691,7 @@ export function decodeDeliveryObservation(value: unknown): DeliveryObservation {
523
691
  "contextDigest",
524
692
  "checks",
525
693
  "review",
694
+ ...(Object.hasOwn((v ?? {}) as object, "waived") ? ["waived"] : []),
526
695
  ]);
527
696
  const checks = list(a.checks, WORKFLOW_LIMITS.checks, step);
528
697
  if (!checks.length || new Set(checks).size !== checks.length)
@@ -534,6 +703,13 @@ export function decodeDeliveryObservation(value: unknown): DeliveryObservation {
534
703
  contextDigest: decodeHash(a.contextDigest),
535
704
  checks,
536
705
  review: step(a.review),
706
+ ...(a.waived === undefined
707
+ ? {}
708
+ : {
709
+ waived: list(a.waived, WORKFLOW_LIMITS.checks, step).filter((id) =>
710
+ checks.includes(id),
711
+ ),
712
+ }),
537
713
  };
538
714
  });
539
715
  const candidate = nullable(d.candidate, gitOid);
@@ -562,6 +738,33 @@ export function decodeDeliveryObservation(value: unknown): DeliveryObservation {
562
738
  binding,
563
739
  taskBranch,
564
740
  worktreeRoot: deliveryPath(d.worktreeRoot),
741
+ ...(d.artifacts === undefined
742
+ ? {}
743
+ : {
744
+ artifacts: list(d.artifacts, 256, (entry) => {
745
+ const a = closed(entry, [
746
+ "id",
747
+ "path",
748
+ "base",
749
+ "head",
750
+ "applied",
751
+ "state",
752
+ ]);
753
+ return {
754
+ id: taskId(a.id),
755
+ path: deliveryPath(a.path),
756
+ base: gitOid(a.base),
757
+ head: gitOid(a.head),
758
+ applied: nullable(a.applied, gitOid),
759
+ state: oneOf(a.state, [
760
+ "preparing",
761
+ "ready",
762
+ "removed",
763
+ "retained",
764
+ ] as const),
765
+ };
766
+ }),
767
+ }),
565
768
  preparation: oneOf(d.preparation, ["pending", "ready", "unknown"]),
566
769
  workspace,
567
770
  candidate,
@@ -589,7 +792,7 @@ export function decodeDeliveryObservation(value: unknown): DeliveryObservation {
589
792
  export function readableDelivery(binding?: DeliveryBinding): string {
590
793
  if (!binding) return "";
591
794
  const t = binding.target;
592
- return `Target: ${t.branch} @ ${t.head}\nTarget checkout: ${t.checkoutRoot}\nExecution: new cadence/<goal>-<run-id> branch and one stable isolated worktree after approval.\nAcceptance: checks and automatic Agent review of the exact candidate.\nDelivery: fast-forward only into the bound target, unchanged since approval or this run's last confirmed merge. Keep the task branch; remove only owned worktrees without any residue, including ignored files. No source/profile/dependency copying, push or deployment.`;
795
+ return `Target: ${t.branch} @ ${t.head}\nTarget checkout: ${t.checkoutRoot}\nExecution: new cadence/<goal>-<run-id> branch and one stable isolated worktree after approval. Assignments that can run side by side each work in a temporary worktree of their own beside it; the service commits that work and picks it onto the candidate.\nAcceptance: checks and automatic Agent review of the exact candidate.\nDelivery: fast-forward only into the bound target, unchanged since approval or this run's last confirmed merge. Keep the task branch; remove only owned worktrees without any residue, including ignored files. No source/profile/dependency copying, push or deployment.`;
593
796
  }
594
797
  export function readableDeliveryRun(d?: DeliveryObservation): string {
595
798
  if (!d) return "";
@@ -656,7 +859,7 @@ export function decodeWorkflowRequest(v: unknown): WorkflowRequest {
656
859
  "model",
657
860
  ...(Object.hasOwn(v ?? {}, "roots") ? ["roots"] : []),
658
861
  ]);
659
- const questions = list(o.questions, WORKFLOW_LIMITS.parallel, (q) =>
862
+ const questions = list(o.questions, WORKFLOW_LIMITS.questions, (q) =>
660
863
  text(q, 8192, true),
661
864
  );
662
865
  if (!questions.length) throw new Error("Research needs a question");
@@ -713,6 +916,9 @@ export function decodeWorkflowRun(v: unknown): WorkflowRun {
713
916
  "humanReviewed",
714
917
  ...(Object.hasOwn(v ?? {}, "stepsBefore") ? ["stepsBefore"] : []),
715
918
  ...(Object.hasOwn(v ?? {}, "revision") ? ["revision"] : []),
919
+ ...(Object.hasOwn(v ?? {}, "scope") ? ["scope"] : []),
920
+ ...(Object.hasOwn(v ?? {}, "deviations") ? ["deviations"] : []),
921
+ ...(Object.hasOwn(v ?? {}, "tasks") ? ["tasks"] : []),
716
922
  ...(Object.hasOwn(v ?? {}, "verification") ? ["verification"] : []),
717
923
  ...(Object.hasOwn(v ?? {}, "diagnostics") ? ["diagnostics"] : []),
718
924
  ...(Object.hasOwn(v ?? {}, "execution") ? ["execution"] : []),
@@ -746,6 +952,53 @@ export function decodeWorkflowRun(v: unknown): WorkflowRun {
746
952
  ? {}
747
953
  : { stepsBefore: integer(o.stepsBefore, 0) }),
748
954
  ...(o.revision === undefined ? {} : { revision: integer(o.revision, 0) }),
955
+ ...(o.scope === undefined
956
+ ? {}
957
+ : { scope: list(o.scope, 1024, (path) => workflowPath(path)) }),
958
+ ...(o.deviations === undefined
959
+ ? {}
960
+ : {
961
+ deviations: list(o.deviations, WORKFLOW_DEVIATIONS, (value) => {
962
+ const d = closed(value, [
963
+ "revision",
964
+ "item",
965
+ "reason",
966
+ "delivered",
967
+ "waives",
968
+ ]);
969
+ return {
970
+ revision: integer(d.revision, 0),
971
+ item: text(d.item, 2048, true),
972
+ reason: text(d.reason, 4096, true),
973
+ delivered: text(d.delivered, 4096, true),
974
+ waives: list(d.waives, 16, (name) => text(name, 128, true)),
975
+ };
976
+ }),
977
+ }),
978
+ ...(o.tasks === undefined
979
+ ? {}
980
+ : {
981
+ tasks: list(o.tasks, WORKFLOW_LIMITS.route, (value) => {
982
+ const t = closed(value, [
983
+ "id",
984
+ "title",
985
+ "after",
986
+ "state",
987
+ ...(Object.hasOwn((value ?? {}) as object, "revision")
988
+ ? ["revision"]
989
+ : []),
990
+ ]);
991
+ return {
992
+ id: taskId(t.id),
993
+ title: text(t.title, 256, true),
994
+ after: list(t.after, WORKFLOW_LIMITS.tasks, (id) => taskId(id)),
995
+ state: oneOf(t.state, WORKFLOW_TASK_STATES),
996
+ ...(t.revision === undefined
997
+ ? {}
998
+ : { revision: integer(t.revision, 1, 1_000_000) }),
999
+ };
1000
+ }),
1001
+ }),
749
1002
  ...(o.delivery === undefined
750
1003
  ? {}
751
1004
  : { delivery: decodeDeliveryObservation(o.delivery) }),
@@ -843,17 +1096,43 @@ export function decodeWorkflowResponse(v: unknown): WorkflowResponse {
843
1096
  expiresAt: integer(o.expiresAt, 0),
844
1097
  };
845
1098
  }
1099
+ const readableCheck = (c: WorkflowCheck) =>
1100
+ `${c.name}: ${c.command} (${c.timeoutMs === undefined ? "no timeout" : `${c.timeoutMs}ms`})`;
1101
+ const readableReading = (r: WorkflowReading) =>
1102
+ "research" in r
1103
+ ? `investigation ${r.research} — ${r.reason}`
1104
+ : `${r.path}${r.section ? ` § ${r.section}` : ""} — ${r.reason}`;
1105
+ /** What approval of each agreement version lets the owner do on its own. */
1106
+ function readableAutomation(p: WorkflowPlan): string {
1107
+ if (p.version === 3)
1108
+ return `After approval the service works to completion without further confirmation. It may on its own: retry and repair a failed assignment; revise the route, the assignments and their order; and bring further repository files into the write scope (never credentials, keys, .env, .git or files outside the repository). When an acceptance item or decision proves impossible it delivers the closest achievable result as a recorded deviation, which names the item, the evidence and what was delivered instead, must be confirmed necessary and minimal by the independent Agent review, and leads the final report. Declared checks always run; a check is set aside only through such a deviation, never silently. At the end it maintains the project's knowledge store under .cadence/ within its fixed budget, adding what this delivery taught and removing what went stale, when a fast-forward can carry it. It stops only for a condition outside the repository: an unavailable model, failed authentication, storage or permission limits, a target branch changed from outside, or a required installation this agreement does not allow. ${p.policy?.installs ? "Revisions may add dependency-installation commands with the project's own package manager." : "No dependency installation beyond the setup commands listed here."}`;
1109
+ if (p.version === 2)
1110
+ return "Retained agreement (readonly): diagnosis, partial-work continuation, task splitting and alternative implementations within these goals, decisions, write paths and exact setup/check commands.";
1111
+ return `Historical fixed pipeline: at most ${p.repairAttempts} repair rounds.`;
1112
+ }
846
1113
  export function readableWorkflowPlan(p: WorkflowPlan): string {
847
- return `# ${p.goal}\n\n## Initial route (automatically adjustable)\n${p.design}\n\n## Decisions\n${p.decisions}\n\n## Acceptance\n${p.acceptance}\n\n## Tasks\n${workflowOrder(
848
- p.tasks,
849
- )
1114
+ const documents = workflowDocuments(p);
1115
+ return `# ${p.goal}\n\n## Initial route (the service may revise it)\n${p.design}\n\n## Decisions\n${p.decisions}\n\n## Acceptance\n${p.acceptance}${
1116
+ p.version === 3
1117
+ ? `\n\n## Assumptions (confirmed by approval)\n${p.assumptions || "None beyond the decisions above."}`
1118
+ : ""
1119
+ }\n\n## Tasks\n${workflowOrder(p.tasks)
850
1120
  .map(
851
1121
  (t) =>
852
- `### ${t.id}: ${t.title}\nDepends on: ${t.after.join(", ") || "none"}\nWrites: ${t.writes.join(", ")}\n${t.instructions}`,
1122
+ `### ${t.id}: ${t.title}\nDepends on: ${t.after.join(", ") || "none"}\nWrites: ${t.writes.join(", ")}${t.reads?.length ? `\nReads first: ${t.reads.map(readableReading).join("; ")}` : ""}\n${t.instructions}`,
853
1123
  )
854
1124
  .join(
855
1125
  "\n\n",
856
- )}\n\n## Setup (explicitly authorized commands)\n${p.setup.map((c) => `${c.name}: ${c.command} (${c.timeoutMs === undefined ? "no timeout" : `${c.timeoutMs}ms`})`).join("\n") || "None; no dependency installation or copying."}\n\n## Baseline verification\n${p.baselineChecks.map((c) => `${c.name}: ${c.command} (${c.timeoutMs === undefined ? "no timeout" : `${c.timeoutMs}ms`})`).join("\n") || "No separate baseline checks declared."}\n\n## Verification\n${p.checks.map((c) => `${c.name}: ${c.command} (${c.timeoutMs === undefined ? "no timeout" : `${c.timeoutMs}ms`})`).join("\n")}\n\n## Automation boundary\n${p.version === 2 ? "Authorize diagnosis, partial-work continuation, task splitting and alternative implementations within these goals, decisions, write paths and exact setup/check commands. No fixed repair-round or delivery-duration quota. Only actual verification and independent Agent review permit delivery." : `Historical fixed pipeline: at most ${p.repairAttempts} repair rounds.`} ${p.delivery === "local-merge" ? "Authorize one new named task branch and stable isolated worktree after approval, local commits and fast-forward delivery of the exact checked and Agent-reviewed candidate into the displayed target. Keep the task branch; retain any worktree with uncommitted, untracked or ignored residue." : "Direct working-copy edits; failures leave actual edits for inspection. No Git commit or merge."} No push, publication, deployment, unplanned installation or recursive delegation. Related project knowledge and workflow Markdown are included. Worktrees/tools are not a sandbox.\n\n## Project knowledge\n${p.version === 2 ? p.knowledge?.join("\n") || "No documentation edits authorized; existing knowledge is still read." : p.projectContext}\n`;
1126
+ )}\n\n## Setup (explicitly authorized commands)\n${p.setup.map(readableCheck).join("\n") || "None; no dependency installation or copying."}\n\n## Baseline verification\n${p.baselineChecks.map(readableCheck).join("\n") || "No separate baseline checks declared."}\n\n## Verification\n${p.checks.map(readableCheck).join("\n")}${
1127
+ p.reviewReads?.length
1128
+ ? `\n\n## Review reads first\n${p.reviewReads.map(readableReading).join("\n")}`
1129
+ : ""
1130
+ }\n\n## Automation boundary\n${readableAutomation(p)} Only actual verification and independent Agent review permit delivery. ${p.delivery === "local-merge" ? "Authorize one new named task branch and stable isolated worktree after approval, temporary worktrees beside it for assignments that run side by side, local commits and fast-forward delivery of the exact checked and Agent-reviewed candidate into the displayed target. Keep the task branch; retain any worktree with uncommitted, untracked or ignored residue." : "Direct working-copy edits; failures leave actual edits for inspection. No Git commit or merge."} No push, publication, deployment or recursive delegation. Related project knowledge and workflow Markdown are included. Worktrees/tools are not a sandbox.\n\n## Project documents\n${
1131
+ p.version === undefined
1132
+ ? p.projectContext
1133
+ : documents.join("\n") ||
1134
+ "No existing document is named for update; project knowledge is still read."
1135
+ }\n`;
857
1136
  }
858
1137
 
859
1138
  const timestamp = (v: unknown) => integer(v, 0, 8640000000000000);