@pieai/doc-gov 0.5.4 → 0.7.0

package/cli-guide.md

@@ -56,8 +56,9 @@ pnpm doc-gov migrate --profile doc-only --check
   `docs/governance/agents-routing/`, and `profiles/` stay connected in the
   expected order.
 - In a downstream project, it verifies the project router block,
-  `docs/governance/ssot-v1.0.md`, the selected agents-routing file, and old
-  shared SSOT/task-routing leftovers.
+  `docs/governance/ssot-v1.1.md`, the selected agents-routing file, the exact
+  `CLAUDE.md -> AGENTS.md` and `.claude/skills -> ../.agents/skills`
+  compatibility links, and old shared SSOT/task-routing leftovers.
 - It also checks that local paths written in backticks inside router-facing
   files such as `AGENTS.md`, `CLAUDE.md`, `README.md`, and the starter
   `AGENTS.template.md` can actually be opened, which catches stale startup

package/dist/cli.js

@@ -895,13 +895,22 @@ import { existsSync as existsSync7, readFileSync as readFileSync7 } from "node:f
 import { isAbsolute, join as join9, resolve as resolve2 } from "node:path";
 
 // src/core/router-integrity.ts
-import { existsSync as existsSync6, readdirSync as readdirSync5, readFileSync as readFileSync6 } from "node:fs";
+import {
+  existsSync as existsSync6,
+  lstatSync as lstatSync2,
+  readlinkSync,
+  readdirSync as readdirSync5,
+  readFileSync as readFileSync6
+} from "node:fs";
 import { join as join8, relative as relative2 } from "node:path";
 var CENTRAL_REQUIRED_FILES = [
   "AGENTS.md",
+  "CLAUDE.md",
+  ".agents/skills",
+  ".claude/skills",
   "README.md",
   "docs/governance/boundary.md",
-  "docs/governance/ssot-v1.0.md",
+  "docs/governance/ssot-v1.1.md",
   "docs/governance/templates/adr.md",
   "docs/governance/templates/spec.md",
   "docs/governance/templates/plan.md",
@@ -909,23 +918,23 @@ var CENTRAL_REQUIRED_FILES = [
   "docs/governance/templates/reference.md",
   "docs/governance/templates/policy.md",
   "docs/governance/templates/archive.md",
-  "docs/governance/agents-routing/engineering-runtime-v1.0.md",
-  "docs/governance/agents-routing/doc-only-v1.0.md",
+  "docs/governance/agents-routing/engineering-runtime-v1.1.md",
+  "docs/governance/agents-routing/doc-only-v1.1.md",
   "integrations/mattpocock-skills.md",
   "profiles/engineering-runtime/profile.md",
   "profiles/engineering-runtime/manifest.yml",
   "profiles/doc-only/profile.md",
   "profiles/doc-only/manifest.yml",
+  "starter/.agents/skills/.gitkeep",
   "starter/AGENTS.template.md",
-  "starter/CLAUDE.template.md",
   "starter/lefthook.template.yml",
   "starter/.github/workflows/docs-check.yml",
   "starter/docs/reference/execution/current-work.md",
   "starter/docs/policy/best-practice-for-this-project.md",
   "starter/docs/governance/boundary.md",
-  "starter/docs/governance/ssot-v1.0.md",
-  "starter/docs/governance/agents-routing/engineering-runtime-v1.0.md",
-  "starter/docs/governance/agents-routing/doc-only-v1.0.md",
+  "starter/docs/governance/ssot-v1.1.md",
+  "starter/docs/governance/agents-routing/engineering-runtime-v1.1.md",
+  "starter/docs/governance/agents-routing/doc-only-v1.1.md",
   "starter/docs/governance/doc-agent-rules.md",
   "starter/docs/governance/doc-types.md",
   "starter/docs/governance/templates/adr.md",
@@ -939,15 +948,17 @@ var CENTRAL_REQUIRED_FILES = [
 var PROJECT_REQUIRED_FILES = [
   "AGENTS.md",
   "CLAUDE.md",
+  ".agents/skills",
+  ".claude/skills",
   "docs/governance/boundary.md",
-  "docs/governance/ssot-v1.0.md",
+  "docs/governance/ssot-v1.1.md",
   "docs/governance/doc-agent-rules.md",
   "docs/governance/doc-types.md",
   "docs/reference/execution/current-work.md"
 ];
 var PROJECT_AGENTS_ROUTING_FILES = [
-  "docs/governance/agents-routing/engineering-runtime-v1.0.md",
-  "docs/governance/agents-routing/doc-only-v1.0.md"
+  "docs/governance/agents-routing/engineering-runtime-v1.1.md",
+  "docs/governance/agents-routing/doc-only-v1.1.md"
 ];
 var FORBIDDEN_LEGACY_PATHS = [
   "governance",
@@ -960,9 +971,14 @@ var FORBIDDEN_PROJECT_PATHS = [
   "docs/policy/shared-rules/ssot.md",
   "docs/policy/shared-rules/task-routing.md"
 ];
+var SUPERSEDED_PROJECT_CONTRACT_PATHS = [
+  "docs/governance/ssot-v1.0.md",
+  "docs/governance/agents-routing/engineering-runtime-v1.0.md",
+  "docs/governance/agents-routing/doc-only-v1.0.md"
+];
 var FORBIDDEN_PROJECT_ROOTS = ["integrations"];
 var FORBIDDEN_CENTRAL_ROOTS = ["shared-rules"];
-var ROUTER_BLOCK_BEGIN = "<!-- PGS-ROUTER:BEGIN v1.0 -->";
+var ROUTER_BLOCK_BEGIN = "<!-- PGS-ROUTER:BEGIN v1.1 -->";
 var ROUTER_BLOCK_END = "<!-- PGS-ROUTER:END -->";
 var EXTERNAL_ROUTER_MARKERS = [
   "## gstack",
@@ -992,8 +1008,8 @@ var CENTRAL_REQUIRED_NEEDLES = [
   },
   {
     file: "AGENTS.md",
-    needle: "docs/governance/ssot-v1.0.md",
-    message: "AGENTS.md must mention docs/governance/ssot-v1.0.md."
+    needle: "docs/governance/ssot-v1.1.md",
+    message: "AGENTS.md must mention docs/governance/ssot-v1.1.md."
   },
   {
     file: "AGENTS.md",
@@ -1007,13 +1023,13 @@ var CENTRAL_REQUIRED_NEEDLES = [
   },
   {
     file: "AGENTS.md",
-    needle: "docs/governance/agents-routing/engineering-runtime-v1.0.md",
-    message: "AGENTS.md must mention docs/governance/agents-routing/engineering-runtime-v1.0.md."
+    needle: "docs/governance/agents-routing/engineering-runtime-v1.1.md",
+    message: "AGENTS.md must mention docs/governance/agents-routing/engineering-runtime-v1.1.md."
   },
   {
     file: "AGENTS.md",
-    needle: "docs/governance/agents-routing/doc-only-v1.0.md",
-    message: "AGENTS.md must mention docs/governance/agents-routing/doc-only-v1.0.md."
+    needle: "docs/governance/agents-routing/doc-only-v1.1.md",
+    message: "AGENTS.md must mention docs/governance/agents-routing/doc-only-v1.1.md."
   },
   {
     file: "AGENTS.md",
@@ -1031,12 +1047,12 @@ var CENTRAL_REQUIRED_NEEDLES = [
     message: "README.md must point readers to agents-routing under docs/governance/."
   },
   {
-    file: "docs/governance/agents-routing/engineering-runtime-v1.0.md",
+    file: "docs/governance/agents-routing/engineering-runtime-v1.1.md",
     needle: "current-work.md",
     message: "Engineering routing must separate routing from current-work.md."
   },
   {
-    file: "docs/governance/agents-routing/doc-only-v1.0.md",
+    file: "docs/governance/agents-routing/doc-only-v1.1.md",
     needle: "does not use engineering test workflows by default",
     message: "Doc-only routing must exclude engineering test workflows by default."
   },
@@ -1057,7 +1073,7 @@ var CENTRAL_REQUIRED_NEEDLES = [
   },
   {
     file: "profiles/engineering-runtime/manifest.yml",
-    needle: "docs/governance/agents-routing/engineering-runtime-v1.0.md",
+    needle: "docs/governance/agents-routing/engineering-runtime-v1.1.md",
     message: "Engineering profile manifest must point to engineering routing."
   },
   {
@@ -1067,7 +1083,7 @@ var CENTRAL_REQUIRED_NEEDLES = [
   },
   {
     file: "profiles/doc-only/manifest.yml",
-    needle: "docs/governance/agents-routing/doc-only-v1.0.md",
+    needle: "docs/governance/agents-routing/doc-only-v1.1.md",
     message: "Doc-only profile manifest must point to doc-only routing."
   },
   {
@@ -1092,8 +1108,8 @@ var CENTRAL_REQUIRED_NEEDLES = [
   },
   {
     file: "starter/AGENTS.template.md",
-    needle: "docs/governance/ssot-v1.0.md",
-    message: "Starter AGENTS template must point agents to docs/governance/ssot-v1.0.md."
+    needle: "docs/governance/ssot-v1.1.md",
+    message: "Starter AGENTS template must point agents to docs/governance/ssot-v1.1.md."
   },
   {
     file: "starter/AGENTS.template.md",
@@ -1179,8 +1195,8 @@ var PROJECT_REQUIRED_NEEDLES = [
   },
   {
     file: "AGENTS.md",
-    needle: "docs/governance/ssot-v1.0.md",
-    message: "AGENTS.md must mention docs/governance/ssot-v1.0.md."
+    needle: "docs/governance/ssot-v1.1.md",
+    message: "AGENTS.md must mention docs/governance/ssot-v1.1.md."
   },
   {
     file: "AGENTS.md",
@@ -1208,7 +1224,7 @@ var PROJECT_REQUIRED_NEEDLES = [
     message: "Governance boundary must preserve the product artifact boundary."
   },
   {
-    file: "docs/governance/ssot-v1.0.md",
+    file: "docs/governance/ssot-v1.1.md",
     needle: "automatically govern every Markdown file",
     message: "SSOT rule must state that not every Markdown file is governed."
   },
@@ -1240,6 +1256,7 @@ function checkRouterIntegrity(rootDir = process.cwd()) {
   if (!isCentral) {
     issues.push(...validateProjectAgentsRouting(rootDir));
   }
+  issues.push(...validateHostSsot(rootDir));
   for (const file of FORBIDDEN_LEGACY_PATHS) {
     if (existsSync6(join8(rootDir, file))) {
       issues.push({
@@ -1259,6 +1276,15 @@ function checkRouterIntegrity(rootDir = process.cwd()) {
         });
       }
     }
+    for (const file of SUPERSEDED_PROJECT_CONTRACT_PATHS) {
+      if (existsSync6(join8(rootDir, file))) {
+        issues.push({
+          file,
+          code: "superseded-project-contract",
+          message: `Superseded governance contract must not remain installed in a project: ${file}. Sync the current v1.1 contract instead.`
+        });
+      }
+    }
     for (const file of FORBIDDEN_PROJECT_ROOTS) {
       if (existsSync6(join8(rootDir, file))) {
         issues.push({
@@ -1303,7 +1329,6 @@ function checkRouterIntegrity(rootDir = process.cwd()) {
     issues.push(...validateRouterBlock(rootDir, file));
   }
   issues.push(...validateBacktickedLocalPaths(rootDir, "AGENTS.md"));
-  issues.push(...validateBacktickedLocalPaths(rootDir, "CLAUDE.md"));
   issues.push(...validateBacktickedLocalPaths(rootDir, "README.md"));
   if (isCentral) {
     issues.push(...validateBacktickedLocalPaths(rootDir, "starter/AGENTS.template.md", "starter"));
@@ -1312,15 +1337,13 @@ function checkRouterIntegrity(rootDir = process.cwd()) {
     "AGENTS.md",
     "README.md",
     "starter/AGENTS.template.md",
-    "starter/CLAUDE.template.md",
-    "docs/governance/agents-routing/engineering-runtime-v1.0.md",
-    "docs/governance/agents-routing/doc-only-v1.0.md"
+    "docs/governance/agents-routing/engineering-runtime-v1.1.md",
+    "docs/governance/agents-routing/doc-only-v1.1.md"
   ] : [
     "AGENTS.md",
-    "CLAUDE.md",
     "README.md",
-    "docs/governance/agents-routing/engineering-runtime-v1.0.md",
-    "docs/governance/agents-routing/doc-only-v1.0.md"
+    "docs/governance/agents-routing/engineering-runtime-v1.1.md",
+    "docs/governance/agents-routing/doc-only-v1.1.md"
   ];
   for (const file of portableRouterFiles) {
     issues.push(...validatePortableRouterText(rootDir, file));
@@ -1330,6 +1353,62 @@ function checkRouterIntegrity(rootDir = process.cwd()) {
     issues
   };
 }
+function validateHostSsot(rootDir) {
+  const issues = [];
+  validateRegularFile("AGENTS.md");
+  validateExactSymlink("CLAUDE.md", "AGENTS.md");
+  validateDirectory(".agents/skills");
+  validateExactSymlink(".claude/skills", "../.agents/skills");
+  return issues;
+  function validateRegularFile(file) {
+    const stat = safeLstat(join8(rootDir, file));
+    if (!stat || stat.isFile()) return;
+    issues.push({
+      file,
+      code: "invalid-host-ssot-source",
+      message: `${file} must be a regular file and the single source of truth for project instructions.`
+    });
+  }
+  function validateDirectory(file) {
+    const stat = safeLstat(join8(rootDir, file));
+    if (!stat || stat.isDirectory()) return;
+    issues.push({
+      file,
+      code: "invalid-host-ssot-source",
+      message: `${file} must be a real directory and the single source of truth for project skills.`
+    });
+  }
+  function validateExactSymlink(file, expectedRawTarget) {
+    const path = join8(rootDir, file);
+    const stat = safeLstat(path);
+    if (!stat) return;
+    if (!stat.isSymbolicLink()) {
+      issues.push({
+        file,
+        code: "invalid-host-ssot-adapter",
+        message: `${file} must be a symbolic link with the exact relative target ${expectedRawTarget}.`
+      });
+      return;
+    }
+    const rawTarget = readlinkSync(path);
+    if (rawTarget !== expectedRawTarget) {
+      issues.push({
+        file,
+        code: "noncanonical-host-ssot-adapter",
+        message: `${file} must use the exact relative symlink target ${expectedRawTarget}; found ${rawTarget}.`
+      });
+    }
+  }
+}
+function safeLstat(path) {
+  try {
+    return lstatSync2(path);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return void 0;
+    throw error;
+  }
+}
 function isCentralRepository(rootDir) {
   const packageJsonPath = join8(rootDir, "package.json");
   if (!existsSync6(packageJsonPath)) return false;
@@ -1445,8 +1524,12 @@ function validatePortableRouterText(rootDir, file) {
   ];
 }
 function hasNonPortablePath(content) {
+  const withoutCanonicalSkillCompatibilityTarget = content.replace(
+    /(^|[\s`'"])\.\.\/\.agents\/skills(?=$|[\s`'"),.;:\]}])/gm,
+    "$1"
+  );
   return /(^|[\s`'"])(\/Users\/|~\/|\$HOME(?:\/|\b)|%USERPROFILE%|[A-Za-z]:\\|\.\.\/)/.test(
-    content
+    withoutCanonicalSkillCompatibilityTarget
   ) || /\b(OneDrive|CloudStorage)\b/.test(content);
 }
 function findGovernedReadmes(rootDir) {
@@ -1935,8 +2018,9 @@ function runInit(args2) {
   console.log(`
 Next steps for a brand-new project:`);
   console.log(`  1. Copy starter/AGENTS.template.md to AGENTS.md and fill the project name.`);
-  console.log(`     Copy starter/CLAUDE.template.md to CLAUDE.md as the Claude adapter.`);
-  console.log(`  2. Copy starter/docs/governance/boundary.md, ssot-v1.0.md,`);
+  console.log(`     Create .agents/skills as the canonical project skill directory.`);
+  console.log(`     Link CLAUDE.md -> AGENTS.md and .claude/skills -> ../.agents/skills.`);
+  console.log(`  2. Copy starter/docs/governance/boundary.md, ssot-v1.1.md,`);
   console.log(`     doc-agent-rules.md, doc-types.md, and one agents-routing file.`);
   console.log(`  3. Copy starter/docs/policy/best-practice-for-this-project.md and replace`);
   console.log(`     placeholder policy with this project's real AI/development rules.`);
@@ -1975,8 +2059,8 @@ function runLinks() {
 import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
 import { join as join12 } from "node:path";
 var PROFILE_ROUTES = {
-  "engineering-runtime": "docs/governance/agents-routing/engineering-runtime-v1.0.md",
-  "doc-only": "docs/governance/agents-routing/doc-only-v1.0.md"
+  "engineering-runtime": "docs/governance/agents-routing/engineering-runtime-v1.1.md",
+  "doc-only": "docs/governance/agents-routing/doc-only-v1.1.md"
 };
 function runMigrate(args2) {
   const checkOnly = args2.includes("--check");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pieai/doc-gov",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "description": "AI-native documentation governance CLI for project docs, agent routing, and lifecycle checks.",
   "keywords": [
     "ai-agents",