@vaubaan/harness 2.1.0 → 2.2.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.
@@ -5,7 +5,7 @@ invokes_skill: doc-audit
5
5
  args:
6
6
  - name: scope
7
7
  type: enum
8
- values: [spec, decisions, handbook, tests, workflow, readme, all]
8
+ values: [spec, decisions, handbook, tests, workflow, readme, journeys, all]
9
9
  default: all
10
10
  description: Audits the completeness and freshness of the project docs (selectable scope).
11
11
  ---
@@ -0,0 +1,22 @@
1
+ ---
2
+ id: journey
3
+ trigger: /journey
4
+ invokes_skill: journey-writer
5
+ args:
6
+ - name: name
7
+ type: string
8
+ description: Writes or updates `docs/journeys/<name>.md`, one node at a time, in wizard mode.
9
+ ---
10
+
11
+ # /journey
12
+
13
+ When the human or the agent invokes `/journey [name]`, load the skill
14
+ `journey-writer` with the optional `name` argument.
15
+
16
+ If `name` is provided, the skill targets `docs/journeys/<name>.md`
17
+ (creation or update). Without an argument, it reads the generated index
18
+ `docs/journeys/README.md`, lists the journeys and asks which one to
19
+ extend or whether to create one.
20
+
21
+ The skill instantiates the `journey.md.tmpl` template for creations. For
22
+ a new behavior to build, prefer `/story <intent>`.
@@ -0,0 +1,24 @@
1
+ ---
2
+ id: story
3
+ trigger: /story
4
+ invokes_skill: journey-writer
5
+ args:
6
+ - name: intent
7
+ type: string
8
+ description: Adds a `proposed` leaf with its acceptance criteria to the right journey, before any code.
9
+ ---
10
+
11
+ # /story
12
+
13
+ When the human or the agent invokes `/story <intent>`, load the skill
14
+ `journey-writer` in its story mode with the `intent` argument: the
15
+ visible change of behavior about to be built, as a verb + object.
16
+
17
+ The skill places a `proposed` leaf in the journey the intent belongs to
18
+ (or creates the journey), with 2 to 5 observable acceptance criteria and
19
+ its `requires:` / `creates:` taken from the spec vocabulary. It writes
20
+ no code and no `anchors:`: the pull request that delivers the leaf adds
21
+ them and passes it `implemented`.
22
+
23
+ It refuses an entity that no linked spec defines and redirects to
24
+ `/spec` first.
package/dist/index.d.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  export { InitArgs, InitResult, initCommand, planInit, writeFilesToTarget } from './init.js';
2
- import { d as RenderedFile } from './render-C-FWmUfX.js';
2
+ import { d as RenderedFile } from './render-BzrBb_l4.js';
3
3
  import './parser/index.js';
4
4
  import 'zod';
5
5
 
6
- declare const VERSION = "2.1.0";
6
+ declare const VERSION = "2.2.0";
7
7
 
8
8
  interface UpdateArgs {
9
9
  targetDir: string;
package/dist/index.js CHANGED
@@ -1,14 +1,20 @@
1
1
  // src/version.ts
2
- var VERSION = "2.1.0";
2
+ var VERSION = "2.2.0";
3
3
 
4
4
  // src/cli/init.ts
5
- import { existsSync as existsSync7, mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync3 } from "fs";
6
- import { dirname as dirname6, join as join9, resolve as resolve6 } from "path";
5
+ import { existsSync as existsSync8, mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync3 } from "fs";
6
+ import { dirname as dirname6, join as join10, resolve as resolve6 } from "path";
7
7
 
8
8
  // src/cli/managed-paths.ts
9
9
  import { lstatSync, realpathSync, statSync } from "fs";
10
10
  import { basename, dirname, isAbsolute, join, resolve, win32 } from "path";
11
- var MANAGED_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".harness-manifest.json"]);
11
+ var MANAGED_FILES = /* @__PURE__ */ new Set([
12
+ "AGENTS.md",
13
+ "CLAUDE.md",
14
+ ".harness-manifest.json",
15
+ // Index of the optional journeys pillar, rendered while a journey exists.
16
+ "docs/journeys/README.md"
17
+ ]);
12
18
  var RELEASED_PATHS = [
13
19
  ".mcp.json",
14
20
  ".codex/config.toml",
@@ -106,8 +112,8 @@ function readManifest(targetDir) {
106
112
  }
107
113
 
108
114
  // src/cli/plan-render.ts
109
- import { existsSync as existsSync3 } from "fs";
110
- import { dirname as dirname2, join as join4, resolve as resolve2 } from "path";
115
+ import { existsSync as existsSync4 } from "fs";
116
+ import { dirname as dirname2, join as join5, resolve as resolve2 } from "path";
111
117
  import { fileURLToPath } from "url";
112
118
 
113
119
  // src/loader.ts
@@ -163,9 +169,18 @@ var CmdFrontmatterSchema = z2.object({
163
169
  args: z2.array(CmdArgSchema).optional(),
164
170
  description: z2.string().min(1)
165
171
  }).strict();
172
+ var JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
173
+ var JourneyFrontmatterSchema = z2.object({
174
+ title: z2.string().min(1),
175
+ status: z2.enum(JOURNEY_STATUSES),
176
+ actors: z2.array(z2.string().min(1)).min(1),
177
+ spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
178
+ last_reviewed: z2.union([z2.date(), z2.string().min(1)])
179
+ }).strict();
166
180
  var Schemas = {
167
181
  Skill: SkillFrontmatterSchema,
168
- Cmd: CmdFrontmatterSchema
182
+ Cmd: CmdFrontmatterSchema,
183
+ Journey: JourneyFrontmatterSchema
169
184
  };
170
185
  var ParseError = class extends Error {
171
186
  constructor(file, issues) {
@@ -249,6 +264,208 @@ function loadOverrides(worktreeDir) {
249
264
  return { add: added, disable };
250
265
  }
251
266
 
267
+ // src/parser/journey.ts
268
+ import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync, statSync as statSync2 } from "fs";
269
+ import { basename as basename2, join as join4 } from "path";
270
+ import matter2 from "gray-matter";
271
+ var JOURNEYS_DIR = "docs/journeys";
272
+ var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
273
+ var NODE_FIELDS = [
274
+ "status",
275
+ "spec",
276
+ "anchors",
277
+ "acceptance",
278
+ "requires",
279
+ "creates"
280
+ ];
281
+ var MASKED_LINE = "\0";
282
+ var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
283
+ var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
284
+ var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
285
+ var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
286
+ function maskFencedCode(lines) {
287
+ let fence;
288
+ return lines.map((line) => {
289
+ const m = FENCE_RE.exec(line);
290
+ if (fence !== void 0) {
291
+ if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
292
+ return MASKED_LINE;
293
+ }
294
+ if (m?.[1]) {
295
+ fence = m[1];
296
+ return MASKED_LINE;
297
+ }
298
+ return line;
299
+ });
300
+ }
301
+ function parseHeading(line) {
302
+ const m = HEADING_RE.exec(line);
303
+ if (!m?.[1] || !m[2]) return void 0;
304
+ return { depth: m[1].length, title: m[2] };
305
+ }
306
+ function splitList(value) {
307
+ return value.split(",").map((v) => v.trim()).filter(Boolean);
308
+ }
309
+ function bodyStart(lines) {
310
+ if (lines[0]?.trim() !== "---") return 0;
311
+ for (let i = 1; i < lines.length; i++) {
312
+ const l = lines[i]?.trim();
313
+ if (l === "---" || l === "...") return i + 1;
314
+ }
315
+ return lines.length;
316
+ }
317
+ function parseFrontmatter(text, errors) {
318
+ let data;
319
+ try {
320
+ data = matter2(text).data;
321
+ } catch (error) {
322
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
323
+ errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
324
+ return void 0;
325
+ }
326
+ const result = Schemas.Journey.safeParse(data);
327
+ if (result.success) return result.data;
328
+ for (const issue of result.error.issues) {
329
+ const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
330
+ errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
331
+ }
332
+ return void 0;
333
+ }
334
+ function newNode(title, level, line) {
335
+ return {
336
+ title,
337
+ level,
338
+ line,
339
+ isLeaf: true,
340
+ fieldLines: {},
341
+ anchors: [],
342
+ acceptance: [],
343
+ requires: [],
344
+ creates: [],
345
+ unknownFields: []
346
+ };
347
+ }
348
+ function parseFields(node, lines, from, to, errors) {
349
+ let lastKey;
350
+ for (let i = from; i < to; i++) {
351
+ const line = lines[i] ?? "";
352
+ if (line.trim() === "") continue;
353
+ const lineNo = i + 1;
354
+ const field = FIELD_RE.exec(line.trimEnd());
355
+ if (field?.[1] !== void 0) {
356
+ const key = field[1];
357
+ const value = (field[2] ?? "").trim();
358
+ lastKey = key;
359
+ if (!NODE_FIELDS.includes(key)) {
360
+ node.unknownFields.push({ key, line: lineNo });
361
+ continue;
362
+ }
363
+ const known = key;
364
+ node.fieldLines[known] = lineNo;
365
+ if (known === "status") {
366
+ if (JOURNEY_STATUSES.includes(value)) {
367
+ node.status = value;
368
+ } else {
369
+ errors.push({
370
+ line: lineNo,
371
+ message: `invalid status \`${value}\` (expected ${JOURNEY_STATUSES.join(" | ")})`
372
+ });
373
+ }
374
+ } else if (known === "spec") {
375
+ node.spec = value;
376
+ } else if (known === "acceptance") {
377
+ if (value) node.acceptance.push(value);
378
+ } else {
379
+ node[known] = splitList(value);
380
+ }
381
+ continue;
382
+ }
383
+ const item = LIST_ITEM_RE.exec(line);
384
+ if (lastKey === "acceptance" && item) {
385
+ const text = (item[1] ?? "").trim();
386
+ if (text) node.acceptance.push(text);
387
+ continue;
388
+ }
389
+ return;
390
+ }
391
+ }
392
+ function parseJourney(relPath, text) {
393
+ const errors = [];
394
+ const meta = parseFrontmatter(text, errors);
395
+ const lines = maskFencedCode(text.split(/\r?\n/));
396
+ const start = bodyStart(lines);
397
+ const headings = [];
398
+ for (let i = start; i < lines.length; i++) {
399
+ const h = parseHeading(lines[i] ?? "");
400
+ if (h) headings.push({ index: i, ...h });
401
+ }
402
+ const h1 = headings.find((h) => h.depth === 1);
403
+ let story;
404
+ if (h1) {
405
+ const paragraph = [];
406
+ for (let i = h1.index + 1; i < lines.length; i++) {
407
+ const line = lines[i] ?? "";
408
+ if (line.trim() === "") {
409
+ if (paragraph.length) break;
410
+ continue;
411
+ }
412
+ if (line === MASKED_LINE || parseHeading(line)) break;
413
+ paragraph.push(line.trim());
414
+ }
415
+ if (paragraph.length) story = paragraph.join(" ");
416
+ }
417
+ const nodes = [];
418
+ const stack = [];
419
+ for (const [k, h] of headings.entries()) {
420
+ if (h.depth < 2) continue;
421
+ const node = newNode(h.title, h.depth - 1, h.index + 1);
422
+ while (stack.length) {
423
+ const top = nodes[stack[stack.length - 1]];
424
+ if (top && top.level < node.level) break;
425
+ stack.pop();
426
+ }
427
+ const parentIndex = stack[stack.length - 1];
428
+ if (parentIndex !== void 0) {
429
+ node.parent = parentIndex;
430
+ const parent = nodes[parentIndex];
431
+ if (parent) parent.isLeaf = false;
432
+ }
433
+ const next = headings[k + 1];
434
+ parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
435
+ const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
436
+ node.effectiveStatus = node.status ?? inherited;
437
+ stack.push(nodes.length);
438
+ nodes.push(node);
439
+ }
440
+ const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
441
+ return { ...meta ? { meta } : {}, title, ...story ? { story } : {}, nodes, errors };
442
+ }
443
+ function listJourneyFiles(targetDir) {
444
+ const dir = join4(targetDir, JOURNEYS_DIR);
445
+ if (!existsSync3(dir) || !statSync2(dir).isDirectory()) return [];
446
+ return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync2(join4(dir, f)).isFile()).sort();
447
+ }
448
+ function readJourneys(targetDir) {
449
+ return listJourneyFiles(targetDir).map((file) => {
450
+ const path = `${JOURNEYS_DIR}/${file}`;
451
+ const text = readFileSync4(join4(targetDir, path), "utf8");
452
+ return { path, file, ...parseJourney(path, text) };
453
+ });
454
+ }
455
+ function loadJourneys(targetDir) {
456
+ const journeys = readJourneys(targetDir);
457
+ const problems = journeys.flatMap(
458
+ (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
459
+ );
460
+ if (problems.length) {
461
+ throw new Error(
462
+ `invalid journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
463
+ ${problems.join("\n")}`
464
+ );
465
+ }
466
+ return journeys;
467
+ }
468
+
252
469
  // src/renderers/common.ts
253
470
  import { stringify as yamlStringify } from "yaml";
254
471
  function checkSkillCapabilities(skill, engine) {
@@ -306,12 +523,15 @@ function frontmatterDataForCmd(cmd) {
306
523
  return data;
307
524
  }
308
525
  function buildUmbrellaBody(extras) {
309
- const triggerBySkill = new Map(
310
- extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
311
- );
526
+ const triggersBySkill = /* @__PURE__ */ new Map();
527
+ for (const c of extras.availableCommands) {
528
+ const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
529
+ triggers.push(c.meta.trigger);
530
+ triggersBySkill.set(c.meta.invokes_skill, triggers);
531
+ }
312
532
  const skillLines = extras.availableSkills.map((s) => {
313
- const trigger = triggerBySkill.get(s.meta.id);
314
- const label = trigger ? `\`${s.meta.id}\` (\`${trigger}\`)` : `\`${s.meta.id}\``;
533
+ const triggers = triggersBySkill.get(s.meta.id) ?? [];
534
+ const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
315
535
  return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
316
536
  });
317
537
  const sections = [
@@ -331,11 +551,17 @@ function buildUmbrellaBody(extras) {
331
551
  ...extras.hasQualityDoc ? [
332
552
  "- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
333
553
  ] : [],
554
+ ...extras.hasJourneys ? [
555
+ "- `docs/journeys/<journey>.md` \u2014 user intentions and journeys, anchored to the code. `docs/journeys/README.md` is the generated index."
556
+ ] : [],
334
557
  "",
335
558
  "## Doc-first",
336
559
  "",
337
560
  "The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
338
561
  "",
562
+ ...extras.hasJourneys ? [
563
+ "- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
564
+ ] : [],
339
565
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
340
566
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
341
567
  "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
@@ -464,6 +690,23 @@ function getRenderer(engine) {
464
690
  return RENDERERS[engine];
465
691
  }
466
692
 
693
+ // src/renderers/journeys-index.ts
694
+ var INTRO = "User intentions and journeys of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/journeys/*.md`: edit the journeys, not this file, then run `npx @vaubaan/harness update .`.";
695
+ function buildJourneysIndex(journeys) {
696
+ const lines = ["# Journeys", "", INTRO, ""];
697
+ const sorted = [...journeys].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
698
+ for (const journey of sorted) {
699
+ const status = journey.meta?.status ?? "proposed";
700
+ const actors = journey.meta?.actors.join(", ") ?? "";
701
+ lines.push(`- [${journey.title}](./${journey.file}) \u2014 ${status} \xB7 ${actors}`);
702
+ for (const node of journey.nodes) {
703
+ lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
704
+ }
705
+ }
706
+ return `${lines.join("\n")}
707
+ `;
708
+ }
709
+
467
710
  // src/render.ts
468
711
  var RenderError = class extends Error {
469
712
  constructor(message) {
@@ -533,12 +776,16 @@ function render(input) {
533
776
  availableSkills: Array.from(exposedSkills.values()),
534
777
  availableCommands: Array.from(exposedCmds.values()),
535
778
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
536
- hasQualityDoc: input.hasQualityDoc === true
779
+ hasQualityDoc: input.hasQualityDoc === true,
780
+ hasJourneys: (input.journeys?.length ?? 0) > 0
537
781
  });
538
782
  files.push({ path: "AGENTS.md", content: umbrellaContent });
539
783
  if (engines.includes("claude-code")) {
540
784
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
541
785
  }
786
+ if (input.journeys && input.journeys.length > 0) {
787
+ files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
788
+ }
542
789
  return { files, warnings };
543
790
  }
544
791
 
@@ -560,7 +807,7 @@ function resolveEngineList(requested) {
560
807
  }
561
808
  function defaultPackageDir() {
562
809
  const here = dirname2(fileURLToPath(import.meta.url));
563
- if (existsSync3(join4(here, "skills"))) return here;
810
+ if (existsSync4(join5(here, "skills"))) return here;
564
811
  return resolve2(here, "..");
565
812
  }
566
813
  function planInit(args) {
@@ -569,14 +816,15 @@ function planInit(args) {
569
816
  const harness = loadHarness(packageDir);
570
817
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
571
818
  const projectSkills = loadProjectSkills(args.targetDir);
572
- const hasQualityDoc = existsSync3(join4(args.targetDir, QUALITY_DOC_PATH));
573
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
819
+ const hasQualityDoc = existsSync4(join5(args.targetDir, QUALITY_DOC_PATH));
820
+ const journeys = loadJourneys(args.targetDir);
821
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, journeys });
574
822
  return { engines, output };
575
823
  }
576
824
 
577
825
  // src/cli/uninstall.ts
578
- import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync, rmdirSync, unlinkSync } from "fs";
579
- import { dirname as dirname3, join as join5, relative, resolve as resolve3 } from "path";
826
+ import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync2, rmdirSync, unlinkSync } from "fs";
827
+ import { dirname as dirname3, join as join6, relative, resolve as resolve3 } from "path";
580
828
  function pruneEmptyDirs(root, leaves) {
581
829
  const candidates = /* @__PURE__ */ new Set();
582
830
  for (const leaf of leaves) {
@@ -589,8 +837,8 @@ function pruneEmptyDirs(root, leaves) {
589
837
  const pruned = [];
590
838
  const sorted = [...candidates].sort((a, b) => b.length - a.length);
591
839
  for (const dir of sorted) {
592
- if (!existsSync4(dir)) continue;
593
- if (readdirSync(dir).length > 0) continue;
840
+ if (!existsSync5(dir)) continue;
841
+ if (readdirSync2(dir).length > 0) continue;
594
842
  rmdirSync(dir);
595
843
  pruned.push(relative(root, dir));
596
844
  }
@@ -606,25 +854,25 @@ import {
606
854
  lstatSync as lstatSync2,
607
855
  mkdirSync,
608
856
  openSync,
609
- readFileSync as readFileSync5,
610
- readdirSync as readdirSync2,
857
+ readFileSync as readFileSync6,
858
+ readdirSync as readdirSync3,
611
859
  realpathSync as realpathSync2,
612
860
  rmdirSync as rmdirSync2,
613
861
  unlinkSync as unlinkSync2,
614
862
  writeFileSync as writeFileSync2
615
863
  } from "fs";
616
864
  import { homedir } from "os";
617
- import { basename as basename2, dirname as dirname4, isAbsolute as isAbsolute2, join as join6, relative as relative2, resolve as resolve4, sep } from "path";
865
+ import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute2, join as join7, relative as relative2, resolve as resolve4, sep } from "path";
618
866
  var MANIFEST_PATH = ".harness-manifest.json";
619
867
  var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
620
868
  function canonicalRoot(root) {
621
869
  let ancestor = resolve4(root);
622
870
  const missing = [];
623
871
  while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
624
- missing.unshift(basename2(ancestor));
872
+ missing.unshift(basename3(ancestor));
625
873
  ancestor = dirname4(ancestor);
626
874
  }
627
- return join6(realpathSync2(ancestor), ...missing);
875
+ return join7(realpathSync2(ancestor), ...missing);
628
876
  }
629
877
  function contains(parent, child) {
630
878
  const path = relative2(parent, child);
@@ -675,14 +923,14 @@ function saveSnapshot(root, paths, backup) {
675
923
  createDirectories(dirname4(backup), [], 448);
676
924
  mkdirSync(backup, { mode: 448 });
677
925
  for (const path of paths) {
678
- const full = join6(root, path);
926
+ const full = join7(root, path);
679
927
  const info = lstatSync2(full, { throwIfNoEntry: false });
680
928
  if (!info) {
681
929
  entries.push({ path, exists: false });
682
930
  continue;
683
931
  }
684
- const content = readFileSync5(full);
685
- writeBackupFile(join6(backup, "files", path), content);
932
+ const content = readFileSync6(full);
933
+ writeBackupFile(join7(backup, "files", path), content);
686
934
  entries.push({
687
935
  path,
688
936
  exists: true,
@@ -691,7 +939,7 @@ function saveSnapshot(root, paths, backup) {
691
939
  });
692
940
  }
693
941
  writeBackupFile(
694
- join6(backup, "snapshot.json"),
942
+ join7(backup, "snapshot.json"),
695
943
  `${JSON.stringify({ version: 1, root, createdAt: (/* @__PURE__ */ new Date()).toISOString(), entries }, null, 2)}
696
944
  `
697
945
  );
@@ -706,14 +954,14 @@ function rollback(root, backup, entries, touched, createdDirectories) {
706
954
  try {
707
955
  assertManagedPaths(root, [path]);
708
956
  const entry = entries.get(path);
709
- const full = join6(root, path);
957
+ const full = join7(root, path);
710
958
  const current = lstatSync2(full, { throwIfNoEntry: false });
711
959
  if (!entry?.exists) {
712
960
  if (current) unlinkSync2(full);
713
961
  continue;
714
962
  }
715
- const original = readFileSync5(join6(backup, "files", path));
716
- if (!current || !readFileSync5(full).equals(original)) {
963
+ const original = readFileSync6(join7(backup, "files", path));
964
+ if (!current || !readFileSync6(full).equals(original)) {
717
965
  if (current) unlinkSync2(full);
718
966
  writeFileSync2(full, original, { mode: 384 });
719
967
  }
@@ -724,7 +972,7 @@ function rollback(root, backup, entries, touched, createdDirectories) {
724
972
  }
725
973
  for (const directory of [...createdDirectories].reverse()) {
726
974
  try {
727
- if (readdirSync2(directory).length === 0) rmdirSync2(directory);
975
+ if (readdirSync3(directory).length === 0) rmdirSync2(directory);
728
976
  } catch (error) {
729
977
  errors.push(`${directory}: ${errorMessage(error)}`);
730
978
  }
@@ -736,7 +984,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
736
984
  assertManagedPaths(root, paths);
737
985
  const target = canonicalRoot(root);
738
986
  const backup = resolve4(
739
- backupDir ?? join6(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
987
+ backupDir ?? join7(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
740
988
  );
741
989
  assertBackupLocation(target, backup);
742
990
  let snapshot;
@@ -754,12 +1002,12 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
754
1002
  try {
755
1003
  assertManagedPaths(target, paths);
756
1004
  for (const path of removals) {
757
- if (!lstatSync2(join6(target, path), { throwIfNoEntry: false })) continue;
1005
+ if (!lstatSync2(join7(target, path), { throwIfNoEntry: false })) continue;
758
1006
  touched.add(path);
759
- unlinkSync2(join6(target, path));
1007
+ unlinkSync2(join7(target, path));
760
1008
  }
761
1009
  for (const file of writes) {
762
- const full = join6(target, file.path);
1010
+ const full = join7(target, file.path);
763
1011
  createDirectories(dirname4(full), createdDirectories);
764
1012
  touched.add(file.path);
765
1013
  const entry = entries.get(file.path);
@@ -779,13 +1027,13 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
779
1027
  }
780
1028
 
781
1029
  // src/cli/update.ts
782
- import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
783
- import { dirname as dirname5, join as join8, resolve as resolve5 } from "path";
1030
+ import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
1031
+ import { dirname as dirname5, join as join9, resolve as resolve5 } from "path";
784
1032
  import { isDeepStrictEqual } from "util";
785
1033
 
786
1034
  // src/cli/update-manifest.ts
787
- import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
788
- import { join as join7 } from "path";
1035
+ import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
1036
+ import { join as join8 } from "path";
789
1037
  import { z as z4 } from "zod";
790
1038
  var EngineSchema = z4.enum(ENGINES);
791
1039
  var LegacySchema = z4.object({
@@ -797,10 +1045,10 @@ var LegacySchema = z4.object({
797
1045
  });
798
1046
  function readUpdateInstallation(root) {
799
1047
  assertManagedPaths(root, [MANIFEST_FILENAME]);
800
- if (!existsSync5(join7(root, MANIFEST_FILENAME))) {
1048
+ if (!existsSync6(join8(root, MANIFEST_FILENAME))) {
801
1049
  throw new Error("no harness manifest found; use init for a new installation");
802
1050
  }
803
- const raw = JSON.parse(readFileSync6(join7(root, MANIFEST_FILENAME), "utf8"));
1051
+ const raw = JSON.parse(readFileSync7(join8(root, MANIFEST_FILENAME), "utf8"));
804
1052
  const sourceVersion = String(raw?.version);
805
1053
  let manifest;
806
1054
  if (["1", "2", "3"].includes(sourceVersion)) {
@@ -825,7 +1073,7 @@ function readUpdateInstallation(root) {
825
1073
  var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
826
1074
  var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
827
1075
  function currentContent(root, path) {
828
- return existsSync6(join8(root, path)) ? readFileSync7(join8(root, path), "utf8") : void 0;
1076
+ return existsSync7(join9(root, path)) ? readFileSync8(join9(root, path), "utf8") : void 0;
829
1077
  }
830
1078
  function checkArtifactConflicts(root, previous, writes, removals) {
831
1079
  const desired = new Map(writes.map((file) => [file.path, file.content]));
@@ -880,14 +1128,14 @@ function planInstallation(args, settings) {
880
1128
  assertManagedPaths(root, [...previous.files, ...preserved]);
881
1129
  const requestedOverrides = args.overridesDir ?? previous.overridesDir;
882
1130
  const overridesDir = args.overridesDir ? resolve5(args.overridesDir) : previous.overridesDir ? resolve5(root, previous.overridesDir) : root;
883
- if (requestedOverrides && !existsSync6(join8(overridesDir, ".harness-overrides"))) {
1131
+ if (requestedOverrides && !existsSync7(join9(overridesDir, ".harness-overrides"))) {
884
1132
  throw new Error(`recorded overrides are missing: ${overridesDir}/.harness-overrides`);
885
1133
  }
886
- const hasOverrides = existsSync6(join8(overridesDir, ".harness-overrides"));
887
- const disablePath = join8(overridesDir, ".harness-overrides", "disable.yaml");
888
- if (existsSync6(disablePath)) {
1134
+ const hasOverrides = existsSync7(join9(overridesDir, ".harness-overrides"));
1135
+ const disablePath = join9(overridesDir, ".harness-overrides", "disable.yaml");
1136
+ if (existsSync7(disablePath)) {
889
1137
  try {
890
- DisableYamlSchema.parse(parseYAML(readFileSync7(disablePath, "utf8")));
1138
+ DisableYamlSchema.parse(parseYAML(readFileSync8(disablePath, "utf8")));
891
1139
  } catch {
892
1140
  throw new Error(`invalid override selection: ${disablePath}`);
893
1141
  }
@@ -917,7 +1165,7 @@ function planInstallation(args, settings) {
917
1165
  ...preserved.length ? { preservedFiles: preserved } : {}
918
1166
  };
919
1167
  const writes = output.filter((file) => currentContent(root, file.path) !== file.content);
920
- const existingRemovals = removals.filter((path) => existsSync6(join8(root, path)));
1168
+ const existingRemovals = removals.filter((path) => existsSync7(join9(root, path)));
921
1169
  if (writes.length || existingRemovals.length || !isDeepStrictEqual(settings.previous, manifest)) {
922
1170
  manifest.renderedAt = (/* @__PURE__ */ new Date()).toISOString();
923
1171
  writes.push({ path: MANIFEST_FILENAME, content: `${JSON.stringify(manifest, null, 2)}
@@ -957,7 +1205,7 @@ function updateCommand(args) {
957
1205
  if (args.dryRun || plan.result.upToDate) return plan.result;
958
1206
  const root = resolve5(args.targetDir);
959
1207
  const { backupDir } = applyUpdateTransaction(root, plan.writes, plan.removals, args.backupDir);
960
- pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname5(join8(root, path)))));
1208
+ pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname5(join9(root, path)))));
961
1209
  return { ...plan.result, backupDir };
962
1210
  }
963
1211
 
@@ -969,7 +1217,7 @@ function writeFilesToTarget(files, targetDir) {
969
1217
  );
970
1218
  const written = [];
971
1219
  for (const f of files) {
972
- const full = join9(targetDir, f.path);
1220
+ const full = join10(targetDir, f.path);
973
1221
  mkdirSync2(dirname6(full), { recursive: true });
974
1222
  writeFileSync3(full, f.content);
975
1223
  written.push(f.path);
@@ -993,7 +1241,7 @@ function initCommand(args) {
993
1241
  { previous, sourceVersion: previous.version, engines }
994
1242
  );
995
1243
  const touchedExisting = [...plan.writes.map((file) => file.path), ...plan.removals].some(
996
- (path) => path !== MANIFEST_FILENAME && existsSync7(join9(root, path))
1244
+ (path) => path !== MANIFEST_FILENAME && existsSync8(join10(root, path))
997
1245
  );
998
1246
  let backupDir;
999
1247
  if (plan.writes.length || plan.removals.length) {
@@ -1002,7 +1250,7 @@ function initCommand(args) {
1002
1250
  rmSync(backupDir, { recursive: true, force: true });
1003
1251
  backupDir = void 0;
1004
1252
  }
1005
- pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname6(join9(root, path)))));
1253
+ pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname6(join10(root, path)))));
1006
1254
  }
1007
1255
  return {
1008
1256
  filesWritten: plan.owned,