@flancer32/skill-adsm-ctx 0.3.0 → 0.5.0

package/src/Skill/Installer.mjs

@@ -5,7 +5,7 @@
  * @description Installs the bundled skill payload into a target skills directory.
  */
 
-const sourceRoot = new URL("../../skill/", import.meta.url);
+const sourceRoot = new URL("../../skills/adsm-ctx/", import.meta.url);
 
 export default class Installer {
   /**
@@ -39,9 +39,9 @@ export default class Installer {
   }
 }
 
-export const __deps__ = Object.freeze({
+export const __deps__ = Object.freeze({default: Object.freeze({
   copyDirectory: "Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory$",
   fs: "node:fs",
   pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
   url: "node:url",
-});
+})});

package/src/Validate/Service.mjs

@@ -31,7 +31,7 @@ export default class Validate {
      *     ruleId: string,
      *     severity: "error" | "warning"
      *   }[],
-     *   metadata: {schema: string, version: string, initializedAt?: string} | null,
+     *   metadata: {capabilities?: string[], schema: string, version: string, initializedAt?: string} | null,
      *   missingPaths: string[],
      *   ok: boolean,
      *   projectRoot: string,
@@ -40,7 +40,8 @@ export default class Validate {
      *     bodies: string[],
      *     orphanSkins: string[],
      *     pairs: {body: string, skin: string}[],
-     *     skins: string[]
+     *     skins: string[],
+     *     verification: {categories: string[], present: boolean}
      *   },
      *   warningCount: number
      * }>}
@@ -54,10 +55,27 @@ export default class Validate {
         ruleId: "required-path",
         severity: "error",
       }));
-      const metadata = readMetadata({constants, fs, pathService, projectRoot});
-      const projection = inspectProjection({constants, fs, pathService, projectRoot});
-
-      if (!metadata.ok) findings.push(metadata.finding);
+      const metadataResult = readMetadata({constants, fs, pathService, projectRoot});
+      const projection = inspectProjection({
+        constants,
+        fs,
+        metadata: metadataResult.ok ? metadataResult.metadata : null,
+        pathService,
+        projectRoot,
+      });
+
+      for (const entry of constants.REQUIRED_PATHS) {
+        const absolute = pathService.join(projectRoot, entry);
+        if (!fs.existsSync(absolute) || typeof fs.statSync !== "function") continue;
+        const stat = fs.statSync(absolute);
+        const file = entry.endsWith(".md") || entry.endsWith(".json");
+        if (file ? !stat.isFile() : !stat.isDirectory()) findings.push(createFinding({
+          message: `Required path has wrong filesystem type: ${entry}`,
+          path: entry, ruleId: "required-path-type", severity: "error",
+        }));
+      }
+      findings.push(...inspectAgentsHierarchy({fs, pathService, projectRoot}));
+      findings.push(...metadataResult.findings);
       findings.push(...projection.findings);
 
       const errorCount = findings.filter((entry) => entry.severity === "error").length;
@@ -66,7 +84,7 @@ export default class Validate {
       return {
         errorCount,
         findings,
-        metadata: metadata.ok ? metadata.metadata : null,
+        metadata: metadataResult.metadata,
         missingPaths,
         ok: errorCount === 0,
         projectRoot,
@@ -104,7 +122,8 @@ export default class Validate {
       const lines = [
         status,
         `Project root: ${result.projectRoot}`,
-        `Context version: ${result.metadata?.version ?? "unknown"}`,
+        `Context schema version: ${result.metadata?.version ?? "unknown"}`,
+        `Supported context schema version: ${constants.CONTEXT_VERSION}`,
         `Errors: ${result.errorCount}`,
         `Warnings: ${result.warningCount}`,
       ];
@@ -180,54 +199,82 @@ function parseSkinFilename(file) {
  * }}
  */
 function readMetadata({constants, fs, pathService, projectRoot}) {
+  const findings = [];
   const metadataPath = pathService.join(projectRoot, "ctx", "adsm.json");
   if (!fs.existsSync(metadataPath)) {
-    return {
-      ok: false,
-      finding: createFinding({
-        message: "Missing ctx/adsm.json",
-        path: "ctx/adsm.json",
-        ruleId: "metadata-file",
-        severity: "error",
-      }),
-    };
+    findings.push(createFinding({
+      message: "Missing ctx/adsm.json",
+      path: "ctx/adsm.json",
+      ruleId: "metadata-file",
+      severity: "error",
+    }));
+    return {findings, metadata: null, ok: false};
   }
 
   try {
     const parsed = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
     if (parsed.schema !== constants.CONTEXT_SCHEMA) {
-      return {
-        ok: false,
-        finding: createFinding({
-          message: `Unexpected schema: ${parsed.schema}`,
-          path: "ctx/adsm.json",
-          ruleId: "metadata-schema",
-          severity: "error",
-        }),
-      };
+      findings.push(createFinding({
+        message: `Unexpected schema: ${parsed.schema}`,
+        path: "ctx/adsm.json",
+        ruleId: "metadata-schema",
+        severity: "error",
+      }));
     }
-    if (!parsed.version) {
-      return {
-        ok: false,
-        finding: createFinding({
-          message: "Missing metadata version",
+    if (parsed.version !== constants.CONTEXT_VERSION) {
+      findings.push(createFinding({
+        message: ["0.1.0", "0.2.0", "0.3.0"].includes(parsed.version)
+          ? `Legacy schema ${parsed.version}; use skill adsm-ctx for agent-driven context evolution. Target schema: ${constants.CONTEXT_VERSION}.`
+          : `Unsupported metadata version: ${parsed.version}; investigate with skill adsm-ctx before changing schema metadata.`,
+        path: "ctx/adsm.json",
+        ruleId: "metadata-version",
+        severity: "error",
+      }));
+    }
+
+    if (Object.hasOwn(parsed, "capabilities")) {
+      if (!Array.isArray(parsed.capabilities)) {
+        findings.push(createFinding({
+          message: "Metadata capabilities must be an array of unique strings",
           path: "ctx/adsm.json",
-          ruleId: "metadata-version",
+          ruleId: "metadata-capabilities",
           severity: "error",
-        }),
-      };
+        }));
+      } else {
+        const seen = new Set();
+        for (const capability of parsed.capabilities) {
+          if (typeof capability !== "string" || capability.length === 0 || seen.has(capability)) {
+            findings.push(createFinding({
+              message: "Metadata capabilities must be an array of unique non-empty strings",
+              path: "ctx/adsm.json",
+              ruleId: "metadata-capabilities",
+              severity: "error",
+            }));
+            break;
+          }
+          seen.add(capability);
+          if (!(constants.CONTEXT_CAPABILITIES ?? []).includes(capability)) {
+            findings.push(createFinding({
+              message: `Unknown context capability: ${capability}`,
+              path: "ctx/adsm.json",
+              ruleId: "metadata-capability-unknown",
+              severity: "warning",
+            }));
+          }
+        }
+      }
     }
-    return {ok: true, metadata: parsed};
+
+    const ok = findings.every((entry) => entry.severity !== "error");
+    return {findings, metadata: parsed, ok};
   } catch (error) {
-    return {
-      ok: false,
-      finding: createFinding({
-        message: `Invalid metadata JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
-        path: "ctx/adsm.json",
-        ruleId: "metadata-json",
-        severity: "error",
-      }),
-    };
+    findings.push(createFinding({
+      message: `Invalid metadata JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
+      path: "ctx/adsm.json",
+      ruleId: "metadata-json",
+      severity: "error",
+    }));
+    return {findings, metadata: null, ok: false};
   }
 }
 
@@ -253,7 +300,7 @@ function readMetadata({constants, fs, pathService, projectRoot}) {
  *   }
  * }}
  */
-function inspectProjection({constants, fs, pathService, projectRoot}) {
+function inspectProjection({constants, fs, metadata, pathService, projectRoot}) {
   const docsRoot = pathService.join(projectRoot, "ctx", "docs");
   const assetsRoot = pathService.join(projectRoot, "ctx", "assets");
   const findings = [];
@@ -303,6 +350,26 @@ function inspectProjection({constants, fs, pathService, projectRoot}) {
     pathService,
     projectRoot,
   }));
+  const verification = inspectVerificationBlock({
+    constants,
+    docsEntryMap,
+    fs,
+    pathService,
+    projectRoot,
+  });
+  findings.push(...verification.findings);
+  if (
+    verification.summary.present
+    && metadata
+    && !metadata.capabilities?.includes(constants.VERIFICATION_CAPABILITY)
+  ) {
+    findings.push(createFinding({
+      message: `Verification block is present without declared ${constants.VERIFICATION_CAPABILITY} capability`,
+      path: "ctx/adsm.json",
+      ruleId: "verification-capability-undocumented",
+      severity: "warning",
+    }));
+  }
 
   const markdownFiles = [];
   for (const file of listFiles({fs, pathService, root: docsRoot, prefix: "ctx/docs"})) {
@@ -365,10 +432,120 @@ function inspectProjection({constants, fs, pathService, projectRoot}) {
       orphanSkins,
       pairs,
       skins,
+      verification: verification.summary,
     },
   };
 }
 
+/**
+ * Inspects the cross-cutting Verification Layer without treating it as a fifth
+ * declarative documentation level.
+ *
+ * @param {object} params
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Constants} params.constants
+ * @param {Map<string, {name: string, isDirectory: () => boolean, isFile: () => boolean}>} params.docsEntryMap
+ * @param {typeof import("node:fs")} params.fs
+ * @param {Fl32_Skill_Adsm_Ctx_Shared_Path} params.pathService
+ * @param {string} params.projectRoot
+ * @returns {{
+ *   findings: {message: string, path: string, ruleId: string, severity: "error" | "warning"}[],
+ *   summary: {categories: string[], present: boolean}
+ * }}
+ */
+function inspectVerificationBlock({constants, docsEntryMap, fs, pathService, projectRoot}) {
+  const findings = [];
+  const summary = {categories: [], present: false};
+  const entry = docsEntryMap.get(constants.VERIFICATION_BLOCK);
+  if (!entry) return {findings, summary};
+
+  summary.present = true;
+  const verificationPath = `ctx/docs/${constants.VERIFICATION_BLOCK}`;
+  if (!entry.isDirectory()) {
+    findings.push(createFinding({
+      message: `Verification block is not a directory: ${verificationPath}`,
+      path: verificationPath,
+      ruleId: "verification-block",
+      severity: "error",
+    }));
+    return {findings, summary};
+  }
+
+  let entries = [];
+  try {
+    entries = listEntries({
+      fs,
+      root: pathService.join(projectRoot, ...verificationPath.split("/")),
+    });
+  } catch (error) {
+    findings.push(createFinding({
+      message: `Unreadable verification block (${error instanceof Error ? error.message : "Unknown error"})`,
+      path: verificationPath,
+      ruleId: "verification-block-readable",
+      severity: "error",
+    }));
+    return {findings, summary};
+  }
+
+  const agentsEntry = entries.find((candidate) => candidate.name === "AGENTS.md");
+  if (!agentsEntry?.isFile()) {
+    findings.push(createFinding({
+      message: `Verification block requires ${verificationPath}/AGENTS.md`,
+      path: `${verificationPath}/AGENTS.md`,
+      ruleId: "verification-agents",
+      severity: "error",
+    }));
+  }
+
+  const targets = constants.VERIFICATION_TARGETS ?? constants.DOC_LEVELS;
+  for (const child of entries) {
+    if (child.name === "AGENTS.md") continue;
+    if (!targets.includes(child.name)) {
+      if (child.isDirectory()) {
+        findings.push(createFinding({
+          message: `Unsupported verification category: ${child.name}`,
+          path: `${verificationPath}/${child.name}`,
+          ruleId: "verification-category",
+          severity: "error",
+        }));
+      }
+      continue;
+    }
+
+    if (!child.isDirectory()) {
+      findings.push(createFinding({
+        message: `Verification category is not a directory: ${child.name}`,
+        path: `${verificationPath}/${child.name}`,
+        ruleId: "verification-category",
+        severity: "error",
+      }));
+      continue;
+    }
+
+    summary.categories.push(child.name);
+    const categoryPath = `${verificationPath}/${child.name}`;
+    const documents = listFiles({
+      fs,
+      pathService,
+      prefix: categoryPath,
+      root: pathService.join(projectRoot, ...categoryPath.split("/")),
+    }).filter((file) => (
+      file.endsWith(".md")
+      && !file.endsWith("/AGENTS.md")
+      && !parseSkinFilename(file)
+    ));
+    if (documents.length === 0) {
+      findings.push(createFinding({
+        message: `Verification category has no durable specification: ${categoryPath}`,
+        path: categoryPath,
+        ruleId: "verification-empty-category",
+        severity: "error",
+      }));
+    }
+  }
+
+  return {findings, summary};
+}
+
 /**
  * Warns when a documentation level exceeds the recommended direct-entry capacity
  * and requires its local AGENTS.md to make an intentional exception explicit.
@@ -578,6 +755,14 @@ function validateSkinDocument({bodySet, constants, file, skinInfo, text}) {
       severity: "error",
     }));
   }
+  if (/^#{1,6}\s+Agent Document\s*#*\s*$/mi.test(text)) {
+    findings.push(createFinding({
+      message: "Redundant Agent Document section: skin pairing is derived from its filename",
+      path: file,
+      ruleId: "skin-redundant-agent-document-section",
+      severity: "error",
+    }));
+  }
   return findings;
 }
 
@@ -650,66 +835,58 @@ function normalizeRelativeSegments(parts) {
   return result;
 }
 
-/**
- * @param {string} text
- * @returns {string}
- */
-function stripFencedCodeBlocks(text) {
-  return text.replace(/```[\s\S]*?```/g, "");
-}
-
-/**
- * Extracts all human-facing skin content while excluding metadata and headings.
- *
- * @param {string} text
- * @returns {string}
- */
-function extractSkinMetricText(text) {
-  return stripSkinPresentation(text);
-}
-
-/**
- * @param {string} text
- * @returns {string}
- */
-function stripSkinPresentation(text) {
-  let insideLegacyReference = false;
-  return stripFencedCodeBlocks(text)
-    .split("\n")
-    .filter((line) => {
-      const trimmed = line.trim();
-      if (/^##\s+Agent Document\s*$/.test(trimmed)) {
-        insideLegacyReference = true;
-        return false;
-      }
-      if (insideLegacyReference && /^##\s+/.test(trimmed)) insideLegacyReference = false;
-      return !insideLegacyReference && !/^#/.test(trimmed) && !/^- (?:Path|Changed): `[^`]+`$/.test(trimmed);
-    })
-    .join("\n")
-    .replace(/^\s*(?:Includes|Excludes):\s*$/gmu, "");
-}
-
-/**
- * @param {string} text
- * @returns {number}
- */
-function countWords(text) {
-  const matches = stripFencedCodeBlocks(text).match(/(?:\p{L}[\p{L}\p{M}\p{N}'’_-]*|\p{N}+)/gu);
-  return matches ? matches.length : 0;
-}
-
-/**
- * @param {string} text
- * @returns {number}
- */
-function countMeaningfulListItems(text) {
-  return [...stripFencedCodeBlocks(text).matchAll(/^\s*(?:[-*+]|\d+[.)])\s+(.+)$/gmu)]
-    .filter((match) => countWords(match[1]) > 0)
-    .length;
-}
-
-export const __deps__ = Object.freeze({
+export const __deps__ = Object.freeze({default: Object.freeze({
   constants: "Fl32_Skill_Adsm_Ctx_Shared_Constants$",
   fs: "node:fs",
   pathService: "Fl32_Skill_Adsm_Ctx_Shared_Path$",
-});
+})});
+
+/** Checks context-side routing sections; root repository instructions have a separate shape. */
+function inspectAgentsHierarchy({fs, pathService, projectRoot}) {
+  const findings = [];
+  const root = pathService.join(projectRoot, "ctx");
+  if (!fs.existsSync(root)) return findings;
+  const visit = (directory, relative) => {
+    let entries;
+    try { entries = listEntries({fs, root: directory}); }
+    catch (error) {
+      findings.push(createFinding({message: `Cannot inspect context routing: ${error.message}`, path: relative, ruleId: "agents-readable", severity: "error"}));
+      return;
+    }
+    for (const entry of entries) {
+      const absolute = pathService.join(directory, entry.name);
+      const file = `${relative}/${entry.name}`;
+      if (entry.isDirectory()) visit(absolute, file);
+      else if (entry.isFile() && entry.name === "AGENTS.md") {
+        let text;
+        try { text = fs.readFileSync(absolute, "utf8"); }
+        catch (error) {
+          findings.push(createFinding({message: `Cannot read context AGENTS.md: ${error.message}`, path: file, ruleId: "agents-readable", severity: "error"}));
+          continue;
+        }
+        // Ignore fenced examples so sample headings cannot satisfy the document structure.
+        const headings = new Set();
+        let fence = null;
+        for (const line of text.split(/\r?\n/)) {
+          const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+          if (marker) {
+            if (!fence) fence = marker[1];
+            else if (marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = null;
+            continue;
+          }
+          if (fence) continue;
+          const heading = /^ {0,3}##[ \t]+(.+?)[ \t]*$/.exec(line);
+          if (heading) headings.add(heading[1].replace(/[ \t]+#+[ \t]*$/, ""));
+        }
+        for (const section of ["Purpose", "Level Map", "Level Boundary"]) {
+          if (!headings.has(section)) findings.push(createFinding({
+            message: `Missing required section: ## ${section}. Add it to this context-side AGENTS.md.`,
+            path: file, ruleId: "agents-required-section", severity: "error",
+          }));
+        }
+      }
+    }
+  };
+  visit(root, "ctx");
+  return findings;
+}

package/types.d.ts

@@ -1,17 +1,13 @@
 declare global {
-  type Fl32_Skill_Adsm_Ctx_Cli_Command_Design = import("./src/Cli/Command/Design.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Cli_Command_Init = import("./src/Cli/Command/Init.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Cli_Command_InstallSkill = import("./src/Cli/Command/InstallSkill.mjs").default;
-  type Fl32_Skill_Adsm_Ctx_Cli_Command_Upgrade = import("./src/Cli/Command/Upgrade.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Cli_Command_Validate = import("./src/Cli/Command/Validate.mjs").default;
-  type Fl32_Skill_Adsm_Ctx_Design_Service = import("./src/Design/Service.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Init_Service = import("./src/Init/Service.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Constants = import("./src/Shared/Constants.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_CopyDirectory = import("./src/Shared/CopyDirectory.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Metadata = import("./src/Shared/Metadata.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Shared_Path = import("./src/Shared/Path.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Skill_Installer = import("./src/Skill/Installer.mjs").default;
-  type Fl32_Skill_Adsm_Ctx_Upgrade_Service = import("./src/Upgrade/Service.mjs").default;
   type Fl32_Skill_Adsm_Ctx_Validate_Service = import("./src/Validate/Service.mjs").default;
 }
 

package/migrations/README.md

@@ -1,9 +0,0 @@
-# Migrations
-
-This directory is reserved for future context migrations.
-
-Each migration should be:
-
-- versioned;
-- non-destructive by default;
-- explicit about prerequisites and post-upgrade manual steps.

package/skill/references/upgrade-policy.md

@@ -1,19 +0,0 @@
-# Upgrade Policy
-
-- Path: `skill/references/upgrade-policy.md`
-- Changed: `20260708`
-
-Upgrades must be non-destructive by default.
-
-Safe upgrade behavior includes:
-
-- adding missing files and directories;
-- updating metadata when the migration rules are explicit;
-- preserving project-authored content unless replacement is proven safe.
-- detecting agent/skin pairs, orphan skins, and projection drift according to `skill/references/document-projections.md`;
-- preserving project-specific nested subdirectories under `ctx/docs/product/`, `ctx/docs/architecture/`, `ctx/docs/environment/`, and `ctx/docs/code/`;
-- keeping visual, generated, rendered, and auxiliary artifacts under `ctx/assets/**`.
-
-Unsafe cases should be reported for manual follow-up instead of applied automatically.
-
-Upgrade must not introduce required `README.md` files inside `ctx/docs/` and must not automatically rewrite human-controlled skins when agent/skin meaning is unclear.

package/skill/templates/AGENTS.md

@@ -1,120 +0,0 @@
-# Root Level
-
-- Path: `AGENTS.md`
-- Template Version: `20260720`
-- Changed: `YYYYMMDD`
-
-## Purpose
-
-This file defines the root-level working rules for the project repository.
-
-This file is the first instruction source for every agent operating within the repository.
-
-## Level Boundary
-
-Defines:
-
-- Root-level working boundaries between the repository, the cognitive context, and the software product.
-- Repository-topology rules needed to work safely when `ctx/` may be mounted separately.
-- Root-level protection and escalation rules for this project.
-
-Does NOT define:
-
-- Product-specific meaning, requirements, or domain knowledge.
-- Implementation-level structure such as source code, runtime details, or filesystem layout.
-- Task-specific instructions, workflows, or local operational procedures.
-
-## ADSM Project Model
-
-An ADSM project consists of two interconnected spaces:
-
-- the **Cognitive Context** located in `./ctx/`
-- the **Software Product** located outside `./ctx/`
-
-The cognitive context is the long-term textual memory of the project.
-
-The cognitive context is the primary communication medium between Humans and Agents working on the project.
-
-The cognitive context is the authoritative knowledge source used by Agents when modifying the project.
-
-The software product is the implementation that must be kept consistent with the cognitive context.
-
-## Human and Agent Roles
-
-The Human defines goals, authorizes work, evaluates outcomes, and evolves the project.
-
-The Agent interprets the cognitive context, performs assigned tasks, modifies the project within task boundaries, and maintains consistency between the cognitive context and the software product.
-
-The Agent operates through text and must treat project documentation as operational memory, not as secondary commentary.
-
-## Cognitive Context
-
-The canonical execution location of the cognitive context is `./ctx/`.
-
-Project-specific knowledge, requirements, architecture, environment descriptions, and implementation guidance are defined within the cognitive context.
-
-The Agent must consult `./ctx/AGENTS.md` for project-specific instructions when `./ctx/` exists.
-
-The Agent must consult `./ctx/docs/filesystem.md` for the project filesystem structure and documentation layout when that file exists.
-
-Documentation distributed with the software product may exist outside `./ctx/`, but it does not replace, redefine, or supersede the cognitive context.
-
-## Bootstrap and Repository Topology
-
-An ADSM project may use one repository or two repositories.
-
-In a one-repository topology, the software product and the cognitive context are versioned together.
-
-In a two-repository topology, the software product and the cognitive context are independent version-controlled repositories, and the cognitive context repository is mounted under `./ctx/`.
-
-The Agent must detect whether `./ctx/` is part of the current repository or an independent repository.
-
-The Agent must preserve repository boundaries.
-
-The Agent must not mix changes between independent repositories.
-
-The Agent must not remove, replace, relocate, or unmount `./ctx/`.
-
-If `./ctx/` does not exist, the Agent may perform bootstrap operations required to create the initial cognitive context structure.
-
-After bootstrap is complete, `./ctx/AGENTS.md` becomes the entry point for project-specific instructions.
-
-## Context and Product Consistency
-
-The cognitive context is the source of truth for the project.
-
-If the cognitive context and the software product diverge, the Agent must treat the cognitive context as authoritative.
-
-The Agent must maintain consistency between the cognitive context and the software product.
-
-The Agent may modify the cognitive context when required by the assigned task and when the modification remains consistent with higher-level context constraints.
-
-The Agent may modify the software product when required by the assigned task and when the modification remains consistent with the cognitive context.
-
-## AGENTS.md Hierarchy
-
-Additional `AGENTS.md` files may exist in subdirectories.
-
-The effective working context of the agent is the aggregate of all `AGENTS.md` files located along the path from the repository root to the target directory.
-
-Rules:
-
-- deeper levels override higher levels within their scope
-- root-level invariants cannot be overridden
-- all levels must remain mutually consistent
-
-## Root File Protection
-
-This file defines root-level project control rules.
-
-The agent must not modify, replace, delete, relocate, or reinterpret this file unless explicitly instructed by the human.
-
-Violation of this rule constitutes an execution error.
-
-## Secret Handling
-
-The Agent must never read, load, print, search for, or expose secret-bearing project files, including `.env` and `.env.*` files, credentials, private keys, tokens, or secret stores. This rule applies even when a file is Git-ignored and includes broad search or command output that could reveal its contents.
-
-The Agent may use a non-secret example template such as `.env.example` only to learn the configuration shape. It must not infer or request the value of any secret.
-
-If secret data is exposed accidentally, the Agent must stop handling that value, must not repeat it, and must tell the Human that the secret should be rotated or revoked.