@planu/cli 5.3.4 → 5.3.5

package/dist/engine/reconcile/apply-changes.js

@@ -1,19 +1,9 @@
-// engine/reconcile/apply-changes.ts — SPEC-1011 Bug D: Apply approved text changes to spec.md
-// Replacement is section-anchored to prevent silent cross-section mutations:
-// the originalValue is searched only inside the named section's body (between its
-// heading and the next heading at the same or shallower level), and the change is
-// applied only when the match is unique within those bounds.
 import { readFile } from 'node:fs/promises';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
-import { RECONCILE_METADATA_SECTIONS, } from '../../types/index.js';
+import { SECTIONS_WITHOUT_LITERAL_BODY_TEXT, } from '../../types/index.js';
 function escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/**
- * Find the body bounds of a markdown section by heading name.
- * Returns the [start, end) offsets of the section body (after the heading line,
- * up to the next heading at the same or shallower level — or EOF).
- */
 function findSectionBounds(content, section) {
     const headingRe = new RegExp(`^(#{1,6})\\s+${escapeRegex(section)}\\s*$`, 'mi');
     const match = headingRe.exec(content);
@@ -22,16 +12,12 @@ function findSectionBounds(content, section) {
     }
     const headingLevel = match[1]?.length ?? 0;
     const start = match.index + match[0].length;
-    // Find next heading at same-or-shallower level
-    const nextRe = new RegExp(`^#{1,${String(headingLevel)}}\\s+\\S`, 'gm');
-    nextRe.lastIndex = start;
-    const next = nextRe.exec(content);
+    const nextHeadingAtSameOrShallowerLevelRe = new RegExp(`^#{1,${String(headingLevel)}}\\s+\\S`, 'gm');
+    nextHeadingAtSameOrShallowerLevelRe.lastIndex = start;
+    const next = nextHeadingAtSameOrShallowerLevelRe.exec(content);
     return { start, end: next ? next.index : content.length };
 }
-/**
- * Count non-overlapping occurrences of `needle` in `haystack`.
- */
-function countOccurrences(haystack, needle) {
+function countNonOverlappingOccurrences(haystack, needle) {
     if (needle.length === 0) {
         return 0;
     }
@@ -45,20 +31,8 @@ function countOccurrences(haystack, needle) {
     }
     return count;
 }
-/**
- * Apply approved text changes to the spec.md body.
- *
- * For each non-metadata approved change:
- * 1. Locate the named section's body via heading anchor.
- * 2. Require exactly one occurrence of `originalValue` inside that section.
- * 3. Replace it in-place at the resolved absolute offset.
- *
- * Skips (with reason) when the section heading is absent, the value is missing
- * inside the section, or the value appears multiple times (ambiguous match).
- * Writes only when at least one substitution succeeded.
- */
 export async function applyChangesToSpec(specPath, changes) {
-    const approvedTextChanges = changes.filter((c) => c.approved && !RECONCILE_METADATA_SECTIONS.has(c.section));
+    const approvedTextChanges = changes.filter((c) => c.approved && !SECTIONS_WITHOUT_LITERAL_BODY_TEXT.has(c.section));
     if (approvedTextChanges.length === 0) {
         return { applied: 0, skipped: [], fileWritten: false };
     }
@@ -74,6 +48,7 @@ export async function applyChangesToSpec(specPath, changes) {
                 section: c.section,
                 originalValue: c.originalValue,
                 reason: `Cannot read spec.md: ${reason}`,
+                reasonCategory: 'skipped',
             })),
             fileWritten: false,
         };
@@ -88,16 +63,18 @@ export async function applyChangesToSpec(specPath, changes) {
                 section: change.section,
                 originalValue: change.originalValue,
                 reason: `Section heading "${change.section}" not found in spec.md`,
+                reasonCategory: 'skipped',
             });
             continue;
         }
         const sectionBody = modified.slice(bounds.start, bounds.end);
-        const occurrences = countOccurrences(sectionBody, change.originalValue);
+        const occurrences = countNonOverlappingOccurrences(sectionBody, change.originalValue);
         if (occurrences === 0) {
             skipped.push({
                 section: change.section,
                 originalValue: change.originalValue,
                 reason: `originalValue not found in section "${change.section}"`,
+                reasonCategory: 'skipped',
             });
             continue;
         }
@@ -106,6 +83,7 @@ export async function applyChangesToSpec(specPath, changes) {
                 section: change.section,
                 originalValue: change.originalValue,
                 reason: `originalValue is ambiguous (${String(occurrences)} matches in section "${change.section}")`,
+                reasonCategory: 'ambiguous',
             });
             continue;
         }

package/dist/engine/reconcile/verify-write.js

@@ -1,7 +1,7 @@
 // engine/reconcile/verify-write.ts — SPEC-1011 Bug D: Post-write integrity verification
 // After reconcile_spec writes changes, re-reads the file to assert each newValue is present.
 import { readFile } from 'node:fs/promises';
-import { RECONCILE_METADATA_SECTIONS, } from '../../types/index.js';
+import { SECTIONS_WITHOUT_LITERAL_BODY_TEXT, } from '../../types/index.js';
 /**
  * Re-reads the file at `filePath` and checks that each approved change's `newValue`
  * is present somewhere in the file content.
@@ -30,8 +30,7 @@ export async function verifyWriteSucceeded(filePath, changes) {
     }
     const missingChanges = [];
     for (const change of approvedChanges) {
-        // Skip metadata-only sections that do not produce text in spec.md
-        if (RECONCILE_METADATA_SECTIONS.has(change.section)) {
+        if (SECTIONS_WITHOUT_LITERAL_BODY_TEXT.has(change.section)) {
             continue;
         }
         if (!content.includes(change.newValue)) {

package/dist/engine/rules-reconciler.js

@@ -67,7 +67,23 @@ function buildCoverageMap(rulesFiles, allRules) {
  *
  * A file is "stale" when it has NO categories in common with CLAUDE.md categories.
  */
-function detectStaleRules(rulesFiles, allRules, claudeCategories) {
+function manifestOwnedRuleFiles(projectPath) {
+    const raw = readFileSafe(join(projectPath, '.claude', 'rules', '.planu-rules-manifest.json'));
+    if (!raw) {
+        return new Set();
+    }
+    try {
+        const manifest = JSON.parse(raw);
+        return new Set((manifest.rules ?? [])
+            .map((rule) => rule.path)
+            .filter((path) => typeof path === 'string')
+            .map((path) => basename(path)));
+    }
+    catch {
+        return new Set();
+    }
+}
+function detectStaleRules(rulesFiles, allRules, claudeCategories, manifestOwned) {
     // Build per-file category sets
     const fileCategories = new Map();
     for (const r of allRules) {
@@ -80,6 +96,9 @@ function detectStaleRules(rulesFiles, allRules, claudeCategories) {
     }
     const stale = [];
     for (const filePath of rulesFiles) {
+        if (manifestOwned.has(basename(filePath))) {
+            continue;
+        }
         const cats = fileCategories.get(filePath);
         if (!cats || cats.size === 0) {
             // No parseable conventions found — candidate for stale
@@ -162,7 +181,7 @@ export function reconcileRules(projectPath) {
             }
         }
         // 5. Detect stale rules files
-        const staleRules = detectStaleRules(rulesFiles, allRules, claudeCategories);
+        const staleRules = detectStaleRules(rulesFiles, allRules, claudeCategories, manifestOwnedRuleFiles(projectPath));
         // 6. Auto-patch: generate new rules files for uncovered categories
         const updatedRules = [];
         for (const category of newRulesNeeded) {

package/dist/engine/spec-format/acceptance-criteria.js

@@ -5,7 +5,7 @@ import { stripFencedBlocks } from './text-fences.js';
 import { createCriterionIdentity, normalizeCriterionText } from '../criterion-identity.js';
 const BDD_STEP = /^(GIVEN|WHEN|THEN|AND|DADO|CUANDO|ENTONCES|Y)\b/i;
 const BDD_START = /^(GIVEN|DADO)\b/i;
-const TECHNICAL_MARKER = /^(FILES|FUNCTIONS|TEST|OWNER):/i;
+const TECHNICAL_MARKER = /^(FILES|FUNCTIONS|TEST|OWNER|NOTE):/i;
 const EXPLICIT_CRITERION_HEADING = /^#{3,6}\s+((?:AC|AB)\s*-?\s*\d+)\b/i;
 function extractBddBlocks(section) {
     const lines = section.split('\n').map((line) => line.trim());
@@ -38,6 +38,12 @@ function extractBddBlocks(section) {
             current.push(withoutListMarker);
             continue;
         }
+        // Wrapped continuation of the step above: keep it, or the criterion identity
+        // truncates at the physical Markdown wrap boundary (SPEC-1253). A line that
+        // carried its own list marker is a sibling item, never a wrap.
+        if (current.length > 0 && withoutListMarker === line) {
+            current.push(withoutListMarker);
+        }
     }
     if (current.length > 0) {
         bddBlocks.push(current.join(' '));

package/dist/engine/universal-rules/catalog.js

@@ -10,6 +10,9 @@ import { planuApprovalGatesRule } from './rules/planu-approval-gates.js';
 import { planuReleasePolicyRule } from './rules/planu-release-policy.js';
 import { planuSddModelRoutingRule } from './rules/planu-sdd-model-routing.js';
 import { planuMinimalChangeRule } from './rules/planu-minimal-change.js';
+import { planuDebateReviewRule } from './rules/planu-debate-review.js';
+import { planuRevertProofTestsRule } from './rules/planu-revert-proof-tests.js';
+import { planuCleanCodeNoCommentsRule } from './rules/planu-clean-code-no-comments.js';
 /**
  * The full catalog of universal Planu rules.
  * Order matters: rules are installed in catalog order.
@@ -25,5 +28,8 @@ export const UNIVERSAL_RULES = [
     planuModesRule,
     agentTeamsRule,
     planuDogfoodBugsRule,
+    planuDebateReviewRule,
+    planuRevertProofTestsRule,
+    planuCleanCodeNoCommentsRule,
 ];
 //# sourceMappingURL=catalog.js.map

package/dist/engine/universal-rules/rules/agent-teams.js

@@ -1,5 +1,3 @@
-// engine/universal-rules/rules/agent-teams.ts — SPEC-779
-// Universal rule: Agent Teams (migrated from rules-generator.ts)
 function buildBody() {
     return `# Agent Teams (MANDATORY when 3+ specs in parallel)
 

package/dist/engine/universal-rules/rules/planu-approval-gates.js

@@ -1,4 +1,3 @@
-// engine/universal-rules/rules/planu-approval-gates.ts — Universal rule: approval and done gates
 function buildBody() {
     return `# Planu Approval and Done Gates
 

package/dist/engine/universal-rules/rules/planu-bdd-criteria.js

@@ -1,4 +1,3 @@
-// engine/universal-rules/rules/planu-bdd-criteria.ts — Universal rule: BDD acceptance criteria
 function buildBody() {
     return `# Planu BDD Acceptance Criteria
 

package/dist/engine/universal-rules/rules/planu-clean-code-no-comments.d.ts

@@ -0,0 +1,3 @@
+import type { UniversalRule } from '../../../types/universal-rules/index.js';
+export declare const planuCleanCodeNoCommentsRule: UniversalRule;
+//# sourceMappingURL=planu-clean-code-no-comments.d.ts.map

package/dist/engine/universal-rules/rules/planu-clean-code-no-comments.js

@@ -0,0 +1,30 @@
+function buildBody() {
+    return `# Planu Clean Code — No Comments
+
+Auto-generated by \`init_project\`. Do not edit manually.
+
+Code must be self-documenting. A comment is allowed only when the behavior cannot be expressed through naming or structure — for example a non-obvious language semantic. Everything else is a naming problem.
+
+This rule assumes \`planu-dogfood-bugs\` already prohibits deferred-work markers such as TODO/FIXME and does not restate that prohibition.
+
+## The Rule
+
+Prohibited: narrative comments that restate the code, \`(SPEC-NNNN: ...)\` rationale blocks whose history belongs in the spec and in git blame, step-by-step or section-divider comments inside a function, and JSDoc that only repeats the signature.
+
+Replacement action: Extract a helper whose name is the comment, promote a magic value to a named constant, or introduce a named type when a shape needs explaining.
+
+## Enforcement
+
+Implementation agents add narrative comments by default. Stripping them before accepting subagent output is part of reviewing that output, not an optional cleanup pass.
+`;
+}
+export const planuCleanCodeNoCommentsRule = {
+    id: 'planu-clean-code-no-comments',
+    name: 'Planu Clean Code — No Comments',
+    description: 'Prohibits narrative comments and rationale blocks, requiring named helpers or constants instead.',
+    category: 'quality',
+    applicableHosts: ['all'],
+    defaultEnabled: true,
+    buildContent: (_host) => buildBody(),
+};
+//# sourceMappingURL=planu-clean-code-no-comments.js.map

package/dist/engine/universal-rules/rules/planu-debate-review.d.ts

@@ -0,0 +1,3 @@
+import type { UniversalRule } from '../../../types/universal-rules/index.js';
+export declare const planuDebateReviewRule: UniversalRule;
+//# sourceMappingURL=planu-debate-review.d.ts.map

package/dist/engine/universal-rules/rules/planu-debate-review.js

@@ -0,0 +1,38 @@
+function buildBody() {
+    return `# Planu Debate Review
+
+Auto-generated by \`init_project\`. Do not edit manually.
+
+This rule assumes \`planu-approval-gates\` (reviewer independence, self-approval prohibitions) and \`planu-sdd-model-routing\` (arbitration) and restates neither.
+
+## Reviewer Plurality And Provider Diversity
+
+Every spec and every implementation is reviewed by two independent reviewers from DIFFERENT providers, in ONE parallel round.
+
+Prohibited: running a single reviewer, or running two reviewers from the same provider, and calling the result a debate round.
+
+Replacement action: launch both reviewers in the same message so they run concurrently, and pick two different providers (for example one Claude-family model and one external model).
+
+## One Parallel Round, No Serial Confirmation Loops
+
+Prohibited: re-launching a reviewer for pass 2, pass 3, or a "confirm the fix" loop after the first round already produced verdicts.
+
+Replacement action: cross the two verdicts once — coincident findings apply directly, divergent findings are arbitrated against the source code — then close the round. Re-open a reviewer only for a specific disagreement the arbiter cannot resolve by reading the code directly.
+
+## Degradation Ladder
+
+Prohibited: silently reviewing with only one provider when a second is unavailable and presenting it as a debate round.
+
+Replacement action: when only one provider is available, run two isolated sessions of the same model instead of one, so two independent verdicts still exist before arbitration.
+`;
+}
+export const planuDebateReviewRule = {
+    id: 'planu-debate-review',
+    name: 'Planu Debate Review',
+    description: 'Requires two-provider parallel review rounds with no serial confirmation loops and a single-provider degradation ladder.',
+    category: 'quality',
+    applicableHosts: ['all'],
+    defaultEnabled: true,
+    buildContent: (_host) => buildBody(),
+};
+//# sourceMappingURL=planu-debate-review.js.map

package/dist/engine/universal-rules/rules/planu-dogfood-bugs.js

@@ -1,5 +1,3 @@
-// engine/universal-rules/rules/planu-dogfood-bugs.ts — SPEC-779
-// Universal rule: Planu Dogfood Bugs (mandatory for all Planu-using projects)
 /** Shared markdown body (same for all hosts). */
 function buildBody() {
     return `# Planu Dogfood Bugs (MANDATORY — STRICT)

package/dist/engine/universal-rules/rules/planu-english-specs.js

@@ -1,4 +1,3 @@
-// engine/universal-rules/rules/planu-english-specs.ts — Universal rule: specs are written in English
 function buildBody() {
     return `# Planu Artifacts Must Be Written in English
 

package/dist/engine/universal-rules/rules/planu-minimal-change.js

@@ -1,5 +1,3 @@
-// engine/universal-rules/rules/planu-minimal-change.ts
-// Universal rule: minimal-change implementation discipline.
 function buildBody() {
     return `# Planu Minimal Change
 

package/dist/engine/universal-rules/rules/planu-modes.js

@@ -1,5 +1,3 @@
-// engine/universal-rules/rules/planu-modes.ts — SPEC-779
-// Universal rule: Claude Code Mode Hints per spec phase (SPEC-494)
 function buildBody(host) {
     if (host === 'claude-code') {
         return `# Claude Code Mode Hints (MANDATORY — Planu SDD)

package/dist/engine/universal-rules/rules/planu-release-policy.js

@@ -1,4 +1,3 @@
-// engine/universal-rules/rules/planu-release-policy.ts — Universal rule: release decision
 function buildBody() {
     return `# Planu Release Policy
 

package/dist/engine/universal-rules/rules/planu-revert-proof-tests.d.ts

@@ -0,0 +1,3 @@
+import type { UniversalRule } from '../../../types/universal-rules/index.js';
+export declare const planuRevertProofTestsRule: UniversalRule;
+//# sourceMappingURL=planu-revert-proof-tests.d.ts.map

package/dist/engine/universal-rules/rules/planu-revert-proof-tests.js

@@ -0,0 +1,34 @@
+function buildBody() {
+    return `# Planu Revert-Proof Tests
+
+Auto-generated by \`init_project\`. Do not edit manually.
+
+A new test that never fails against the unfixed source proves nothing.
+
+## The Rule
+
+Prohibited: reporting a new test as passing evidence without ever having watched it fail. This includes an assertion that compares a value to itself, a mock that echoes back what it was given, and a negative assertion that holds vacuously regardless of the source under test.
+
+Replacement action: before reporting the test as evidence, revert only the source change it covers — invert the specific guard line in place, or run the test against the pre-change body read with \`git show <ref>:<path>\` — run the test, and observe it fail. Then restore the source and confirm the test passes again. Report the observed failure output, not just the final green run.
+
+Prohibited: using \`git stash\`, \`git checkout\` or \`git restore\` on a shared checkout to stage the revert. Stashes are a process-wide LIFO stack, so a concurrent agent can pop work that is not its own.
+
+A guard's regression test must fail against the unguarded variant specifically, not merely against an unrelated point in history such as HEAD.
+
+## Hard Blocks
+
+- Do not accept a test whose only run is against already-fixed source.
+- Do not accept an assertion that compares a value to itself.
+- Do not accept an assertion that cannot fail for any input.
+`;
+}
+export const planuRevertProofTestsRule = {
+    id: 'planu-revert-proof-tests',
+    name: 'Planu Revert-Proof Tests',
+    description: 'Requires new tests to be proven to fail against the unfixed source before being reported as evidence.',
+    category: 'quality',
+    applicableHosts: ['all'],
+    defaultEnabled: true,
+    buildContent: (_host) => buildBody(),
+};
+//# sourceMappingURL=planu-revert-proof-tests.js.map

package/dist/engine/universal-rules/rules/planu-sdd-model-routing.js

@@ -1,4 +1,3 @@
-// engine/universal-rules/rules/planu-sdd-model-routing.ts — Universal rule: model routing + context continuity
 function buildBody() {
     return `# Planu SDD Model Routing and Context Guarantee
 

package/dist/engine/universal-rules/rules/planu-workflow.js

@@ -1,5 +1,3 @@
-// engine/universal-rules/rules/planu-workflow.ts — SPEC-779
-// Universal rule: Planu Workflow (migrated from rules-generator.ts)
 function buildBody() {
     return `# Planu SDD Workflow (MANDATORY)
 

package/dist/engine/validator/validation-report-writer.js

@@ -39,7 +39,7 @@ export async function writeImplementationReviewReport(input) {
         return {
             written: true,
             path: artifact.path,
-            sha: artifact.sha,
+            sha: `sha256:${artifact.sha}`,
             reviewer,
             passed,
             gates: mergedGates,

package/dist/tools/reconcile-spec.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { ReconcileSpecInput, ToolResult } from '../types/index.js';
+import { type ReconcileSpecInput, type ToolResult } from '../types/index.js';
 export declare function handleReconcileSpec(params: ReconcileSpecInput, server?: McpServer): Promise<ToolResult>;
 //# sourceMappingURL=reconcile-spec.d.ts.map