@vaubaan/harness 2.1.0 → 2.3.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/index.js CHANGED
@@ -1,14 +1,26 @@
1
1
  // src/version.ts
2
- var VERSION = "2.1.0";
2
+ var VERSION = "2.3.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 intents pillar, rendered while an intent file exists.
16
+ "docs/intents/README.md",
17
+ // Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
18
+ "docs/journeys/README.md"
19
+ ]);
20
+ var MOVED_PATHS = /* @__PURE__ */ new Map([
21
+ // 2.3: the journeys pillar became the intents pillar.
22
+ ["docs/journeys/README.md", "docs/intents/README.md"]
23
+ ]);
12
24
  var RELEASED_PATHS = [
13
25
  ".mcp.json",
14
26
  ".codex/config.toml",
@@ -106,8 +118,8 @@ function readManifest(targetDir) {
106
118
  }
107
119
 
108
120
  // 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";
121
+ import { existsSync as existsSync4 } from "fs";
122
+ import { dirname as dirname2, join as join5, resolve as resolve2 } from "path";
111
123
  import { fileURLToPath } from "url";
112
124
 
113
125
  // src/loader.ts
@@ -148,12 +160,16 @@ var CmdArgEnumSchema = z2.object({
148
160
  name: z2.string().min(1),
149
161
  type: z2.literal("enum"),
150
162
  values: z2.array(z2.string()).min(1),
151
- default: z2.string().optional()
163
+ default: z2.string().optional(),
164
+ /** False when the command runs without the argument. Defaults to true. */
165
+ required: z2.boolean().optional()
152
166
  }).strict();
153
167
  var CmdArgStringSchema = z2.object({
154
168
  name: z2.string().min(1),
155
169
  type: z2.literal("string"),
156
- default: z2.string().optional()
170
+ default: z2.string().optional(),
171
+ /** False when the command runs without the argument. Defaults to true. */
172
+ required: z2.boolean().optional()
157
173
  }).strict();
158
174
  var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
159
175
  var CmdFrontmatterSchema = z2.object({
@@ -163,9 +179,18 @@ var CmdFrontmatterSchema = z2.object({
163
179
  args: z2.array(CmdArgSchema).optional(),
164
180
  description: z2.string().min(1)
165
181
  }).strict();
182
+ var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
183
+ var IntentFrontmatterSchema = z2.object({
184
+ title: z2.string().min(1),
185
+ status: z2.enum(INTENT_STATUSES),
186
+ actors: z2.array(z2.string().min(1)).min(1),
187
+ spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
188
+ last_reviewed: z2.union([z2.date(), z2.string().min(1)])
189
+ }).strict();
166
190
  var Schemas = {
167
191
  Skill: SkillFrontmatterSchema,
168
- Cmd: CmdFrontmatterSchema
192
+ Cmd: CmdFrontmatterSchema,
193
+ Intent: IntentFrontmatterSchema
169
194
  };
170
195
  var ParseError = class extends Error {
171
196
  constructor(file, issues) {
@@ -249,6 +274,208 @@ function loadOverrides(worktreeDir) {
249
274
  return { add: added, disable };
250
275
  }
251
276
 
277
+ // src/parser/intent.ts
278
+ import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync, statSync as statSync2 } from "fs";
279
+ import { basename as basename2, join as join4 } from "path";
280
+ import matter2 from "gray-matter";
281
+ var INTENTS_DIR = "docs/intents";
282
+ var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
283
+ var NODE_FIELDS = [
284
+ "status",
285
+ "spec",
286
+ "anchors",
287
+ "acceptance",
288
+ "requires",
289
+ "creates"
290
+ ];
291
+ var MASKED_LINE = "\0";
292
+ var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
293
+ var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
294
+ var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
295
+ var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
296
+ function maskFencedCode(lines) {
297
+ let fence;
298
+ return lines.map((line) => {
299
+ const m = FENCE_RE.exec(line);
300
+ if (fence !== void 0) {
301
+ if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
302
+ return MASKED_LINE;
303
+ }
304
+ if (m?.[1]) {
305
+ fence = m[1];
306
+ return MASKED_LINE;
307
+ }
308
+ return line;
309
+ });
310
+ }
311
+ function parseHeading(line) {
312
+ const m = HEADING_RE.exec(line);
313
+ if (!m?.[1] || !m[2]) return void 0;
314
+ return { depth: m[1].length, title: m[2] };
315
+ }
316
+ function splitList(value) {
317
+ return value.split(",").map((v) => v.trim()).filter(Boolean);
318
+ }
319
+ function bodyStart(lines) {
320
+ if (lines[0]?.trim() !== "---") return 0;
321
+ for (let i = 1; i < lines.length; i++) {
322
+ const l = lines[i]?.trim();
323
+ if (l === "---" || l === "...") return i + 1;
324
+ }
325
+ return lines.length;
326
+ }
327
+ function parseFrontmatter(text, errors) {
328
+ let data;
329
+ try {
330
+ data = matter2(text).data;
331
+ } catch (error) {
332
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
333
+ errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
334
+ return void 0;
335
+ }
336
+ const result = Schemas.Intent.safeParse(data);
337
+ if (result.success) return result.data;
338
+ for (const issue of result.error.issues) {
339
+ const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
340
+ errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
341
+ }
342
+ return void 0;
343
+ }
344
+ function newNode(title, level, line) {
345
+ return {
346
+ title,
347
+ level,
348
+ line,
349
+ isTerminal: true,
350
+ fieldLines: {},
351
+ anchors: [],
352
+ acceptance: [],
353
+ requires: [],
354
+ creates: [],
355
+ unknownFields: []
356
+ };
357
+ }
358
+ function parseFields(node, lines, from, to, errors) {
359
+ let lastKey;
360
+ for (let i = from; i < to; i++) {
361
+ const line = lines[i] ?? "";
362
+ if (line.trim() === "") continue;
363
+ const lineNo = i + 1;
364
+ const field = FIELD_RE.exec(line.trimEnd());
365
+ if (field?.[1] !== void 0) {
366
+ const key = field[1];
367
+ const value = (field[2] ?? "").trim();
368
+ lastKey = key;
369
+ if (!NODE_FIELDS.includes(key)) {
370
+ node.unknownFields.push({ key, line: lineNo });
371
+ continue;
372
+ }
373
+ const known = key;
374
+ node.fieldLines[known] = lineNo;
375
+ if (known === "status") {
376
+ if (INTENT_STATUSES.includes(value)) {
377
+ node.status = value;
378
+ } else {
379
+ errors.push({
380
+ line: lineNo,
381
+ message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
382
+ });
383
+ }
384
+ } else if (known === "spec") {
385
+ node.spec = value;
386
+ } else if (known === "acceptance") {
387
+ if (value) node.acceptance.push(value);
388
+ } else {
389
+ node[known] = splitList(value);
390
+ }
391
+ continue;
392
+ }
393
+ const item = LIST_ITEM_RE.exec(line);
394
+ if (lastKey === "acceptance" && item) {
395
+ const text = (item[1] ?? "").trim();
396
+ if (text) node.acceptance.push(text);
397
+ continue;
398
+ }
399
+ return;
400
+ }
401
+ }
402
+ function parseIntentFile(relPath, text) {
403
+ const errors = [];
404
+ const meta = parseFrontmatter(text, errors);
405
+ const lines = maskFencedCode(text.split(/\r?\n/));
406
+ const start = bodyStart(lines);
407
+ const headings = [];
408
+ for (let i = start; i < lines.length; i++) {
409
+ const h = parseHeading(lines[i] ?? "");
410
+ if (h) headings.push({ index: i, ...h });
411
+ }
412
+ const h1 = headings.find((h) => h.depth === 1);
413
+ let statement;
414
+ if (h1) {
415
+ const paragraph = [];
416
+ for (let i = h1.index + 1; i < lines.length; i++) {
417
+ const line = lines[i] ?? "";
418
+ if (line.trim() === "") {
419
+ if (paragraph.length) break;
420
+ continue;
421
+ }
422
+ if (line === MASKED_LINE || parseHeading(line)) break;
423
+ paragraph.push(line.trim());
424
+ }
425
+ if (paragraph.length) statement = paragraph.join(" ");
426
+ }
427
+ const nodes = [];
428
+ const stack = [];
429
+ for (const [k, h] of headings.entries()) {
430
+ if (h.depth < 2) continue;
431
+ const node = newNode(h.title, h.depth - 1, h.index + 1);
432
+ while (stack.length) {
433
+ const top = nodes[stack[stack.length - 1]];
434
+ if (top && top.level < node.level) break;
435
+ stack.pop();
436
+ }
437
+ const parentIndex = stack[stack.length - 1];
438
+ if (parentIndex !== void 0) {
439
+ node.parent = parentIndex;
440
+ const parent = nodes[parentIndex];
441
+ if (parent) parent.isTerminal = false;
442
+ }
443
+ const next = headings[k + 1];
444
+ parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
445
+ const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
446
+ node.effectiveStatus = node.status ?? inherited;
447
+ stack.push(nodes.length);
448
+ nodes.push(node);
449
+ }
450
+ const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
451
+ return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
452
+ }
453
+ function listIntentFiles(targetDir) {
454
+ const dir = join4(targetDir, INTENTS_DIR);
455
+ if (!existsSync3(dir) || !statSync2(dir).isDirectory()) return [];
456
+ return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync2(join4(dir, f)).isFile()).sort();
457
+ }
458
+ function readIntentFiles(targetDir) {
459
+ return listIntentFiles(targetDir).map((file) => {
460
+ const path = `${INTENTS_DIR}/${file}`;
461
+ const text = readFileSync4(join4(targetDir, path), "utf8");
462
+ return { path, file, ...parseIntentFile(path, text) };
463
+ });
464
+ }
465
+ function loadIntentFiles(targetDir) {
466
+ const intentFiles = readIntentFiles(targetDir);
467
+ const problems = intentFiles.flatMap(
468
+ (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
469
+ );
470
+ if (problems.length) {
471
+ throw new Error(
472
+ `invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
473
+ ${problems.join("\n")}`
474
+ );
475
+ }
476
+ return intentFiles;
477
+ }
478
+
252
479
  // src/renderers/common.ts
253
480
  import { stringify as yamlStringify } from "yaml";
254
481
  function checkSkillCapabilities(skill, engine) {
@@ -296,22 +523,26 @@ function frontmatterDataForCmd(cmd) {
296
523
  description: cmd.meta.description
297
524
  };
298
525
  if (cmd.meta.args && cmd.meta.args.length > 0) {
299
- data.args = cmd.meta.args.map((a) => {
300
- if (a.type === "enum") {
301
- return a.default !== void 0 ? { name: a.name, type: a.type, values: a.values, default: a.default } : { name: a.name, type: a.type, values: a.values };
302
- }
303
- return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
304
- });
526
+ data.args = cmd.meta.args.map((a) => ({
527
+ name: a.name,
528
+ type: a.type,
529
+ ...a.type === "enum" ? { values: a.values } : {},
530
+ ...a.default !== void 0 ? { default: a.default } : {},
531
+ ...a.required === false ? { required: false } : {}
532
+ }));
305
533
  }
306
534
  return data;
307
535
  }
308
536
  function buildUmbrellaBody(extras) {
309
- const triggerBySkill = new Map(
310
- extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
311
- );
537
+ const triggersBySkill = /* @__PURE__ */ new Map();
538
+ for (const c of extras.availableCommands) {
539
+ const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
540
+ triggers.push(c.meta.trigger);
541
+ triggersBySkill.set(c.meta.invokes_skill, triggers);
542
+ }
312
543
  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}\``;
544
+ const triggers = triggersBySkill.get(s.meta.id) ?? [];
545
+ const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
315
546
  return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
316
547
  });
317
548
  const sections = [
@@ -331,11 +562,17 @@ function buildUmbrellaBody(extras) {
331
562
  ...extras.hasQualityDoc ? [
332
563
  "- `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
564
  ] : [],
565
+ ...extras.hasIntents ? [
566
+ "- `docs/intents/<intent>.md` \u2014 user intents, one tree per level-1 intent, anchored to the code. `docs/intents/README.md` is the generated index."
567
+ ] : [],
334
568
  "",
335
569
  "## Doc-first",
336
570
  "",
337
571
  "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
572
  "",
573
+ ...extras.hasIntents ? [
574
+ "- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
575
+ ] : [],
339
576
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
340
577
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
341
578
  "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
@@ -464,6 +701,23 @@ function getRenderer(engine) {
464
701
  return RENDERERS[engine];
465
702
  }
466
703
 
704
+ // src/renderers/intents-index.ts
705
+ var INTRO = "User intents of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/intents/*.md`: edit the intents, not this file, then run `npx @vaubaan/harness update .`.";
706
+ function buildIntentsIndex(intentFiles) {
707
+ const lines = ["# Intents", "", INTRO, ""];
708
+ const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
709
+ for (const intentFile of sorted) {
710
+ const status = intentFile.meta?.status ?? "proposed";
711
+ const actors = intentFile.meta?.actors.join(", ") ?? "";
712
+ lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
713
+ for (const node of intentFile.nodes) {
714
+ lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
715
+ }
716
+ }
717
+ return `${lines.join("\n")}
718
+ `;
719
+ }
720
+
467
721
  // src/render.ts
468
722
  var RenderError = class extends Error {
469
723
  constructor(message) {
@@ -533,12 +787,16 @@ function render(input) {
533
787
  availableSkills: Array.from(exposedSkills.values()),
534
788
  availableCommands: Array.from(exposedCmds.values()),
535
789
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
536
- hasQualityDoc: input.hasQualityDoc === true
790
+ hasQualityDoc: input.hasQualityDoc === true,
791
+ hasIntents: (input.intentFiles?.length ?? 0) > 0
537
792
  });
538
793
  files.push({ path: "AGENTS.md", content: umbrellaContent });
539
794
  if (engines.includes("claude-code")) {
540
795
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
541
796
  }
797
+ if (input.intentFiles && input.intentFiles.length > 0) {
798
+ files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
799
+ }
542
800
  return { files, warnings };
543
801
  }
544
802
 
@@ -560,7 +818,7 @@ function resolveEngineList(requested) {
560
818
  }
561
819
  function defaultPackageDir() {
562
820
  const here = dirname2(fileURLToPath(import.meta.url));
563
- if (existsSync3(join4(here, "skills"))) return here;
821
+ if (existsSync4(join5(here, "skills"))) return here;
564
822
  return resolve2(here, "..");
565
823
  }
566
824
  function planInit(args) {
@@ -569,14 +827,15 @@ function planInit(args) {
569
827
  const harness = loadHarness(packageDir);
570
828
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
571
829
  const projectSkills = loadProjectSkills(args.targetDir);
572
- const hasQualityDoc = existsSync3(join4(args.targetDir, QUALITY_DOC_PATH));
573
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
830
+ const hasQualityDoc = existsSync4(join5(args.targetDir, QUALITY_DOC_PATH));
831
+ const intentFiles = loadIntentFiles(args.targetDir);
832
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
574
833
  return { engines, output };
575
834
  }
576
835
 
577
836
  // 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";
837
+ import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync2, rmdirSync, unlinkSync } from "fs";
838
+ import { dirname as dirname3, join as join6, relative, resolve as resolve3 } from "path";
580
839
  function pruneEmptyDirs(root, leaves) {
581
840
  const candidates = /* @__PURE__ */ new Set();
582
841
  for (const leaf of leaves) {
@@ -589,8 +848,8 @@ function pruneEmptyDirs(root, leaves) {
589
848
  const pruned = [];
590
849
  const sorted = [...candidates].sort((a, b) => b.length - a.length);
591
850
  for (const dir of sorted) {
592
- if (!existsSync4(dir)) continue;
593
- if (readdirSync(dir).length > 0) continue;
851
+ if (!existsSync5(dir)) continue;
852
+ if (readdirSync2(dir).length > 0) continue;
594
853
  rmdirSync(dir);
595
854
  pruned.push(relative(root, dir));
596
855
  }
@@ -606,25 +865,25 @@ import {
606
865
  lstatSync as lstatSync2,
607
866
  mkdirSync,
608
867
  openSync,
609
- readFileSync as readFileSync5,
610
- readdirSync as readdirSync2,
868
+ readFileSync as readFileSync6,
869
+ readdirSync as readdirSync3,
611
870
  realpathSync as realpathSync2,
612
871
  rmdirSync as rmdirSync2,
613
872
  unlinkSync as unlinkSync2,
614
873
  writeFileSync as writeFileSync2
615
874
  } from "fs";
616
875
  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";
876
+ import { basename as basename3, dirname as dirname4, isAbsolute as isAbsolute2, join as join7, relative as relative2, resolve as resolve4, sep } from "path";
618
877
  var MANIFEST_PATH = ".harness-manifest.json";
619
878
  var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
620
879
  function canonicalRoot(root) {
621
880
  let ancestor = resolve4(root);
622
881
  const missing = [];
623
882
  while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
624
- missing.unshift(basename2(ancestor));
883
+ missing.unshift(basename3(ancestor));
625
884
  ancestor = dirname4(ancestor);
626
885
  }
627
- return join6(realpathSync2(ancestor), ...missing);
886
+ return join7(realpathSync2(ancestor), ...missing);
628
887
  }
629
888
  function contains(parent, child) {
630
889
  const path = relative2(parent, child);
@@ -675,14 +934,14 @@ function saveSnapshot(root, paths, backup) {
675
934
  createDirectories(dirname4(backup), [], 448);
676
935
  mkdirSync(backup, { mode: 448 });
677
936
  for (const path of paths) {
678
- const full = join6(root, path);
937
+ const full = join7(root, path);
679
938
  const info = lstatSync2(full, { throwIfNoEntry: false });
680
939
  if (!info) {
681
940
  entries.push({ path, exists: false });
682
941
  continue;
683
942
  }
684
- const content = readFileSync5(full);
685
- writeBackupFile(join6(backup, "files", path), content);
943
+ const content = readFileSync6(full);
944
+ writeBackupFile(join7(backup, "files", path), content);
686
945
  entries.push({
687
946
  path,
688
947
  exists: true,
@@ -691,7 +950,7 @@ function saveSnapshot(root, paths, backup) {
691
950
  });
692
951
  }
693
952
  writeBackupFile(
694
- join6(backup, "snapshot.json"),
953
+ join7(backup, "snapshot.json"),
695
954
  `${JSON.stringify({ version: 1, root, createdAt: (/* @__PURE__ */ new Date()).toISOString(), entries }, null, 2)}
696
955
  `
697
956
  );
@@ -706,14 +965,14 @@ function rollback(root, backup, entries, touched, createdDirectories) {
706
965
  try {
707
966
  assertManagedPaths(root, [path]);
708
967
  const entry = entries.get(path);
709
- const full = join6(root, path);
968
+ const full = join7(root, path);
710
969
  const current = lstatSync2(full, { throwIfNoEntry: false });
711
970
  if (!entry?.exists) {
712
971
  if (current) unlinkSync2(full);
713
972
  continue;
714
973
  }
715
- const original = readFileSync5(join6(backup, "files", path));
716
- if (!current || !readFileSync5(full).equals(original)) {
974
+ const original = readFileSync6(join7(backup, "files", path));
975
+ if (!current || !readFileSync6(full).equals(original)) {
717
976
  if (current) unlinkSync2(full);
718
977
  writeFileSync2(full, original, { mode: 384 });
719
978
  }
@@ -724,7 +983,7 @@ function rollback(root, backup, entries, touched, createdDirectories) {
724
983
  }
725
984
  for (const directory of [...createdDirectories].reverse()) {
726
985
  try {
727
- if (readdirSync2(directory).length === 0) rmdirSync2(directory);
986
+ if (readdirSync3(directory).length === 0) rmdirSync2(directory);
728
987
  } catch (error) {
729
988
  errors.push(`${directory}: ${errorMessage(error)}`);
730
989
  }
@@ -736,7 +995,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
736
995
  assertManagedPaths(root, paths);
737
996
  const target = canonicalRoot(root);
738
997
  const backup = resolve4(
739
- backupDir ?? join6(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
998
+ backupDir ?? join7(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
740
999
  );
741
1000
  assertBackupLocation(target, backup);
742
1001
  let snapshot;
@@ -754,12 +1013,12 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
754
1013
  try {
755
1014
  assertManagedPaths(target, paths);
756
1015
  for (const path of removals) {
757
- if (!lstatSync2(join6(target, path), { throwIfNoEntry: false })) continue;
1016
+ if (!lstatSync2(join7(target, path), { throwIfNoEntry: false })) continue;
758
1017
  touched.add(path);
759
- unlinkSync2(join6(target, path));
1018
+ unlinkSync2(join7(target, path));
760
1019
  }
761
1020
  for (const file of writes) {
762
- const full = join6(target, file.path);
1021
+ const full = join7(target, file.path);
763
1022
  createDirectories(dirname4(full), createdDirectories);
764
1023
  touched.add(file.path);
765
1024
  const entry = entries.get(file.path);
@@ -779,13 +1038,13 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
779
1038
  }
780
1039
 
781
1040
  // 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";
1041
+ import { existsSync as existsSync7, readFileSync as readFileSync8, readdirSync as readdirSync4, statSync as statSync3 } from "fs";
1042
+ import { dirname as dirname5, join as join9, resolve as resolve5 } from "path";
784
1043
  import { isDeepStrictEqual } from "util";
785
1044
 
786
1045
  // src/cli/update-manifest.ts
787
- import { existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
788
- import { join as join7 } from "path";
1046
+ import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
1047
+ import { join as join8 } from "path";
789
1048
  import { z as z4 } from "zod";
790
1049
  var EngineSchema = z4.enum(ENGINES);
791
1050
  var LegacySchema = z4.object({
@@ -797,10 +1056,10 @@ var LegacySchema = z4.object({
797
1056
  });
798
1057
  function readUpdateInstallation(root) {
799
1058
  assertManagedPaths(root, [MANIFEST_FILENAME]);
800
- if (!existsSync5(join7(root, MANIFEST_FILENAME))) {
1059
+ if (!existsSync6(join8(root, MANIFEST_FILENAME))) {
801
1060
  throw new Error("no harness manifest found; use init for a new installation");
802
1061
  }
803
- const raw = JSON.parse(readFileSync6(join7(root, MANIFEST_FILENAME), "utf8"));
1062
+ const raw = JSON.parse(readFileSync7(join8(root, MANIFEST_FILENAME), "utf8"));
804
1063
  const sourceVersion = String(raw?.version);
805
1064
  let manifest;
806
1065
  if (["1", "2", "3"].includes(sourceVersion)) {
@@ -825,7 +1084,7 @@ function readUpdateInstallation(root) {
825
1084
  var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
826
1085
  var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
827
1086
  function currentContent(root, path) {
828
- return existsSync6(join8(root, path)) ? readFileSync7(join8(root, path), "utf8") : void 0;
1087
+ return existsSync7(join9(root, path)) ? readFileSync8(join9(root, path), "utf8") : void 0;
829
1088
  }
830
1089
  function checkArtifactConflicts(root, previous, writes, removals) {
831
1090
  const desired = new Map(writes.map((file) => [file.path, file.content]));
@@ -855,6 +1114,27 @@ function releaseLegacyPaths(previous, warnings) {
855
1114
  if (released.length === 0) return previous;
856
1115
  return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
857
1116
  }
1117
+ function carryMovedPaths(root, previous, warnings) {
1118
+ let files = previous.files;
1119
+ let fileHashes = previous.fileHashes;
1120
+ for (const [from, to] of MOVED_PATHS) {
1121
+ if (!files.includes(from) || existsSync7(join9(root, from))) continue;
1122
+ files = [...new Set(files.map((path) => path === from ? to : path))];
1123
+ const hash = fileHashes?.[from];
1124
+ if (fileHashes && hash !== void 0) {
1125
+ const { [from]: _moved, ...rest } = fileHashes;
1126
+ fileHashes = { ...rest, [to]: hash };
1127
+ }
1128
+ }
1129
+ const oldDir = join9(root, "docs/journeys");
1130
+ if (existsSync7(oldDir) && statSync3(oldDir).isDirectory() && readdirSync4(oldDir).length > 0) {
1131
+ warnings.push(
1132
+ "docs/journeys/ is now docs/intents/: run `git mv docs/journeys docs/intents`, then `npx @vaubaan/harness update .` again"
1133
+ );
1134
+ }
1135
+ if (files === previous.files) return previous;
1136
+ return { ...previous, files, ...fileHashes ? { fileHashes } : {} };
1137
+ }
858
1138
  function legacyHookWarnings(root) {
859
1139
  const warnings = [];
860
1140
  for (const path of LEGACY_HOOK_FILES) {
@@ -871,7 +1151,7 @@ function planInstallation(args, settings) {
871
1151
  const root = resolve5(args.targetDir);
872
1152
  const { engines } = settings;
873
1153
  const warnings = [];
874
- const previous = releaseLegacyPaths(settings.previous, warnings);
1154
+ const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
875
1155
  const preserved = [
876
1156
  .../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
877
1157
  ].sort();
@@ -880,14 +1160,14 @@ function planInstallation(args, settings) {
880
1160
  assertManagedPaths(root, [...previous.files, ...preserved]);
881
1161
  const requestedOverrides = args.overridesDir ?? previous.overridesDir;
882
1162
  const overridesDir = args.overridesDir ? resolve5(args.overridesDir) : previous.overridesDir ? resolve5(root, previous.overridesDir) : root;
883
- if (requestedOverrides && !existsSync6(join8(overridesDir, ".harness-overrides"))) {
1163
+ if (requestedOverrides && !existsSync7(join9(overridesDir, ".harness-overrides"))) {
884
1164
  throw new Error(`recorded overrides are missing: ${overridesDir}/.harness-overrides`);
885
1165
  }
886
- const hasOverrides = existsSync6(join8(overridesDir, ".harness-overrides"));
887
- const disablePath = join8(overridesDir, ".harness-overrides", "disable.yaml");
888
- if (existsSync6(disablePath)) {
1166
+ const hasOverrides = existsSync7(join9(overridesDir, ".harness-overrides"));
1167
+ const disablePath = join9(overridesDir, ".harness-overrides", "disable.yaml");
1168
+ if (existsSync7(disablePath)) {
889
1169
  try {
890
- DisableYamlSchema.parse(parseYAML(readFileSync7(disablePath, "utf8")));
1170
+ DisableYamlSchema.parse(parseYAML(readFileSync8(disablePath, "utf8")));
891
1171
  } catch {
892
1172
  throw new Error(`invalid override selection: ${disablePath}`);
893
1173
  }
@@ -917,7 +1197,7 @@ function planInstallation(args, settings) {
917
1197
  ...preserved.length ? { preservedFiles: preserved } : {}
918
1198
  };
919
1199
  const writes = output.filter((file) => currentContent(root, file.path) !== file.content);
920
- const existingRemovals = removals.filter((path) => existsSync6(join8(root, path)));
1200
+ const existingRemovals = removals.filter((path) => existsSync7(join9(root, path)));
921
1201
  if (writes.length || existingRemovals.length || !isDeepStrictEqual(settings.previous, manifest)) {
922
1202
  manifest.renderedAt = (/* @__PURE__ */ new Date()).toISOString();
923
1203
  writes.push({ path: MANIFEST_FILENAME, content: `${JSON.stringify(manifest, null, 2)}
@@ -957,7 +1237,7 @@ function updateCommand(args) {
957
1237
  if (args.dryRun || plan.result.upToDate) return plan.result;
958
1238
  const root = resolve5(args.targetDir);
959
1239
  const { backupDir } = applyUpdateTransaction(root, plan.writes, plan.removals, args.backupDir);
960
- pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname5(join8(root, path)))));
1240
+ pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname5(join9(root, path)))));
961
1241
  return { ...plan.result, backupDir };
962
1242
  }
963
1243
 
@@ -969,7 +1249,7 @@ function writeFilesToTarget(files, targetDir) {
969
1249
  );
970
1250
  const written = [];
971
1251
  for (const f of files) {
972
- const full = join9(targetDir, f.path);
1252
+ const full = join10(targetDir, f.path);
973
1253
  mkdirSync2(dirname6(full), { recursive: true });
974
1254
  writeFileSync3(full, f.content);
975
1255
  written.push(f.path);
@@ -993,7 +1273,7 @@ function initCommand(args) {
993
1273
  { previous, sourceVersion: previous.version, engines }
994
1274
  );
995
1275
  const touchedExisting = [...plan.writes.map((file) => file.path), ...plan.removals].some(
996
- (path) => path !== MANIFEST_FILENAME && existsSync7(join9(root, path))
1276
+ (path) => path !== MANIFEST_FILENAME && existsSync8(join10(root, path))
997
1277
  );
998
1278
  let backupDir;
999
1279
  if (plan.writes.length || plan.removals.length) {
@@ -1002,7 +1282,7 @@ function initCommand(args) {
1002
1282
  rmSync(backupDir, { recursive: true, force: true });
1003
1283
  backupDir = void 0;
1004
1284
  }
1005
- pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname6(join9(root, path)))));
1285
+ pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname6(join10(root, path)))));
1006
1286
  }
1007
1287
  return {
1008
1288
  filesWritten: plan.owned,