roadmapsmith 0.9.30 → 0.9.31

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.30",
+  "version": "0.9.31",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.30",
+  "version": "0.9.31",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "author": {
     "name": "PapiScholz"

package/bin/cli.js

@@ -21,7 +21,7 @@ function printHelp() {
     'Usage:',
     '  Canonical commands:',
     '  roadmapsmith zero [--project-root <path>] [--config <path>]',
-    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen]',
+    '  roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--full-regen] [--refresh-annotations]',
     '  roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]',
     '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json] [--strict]',
     '  roadmapsmith update [--task <stable-id> --evidence <text>] [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]',
@@ -30,7 +30,7 @@ function printHelp() {
     '  Advanced commands:',
     '  roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]',
     '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit] [--full-regen]',
-    '  roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]',
+    '  roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit] [--refresh-annotations]',
     '  roadmapsmith /roadmap',
     '  roadmapsmith /roadmap <action>',
     '  roadmapsmith /roadmap-zero | /roadmap-maintain | /roadmap-status | /roadmap-validate | /roadmap-update | /roadmap-setup | /roadmap-init | /roadmap-generate | /roadmap-audit',
@@ -226,7 +226,8 @@ function runSyncCommand(projectRoot, config, flags, options = {}) {
   const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
   const results = validateTasks(syncTasks, validationContext, config, validationContext.plugins);
   applyMinimumConfidence(results, config.validation?.minimumConfidence);
-  const next = applySync(content, syncTasks, results);
+  const forceRefresh = isEnabled(flags['refresh-annotations']);
+  const next = applySync(content, syncTasks, results, { forceRefresh });
   const dryRun = isEnabled(flags['dry-run']);
   const writeResult = writeText(roadmapFile, next, { dryRun });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.30",
+  "version": "0.9.31",
   "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "main": "src/index.js",
   "bin": {

package/skills/roadmap-maintain/SKILL.md

@@ -17,3 +17,4 @@ Use this command when the repository already has code, tests, docs, or an existi
 4. Mention that maintain runs preserve-first generate, sync, and audit in one invocation.
 5. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.
 6. Mention that `roadmapsmith maintain --full-regen` or `roadmapsmith generate --full-regen` is the explicit destructive rebuild path when the user truly wants a full managed-block replacement.
+7. When the user wants stale or outdated warning annotations to be recomputed from scratch (including annotations that were written by a prior maintain run or an external agent), use `roadmapsmith maintain --refresh-annotations`. This forces all existing warning text to be replaced with the current deterministic result rather than preserved. It is distinct from `--full-regen` (which rebuilds the managed block structure) — `--refresh-annotations` only affects warning annotations on still-failing tasks.

package/skills.json

@@ -28,67 +28,67 @@
       "name": "roadmap",
       "path": "skills/roadmap",
       "description": "Native slash palette for RoadmapSmith commands and recommended entrypoints across supported hosts.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
       "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
       "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-generate",
       "path": "skills/roadmap-generate",
       "description": "Native slash entrypoint for managed roadmap updates that require --full-regen before destructive replacement.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
       "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
       "description": "Native slash entrypoint for the advanced sync-plus-audit mutating summary workflow.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.30"
+      "version": "0.9.31"
     }
   ]
 }

package/src/reasons.js

@@ -0,0 +1,28 @@
+'use strict';
+
+// Low-specificity reason strings produced by the deterministic validator for
+// policy-level failures. These messages carry no file- or symbol-specific
+// information and should not overwrite more informative existing annotations
+// that a prior run or a human/agent authored.
+const LOW_SPECIFICITY_REASONS = new Set([
+  'validation failed',
+  'implementation task requires deterministic Verify metadata or explicit Evidence to be marked complete',
+  'implementation task requires Evidence line or high-confidence evidence (code + test) to be marked complete',
+]);
+
+/**
+ * Returns true when `reason` is a low-specificity policy message — one that carries
+ * no file- or symbol-specific diagnostic value and should not be used to overwrite
+ * a more informative existing annotation.
+ *
+ * Input should be a normalized reason string (⚠️ prefix and warning prefixes already
+ * stripped, as produced by normalizeWarningReason in src/sync/index.js).
+ *
+ * @param {string} reason
+ * @returns {boolean}
+ */
+function isLowSpecificityReason(reason) {
+  return LOW_SPECIFICITY_REASONS.has(String(reason || '').trim());
+}
+
+module.exports = { LOW_SPECIFICITY_REASONS, isLowSpecificityReason };

package/src/sync/index.js

@@ -2,6 +2,7 @@
 
 const { parseRoadmap } = require('../parser');
 const { ensureTrailingNewline } = require('../utils');
+const { isLowSpecificityReason } = require('../reasons');
 
 const ATTEMPTED_WARNING_REASON_PREFIX = 'attempted but validation failed:';
 const NO_EVIDENCE_WARNING_REASON_PREFIX = 'no implementation evidence found yet:';
@@ -106,10 +107,14 @@ function normalizeWarningReasons(reasons) {
   return normalized;
 }
 
-function shouldPreserveExistingWarning(existingReason, newReason) {
+function shouldPreserveExistingWarning(existingReason, newReason, options) {
+  if (options && options.forceRefresh) return false;
   const cleanExisting = normalizeWarningReason(existingReason);
   const cleanNew = normalizeWarningReason(newReason) || 'validation failed';
-  return cleanNew === 'validation failed' && cleanExisting && cleanExisting !== cleanNew;
+  // Preserve when the freshly computed reason is a low-specificity policy message (no
+  // file- or symbol-specific information) and the existing annotation carries more
+  // diagnostic value (is not itself a low-specificity message).
+  return isLowSpecificityReason(cleanNew) && Boolean(cleanExisting) && !isLowSpecificityReason(cleanExisting);
 }
 
 function formatVerificationRecipe(indent, recipe) {
@@ -129,7 +134,7 @@ function findVerificationRecipeIndex(lines, taskLineIndex) {
   return null;
 }
 
-function applySync(content, parsedTasks, results) {
+function applySync(content, parsedTasks, results, options) {
   const parsed = parseRoadmap(content);
   const lines = [...parsed.lines];
   const tasks = parsedTasks || parsed.tasks;
@@ -187,7 +192,7 @@ function applySync(content, parsedTasks, results) {
     } else if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
       const existingReason = normalizeWarningReason(lines[warningIndex]);
       const newReason = reason || 'validation failed';
-      if (!shouldPreserveExistingWarning(existingReason, newReason)) {
+      if (!shouldPreserveExistingWarning(existingReason, newReason, options)) {
         lines[warningIndex] = warningText;
       }
     } else {