claudeos-core 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [2.0.2] — 2026-04-20
+
+### Fixed
+
+- **Upgrade-path silent-skip regression for pre-v2.0.0 projects** — `npx claudeos-core health` permanently reported `content-validator: fail` with 9 × MISSING guide errors on projects that had been initialized on a pre-v2.0.0 release and then upgraded. Pass 3 wrote `pass3-complete.json` before the Pass 3 output-completeness guards (H1/H2) existed, so the marker was valid-looking on disk even though `claudeos-core/guide/` (and sometimes `standard/00.core/01.project-overview.md`, `skills/`, or `plan/`) had never been populated. On subsequent runs, `init.js` observed the marker + an existing CLAUDE.md, skipped Pass 3, and never regenerated the missing outputs — leaving the project in a stuck-fail state that only `--force` (which wipes `.claude/rules/` and loses manual edits) could recover. The Pass 3 stale-marker branch in `bin/commands/init.js` previously only detected externally-deleted CLAUDE.md; it now also drops the marker when any entry in `lib/expected-guides.js` is missing/BOM-aware-empty or when `findMissingOutputs()` (`lib/expected-outputs.js`) flags a missing standard sentinel / `skills/` / `plan/`. Mirrors the existing `dropStalePass4Marker` pattern (symmetric helper `dropStalePass3Marker` added) and reuses the same "unlink failure surfaces as `InitError` with Windows AV/file-lock guidance" contract so the recovery itself can't silently regress. Recovery is one-shot: next `init` re-runs Pass 3, which populates the missing outputs and writes a fresh marker gated by the v2.0.0 H1/H2 guards.
+
+### Added
+
+- **`tests/pass3-marker.test.js`** — Six new cases covering the stale-detection branches: (a) missing guide dir → drop, (b) single BOM-only guide file → drop, (c) guides present but `skills/` gone → drop, (d) guides present but standard sentinel missing → drop, (e) complete state preserves marker, (f) `init.js` source-parity tripwire asserting `dropStalePass3Marker` + both `EXPECTED_GUIDE_FILES` and `findMissingOutputs` references appear in the stale-check region (guards against refactors silently regressing to v2.0.1 behavior).
+
 ## [2.0.1] — 2026-04-19
 
 ### Fixed

package/bin/commands/init.js

@@ -461,16 +461,28 @@ async function cmdInit(parsedArgs) {
     }
   }
 
-  // Stale marker detection: if marker exists but CLAUDE.md was deleted externally,
-  // treat marker as stale and re-run (user clearly wants regeneration).
+  // Stale marker detection (Pass 3). Drops the marker and re-runs Pass 3 if
+  // any of the following is true:
+  //   (a) CLAUDE.md was deleted externally (original check),
+  //   (b) any of EXPECTED_GUIDE_FILES is missing or BOM-aware empty,
+  //   (c) any entry in expected-outputs (standard sentinel / skills / plan) is
+  //       missing or empty.
   //
-  // Unlink is surfaced as InitError on failure (symmetric with Pass 4
-  // dropStalePass4Marker). Silently ignoring the error would leave the stale
-  // marker in place, and the `if (fileExists(pass3Marker))` check below would
-  // accept it — skipping Pass 3 while CLAUDE.md is still missing. That
-  // silent-skip is the exact bug class this audit round closes.
-  if (fileExists(pass3Marker) && !fileExists(claudeMdPath)) {
-    log("    ⚠️  pass3-complete.json exists but CLAUDE.md is missing — treating marker as stale, re-running Pass 3");
+  // (b) and (c) were previously only enforced as Pass 3 post-generation Guards
+  // 3 (H2/H1), which gate marker *creation* on fresh runs. Projects that were
+  // initialized on a pre-v2.0.0 release (before those guards existed) can end
+  // up with a marker on disk even though guide/ or standard/skills/plan are
+  // empty. Without this stale check, such projects hit a permanent
+  // content-validator fail loop because init sees the marker and skips Pass 3
+  // forever. This mirrors the Pass 4 dropStalePass4Marker pattern below.
+  //
+  // Unlink is surfaced as InitError on failure (symmetric with Pass 4).
+  // Silently ignoring the error would leave the stale marker in place, and
+  // the `if (fileExists(pass3Marker))` check below would accept it — skipping
+  // Pass 3 while outputs are still incomplete. That silent-skip is the exact
+  // bug class this audit round closes.
+  function dropStalePass3Marker(reasonLog) {
+    log(reasonLog);
     try { fs.unlinkSync(pass3Marker); } catch (e) {
       log(`    ❌ Failed to delete stale pass3-complete.json: ${e.code || e.message}`);
       throw new InitError(
@@ -480,6 +492,32 @@ async function cmdInit(parsedArgs) {
       );
     }
   }
+  if (fileExists(pass3Marker)) {
+    if (!fileExists(claudeMdPath)) {
+      dropStalePass3Marker("    ⚠️  pass3-complete.json exists but CLAUDE.md is missing — treating marker as stale, re-running Pass 3");
+    } else {
+      const guideDirForStale = path.join(PROJECT_ROOT, "claudeos-core/guide");
+      const staleMissingGuides = EXPECTED_GUIDE_FILES.filter(g => {
+        const fp = path.join(guideDirForStale, g);
+        if (!fileExists(fp)) return true;
+        try {
+          return fs.readFileSync(fp, "utf-8").replace(/^\uFEFF/, "").trim().length === 0;
+        } catch (_e) { return true; }
+      });
+      if (staleMissingGuides.length > 0) {
+        dropStalePass3Marker(
+          `    ⚠️  pass3-complete.json exists but ${staleMissingGuides.length}/${EXPECTED_GUIDE_FILES.length} guide files are missing or empty — treating marker as stale, re-running Pass 3`
+        );
+      } else {
+        const staleMissingOutputs = findMissingOutputs(PROJECT_ROOT);
+        if (staleMissingOutputs.length > 0) {
+          dropStalePass3Marker(
+            `    ⚠️  pass3-complete.json exists but ${staleMissingOutputs.length} required output(s) are missing or empty — treating marker as stale, re-running Pass 3`
+          );
+        }
+      }
+    }
+  }
 
   if (fileExists(pass3Marker)) {
     log("    ⏭️  pass3-complete.json already exists, skipping");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeos-core",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Auto-generate Claude Code documentation from your actual source code — Standards, Rules, Skills, and Guides tailored to your project",
   "main": "bin/cli.js",
   "bin": {