@infinitedusky/indusk-mcp 1.24.5 → 1.25.1

package/dist/lib/trajectory/validator.d.ts

@@ -14,6 +14,15 @@ export interface ValidateTrajectoryOptions {
      * check at apps/indusk-mcp/hooks/validate-impl-structure.js.
      */
     rationaleRequired?: boolean;
+    /**
+     * The phase number that counts as "writable today against the current stack."
+     * Trajectory rows whose `Writable at` is ≤ baseline are exempt from the
+     * rationale-completeness rule. Defaults to 0 (the original behavior:
+     * Phase 0 rows are exempt). Plans where Phase 1 IS the enabling work
+     * (refactors, schema migrations, scaffolding) set this to 1 so rows
+     * authored at Phase 1 don't require justification entries.
+     */
+    rationaleBaseline?: number;
 }
 /**
  * Rule 1: Every impl document must have a `## Test Trajectory` section.
@@ -39,23 +48,27 @@ export declare function validateTemporalCoherence(trajectory: Trajectory): Valid
 export declare function validateDeferredCompleteness(trajectory: Trajectory): ValidationError[];
 /**
  * Rule 5: When the impl frontmatter sets `rationale: required`, every
- * trajectory row whose `Writable at` is later than Phase 0 (the pre-plan
- * baseline) must have an entry in the `### Trajectory Rationale` subsection.
+ * trajectory row whose `Writable at` is later than the configured baseline
+ * (default Phase 0) must have an entry in the `### Trajectory Rationale`
+ * subsection.
  *
- * Phase 0 rows do NOT need a rationale — Phase 0 means "writable today
- * against the current stack, before any plan implementation," which is
- * the default and needs no justification. We only require rationale when
- * a test will be authored after some plan code lands (Writable at: Phase 1+).
+ * The baseline names the phase that counts as "writable today against the
+ * current stack" for this plan. Default 0 — Phase 0 rows are exempt because
+ * they're writable before any plan code lands. Plans where Phase 1 IS the
+ * enabling work (refactors, schema migrations, scaffolding) can declare
+ * `rationale_baseline: 1` in frontmatter so Phase 1 rows are exempt too.
  *
- * If no row needs a rationale (every row is Phase 0), the subsection itself
- * is optional. If any row is Phase 1+, the subsection must exist and contain
- * an entry for every Phase 1+ row. Stale entries (entries for IDs not in the
- * trajectory) are always flagged.
+ * If no row needs a rationale (every row is ≤ baseline), the subsection
+ * itself is optional. If any row is later than baseline, the subsection
+ * must exist and contain an entry for every such row. Stale entries
+ * (entries for IDs not in the trajectory) are always flagged.
  *
  * Mirrors `validateRationaleCompleteness` in
  * `.claude/hooks/validate-impl-structure.js`.
  */
-export declare function validateRationaleCompleteness(body: string, trajectory: Trajectory): ValidationError[];
+export declare function validateRationaleCompleteness(body: string, trajectory: Trajectory, options?: {
+    baseline?: number;
+}): ValidationError[];
 /**
  * Run all trajectory validation rules against an impl body. The body is the
  * markdown content after the frontmatter — pass the output of `gray-matter`

package/dist/lib/trajectory/validator.js

@@ -185,31 +185,34 @@ export function validateDeferredCompleteness(trajectory) {
 }
 /**
  * Rule 5: When the impl frontmatter sets `rationale: required`, every
- * trajectory row whose `Writable at` is later than Phase 0 (the pre-plan
- * baseline) must have an entry in the `### Trajectory Rationale` subsection.
+ * trajectory row whose `Writable at` is later than the configured baseline
+ * (default Phase 0) must have an entry in the `### Trajectory Rationale`
+ * subsection.
  *
- * Phase 0 rows do NOT need a rationale — Phase 0 means "writable today
- * against the current stack, before any plan implementation," which is
- * the default and needs no justification. We only require rationale when
- * a test will be authored after some plan code lands (Writable at: Phase 1+).
+ * The baseline names the phase that counts as "writable today against the
+ * current stack" for this plan. Default 0 — Phase 0 rows are exempt because
+ * they're writable before any plan code lands. Plans where Phase 1 IS the
+ * enabling work (refactors, schema migrations, scaffolding) can declare
+ * `rationale_baseline: 1` in frontmatter so Phase 1 rows are exempt too.
  *
- * If no row needs a rationale (every row is Phase 0), the subsection itself
- * is optional. If any row is Phase 1+, the subsection must exist and contain
- * an entry for every Phase 1+ row. Stale entries (entries for IDs not in the
- * trajectory) are always flagged.
+ * If no row needs a rationale (every row is ≤ baseline), the subsection
+ * itself is optional. If any row is later than baseline, the subsection
+ * must exist and contain an entry for every such row. Stale entries
+ * (entries for IDs not in the trajectory) are always flagged.
  *
  * Mirrors `validateRationaleCompleteness` in
  * `.claude/hooks/validate-impl-structure.js`.
  */
-export function validateRationaleCompleteness(body, trajectory) {
+export function validateRationaleCompleteness(body, trajectory, options = {}) {
     const errors = [];
-    const rowsNeedingRationale = trajectory.rows.filter((r) => Number.isFinite(r.writableAt) && r.writableAt > 0);
+    const baseline = Number.isFinite(options.baseline) ? Number(options.baseline) : 0;
+    const rowsNeedingRationale = trajectory.rows.filter((r) => Number.isFinite(r.writableAt) && r.writableAt > baseline);
     const hasSubsection = /^###\s+Trajectory Rationale\b/m.test(body);
     const rationaleIds = hasSubsection ? parseRationaleBlock(body) : new Set();
     if (rowsNeedingRationale.length > 0 && !hasSubsection) {
         errors.push({
             rule: "rationale-completeness",
-            message: `\`rationale: required\` is set and ${rowsNeedingRationale.length} trajectory row(s) have \`Writable at\` later than Phase 0, but the impl is missing the \`### Trajectory Rationale\` subsection. Phase 0 rows don't need rationale; rows where authoring waits on plan code do — add an entry for ${rowsNeedingRationale.map((r) => r.id).join(", ")}.`,
+            message: `\`rationale: required\` is set and ${rowsNeedingRationale.length} trajectory row(s) have \`Writable at\` later than Phase ${baseline}, but the impl is missing the \`### Trajectory Rationale\` subsection. Rows at or below the baseline don't need rationale; rows where authoring waits on later plan code do — add an entry for ${rowsNeedingRationale.map((r) => r.id).join(", ")}.`,
         });
         // Even without the subsection, fall through to also check for stale entries
         // (there are none in this case, but the structure is symmetric).
@@ -222,7 +225,7 @@ export function validateRationaleCompleteness(body, trajectory) {
     if (missing.length > 0 && hasSubsection) {
         errors.push({
             rule: "rationale-completeness",
-            message: `Trajectory rows with \`Writable at\` later than Phase 0 missing from \`### Trajectory Rationale\`: ${missing.join(", ")}. Every row whose authoring waits on plan code needs a \`- **TN** \`Writable at: Phase N\` — {reason}\` entry. Phase 0 rows (writable today against the current stack) do not need rationale.`,
+            message: `Trajectory rows with \`Writable at\` later than Phase ${baseline} missing from \`### Trajectory Rationale\`: ${missing.join(", ")}. Every row whose authoring waits on later plan code needs a \`- **TN** \`Writable at: Phase N\` — {reason}\` entry. Rows at or below the baseline (Phase ${baseline}) do not need rationale.`,
         });
     }
     const knownIds = new Set(trajectory.rows.map((r) => r.id));
@@ -278,7 +281,9 @@ export function validateTrajectory(body, options = {}) {
         ...validateDeferredCompleteness(trajectory),
     ];
     if (options.rationaleRequired) {
-        errors.push(...validateRationaleCompleteness(body, trajectory));
+        errors.push(...validateRationaleCompleteness(body, trajectory, {
+            baseline: options.rationaleBaseline,
+        }));
     }
     return errors;
 }

package/hooks/validate-impl-structure.js

@@ -312,9 +312,19 @@ const trajectoryRequiredFrontmatter = /trajectory:\s*required/.test(frontmatter)
 const hasTrajectoryHeading = /^##\s+Test Trajectory\b/m.test(body);
 const trajectoryValidationEnabled = trajectoryRequiredFrontmatter || hasTrajectoryHeading;
 const rationaleRequiredFrontmatter = /rationale:\s*required/.test(frontmatter);
+// Anchor to start-of-line within frontmatter (m flag) so the key is only matched
+// when it appears as a top-level YAML key — NOT when its name appears as a
+// substring inside a quoted value (e.g., a `title:` mentioning the key).
+// Surfaced by /falsify hypothesis 1: a documentation plan whose title contained
+// the literal `rationale_baseline: 1` silently inherited that baseline from the
+// title's substring. See .indusk/planning/rationale-baseline-frontmatter/falsification.md.
+const rationaleBaselineMatch = frontmatter.match(/^rationale_baseline:\s*(\d+)/m);
+const rationaleBaseline = rationaleBaselineMatch
+	? Number.parseInt(rationaleBaselineMatch[1], 10)
+	: 0;
 
 if (trajectoryValidationEnabled) {
-	const trajectoryErrors = validateTrajectory(body, rationaleRequiredFrontmatter);
+	const trajectoryErrors = validateTrajectory(body, rationaleRequiredFrontmatter, rationaleBaseline);
 	if (trajectoryErrors.length > 0) {
 		process.stderr.write(
 			`Test Trajectory validation failed (policy: ${gatePolicy}):\n${trajectoryErrors.map((e) => `  [${e.rule}] ${e.message}`).join("\n")}\n\nSee .indusk/planning/tests-first-planning/adr.md Sections 3-6 for the Test Trajectory shape and validator rules.\n`,
@@ -347,7 +357,7 @@ process.exit(0);
 // apps/indusk-mcp/src/lib/trajectory/validator.ts and parser.ts)
 // ------------------------------------------------------------------
 
-function validateTrajectory(implBody, rationaleRequired) {
+function validateTrajectory(implBody, rationaleRequired, rationaleBaseline = 0) {
 	const errors = [];
 
 	// Rule 1: trajectory presence
@@ -365,7 +375,7 @@ function validateTrajectory(implBody, rationaleRequired) {
 	errors.push(...validateTemporalCoherence(trajectory));
 	errors.push(...validateDeferredCompleteness(trajectory));
 	if (rationaleRequired) {
-		errors.push(...validateRationaleCompleteness(implBody, trajectory));
+		errors.push(...validateRationaleCompleteness(implBody, trajectory, rationaleBaseline));
 	}
 	return errors;
 }
@@ -646,11 +656,12 @@ function validateDeferredCompleteness(trajectory) {
 // Read the entries together: shared weak excuses signal over-sequencing.
 // ------------------------------------------------------------------
 
-function validateRationaleCompleteness(implBody, trajectory) {
+function validateRationaleCompleteness(implBody, trajectory, baseline = 0) {
 	const errors = [];
+	const baselineNum = Number.isFinite(baseline) ? Number(baseline) : 0;
 
 	const rowsNeedingRationale = trajectory.rows.filter(
-		(r) => Number.isFinite(r.writableAt) && r.writableAt > 0,
+		(r) => Number.isFinite(r.writableAt) && r.writableAt > baselineNum,
 	);
 	const hasSubsection = /^###\s+Trajectory Rationale\b/m.test(implBody);
 	const rationaleIds = hasSubsection ? parseRationaleBlock(implBody) : new Set();
@@ -658,7 +669,7 @@ function validateRationaleCompleteness(implBody, trajectory) {
 	if (rowsNeedingRationale.length > 0 && !hasSubsection) {
 		errors.push({
 			rule: "rationale-completeness",
-			message: `\`rationale: required\` is set and ${rowsNeedingRationale.length} trajectory row(s) have \`Writable at\` later than Phase 0, but the impl is missing the \`### Trajectory Rationale\` subsection. Phase 0 rows don't need rationale; rows where authoring waits on plan code do — add an entry for ${rowsNeedingRationale.map((r) => r.id).join(", ")}.`,
+			message: `\`rationale: required\` is set and ${rowsNeedingRationale.length} trajectory row(s) have \`Writable at\` later than Phase ${baselineNum}, but the impl is missing the \`### Trajectory Rationale\` subsection. Rows at or below the baseline don't need rationale; rows where authoring waits on later plan code do — add an entry for ${rowsNeedingRationale.map((r) => r.id).join(", ")}.`,
 		});
 	}
 
@@ -670,7 +681,7 @@ function validateRationaleCompleteness(implBody, trajectory) {
 	if (missing.length > 0 && hasSubsection) {
 		errors.push({
 			rule: "rationale-completeness",
-			message: `Trajectory rows with \`Writable at\` later than Phase 0 missing from \`### Trajectory Rationale\`: ${missing.join(", ")}. Every row whose authoring waits on plan code needs a \`- **TN** \`Writable at: Phase N\` — {reason}\` entry. Phase 0 rows (writable today against the current stack) do not need rationale.`,
+			message: `Trajectory rows with \`Writable at\` later than Phase ${baselineNum} missing from \`### Trajectory Rationale\`: ${missing.join(", ")}. Every row whose authoring waits on later plan code needs a \`- **TN** \`Writable at: Phase N\` — {reason}\` entry. Rows at or below the baseline (Phase ${baselineNum}) do not need rationale.`,
 		});
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.24.5",
+	"version": "1.25.1",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [