@planu/cli 5.3.69 → 5.4.1

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [5.4.1] - 2026-08-29
+
+### Bug Fixes
+- fix(SPEC-1675): strip FILES/FUNCTIONS/TEST metadata markers from contradiction analysis
+- fix(SPEC-1676): rebuild expired project knowledge graph and re-stamp cached reuse
+
+
+## [5.4.0] - 2026-08-29
+
+### Features
+- feat(SPEC-1672): install phase skills with managed-by ownership marker on init hosts
+
+### Chores
+- chore(deps): upgrade stryker to v10 majors
+- chore(deps): update 13 patch/minor dependencies and adapt readFile mock casts
+
+
 ## [5.3.69] - 2026-08-29
 
 ### Features

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"3cfd6dac20d6444035162379c6284620d6d8961a"}
+{"schemaVersion":1,"commit":"c920f236390f64d91a02ca3e0566e59210f00a49"}

package/dist/config/skill-templates/planu-dogfood-bug.md

@@ -0,0 +1,43 @@
+---
+name: planu-dogfood-bug
+description: File a bug spec the moment a Planu tool is observed behaving wrong, silent, or stale while using Planu — never deferred to a backlog or a code TODO.
+triggers:
+  - planu bug
+  - this tool is wrong
+  - unexpected planu output
+  - planu returned stale data
+  - dogfood bug
+version: 1.0.0
+managed-by: planu
+---
+
+# /planu-dogfood-bug — File a Dogfood Bug Immediately
+
+## When to invoke
+
+Use this skill the moment a Planu MCP tool returns wrong, stale, silent, or irrelevant output while it is being used for its own SDD lifecycle. Invoke it in the same turn the bug is observed — never later.
+
+**Trigger phrases**: "this tool is wrong", "unexpected Planu output", "Planu returned stale data", "dogfood bug"
+
+## How it works
+
+The normative tool-call sequence for this phase:
+
+1. **Create the spec now** — call `create_spec` in the same turn the bug is observed, with:
+   - **Reproducer** — exact tool call, exact response observed, exact expected response
+   - **Root cause hypothesis** — pointer to file path and line number in `src/` where the bug likely lives
+   - BDD acceptance criteria carrying `FILES:`, `FUNCTIONS:`, and `TEST:` markers per scenario
+   - Files to create/modify with exact paths
+   - Implementation order scoped for a cheap implementer
+2. **Move to review** — call `update_status(review)` so the bug enters the normal spec lifecycle, then continue the original task
+
+## Anti-patterns
+
+- **Never defer to a backlog** — "I'll note this for later" is not acceptable; file the spec in the same turn
+- **Never leave a code TODO** — code TODOs rot; the tracked spec is the only durable record of the bug
+- Treating a bug as "too small for a spec" — every dogfood bug becomes a spec, regardless of size
+- Filing multiple observed bugs sequentially instead of in parallel `create_spec` calls in one message
+
+## Ownership
+
+This skill is managed by Planu (`managed-by: planu` in its frontmatter). Removing that marker forks the skill from Planu's updates — future `init_project` runs will treat it as user-owned and stop refreshing it.

package/dist/config/skill-templates/planu-implement.md

@@ -0,0 +1,42 @@
+---
+name: planu-implement
+description: Implement an approved Planu spec — packages the handoff contract, moves the spec to implementing, and works in an isolated worktree with revert-proof tests and no narrative comments.
+triggers:
+  - implement the spec
+  - start implementing
+  - build this spec
+  - begin implementation
+  - implement this feature
+version: 1.0.0
+managed-by: planu
+---
+
+# /planu-implement — Implement an Approved Spec
+
+## When to invoke
+
+Use this skill once a spec is `approved` and implementation is about to begin.
+
+**Trigger phrases**: "implement the spec", "start implementing", "build this spec", "begin implementation"
+
+## How it works
+
+The normative tool-call sequence for this phase:
+
+1. **Package the handoff** — call `package_handoff` to build the operating contract for the implementer: objective, BDD acceptance criteria, files to modify/create, ownership, test plan, risks, out-of-scope, current state, next action. Persist it outside chat history
+2. **Move to implementing** — call `update_status(implementing)` only after the handoff package exists
+3. **Isolate the work** — implement inside an isolated git worktree created from the current base branch, never on the shared checkout
+4. **Write revert-proof tests** — for every guard or fix, write the test first, revert the source change and watch the test fail, then restore the source and confirm it passes. Report the observed failure output, not just the final green run
+5. **No narrative comments** — code is self-documenting; no step-by-step comments, no `(SPEC-NNNN: ...)` rationale blocks, no TODO/FIXME markers
+6. **Validate** — call `validate` when implementation is complete and inspect the completed job's `structuredContent`, not the initial acknowledgement
+
+## Anti-patterns
+
+- Implementing directly on the shared checkout instead of an isolated worktree
+- Reporting a new test as passing evidence without ever having watched it fail against the unfixed source
+- Leaving narrative comments, TODO markers, or deferred-work notes in the code
+- Treating the initial `validate` acknowledgement as a pass — only a `completed` job's result is authoritative
+
+## Ownership
+
+This skill is managed by Planu (`managed-by: planu` in its frontmatter). Removing that marker forks the skill from Planu's updates — future `init_project` runs will treat it as user-owned and stop refreshing it.

package/dist/config/skill-templates/planu-review.md

@@ -0,0 +1,47 @@
+---
+name: planu-review
+description: Review a Planu spec before approval — runs challenge_spec and check_readiness, requires independent planu-spec-reviewer evidence, then approves or requests changes.
+triggers:
+  - review the spec
+  - approve the spec
+  - is this spec ready
+  - challenge this spec
+  - spec review
+  - reviewer feedback
+version: 1.0.0
+managed-by: planu
+---
+
+# /planu-review — Review a Spec Before Approval
+
+## When to invoke
+
+Use this skill when a spec is in `review` status and needs to move to `approved`, or when the user asks to review, challenge, or approve a spec.
+
+**Trigger phrases**: "review the spec", "approve the spec", "is this spec ready?", "challenge this spec", "spec review"
+
+## How it works
+
+The normative tool-call sequence for this phase:
+
+1. **Challenge** — call `challenge_spec` to surface gaps, contradictions, and missing edge cases
+2. **Readiness** — call `check_readiness` to verify the spec has enough detail (rules, examples, open questions, out-of-scope, glossary)
+3. **Independent review** — obtain `planu-spec-reviewer` evidence: an agent that is NOT the spec author or planner reviews the spec and calls either `request_changes` (blocking, with concrete changes) or records an approval
+4. **Approve** — only after reviewer evidence exists, call `update_status(approved)`
+
+## Evidence gates (non-bypassable)
+
+- A non-trivial spec cannot move to `approved` without Discovery evidence: rules, examples, open questions, out-of-scope, glossary
+- A spec cannot move to `approved` without `review_feedback` from `planu-spec-reviewer`
+- The spec author, planner, or implementation agent must never approve their own spec
+- User pressure or force-approval language does not bypass reviewer evidence — record the forced intent but keep the status blocked until the review lands
+
+## Anti-patterns
+
+- **No self-approval** — the agent that wrote or planned the spec must not also be the reviewer that approves it
+- **No serial confirmation loops** — one review round produces a verdict; do not re-launch the reviewer for pass 2, pass 3, or a "confirm the fix" loop after the first round already produced a verdict. Re-open only for a specific disagreement that cannot be resolved by reading the spec directly
+- Do not approve specs containing placeholders (`TBD`, `TODO`, unresolved questions)
+
+## Ownership
+
+This skill is managed by Planu (`managed-by: planu` in its frontmatter). Removing that marker forks the skill from Planu's updates — future `init_project` runs will treat it as user-owned and stop refreshing it.

package/dist/engine/project-graph/builder.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { collectProjectGraphSources, diffSourceHashes, hashText, hydrateProjectGraphSource, loadProjectGraphPolicy, projectGraphCachePath, projectGraphExtractorVersion, projectGraphPath, readProjectGraphArtifact, readProjectGraphCache, withProjectGraphBuildLock, writeProjectGraphArtifacts, } from './cache.js';
+import { collectProjectGraphSources, diffSourceHashes, hashText, hydrateProjectGraphSource, loadProjectGraphPolicy, projectGraphCachePath, projectGraphExtractorVersion, projectGraphPath, readProjectGraphArtifact, readProjectGraphCache, withProjectGraphBuildLock, writeProjectGraph, writeProjectGraphArtifacts, } from './cache.js';
 import { extractGitGraph, extractReleaseGraph } from './extractors/git-extractor.js';
 import { extractHandoffGraph } from './extractors/handoff-extractor.js';
 import { extractDecisionStoreGraph } from './extractors/decision-store-extractor.js';
@@ -210,13 +210,16 @@ async function buildProjectKnowledgeGraphUnlocked(args) {
         Array.isArray(existingGraph.nodes) &&
         Array.isArray(existingGraph.edges);
     if (hasConsistentExistingGraph && diff.changed.length === 0 && diff.removed.length === 0) {
+        const refreshedGeneratedAt = new Date().toISOString();
         const graphWithCurrentOversizedSources = {
             ...existingGraph,
+            generatedAt: refreshedGeneratedAt,
             oversizedSources,
         };
+        await writeProjectGraph(args.projectId, args.policy, graphWithCurrentOversizedSources);
         publishFreshProjectGraphProjection({
             projectId: args.projectId,
-            generatedAt: existingGraph.generatedAt,
+            generatedAt: refreshedGeneratedAt,
             generation: existingGraph.generation,
         });
         return {

package/dist/engine/project-graph/query.js

@@ -55,7 +55,8 @@ async function ensureFreshProjectGraph(args) {
     const freshness = await getProjectGraphFreshness(args);
     if (!freshness.exists ||
         freshness.reason === 'source_changed' ||
-        freshness.reason === 'corrupt') {
+        freshness.reason === 'corrupt' ||
+        freshness.reason === 'expired') {
         await buildProjectKnowledgeGraph(args);
         return getProjectGraphFreshness(args);
     }

package/dist/engine/scope-boundaries/contradiction-checker.js

@@ -203,14 +203,35 @@ function assertsActionNearScope(clause, outOfScopeItem) {
     }
     return false;
 }
+const METADATA_MARKER_KEYWORD = /\b(?:FILES?|FUNCTIONS?|TESTS?)\s*:/gi;
+const SENTENCE_BOUNDARY_AFTER_MARKER = /\.\s+(?=[A-Z])/;
+function stripMetadataMarkers(text) {
+    const markers = [...text.matchAll(METADATA_MARKER_KEYWORD)];
+    if (markers.length === 0) {
+        return text;
+    }
+    let result = '';
+    let cursor = 0;
+    for (let i = 0; i < markers.length; i++) {
+        const start = markers[i]?.index ?? 0;
+        result += text.slice(cursor, start);
+        const nextMarkerStart = markers[i + 1]?.index ?? text.length;
+        const searchRegion = text.slice(start, nextMarkerStart);
+        const boundaryMatch = SENTENCE_BOUNDARY_AFTER_MARKER.exec(searchRegion);
+        cursor = boundaryMatch ? start + boundaryMatch.index + 1 : nextMarkerStart;
+    }
+    result += text.slice(cursor);
+    return result.replace(/\s+/g, ' ').trim();
+}
 /**
  * Determine whether a criterion text contradicts an out-of-scope item.
  * Uses substring match first, then keyword overlap as fuzzy fallback.
  */
 function contradicts(criterionText, outOfScopeItem) {
-    const normCriterion = normalize(criterionText);
+    const strippedCriterionText = stripMetadataMarkers(criterionText);
+    const normCriterion = normalize(strippedCriterionText);
     const normScope = normalize(outOfScopeItem);
-    const clauses = splitClauses(criterionText);
+    const clauses = splitClauses(strippedCriterionText);
     const relevantClauses = clauses.filter((clause) => clauseMentionsScope(clause, outOfScopeItem));
     const hasConditionalException = /\b(?:unless|except)\b/i.test(criterionText);
     if (!hasConditionalException &&

package/dist/tools/create-skill.js

@@ -26,14 +26,14 @@ function resolveHost(input) {
 // ---------------------------------------------------------------------------
 // Writers per host
 // ---------------------------------------------------------------------------
-async function writeSkillForClaudeCode(name, content, description, projectPath, overwrite) {
+async function writeSkillForClaudeCode(name, content, description, projectPath, overwrite, managedByPlanu) {
     const dirPath = join(projectPath, '.claude', 'skills', name);
     const skillFilePath = join(dirPath, 'SKILL.md');
     // Overwrite protection
     try {
         const existing = await readFile(skillFilePath, 'utf-8');
         const existingHash = hashContent(existing);
-        const newContent = buildSkillMd(name, description, content);
+        const newContent = buildSkillMd(name, description, content, managedByPlanu);
         const newHash = hashContent(newContent);
         if (existingHash !== newHash && !overwrite) {
             throw new Error(`Skill already exists at ${skillFilePath}. Pass overwriteExisting: true to replace.`);
@@ -46,13 +46,14 @@ async function writeSkillForClaudeCode(name, content, description, projectPath,
         // File doesn't exist — proceed
     }
     await mkdir(dirPath, { recursive: true });
-    const skillContent = buildSkillMd(name, description, content);
+    const skillContent = buildSkillMd(name, description, content, managedByPlanu);
     await writeFile(skillFilePath, skillContent, 'utf-8');
     return { dirPath, skillFilePath };
 }
-function buildSkillMd(name, description, body) {
+function buildSkillMd(name, description, body, managedByPlanu) {
     const desc = description.length > 0 ? description : `Auto-generated skill: ${name}`;
-    return `---\nname: ${name}\ndescription: "${desc}"\n---\n\n${body}\n`;
+    const managedByLine = managedByPlanu ? 'managed-by: planu\n' : '';
+    return `---\nname: ${name}\ndescription: "${desc}"\n${managedByLine}---\n\n${body}\n`;
 }
 async function writeSkillForCodex(name, content, description, projectPath) {
     // For Codex, append to AGENTS.md with markers
@@ -80,13 +81,13 @@ async function writeSkillForCodex(name, content, description, projectPath) {
     await writeFile(agentsMdPath, updated, 'utf-8');
     return { dirPath: projectPath, skillFilePath: agentsMdPath };
 }
-async function writeSkillForGemini(name, content, description, projectPath) {
+async function writeSkillForGemini(name, content, description, projectPath, managedByPlanu) {
     const geminiDir = join(projectPath, '.gemini');
     const skillsDir = join(geminiDir, 'skills');
     await mkdir(skillsDir, { recursive: true });
     const skillFilePath = join(skillsDir, `${name}.md`);
     const desc = description.length > 0 ? description : name;
-    const skillContent = buildSkillMd(name, desc, content);
+    const skillContent = buildSkillMd(name, desc, content, managedByPlanu);
     await writeFile(skillFilePath, skillContent, 'utf-8');
     return { dirPath: skillsDir, skillFilePath };
 }
@@ -96,6 +97,7 @@ async function writeSkillForGemini(name, content, description, projectPath) {
 export async function handleCreateSkill(input) {
     const { projectPath, name, content, overwriteExisting } = input;
     const description = input.description ?? '';
+    const managedByPlanu = input.managedByPlanu === true;
     const host = resolveHost(input);
     const languageValidation = validateEnglishOnlyArtifactText(`${name}\n\n${description}\n\n${content}`, 'skill');
     if (!languageValidation.ok) {
@@ -121,13 +123,13 @@ export async function handleCreateSkill(input) {
     try {
         switch (host) {
             case 'claude-code':
-                result = await writeSkillForClaudeCode(name, content, description, projectPath, overwriteExisting === true);
+                result = await writeSkillForClaudeCode(name, content, description, projectPath, overwriteExisting === true, managedByPlanu);
                 break;
             case 'codex':
                 result = await writeSkillForCodex(name, content, description, projectPath);
                 break;
             case 'gemini':
-                result = await writeSkillForGemini(name, content, description, projectPath);
+                result = await writeSkillForGemini(name, content, description, projectPath, managedByPlanu);
                 break;
         }
     }

package/dist/tools/init-project/host-assets-writer.js

@@ -12,6 +12,9 @@ const CORE_SKILL_TEMPLATES = [
     'planu-native.md',
     'planu-multi-teammate-review.md',
     'planu-context-assets.md',
+    'planu-review.md',
+    'planu-implement.md',
+    'planu-dogfood-bug.md',
 ];
 function addHost(hosts, host) {
     if (!hosts.includes(host)) {
@@ -107,6 +110,9 @@ async function canRefreshCoreSkill(projectPath, host, name) {
             return (existing.includes(`<!-- planu:skills:${name} -->`) ||
                 !existing.includes(`## Skill: ${name}`));
         }
+        if (existing.includes('managed-by: planu')) {
+            return true;
+        }
         return existing.includes(`name: ${name}`) && existing.includes(`# /${name}`);
     }
     catch {
@@ -130,6 +136,7 @@ async function installCoreSkillsForHost(projectPath, host) {
             description: template.description,
             content: template.content,
             overwriteExisting: true,
+            managedByPlanu: true,
         });
         if (result.isError === true) {
             continue;

package/dist/types/universal-rules/index.d.ts

@@ -73,6 +73,7 @@ export interface CreateSkillInput {
     host: HostId | 'auto';
     overwriteExisting?: boolean;
     description?: string;
+    managedByPlanu?: boolean;
 }
 /** Result of the create_skill MCP tool handler. */
 export interface CreateSkillResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.69",
+  "version": "5.4.1",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",
@@ -129,7 +129,7 @@
   ],
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.120.0",
+    "@anthropic-ai/sdk": "^0.122.0",
     "@hono/node-server": "2.1.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "glob": "^13.0.6",
@@ -142,40 +142,40 @@
     "@commitlint/config-conventional": "^21.2.2",
     "@eslint/js": "^10.0.1",
     "@lhci/cli": "0.15.1",
-    "@noble/hashes": "2.3.0",
+    "@noble/hashes": "2.4.0",
     "@playwright/test": "1.62.1",
     "@scure/base": "2.3.0",
-    "@secretlint/secretlint-rule-no-homedir": "^13.0.4",
-    "@secretlint/secretlint-rule-preset-recommend": "^13.0.4",
-    "@stryker-mutator/core": "^9.6.1",
-    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@secretlint/secretlint-rule-no-homedir": "^13.0.5",
+    "@secretlint/secretlint-rule-preset-recommend": "^13.0.5",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@supabase/supabase-js": "^2.112.4",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "@types/qrcode": "1.5.6",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vitest/coverage-v8": "^4.1.11",
-    "@vue/test-utils": "^2.4.11",
-    "eslint": "10.9.0",
+    "@vue/test-utils": "^2.5.0",
+    "eslint": "10.9.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "happy-dom": "^20.11.6",
+    "happy-dom": "^20.11.12",
     "husky": "^9.1.7",
     "javascript-obfuscator": "^5.6.0",
     "jiti": "2.7.0",
-    "knip": "^6.32.2",
-    "lint-staged": "^17.3.0",
+    "knip": "^6.32.3",
+    "lint-staged": "^17.4.1",
     "madge": "^8.0.0",
     "prettier": "^3.9.6",
     "qrcode": "1.5.4",
-    "secretlint": "^13.0.4",
+    "secretlint": "^13.0.5",
     "tsc-alias": "^1.9.2",
     "type-coverage": "^2.30.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "^8.67.0",
+    "typescript-eslint": "^8.68.0",
     "vite": "^8.2.2",
     "vitest": "^4.1.11",
-    "vue": "^3.5.41"
+    "vue": "^3.5.42"
   }
 }

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": "5.3.69",
+  "version": "5.4.1",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",