@vaubaan/harness 2.2.0 → 2.3.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.
@@ -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, journeys, all]
8
+ values: [spec, decisions, handbook, tests, workflow, readme, intents, all]
9
9
  default: all
10
10
  description: Audits the completeness and freshness of the project docs (selectable scope).
11
11
  ---
@@ -0,0 +1,33 @@
1
+ ---
2
+ id: intent
3
+ trigger: /intent
4
+ invokes_skill: intent-writer
5
+ args:
6
+ - name: intent
7
+ type: string
8
+ required: false
9
+ description: Proposes an intent before any code (`/intent <verb + object>`), or maps and extends the intent tree under `docs/intents/`.
10
+ ---
11
+
12
+ # /intent
13
+
14
+ When the human or the agent invokes `/intent [verb + object]`, load the
15
+ skill `intent-writer` with the optional `intent` argument.
16
+
17
+ **With an argument**, `/intent <verb + object>` names the visible change
18
+ of behavior about to be built. The skill places it as a `proposed`
19
+ terminal intent in the level-1 intent it belongs to (or creates the
20
+ file), with 2 to 5 observable acceptance criteria and its `requires:` /
21
+ `creates:` taken from the spec vocabulary. It writes no code and no
22
+ `anchors:`: the pull request that delivers the intent adds them and
23
+ passes it `implemented`. It refuses an entity that no linked spec
24
+ defines and redirects to `/spec` first.
25
+
26
+ **Without an argument**, the skill maps or extends the tree. It reads
27
+ the generated index `docs/intents/README.md`, lists the level-1 intents
28
+ and asks which one to extend or whether to create one. Greenfield: three
29
+ questions, one at a time (actor, intent statement, out of scope).
30
+ Mature: it reads the code's entry points and proposes anchored terminal
31
+ intents, one sub-domain at a time.
32
+
33
+ The skill instantiates the `intent.md.tmpl` template for creations.
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-BzrBb_l4.js';
2
+ import { d as RenderedFile } from './render-CTx7VNOK.js';
3
3
  import './parser/index.js';
4
4
  import 'zod';
5
5
 
6
- declare const VERSION = "2.2.0";
6
+ declare const VERSION = "2.3.1";
7
7
 
8
8
  interface UpdateArgs {
9
9
  targetDir: string;
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  // src/version.ts
2
- var VERSION = "2.2.0";
2
+ var VERSION = "2.3.1";
3
3
 
4
4
  // src/cli/init.ts
5
5
  import { existsSync as existsSync8, mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync3 } from "fs";
@@ -12,9 +12,15 @@ var MANAGED_FILES = /* @__PURE__ */ new Set([
12
12
  "AGENTS.md",
13
13
  "CLAUDE.md",
14
14
  ".harness-manifest.json",
15
- // Index of the optional journeys pillar, rendered while a journey exists.
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).
16
18
  "docs/journeys/README.md"
17
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
+ ]);
18
24
  var RELEASED_PATHS = [
19
25
  ".mcp.json",
20
26
  ".codex/config.toml",
@@ -154,12 +160,16 @@ var CmdArgEnumSchema = z2.object({
154
160
  name: z2.string().min(1),
155
161
  type: z2.literal("enum"),
156
162
  values: z2.array(z2.string()).min(1),
157
- 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()
158
166
  }).strict();
159
167
  var CmdArgStringSchema = z2.object({
160
168
  name: z2.string().min(1),
161
169
  type: z2.literal("string"),
162
- 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()
163
173
  }).strict();
164
174
  var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
165
175
  var CmdFrontmatterSchema = z2.object({
@@ -169,10 +179,10 @@ var CmdFrontmatterSchema = z2.object({
169
179
  args: z2.array(CmdArgSchema).optional(),
170
180
  description: z2.string().min(1)
171
181
  }).strict();
172
- var JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
173
- var JourneyFrontmatterSchema = z2.object({
182
+ var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
183
+ var IntentFrontmatterSchema = z2.object({
174
184
  title: z2.string().min(1),
175
- status: z2.enum(JOURNEY_STATUSES),
185
+ status: z2.enum(INTENT_STATUSES),
176
186
  actors: z2.array(z2.string().min(1)).min(1),
177
187
  spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
178
188
  last_reviewed: z2.union([z2.date(), z2.string().min(1)])
@@ -180,7 +190,7 @@ var JourneyFrontmatterSchema = z2.object({
180
190
  var Schemas = {
181
191
  Skill: SkillFrontmatterSchema,
182
192
  Cmd: CmdFrontmatterSchema,
183
- Journey: JourneyFrontmatterSchema
193
+ Intent: IntentFrontmatterSchema
184
194
  };
185
195
  var ParseError = class extends Error {
186
196
  constructor(file, issues) {
@@ -264,12 +274,12 @@ function loadOverrides(worktreeDir) {
264
274
  return { add: added, disable };
265
275
  }
266
276
 
267
- // src/parser/journey.ts
277
+ // src/parser/intent.ts
268
278
  import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync, statSync as statSync2 } from "fs";
269
279
  import { basename as basename2, join as join4 } from "path";
270
280
  import matter2 from "gray-matter";
271
- var JOURNEYS_DIR = "docs/journeys";
272
- var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
281
+ var INTENTS_DIR = "docs/intents";
282
+ var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
273
283
  var NODE_FIELDS = [
274
284
  "status",
275
285
  "spec",
@@ -323,7 +333,7 @@ function parseFrontmatter(text, errors) {
323
333
  errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
324
334
  return void 0;
325
335
  }
326
- const result = Schemas.Journey.safeParse(data);
336
+ const result = Schemas.Intent.safeParse(data);
327
337
  if (result.success) return result.data;
328
338
  for (const issue of result.error.issues) {
329
339
  const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
@@ -336,7 +346,7 @@ function newNode(title, level, line) {
336
346
  title,
337
347
  level,
338
348
  line,
339
- isLeaf: true,
349
+ isTerminal: true,
340
350
  fieldLines: {},
341
351
  anchors: [],
342
352
  acceptance: [],
@@ -363,12 +373,12 @@ function parseFields(node, lines, from, to, errors) {
363
373
  const known = key;
364
374
  node.fieldLines[known] = lineNo;
365
375
  if (known === "status") {
366
- if (JOURNEY_STATUSES.includes(value)) {
376
+ if (INTENT_STATUSES.includes(value)) {
367
377
  node.status = value;
368
378
  } else {
369
379
  errors.push({
370
380
  line: lineNo,
371
- message: `invalid status \`${value}\` (expected ${JOURNEY_STATUSES.join(" | ")})`
381
+ message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
372
382
  });
373
383
  }
374
384
  } else if (known === "spec") {
@@ -389,7 +399,7 @@ function parseFields(node, lines, from, to, errors) {
389
399
  return;
390
400
  }
391
401
  }
392
- function parseJourney(relPath, text) {
402
+ function parseIntentFile(relPath, text) {
393
403
  const errors = [];
394
404
  const meta = parseFrontmatter(text, errors);
395
405
  const lines = maskFencedCode(text.split(/\r?\n/));
@@ -400,7 +410,7 @@ function parseJourney(relPath, text) {
400
410
  if (h) headings.push({ index: i, ...h });
401
411
  }
402
412
  const h1 = headings.find((h) => h.depth === 1);
403
- let story;
413
+ let statement;
404
414
  if (h1) {
405
415
  const paragraph = [];
406
416
  for (let i = h1.index + 1; i < lines.length; i++) {
@@ -412,7 +422,7 @@ function parseJourney(relPath, text) {
412
422
  if (line === MASKED_LINE || parseHeading(line)) break;
413
423
  paragraph.push(line.trim());
414
424
  }
415
- if (paragraph.length) story = paragraph.join(" ");
425
+ if (paragraph.length) statement = paragraph.join(" ");
416
426
  }
417
427
  const nodes = [];
418
428
  const stack = [];
@@ -428,7 +438,7 @@ function parseJourney(relPath, text) {
428
438
  if (parentIndex !== void 0) {
429
439
  node.parent = parentIndex;
430
440
  const parent = nodes[parentIndex];
431
- if (parent) parent.isLeaf = false;
441
+ if (parent) parent.isTerminal = false;
432
442
  }
433
443
  const next = headings[k + 1];
434
444
  parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
@@ -438,32 +448,32 @@ function parseJourney(relPath, text) {
438
448
  nodes.push(node);
439
449
  }
440
450
  const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
441
- return { ...meta ? { meta } : {}, title, ...story ? { story } : {}, nodes, errors };
451
+ return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
442
452
  }
443
- function listJourneyFiles(targetDir) {
444
- const dir = join4(targetDir, JOURNEYS_DIR);
453
+ function listIntentFiles(targetDir) {
454
+ const dir = join4(targetDir, INTENTS_DIR);
445
455
  if (!existsSync3(dir) || !statSync2(dir).isDirectory()) return [];
446
456
  return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync2(join4(dir, f)).isFile()).sort();
447
457
  }
448
- function readJourneys(targetDir) {
449
- return listJourneyFiles(targetDir).map((file) => {
450
- const path = `${JOURNEYS_DIR}/${file}`;
458
+ function readIntentFiles(targetDir) {
459
+ return listIntentFiles(targetDir).map((file) => {
460
+ const path = `${INTENTS_DIR}/${file}`;
451
461
  const text = readFileSync4(join4(targetDir, path), "utf8");
452
- return { path, file, ...parseJourney(path, text) };
462
+ return { path, file, ...parseIntentFile(path, text) };
453
463
  });
454
464
  }
455
- function loadJourneys(targetDir) {
456
- const journeys = readJourneys(targetDir);
457
- const problems = journeys.flatMap(
465
+ function loadIntentFiles(targetDir) {
466
+ const intentFiles = readIntentFiles(targetDir);
467
+ const problems = intentFiles.flatMap(
458
468
  (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
459
469
  );
460
470
  if (problems.length) {
461
471
  throw new Error(
462
- `invalid journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
472
+ `invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
463
473
  ${problems.join("\n")}`
464
474
  );
465
475
  }
466
- return journeys;
476
+ return intentFiles;
467
477
  }
468
478
 
469
479
  // src/renderers/common.ts
@@ -513,12 +523,13 @@ function frontmatterDataForCmd(cmd) {
513
523
  description: cmd.meta.description
514
524
  };
515
525
  if (cmd.meta.args && cmd.meta.args.length > 0) {
516
- data.args = cmd.meta.args.map((a) => {
517
- if (a.type === "enum") {
518
- 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 };
519
- }
520
- return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
521
- });
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
+ }));
522
533
  }
523
534
  return data;
524
535
  }
@@ -551,16 +562,16 @@ function buildUmbrellaBody(extras) {
551
562
  ...extras.hasQualityDoc ? [
552
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."
553
564
  ] : [],
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."
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."
556
567
  ] : [],
557
568
  "",
558
569
  "## Doc-first",
559
570
  "",
560
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.",
561
572
  "",
562
- ...extras.hasJourneys ? [
563
- "- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
573
+ ...extras.hasIntents ? [
574
+ "- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
564
575
  ] : [],
565
576
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
566
577
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
@@ -690,16 +701,16 @@ function getRenderer(engine) {
690
701
  return RENDERERS[engine];
691
702
  }
692
703
 
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) {
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) {
703
714
  lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
704
715
  }
705
716
  }
@@ -777,14 +788,14 @@ function render(input) {
777
788
  availableCommands: Array.from(exposedCmds.values()),
778
789
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
779
790
  hasQualityDoc: input.hasQualityDoc === true,
780
- hasJourneys: (input.journeys?.length ?? 0) > 0
791
+ hasIntents: (input.intentFiles?.length ?? 0) > 0
781
792
  });
782
793
  files.push({ path: "AGENTS.md", content: umbrellaContent });
783
794
  if (engines.includes("claude-code")) {
784
795
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
785
796
  }
786
- if (input.journeys && input.journeys.length > 0) {
787
- files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
797
+ if (input.intentFiles && input.intentFiles.length > 0) {
798
+ files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
788
799
  }
789
800
  return { files, warnings };
790
801
  }
@@ -817,8 +828,8 @@ function planInit(args) {
817
828
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
818
829
  const projectSkills = loadProjectSkills(args.targetDir);
819
830
  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 });
831
+ const intentFiles = loadIntentFiles(args.targetDir);
832
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
822
833
  return { engines, output };
823
834
  }
824
835
 
@@ -1027,7 +1038,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
1027
1038
  }
1028
1039
 
1029
1040
  // src/cli/update.ts
1030
- import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
1041
+ import { existsSync as existsSync7, readFileSync as readFileSync8, readdirSync as readdirSync4, statSync as statSync3 } from "fs";
1031
1042
  import { dirname as dirname5, join as join9, resolve as resolve5 } from "path";
1032
1043
  import { isDeepStrictEqual } from "util";
1033
1044
 
@@ -1103,6 +1114,27 @@ function releaseLegacyPaths(previous, warnings) {
1103
1114
  if (released.length === 0) return previous;
1104
1115
  return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
1105
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
+ }
1106
1138
  function legacyHookWarnings(root) {
1107
1139
  const warnings = [];
1108
1140
  for (const path of LEGACY_HOOK_FILES) {
@@ -1119,7 +1151,7 @@ function planInstallation(args, settings) {
1119
1151
  const root = resolve5(args.targetDir);
1120
1152
  const { engines } = settings;
1121
1153
  const warnings = [];
1122
- const previous = releaseLegacyPaths(settings.previous, warnings);
1154
+ const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
1123
1155
  const preserved = [
1124
1156
  .../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
1125
1157
  ].sort();