claudeos-core 2.4.2 → 2.4.4

package/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 Quick navigation to recent releases:
 
+- [`2.4.4`](#244--2026-05-04) — Translation polish for `docs/{lang}/` × 8 non-Korean languages + broken `#quick-start` anchor fix
+- [`2.4.3`](#243--2026-04-27) — Skills catalog reconciliation (MANIFEST ↔ §6 sync) + `STALE_PATH` naming-convention placeholder exemption
 - [`2.4.2`](#242--2026-04-26) — README structural tightening + 9-language re-sync (same-day after v2.4.1 docs overhaul)
 - [`2.4.1`](#241--2026-04-26) — Documentation overhaul, 10-language localization, fixture sanitization (post-release docs)
 - [`2.4.0`](#240--2026-04-25) — Session Continuity Protocol (v2.4 series feature 1 of 3)
@@ -24,6 +26,32 @@ For older entries scroll past v1.5.0 or use the GitHub blame view.
 
 ---
 
+## [2.4.4] — 2026-05-04
+
+Documentation-only release. Translation polish across 8 non-Korean language `docs/{lang}/` directories. Test suite remains 736 / 736 pass.
+
+- **`docs/{zh-CN,ja,es,vi,hi,ru,fr,de}/` × 12 files each polished** — translation naturalness polish (calque elimination, em-dash reduction, passive → active, pronoun-overuse reduction, noun-verb redundancy, native dev-blog tone). Four rounds applied per language: initial polish → deep audit → final polish → file-by-file verification. Line counts within ±2 per file; code blocks, CLI commands, anchor links, version strings all byte-identical.
+- **Broken `#quick-start` anchor fixed in 5 languages** — `docs/{ja,zh-CN,vi,hi,ru}/{architecture,commands}.md` linked to `README.{lang}.md#quick-start`, but those READMEs use localized headings (`クイックスタート` / `快速开始` / `Bắt đầu nhanh` / `त्वरित शुरुआत` / `Быстрый старт`). 15 anchor instances corrected to native GitHub slugs.
+- **English source minor fixes** — `docs/verification.md` malformed `content-validator` table (header had 2 columns, data rows merged Check ID into description) and Section 5 heading (`Disk ↔ Master Plan` → `Disk ↔ sync-map.json`, reflecting the v2.1.0 master-plan removal).
+- **Version** — `package.json`, `package-lock.json` (top-level + `packages.""`), `CLAUDE.md`, and 10 `docs/{lang,en}/manual-installation.md` files bumped to `2.4.4`.
+
+---
+
+## [2.4.3] — 2026-04-27
+
+Skills catalog reconciliation. Closes a structural gap where Pass 3c-core registers per-domain orchestrators (`{category}/02.domains.md`) and their sub-skills (`{category}/domains/{name}.md`) inconsistently — leading to `MANIFEST_DRIFT` advisories. No template, scanner, prompt, or pass-pipeline behavior change. Test suite remains 736 / 736 pass.
+
+- **NEW `manifest-generator/skills-sync.js`** — deterministic post-Pass-3 sync step (~270 lines, pure CommonJS, no new deps). Three pure functions wired into `manifest-generator/index.js` `main()` between `sync-map.json` write and `stale-report.json` initialization:
+  - `discoverPerDomainCatalogs` — walks `claudeos-core/skills/{category}/domains/`, sorts alphabetically.
+  - `patchManifestPerDomainSections` — ensures `MANIFEST.md` contains a canonical `### Per-domain notes` section per category. Idempotent: section current → no write; line stale → replace only the domain-list paragraph (sibling content preserved); section missing → append fresh.
+  - `patchClaudeMdSkillsSection` — ensures each MANIFEST-registered category-root orchestrator is mentioned in §6 Skills sub-section. Sub-skills excluded by design (the v2.3.0 `MANIFEST_DRIFT` exemption handles transitive coverage). §6 detection is multilingual via heading-number matching (`## 6.` plus first `### *Skills*` sub-heading).
+- **Design invariants** — deterministic (no LLM); idempotent (3 consecutive runs produce MD5-identical files); append-only with respect to user edits; failure-isolated (errors logged; `manifest-generator`'s primary outputs unaffected); domain ordering alphabetical (OS-independent reproducibility).
+- **`STALE_PATH` naming-convention placeholder exemption** — `content-validator`'s `hasPlaceholder` predicate (introduced v2.3.0, extended v2.4.0 with `/.../` ellipsis) gains a fourth placeholder family: naming-convention tokens (`camelCase`, `PascalCase`, `kebab-case`, `snake_case`). LLMs writing naming-convention docs routinely cite `src/.../camelCase.tsx` as a template — the convention name IS the lesson, not a path claim. Word-boundary anchored (`\b...\b`), so embedded substrings like `myCamelCaseUtil.ts` are NOT skipped.
+- **Migration** — purely additive. First run after upgrade: existing projects with an LLM-ordered domain list see ONE alphabetic-reordering write; subsequent runs no-op. Projects without `domains/` are unaffected. Projects emitting the naming-convention false positive will see those `STALE_PATH` entries disappear on the next `health` run.
+- **Files changed** — `manifest-generator/skills-sync.js` (NEW), `manifest-generator/index.js` (+2 lines: import + try/catch wrapper), `content-validator/index.js` (one regex line in `hasPlaceholder`), `package.json` / `package-lock.json` (`2.4.2` → `2.4.3`).
+
+---
+
 ## [2.4.2] — 2026-04-26
 
 Same-day documentation patch on top of v2.4.1. **No source code, scanner, template, or validator change.** Test suite remains 736 / 736 pass.

package/README.hi.md

@@ -336,7 +336,7 @@ Pipeline **तीन stages** में चलती है, और LLM call क
 **2. Step B — 4-Pass Claude pipeline (Step A के facts के दायरे में)।**
 - **Pass 1** हर domain group के representative files पढ़ता है और प्रति domain करीब 50–100 conventions निकालता है — response wrappers, logging libraries, error handling, naming conventions, test patterns वगैरह। यह domain group पर एक बार चलता है (`max 4 domains, 40 files per group`), इसलिए context कभी overflow नहीं होता।
 - **Pass 2** सारे per-domain analysis को project-wide picture में merge कर देता है, और जहाँ disagreement हो वहाँ dominant convention चुन लेता है।
-- **Pass 3** `CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, skills और guides लिखता है। यह stages में split होता है (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide), जिससे `pass2-merged.json` बड़ा होने पर भी हर stage का prompt LLM के context window में आ जाता है। 16 या उससे ज्यादा domains वाले projects के लिए 3b/3c को ≤15-domain batches में sub-divide कर दिया जाता है।
+- **Pass 3** `CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, skills और guides लिखता है। यह stages में split होता है (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide), जिससे `pass2-merged.json` बड़ा होने पर भी हर stage का prompt LLM के context window में आ जाता है। 16 या उससे ज़्यादा domains वाले projects के लिए 3b/3c को ≤15-domain batches में sub-divide कर दिया जाता है।
 - **Pass 4** L4 memory layer को seed करता है (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) और कुछ universal scaffold rules जोड़ता है। Pass 4 को **`CLAUDE.md` modify करने की इजाज़त नहीं है** — Pass 3 का Section 8 ही authoritative है।
 
 **3. Step C — Verification (deterministic, कोई LLM नहीं)।** पाँच validators output check करते हैं:

package/README.ja.md

@@ -148,7 +148,7 @@ an XML-driven MyBatis persistence layer and JWT-based authentication.
 | Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
 ```
 
-上の表の値はすべて、正確な dependency の座標も、`dev.db` というファイル名も、`V1__create_tables.sql` というマイグレーション名も、「no JPA」という事実も、Claude がファイルを書く前にスキャナが `build.gradle`、`application.properties`、ソースツリーから直接読み取った内容です。推測した値は 1 つも入っていません。
+上の表の値はすべて、正確な dependency の座標も、`dev.db` というファイル名も、`V1__create_tables.sql` というマイグレーション名も、「no JPA」という注記も、Claude がファイルを書く前にスキャナが `build.gradle`、`application.properties`、ソースツリーから直接読み取った内容です。推測した値は 1 つも入っていません。
 
 </details>
 

package/README.ko.md

@@ -329,7 +329,7 @@ ClaudeOS-Core는 일반적인 Claude Code 워크플로를 거꾸로 뒤집습니
 이 도구: 코드가 스택을 분석   → 확정된 사실을 Claude에게 전달 → Claude가 그 사실만으로 문서 작성
 ```
 
-파이프라인은 **3 단계**로 동작합니다. LLM 호출 앞뒤 모두에 코드가 자리잡고 있습니다:
+파이프라인은 **3단계**로 동작합니다. LLM 호출 앞뒤 모두에 코드가 자리잡고 있습니다:
 
 **1. Step A — Scanner (일관된 동작, LLM 없음).** Node.js scanner가 프로젝트 루트를 순회하면서 `package.json`, `build.gradle`, `pom.xml`, `pyproject.toml`을 읽고, `.env*` 파일을 파싱합니다 (`PASSWORD/SECRET/TOKEN/JWT_SECRET/...` 같은 민감 변수는 자동으로 가립니다). 그런 다음 아키텍처 패턴을 분류하고 (Java 5개 패턴 A/B/C/D/E, Kotlin CQRS / 멀티모듈, Next.js App vs Pages Router, FSD, components 패턴), 도메인을 찾고, 존재하는 모든 소스 파일 경로의 명시적 allowlist를 만듭니다. 결과는 `project-analysis.json` 한 파일에 모이고, 이후 모든 단계는 이걸 단일 source of truth로 삼습니다.
 

package/bin/commands/init.js

@@ -344,8 +344,8 @@ async function runPass3Split(ctx) {
     //
     // Per-domain type lookup uses `domainTypeMap` from
     // `project-analysis.json`. Domains not in either set fall back to
-    // `backend` (the dominant case in real-world projects) — this
-    // happens only when the analysis JSON is malformed or absent.
+    // `backend` (the dominant project type) — this happens only when
+    // the analysis JSON is malformed or absent.
     const typeOf = (name) => {
       if (domainTypeMap.frontend.has(name)) return "frontend";
       // backend is the default when the domain is unknown to both sets.
@@ -486,7 +486,7 @@ async function runPass3Split(ctx) {
   // was removed because master plans are an internal tool backup not consumed
   // by Claude Code at runtime, and aggregating 30+ files in a single session
   // was the primary source of "Prompt is too long" failures on mid-sized
-  // projects (observed on an 18-domain production run).
+  // projects (observed on 18-domain-class projects).
   //
   // The subStage parameter is kept for forward-compat: if a future version
   // reintroduces master plans via Node-side aggregation, this helper can

package/content-validator/index.js

@@ -463,11 +463,28 @@ async function main() {
   // refuse it on most platforms — `.` and `..` are the only legal
   // dot-only directory names). Three consecutive dots in a path segment
   // are unambiguous placeholder signal.
+  //
+  // v2.4.3 — Naming-convention placeholders (`camelCase`, `PascalCase`,
+  // `kebab-case`, `snake_case`) added as placeholder markers.
+  //
+  // LLMs writing naming-convention docs frequently illustrate file naming
+  // rules using the convention name itself as the example filename, e.g.
+  // `src/admin/pages/mgmt/camelCase.tsx` (e.g. `userMgt.tsx`). The reader
+  // is expected to substitute their actual filename — the `camelCase` token
+  // is the lesson, not a path claim. The same pattern shows up for
+  // `PascalCase.tsx` (component naming), `kebab-case.tsx` (sometimes used
+  // for slugs), and `snake_case.py`/`.rb` (less common in TS but seen in
+  // multi-language standards docs). All four are unambiguous placeholders
+  // when used as a filename stem — no real production file would carry
+  // these literal names. Word-boundary anchored to avoid matching real
+  // identifiers that happen to contain these substrings (e.g. a real
+  // `myCamelCaseUtil.ts` should NOT be skipped — only standalone tokens).
   const hasPlaceholder = (p) =>
     /\{[^}]+\}/.test(p) ||       // {domain} style
     /X{3,}/.test(p) || /Xxx/.test(p) ||  // XXX+ anywhere, or Xxx token
     /\*/.test(p) ||              // glob star
-    /\/\.\.\.\//.test(p);        // /.../ ellipsis path segment (v2.4.0)
+    /\/\.\.\.\//.test(p) ||      // /.../ ellipsis path segment (v2.4.0)
+    /\b(?:camelCase|PascalCase|kebab-case|snake_case)\b/.test(p);  // v2.4.3 naming-convention tokens
 
   // File-level exclusion: some generated rule files are DESIGNED to cite
   // convention-trap paths as teaching examples — they tell the reader
@@ -625,8 +642,8 @@ async function main() {
 
     // Pull every `claudeos-core/skills/...` path that appears inside
     // a backtick span in the MANIFEST. This catches the table's
-    // "entry" column regardless of the heading language ("등록된
-    // 스킬" / "Registered Skills" / "登録済みスキル" — all match).
+    // "entry" column regardless of the heading language — match works
+    // on the path token only, not on any per-language heading text.
     const SKILL_PATH_RE = /`(claudeos-core\/skills\/[\w\-./]+\.md)`/g;
     const registered = new Set();
     let m;

package/lib/expected-outputs.js

@@ -33,7 +33,7 @@ const EXPECTED_OUTPUTS = [
   // no longer generated. Master plans were an internal tool backup not
   // consumed by Claude Code at runtime, and aggregating many files in a
   // single session caused "Prompt is too long" failures on mid-sized
-  // projects (confirmed on an 18-domain production run).
+  // projects (observed on 18-domain-class projects).
 ];
 
 function readSafe(p) {

package/manifest-generator/index.js

@@ -22,6 +22,7 @@ const matter = require("gray-matter");
 const { glob } = require("glob");
 const { parseFileBlocks, parseCodeBlocks, CODE_BLOCK_PLANS } = require("../lib/plan-parser");
 const { updateStaleReport } = require("../lib/stale-report");
+const { syncSkillsCatalog } = require("./skills-sync");
 
 const ROOT = process.env.CLAUDEOS_ROOT || path.resolve(__dirname, "../..");
 const GEN = path.join(ROOT, "claudeos-core/generated");
@@ -161,6 +162,16 @@ async function main() {
   // to match the declared v2.1.0 contract "plan/ directory is no longer
   // created during init".
 
+  // ─── Skills catalog reconciliation (v2.4.3) ─────────────
+  // Deterministically reconcile MANIFEST.md ↔ CLAUDE.md §6 cross-references
+  // that LLM stages routinely drift on. Failure here is logged but not
+  // fatal — manifest-generator's primary outputs above are already on disk.
+  try {
+    syncSkillsCatalog(ROOT);
+  } catch (e) {
+    console.log(`  ⚠️  skills-sync: unexpected error (${e.message || e})`);
+  }
+
   // ─── Initialize stale-report.json (preserve existing sub-tool results) ──
   updateStaleReport(GEN, "generatedAt", new Date().toISOString(), { totalIssues: 0, status: "initial" });
   console.log("  ✅ stale-report.json — initialized");

package/manifest-generator/skills-sync.js

@@ -0,0 +1,393 @@
+/**
+ * ClaudeOS-Core — Skills Sync (manifest-generator hook)
+ *
+ * Role: After all Pass 3 stages complete, deterministically reconcile two
+ * cross-references that LLMs (3b-core / 3c-core) routinely drift on:
+ *
+ *   1. MANIFEST.md "Per-domain notes" section
+ *      - When `claudeos-core/skills/{category}/domains/` exists with N files,
+ *        ensure MANIFEST.md surfaces the per-domain catalog explicitly.
+ *      - Pattern matches the backend-style MANIFEST: a self-describing
+ *        section listing all domain stems by name.
+ *
+ *   2. CLAUDE.md §6 Skills sub-section
+ *      - When MANIFEST.md registers a category-root orchestrator
+ *        (`{category}/{NN}.{name}.md`), ensure §6 mentions it.
+ *      - Sub-skills (`{category}/{stem}/{file}.md`) are NOT added — they
+ *        belong only in MANIFEST per the convention.
+ *
+ * Design principles:
+ *   - Deterministic (no LLM)
+ *   - Idempotent (safe to run repeatedly)
+ *   - Append-only (never deletes user-edited content)
+ *   - Failure-isolated (errors logged, don't break manifest-generator)
+ *   - Multilingual (§6 detection by heading number, not text)
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ─── Per-domain catalog discovery ────────────────────────────────────
+//
+// Walk every category under skills/ and find ones with a domains/ folder.
+// Returns: [{ categoryDir, categoryRel, domains: [stem...] }, ...]
+function discoverPerDomainCatalogs(skillsDir, rootRel) {
+  const catalogs = [];
+  if (!fs.existsSync(skillsDir)) return catalogs;
+
+  for (const cat of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!cat.isDirectory()) continue;
+    const domainsDir = path.join(skillsDir, cat.name, "domains");
+    if (!fs.existsSync(domainsDir)) continue;
+    if (!fs.statSync(domainsDir).isDirectory()) continue;
+
+    const domains = fs
+      .readdirSync(domainsDir)
+      .filter((f) => f.endsWith(".md") && !f.startsWith("."))
+      .map((f) => f.replace(/\.md$/, ""))
+      .sort();
+
+    if (domains.length === 0) continue;
+
+    catalogs.push({
+      categoryName: cat.name,
+      categoryRel: `${rootRel}/${cat.name}`,
+      domains,
+    });
+  }
+  return catalogs;
+}
+
+// ─── MANIFEST.md patcher ─────────────────────────────────────────────
+//
+// For each category with domains/, ensure MANIFEST.md contains a
+// "Per-domain notes" section listing the domain stems.
+//
+// Idempotency:
+//   - If section exists AND already lists all current domains → no-op.
+//   - If section exists but domain list is stale → replace ONLY the list
+//     paragraph, preserving any user-added bullet/explanation below.
+//   - If section missing → append at end of category section (or end of
+//     file if category section structure is unrecognized).
+//
+// Returns: { patched: boolean, addedSections: [...], updatedLists: [...] }
+function patchManifestPerDomainSections(manifestPath, catalogs) {
+  if (!fs.existsSync(manifestPath)) {
+    return { patched: false, reason: "MANIFEST.md not found" };
+  }
+
+  let content = fs.readFileSync(manifestPath, "utf-8");
+  const original = content;
+  const addedSections = [];
+  const updatedLists = [];
+
+  for (const cat of catalogs) {
+    // Build the canonical domain list paragraph.
+    const listLine =
+      `\`${cat.categoryRel}/domains/{domain}.md\` — one file per domain. ` +
+      `${cat.domains.length} domain${cat.domains.length === 1 ? "" : "s"} (${cat.domains.join(", ")}).`;
+
+    // Detection regex: "### Per-domain notes" heading anywhere in file.
+    // Multilingual variants are not auto-detected here — we use the
+    // canonical English heading. If a project later adopts a different
+    // heading, the section will simply be appended fresh, which is safe
+    // (idempotency loss in that case is the cost of multilingual support).
+    const sectionRe =
+      /###\s+Per-domain\s+notes\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/;
+
+    const match = sectionRe.exec(content);
+
+    if (match) {
+      // Section exists. Check if our category's domain line is already
+      // present and current.
+      const sectionBody = match[1];
+      const categoryLineRe = new RegExp(
+        // Match a line containing the category path + "/domains/" followed
+        // by a domain count. Capture full line for replacement.
+        `(?:^|\\n)([^\\n]*\`${escapeRegex(cat.categoryRel)}/domains/[^\`]*\`[^\\n]*)`,
+        "m"
+      );
+      const lineMatch = categoryLineRe.exec(sectionBody);
+
+      if (lineMatch) {
+        // Line exists for this category. Replace if stale.
+        if (lineMatch[1].trim() !== listLine) {
+          const newBody = sectionBody.replace(lineMatch[1], listLine);
+          content = content.replace(sectionBody, newBody);
+          updatedLists.push(cat.categoryName);
+        }
+        // else: already correct, skip silently.
+      } else {
+        // Section exists but no line for this category. Append the line
+        // at the start of the section body (after the heading).
+        const insertion = `\n${listLine}\n`;
+        const newBody = insertion + sectionBody;
+        content = content.replace(sectionBody, newBody);
+        addedSections.push(cat.categoryName);
+      }
+    } else {
+      // No "### Per-domain notes" section anywhere. Append a fresh section
+      // at the end of the file.
+      const fresh = `\n### Per-domain notes\n\n${listLine}\n`;
+      content = content.trimEnd() + "\n" + fresh;
+      addedSections.push(cat.categoryName);
+    }
+  }
+
+  if (content === original) {
+    return { patched: false, addedSections: [], updatedLists: [] };
+  }
+
+  fs.writeFileSync(manifestPath, content);
+  return { patched: true, addedSections, updatedLists };
+}
+
+// ─── CLAUDE.md §6 Skills patcher ─────────────────────────────────────
+//
+// Extract orchestrators from MANIFEST.md (category-root files only),
+// ensure §6 Skills sub-section mentions each one. Append missing entries
+// after the existing bullet list.
+//
+// Section detection:
+//   - §6 = first heading starting with "## 6." (any language after that)
+//   - Skills sub-section = first "### " heading inside §6 whose text
+//     contains "Skills" (covers EN/KO/JA/etc — most translations keep
+//     the word "Skills")
+//
+// Idempotency:
+//   - For each orchestrator path, search the WHOLE §6 Skills sub-section
+//     body. If the path is already mentioned anywhere, skip.
+//   - Otherwise, append a new bullet at end of sub-section.
+function patchClaudeMdSkillsSection(claudeMdPath, manifestPath) {
+  if (!fs.existsSync(claudeMdPath)) {
+    return { patched: false, reason: "CLAUDE.md not found" };
+  }
+  if (!fs.existsSync(manifestPath)) {
+    return { patched: false, reason: "MANIFEST.md not found" };
+  }
+
+  const manifestContent = fs.readFileSync(manifestPath, "utf-8");
+
+  // Extract orchestrators from MANIFEST.
+  // An orchestrator is a path of the form:
+  //   claudeos-core/skills/{category}/{NN}.{name}.md
+  // (sub-folder paths like {category}/{stem}/file.md are NOT orchestrators)
+  const orchestrators = [];
+  const seen = new Set();
+  // Match backtick-quoted paths in MANIFEST. Then filter to category-root.
+  // CRITICAL: the inline description capture must stay on the SAME line.
+  // We use [^\S\n] for "horizontal whitespace" to exclude newlines, and
+  // [^|`\n] for the description content (already excludes \n).
+  const pathRe =
+    /`(claudeos-core\/skills\/[^/`]+\/[^/`]+\.md)`(?:[^\S\n]*\|[^\S\n]*([^|`\n]+))?/g;
+  let m;
+  while ((m = pathRe.exec(manifestContent)) !== null) {
+    const fullPath = m[1];
+    // Exclude MANIFEST.md itself and any path with sub-folder.
+    if (fullPath.endsWith("/MANIFEST.md")) continue;
+    // Verify it's category-root: 4 segments exactly
+    //   claudeos-core/skills/{category}/{file}.md
+    const parts = fullPath.split("/");
+    if (parts.length !== 4) continue;
+    if (seen.has(fullPath)) continue;
+    seen.add(fullPath);
+
+    // Try to capture the description from the same MANIFEST table row.
+    // We look ONLY on the same line (until the next newline) to avoid
+    // accidentally absorbing content from following sections (e.g.
+    // "### Per-domain notes" heading appearing right after).
+    const afterPath = manifestContent.slice(m.index + m[0].length);
+    const lineEnd = afterPath.indexOf("\n");
+    const sameLine = lineEnd === -1 ? afterPath : afterPath.slice(0, lineEnd);
+    let description = (m[2] || "").trim();
+    if (!description) {
+      // Look for `| description |` or `| description` pattern on same line.
+      const descMatch = /^\s*\|\s*([^|\n]+?)\s*(?:\||$)/.exec(sameLine);
+      if (descMatch) description = descMatch[1].trim();
+    }
+
+    orchestrators.push({ path: fullPath, description });
+  }
+
+  if (orchestrators.length === 0) {
+    return { patched: false, reason: "no orchestrators found in MANIFEST" };
+  }
+
+  let content = fs.readFileSync(claudeMdPath, "utf-8");
+  const original = content;
+
+  // Locate §6 Skills sub-section.
+  // Step 1: find "## 6." heading position
+  const section6Re = /^##\s+6\.\s+[^\n]*$/m;
+  const s6Match = section6Re.exec(content);
+  if (!s6Match) {
+    return { patched: false, reason: "§6 heading not found in CLAUDE.md" };
+  }
+  const s6Start = s6Match.index;
+
+  // Find end of §6: next "## " heading at same level
+  const afterS6 = content.slice(s6Start + s6Match[0].length);
+  const nextSectionRe = /\n##\s+/;
+  const nextMatch = nextSectionRe.exec(afterS6);
+  const s6End = nextMatch
+    ? s6Start + s6Match[0].length + nextMatch.index
+    : content.length;
+
+  const section6 = content.slice(s6Start, s6End);
+
+  // Step 2: find Skills sub-section inside §6
+  // Match "### " line containing word "Skills" (case-insensitive).
+  // Capture body until next "### " or end of section.
+  const skillsSubRe = /^###\s+[^\n]*Skills[^\n]*$/im;
+  const skillsMatch = skillsSubRe.exec(section6);
+  if (!skillsMatch) {
+    return {
+      patched: false,
+      reason: "Skills sub-section not found in CLAUDE.md §6",
+    };
+  }
+
+  const skillsHeadingStart = skillsMatch.index;
+  const skillsBodyStart = skillsHeadingStart + skillsMatch[0].length;
+  const afterSkills = section6.slice(skillsBodyStart);
+  const nextSubRe = /\n###\s+/;
+  const nextSubMatch = nextSubRe.exec(afterSkills);
+  const skillsBodyEnd = nextSubMatch
+    ? skillsBodyStart + nextSubMatch.index
+    : section6.length;
+
+  const skillsBody = section6.slice(skillsBodyStart, skillsBodyEnd);
+
+  // Step 3: for each orchestrator, check if mentioned in skillsBody.
+  // We accept any mention (path appears in body) as "covered".
+  const missing = [];
+  for (const orch of orchestrators) {
+    if (skillsBody.includes(orch.path)) continue;
+    missing.push(orch);
+  }
+
+  if (missing.length === 0) {
+    return { patched: false, addedOrchestrators: [] };
+  }
+
+  // Step 4: build new bullets and append before the trailing whitespace
+  // of skillsBody (so they sit at the end of the bullet list, before
+  // the blank line that precedes the next sub-section).
+  const newBullets = missing
+    .map((o) => {
+      const desc = o.description || "orchestrator";
+      return `- \`${o.path}\` — ${desc}`;
+    })
+    .join("\n");
+
+  // Trim trailing whitespace from skillsBody, append bullets, restore
+  // a trailing blank line for separation.
+  const trimmed = skillsBody.replace(/\s+$/, "");
+  const newSkillsBody = `${trimmed}\n${newBullets}\n\n`;
+
+  // Reassemble §6
+  const newSection6 =
+    section6.slice(0, skillsBodyStart) +
+    newSkillsBody +
+    section6.slice(skillsBodyEnd);
+
+  // Reassemble full file
+  content =
+    content.slice(0, s6Start) + newSection6 + content.slice(s6End);
+
+  if (content === original) {
+    return { patched: false, addedOrchestrators: [] };
+  }
+
+  fs.writeFileSync(claudeMdPath, content);
+  return {
+    patched: true,
+    addedOrchestrators: missing.map((o) => o.path),
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ─── Public entry point ──────────────────────────────────────────────
+//
+// Called from manifest-generator/index.js main() after rule-manifest.json
+// + sync-map.json + stale-report.json are written.
+//
+// Errors are logged but do NOT throw — manifest-generator must remain
+// robust to partial-state projects (e.g. small projects without a
+// domains/ folder, or projects that haven't run Pass 3 yet).
+function syncSkillsCatalog(rootDir) {
+  const skillsDir = path.join(rootDir, "claudeos-core/skills");
+  const sharedManifestPath = path.join(skillsDir, "00.shared/MANIFEST.md");
+  const claudeMdPath = path.join(rootDir, "CLAUDE.md");
+
+  const result = {
+    perDomain: { patched: false },
+    skillsSection: { patched: false },
+  };
+
+  // Step 1: discover per-domain catalogs.
+  let catalogs;
+  try {
+    catalogs = discoverPerDomainCatalogs(skillsDir, "claudeos-core/skills");
+  } catch (e) {
+    console.log(`  ⚠️  skills-sync: discovery failed (${e.message})`);
+    return result;
+  }
+
+  // Step 2: patch MANIFEST.md per-domain sections.
+  if (catalogs.length > 0) {
+    try {
+      result.perDomain = patchManifestPerDomainSections(
+        sharedManifestPath,
+        catalogs
+      );
+      if (result.perDomain.patched) {
+        const added = result.perDomain.addedSections || [];
+        const updated = result.perDomain.updatedLists || [];
+        if (added.length) {
+          console.log(
+            `  ✅ MANIFEST.md — Per-domain section added for [${added.join(", ")}]`
+          );
+        }
+        if (updated.length) {
+          console.log(
+            `  ✅ MANIFEST.md — Per-domain list refreshed for [${updated.join(", ")}]`
+          );
+        }
+      }
+    } catch (e) {
+      console.log(`  ⚠️  skills-sync: MANIFEST patch failed (${e.message})`);
+    }
+  }
+
+  // Step 3: patch CLAUDE.md §6 Skills sub-section.
+  try {
+    result.skillsSection = patchClaudeMdSkillsSection(
+      claudeMdPath,
+      sharedManifestPath
+    );
+    if (result.skillsSection.patched) {
+      const added = result.skillsSection.addedOrchestrators || [];
+      console.log(
+        `  ✅ CLAUDE.md — §6 Skills updated (${added.length} orchestrator${added.length === 1 ? "" : "s"} added)`
+      );
+    }
+  } catch (e) {
+    console.log(`  ⚠️  skills-sync: CLAUDE.md patch failed (${e.message})`);
+  }
+
+  return result;
+}
+
+module.exports = {
+  syncSkillsCatalog,
+  // Exposed for unit tests
+  discoverPerDomainCatalogs,
+  patchManifestPerDomainSections,
+  patchClaudeMdSkillsSection,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeos-core",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "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": {

package/plan-installer/scanners/scan-java.js

@@ -209,7 +209,7 @@ async function scanJavaDomains(stack, ROOT) {
     // v2.4.0 — Deep-sweep fallback (Pattern B/D only).
     //
     // Pre-v2.4.0: standard globs assume `{domain}/{layer}/X.java`. This
-    // misses two real-world layouts:
+    // misses two non-canonical layouts:
     //   (a) Multi-module split: `front/{domain}/{layer}/` for HTTP
     //       layer + `core/{domain}/{layer}/` for service/dao layer.
     //       Standard glob `**/{domain}/{layer}/` actually matches BOTH
@@ -234,7 +234,7 @@ async function scanJavaDomains(stack, ROOT) {
     const standardCount = svc.length + agg.length + mpr.length + dto.length + xml.length;
     if (standardCount === 0 && (p === "B" || p === "D")) {
       const deepFiles = (await glob(`src/main/java/**/${dn}/**/*.java`, { cwd: ROOT })).map(norm);
-      // v2.4.0 — extended layer recognition. Real-world enterprise codebases
+      // v2.4.0 — extended layer recognition. Enterprise codebases
       // commonly include implementation/support layers beyond the canonical
       // controller/service/mapper/dto trio. Files in `factory/`, `strategy/`,
       // `impl/`, `helper/`, etc. were previously dropped by deep-sweep