@planu/cli 4.7.4 → 4.8.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [4.8.0] - 2026-06-24
+
+### Features
+- feat(website): refine Planu landing
+- feat(website): refine Planu landing
+
+
+## [4.7.5] - 2026-06-24
+
+### Features
+- feat: add Planu minimal-change rule and guidance inspired by Ponytail
+
+### Bug Fixes
+- fix: keep generated Planu session artifacts stable after lifecycle close
+
+### Chores
+- chore(deps): refresh push-gate dev dependency knip
+
+
 ## [4.7.4] - 2026-06-23
 
 ### Bug Fixes

package/dist/config/minimal-implementation-gate.json

@@ -31,7 +31,7 @@
       "tag": "stdlib",
       "severity": "warning",
       "confidence": "medium",
-      "patterns": ["custom parser", "manual parser", "hand rolled parser"],
+      "patterns": ["custom parser", "manual parser", "hand rolled parser", "hand-rolled stdlib"],
       "replacementGuidance": "Use an existing parser from the runtime or current dependency set before writing parsing code."
     },
     {
@@ -39,7 +39,7 @@
       "tag": "native",
       "severity": "warning",
       "confidence": "high",
-      "patterns": ["new public mcp tool", "new command", "new cli command"],
+      "patterns": ["new public mcp tool", "new command", "new cli command", "native platform feature"],
       "replacementGuidance": "Prefer existing Planu SDD surfaces unless the spec proves a new public surface is required."
     },
     {
@@ -55,7 +55,7 @@
       "tag": "yagni",
       "severity": "blocker",
       "confidence": "high",
-      "patterns": ["future-proof", "just in case", "might need later", "eventually support"],
+      "patterns": ["future-proof", "just in case", "might need later", "eventually support", "speculative config"],
       "replacementGuidance": "Remove speculative scope unless it is directly required by an acceptance criterion.",
       "blockWhenRiskAtLeast": "medium"
     },
@@ -64,7 +64,15 @@
       "tag": "shrink",
       "severity": "warning",
       "confidence": "medium",
-      "patterns": ["framework", "orchestration layer", "plugin architecture", "abstract factory"],
+      "patterns": [
+        "framework",
+        "orchestration layer",
+        "plugin architecture",
+        "abstract factory",
+        "wrapper that only delegates",
+        "delegate-only wrapper",
+        "shrinkable logic"
+      ],
       "replacementGuidance": "Shrink the design to the smallest correct module/function that satisfies the spec."
     },
     {

package/dist/engine/context-md-generator.js

@@ -1,8 +1,9 @@
 // engine/context-md-generator.ts — SPEC-635: Live ≤800-token context briefing for any LLM
-import { writeFile, mkdir, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore } from '../storage/index.js';
 import { stripFrontmatter } from './frontmatter-parser.js';
+import { stableWriteGeneratedFile, stripSessionMarkdownVolatileFields, } from './generated-artifact-writer.js';
 const MAX_TOKENS = 800;
 const CHARS_PER_TOKEN = 4; // rough estimate
 const MAX_CHARS = MAX_TOKENS * CHARS_PER_TOKEN;
@@ -92,9 +93,9 @@ export async function generateContextMd(projectPath, projectId) {
             }
         }
         const content = truncate(lines.join('\n'), MAX_CHARS);
-        const planuDir = join(projectPath, 'planu');
-        await mkdir(planuDir, { recursive: true });
-        await writeFile(join(planuDir, 'context.md'), content + '\n', 'utf-8');
+        await stableWriteGeneratedFile(join(projectPath, 'planu', 'context.md'), content, {
+            equivalence: stripSessionMarkdownVolatileFields,
+        });
     }
     catch {
         /* best-effort — never blocks status transition */

package/dist/engine/generated-artifact-writer.d.ts

@@ -0,0 +1,7 @@
+import type { StableWriteOptions, StableWriteResult } from '../types/generated-artifacts.js';
+export declare function withFinalNewline(content: string): string;
+export declare function stripSessionMarkdownVolatileFields(content: string): string;
+export declare function stableJsonStringify(value: unknown): string;
+export declare function stripRootUpdatedAt(content: string): string;
+export declare function stableWriteGeneratedFile(filePath: string, content: string, options?: StableWriteOptions): Promise<StableWriteResult>;
+//# sourceMappingURL=generated-artifact-writer.d.ts.map

package/dist/engine/generated-artifact-writer.js

@@ -0,0 +1,63 @@
+// engine/generated-artifact-writer.ts — stable writes for generated Planu artifacts.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export function withFinalNewline(content) {
+    return content.replace(/\s*$/u, '\n');
+}
+export function stripSessionMarkdownVolatileFields(content) {
+    return withFinalNewline(content)
+        .replace(/^# Planu Context — \d{4}-\d{2}-\d{2}$/mu, '# Planu Context — <date>')
+        .replace(/^> Last updated: .+$/mu, '> Last updated: <timestamp>');
+}
+export function stableJsonStringify(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function stripRootUpdatedAt(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const clone = { ...parsed };
+            delete clone.updatedAt;
+            return stableJsonStringify(clone);
+        }
+    }
+    catch {
+        // Fall back to exact normalized text comparison for invalid existing JSON.
+    }
+    return withFinalNewline(content);
+}
+export async function stableWriteGeneratedFile(filePath, content, options = {}) {
+    const next = withFinalNewline(content);
+    let existing;
+    if (options.existingContent !== undefined) {
+        if (options.existingContent === null) {
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, next, 'utf-8');
+            return { written: true, reason: 'missing' };
+        }
+        existing = options.existingContent;
+    }
+    else {
+        try {
+            existing = await readFile(filePath, 'utf-8');
+        }
+        catch {
+            await mkdir(dirname(filePath), { recursive: true });
+            await writeFile(filePath, next, 'utf-8');
+            return { written: true, reason: 'missing' };
+        }
+    }
+    if (existing === next) {
+        return { written: false, reason: 'unchanged' };
+    }
+    const existingHasStableNewline = existing.endsWith('\n') && !existing.endsWith('\n\n');
+    const equivalent = options.equivalence !== undefined &&
+        options.equivalence(existing) === options.equivalence(next);
+    if (equivalent && existingHasStableNewline) {
+        return { written: false, reason: 'unchanged' };
+    }
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, next, 'utf-8');
+    return { written: true, reason: 'changed' };
+}
+//# sourceMappingURL=generated-artifact-writer.js.map

package/dist/engine/implementation-contract/renderer.js

@@ -21,6 +21,9 @@ export function buildImplementationContractSection(input) {
         '### File-Level Work Plan',
         ...renderFilePlan(input.files),
         '',
+        '### Minimal Change Guidance',
+        ...renderMinimalChangeGuidance(),
+        '',
         '### Acceptance-To-Verification Map',
         ...criteria.map((criterion, index) => renderVerificationRow(criterion.text, index + 1, testFiles, verificationCommands)),
         '',
@@ -45,6 +48,13 @@ export function appendImplementationContractIfMissing(specBody, input) {
     }
     return `${specBody.trimEnd()}\n\n${buildImplementationContractSection(input)}`;
 }
+function renderMinimalChangeGuidance() {
+    return [
+        '- Before implementing, check whether the work is unnecessary, already exists in this codebase, is covered by stdlib, is covered by the native platform, or is covered by an already-installed dependency.',
+        '- Add new code only after those checks, and keep the diff to the minimum that satisfies the accepted criteria.',
+        '- Do not use minimality to remove security, trust-boundary validation, data-loss handling, accessibility, explicit requirements, or required validation.',
+    ];
+}
 function fallbackCriteria() {
     return [
         {

package/dist/engine/next-spec-resolver/session-writer.js

@@ -1,7 +1,8 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // engine/next-spec-resolver/session-writer.ts — SPEC-686: Best-effort session.json writer
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stableJsonStringify, stableWriteGeneratedFile, stripRootUpdatedAt, } from '../generated-artifact-writer.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -68,11 +69,11 @@ export async function writeOrchestrationPlan(projectPath, plan) {
 export async function patchSessionJson(projectPath, patch) {
     try {
         const filePath = join(projectPath, 'planu', 'session.json');
-        await mkdir(dirname(filePath), { recursive: true });
+        let existingContent = null;
         let current = { activeSpecs: [], updatedAt: '' };
         try {
-            const raw = await readFile(filePath, 'utf-8');
-            current = JSON.parse(raw);
+            existingContent = await readFile(filePath, 'utf-8');
+            current = JSON.parse(existingContent);
         }
         catch {
             /* start fresh */
@@ -82,7 +83,10 @@ export async function patchSessionJson(projectPath, patch) {
             ...patch,
             updatedAt: new Date().toISOString(),
         };
-        await writeFile(filePath, JSON.stringify(updated, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(filePath, stableJsonStringify(updated), {
+            equivalence: stripRootUpdatedAt,
+            existingContent,
+        });
     }
     catch {
         /* best-effort — never throw */

package/dist/engine/session-context-generator.js

@@ -1,8 +1,9 @@
 // engine/session-context-generator.ts — SPEC-496: Auto-generate portable session-context.md
 // Writes planu/session-context.md so any LLM (Cursor, Windsurf, Aider…) can pick up project state.
-import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore, lessonsStore } from '../storage/index.js';
+import { stableWriteGeneratedFile, stripSessionMarkdownVolatileFields, } from './generated-artifact-writer.js';
 /** Reads the `version` field from the project's package.json, or returns 'unknown'. */
 async function readProjectVersion(projectPath) {
     try {
@@ -128,10 +129,13 @@ export async function generateSessionContext(projectPath, projectId) {
             lessonsContent: buildLessonsSection(lessons),
             generatedAt: new Date().toISOString(),
         });
-        const planuDir = join(projectPath, 'planu');
-        await mkdir(planuDir, { recursive: true });
-        const contextPath = join(planuDir, 'session-context.md');
-        await writeFile(contextPath, content, 'utf-8');
+        const contextPath = join(projectPath, 'planu', 'session-context.md');
+        const writeResult = await stableWriteGeneratedFile(contextPath, content, {
+            equivalence: stripSessionMarkdownVolatileFields,
+        });
+        if (!writeResult.written) {
+            return;
+        }
         if (process.env.PLANU_ENABLE_AUTOCOMMIT !== 'true') {
             return;
         }

package/dist/engine/session-state/writer.js

@@ -1,8 +1,9 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // engine/session-state/writer.ts — SPEC-633: Write session.json universal state file
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
+import { stableJsonStringify, stableWriteGeneratedFile, stripRootUpdatedAt, } from '../generated-artifact-writer.js';
 const STATE_DIR = 'state';
 const ROOT_SESSION = 'session.json';
 function stateDir(projectPath) {
@@ -69,12 +70,15 @@ export async function writeSpecSessionState(projectPath, specId, specTitle, last
             resumePrompt: resumePrompt.slice(0, 300),
             updatedAt: new Date().toISOString(),
         };
-        await writeFile(specFile(projectPath, specId), JSON.stringify(state, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(specFile(projectPath, specId), stableJsonStringify(state), {
+            equivalence: stripRootUpdatedAt,
+        });
         // Update root session.json index
+        let existingIndexContent = null;
         let index = { activeSpecs: [], updatedAt: '' };
         try {
-            const raw = await readFile(rootFile(projectPath), 'utf-8');
-            index = JSON.parse(raw);
+            existingIndexContent = await readFile(rootFile(projectPath), 'utf-8');
+            index = JSON.parse(existingIndexContent);
         }
         catch {
             /* start fresh */
@@ -83,7 +87,10 @@ export async function writeSpecSessionState(projectPath, specId, specTitle, last
             index.activeSpecs.push(specId);
         }
         index.updatedAt = new Date().toISOString();
-        await writeFile(rootFile(projectPath), JSON.stringify(index, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(rootFile(projectPath), stableJsonStringify(index), {
+            equivalence: stripRootUpdatedAt,
+            existingContent: existingIndexContent,
+        });
         // Auto-commit planu/ changes so session.json is never left unstaged
         void (async () => {
             try {
@@ -127,10 +134,11 @@ export async function updateEpicProgressInSession(projectPath, specs) {
             return;
         }
         const filePath = rootFile(projectPath);
+        let existingContent = null;
         let index = { activeSpecs: [], updatedAt: '' };
         try {
-            const raw = await readFile(filePath, 'utf-8');
-            index = JSON.parse(raw);
+            existingContent = await readFile(filePath, 'utf-8');
+            index = JSON.parse(existingContent);
         }
         catch {
             /* start fresh */
@@ -141,7 +149,10 @@ export async function updateEpicProgressInSession(projectPath, specs) {
         index.activeSpecs = index.activeSpecs.filter((specId) => !terminalSpecIds.has(specId));
         index.epicProgress = epicProgress;
         index.updatedAt = new Date().toISOString();
-        await writeFile(filePath, JSON.stringify(index, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(filePath, stableJsonStringify(index), {
+            equivalence: stripRootUpdatedAt,
+            existingContent,
+        });
         // Auto-commit planu/ changes so session.json is never left unstaged
         void (async () => {
             try {
@@ -166,10 +177,11 @@ export async function patchSessionJson(projectPath, patch) {
     try {
         const filePath = rootFile(projectPath);
         await mkdir(stateDir(projectPath), { recursive: true });
+        let existingContent = null;
         let index = { activeSpecs: [], updatedAt: '' };
         try {
-            const raw = await readFile(filePath, 'utf-8');
-            index = JSON.parse(raw);
+            existingContent = await readFile(filePath, 'utf-8');
+            index = JSON.parse(existingContent);
         }
         catch {
             /* start fresh */
@@ -179,7 +191,10 @@ export async function patchSessionJson(projectPath, patch) {
             ...patch,
             updatedAt: new Date().toISOString(),
         };
-        await writeFile(filePath, JSON.stringify(updated, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(filePath, stableJsonStringify(updated), {
+            equivalence: stripRootUpdatedAt,
+            existingContent,
+        });
         // Auto-commit planu/ changes so session.json is never left unstaged
         void (async () => {
             try {
@@ -200,11 +215,15 @@ export async function patchSessionJson(projectPath, patch) {
  */
 export async function removeSpecFromSession(projectPath, specId) {
     try {
-        const raw = await readFile(rootFile(projectPath), 'utf-8');
-        const index = JSON.parse(raw);
+        const filePath = rootFile(projectPath);
+        const existingContent = await readFile(filePath, 'utf-8');
+        const index = JSON.parse(existingContent);
         index.activeSpecs = index.activeSpecs.filter((id) => id !== specId);
         index.updatedAt = new Date().toISOString();
-        await writeFile(rootFile(projectPath), JSON.stringify(index, null, 2), 'utf-8');
+        await stableWriteGeneratedFile(filePath, stableJsonStringify(index), {
+            equivalence: stripRootUpdatedAt,
+            existingContent,
+        });
         // Auto-commit planu/ changes so session.json is never left unstaged
         void (async () => {
             try {

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

@@ -9,6 +9,7 @@ import { planuBddCriteriaRule } from './rules/planu-bdd-criteria.js';
 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';
 /**
  * The full catalog of universal Planu rules.
  * Order matters: rules are installed in catalog order.
@@ -19,6 +20,7 @@ export const UNIVERSAL_RULES = [
     planuBddCriteriaRule,
     planuApprovalGatesRule,
     planuSddModelRoutingRule,
+    planuMinimalChangeRule,
     planuReleasePolicyRule,
     planuModesRule,
     agentTeamsRule,

package/dist/engine/universal-rules/rules/planu-minimal-change.d.ts

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

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

@@ -0,0 +1,44 @@
+// engine/universal-rules/rules/planu-minimal-change.ts
+// Universal rule: minimal-change implementation discipline.
+function buildBody() {
+    return `# Planu Minimal Change
+
+Use the smallest correct change after reading the task and the code path it touches.
+
+Before writing code, stop at the first rung that holds:
+
+1. Does this need to be built at all? If not, do not build it.
+2. Does this codebase already have the helper, utility, convention, or pattern? Reuse it.
+3. Does the standard library already do this? Use it.
+4. Does the native platform already cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one clear line? Use one clear line.
+7. Only then, write the minimum code that satisfies the approved spec.
+
+The ladder runs after understanding, not instead of understanding. Read the relevant files, trace the real flow, and fix shared root causes rather than patching one visible symptom per caller.
+
+Prefer deletion over addition, boring over clever, and fewer touched files over broader refactors. Do not add abstractions, dependencies, configuration, feature flags, compatibility paths, or future-proofing unless the approved spec explicitly requires them.
+
+Minimal does not mean unsafe. Never remove or weaken:
+
+- security checks
+- trust-boundary validation
+- data-loss error handling
+- accessibility
+- explicit user requirements
+- required tests or validation commands
+- SDD approval, evidence, review, or done gates
+
+If a deliberate shortcut has a known ceiling, record the ceiling and upgrade trigger as structured Planu debt evidence instead of leaving a vague comment.
+`;
+}
+export const planuMinimalChangeRule = {
+    id: 'planu-minimal-change',
+    name: 'Planu Minimal Change',
+    description: 'Smallest-correct-change ladder with explicit safety boundaries.',
+    category: 'quality',
+    applicableHosts: ['all'],
+    defaultEnabled: true,
+    buildContent: (_host) => buildBody(),
+};
+//# sourceMappingURL=planu-minimal-change.js.map

package/dist/types/generated-artifacts.d.ts

@@ -0,0 +1,13 @@
+export interface StableWriteResult {
+    written: boolean;
+    reason: 'changed' | 'missing' | 'unchanged';
+}
+export interface StableWriteOptions {
+    /**
+     * Normalize content for semantic comparison. The original content is still
+     * written when formatting differs, but volatile-only differences can be skipped.
+     */
+    equivalence?: (content: string) => string;
+    existingContent?: string | null;
+}
+//# sourceMappingURL=generated-artifacts.d.ts.map

package/dist/types/generated-artifacts.js

@@ -0,0 +1,3 @@
+// types/generated-artifacts.ts — stable generated artifact write contracts.
+export {};
+//# sourceMappingURL=generated-artifacts.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.7.4",
+  "version": "4.8.0",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.7.4",
-    "@planu/core-darwin-x64": "4.7.4",
-    "@planu/core-linux-arm64-gnu": "4.7.4",
-    "@planu/core-linux-arm64-musl": "4.7.4",
-    "@planu/core-linux-x64-gnu": "4.7.4",
-    "@planu/core-linux-x64-musl": "4.7.4",
-    "@planu/core-win32-arm64-msvc": "4.7.4",
-    "@planu/core-win32-x64-msvc": "4.7.4"
+    "@planu/core-darwin-arm64": "4.8.0",
+    "@planu/core-darwin-x64": "4.8.0",
+    "@planu/core-linux-arm64-gnu": "4.8.0",
+    "@planu/core-linux-arm64-musl": "4.8.0",
+    "@planu/core-linux-x64-gnu": "4.8.0",
+    "@planu/core-linux-x64-musl": "4.8.0",
+    "@planu/core-win32-arm64-msvc": "4.8.0",
+    "@planu/core-win32-x64-msvc": "4.8.0"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -194,7 +194,7 @@
     "happy-dom": "^20.10.6",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.4.3",
-    "knip": "^6.18.0",
+    "knip": "^6.20.0",
     "lint-staged": "^17.0.8",
     "madge": "^8.0.0",
     "prettier": "^3.8.4",

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.7.4",
+  "version": "4.8.0",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.7.4",
+  "version": "4.8.0",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",