@ankhorage/devtools 1.21.3 → 2.0.0

package/README.md

@@ -3,9 +3,9 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.21.3](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v2.0.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
-Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
+Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects
 
 ## Usage
 
@@ -13,7 +13,7 @@ Shared development tools and repository standards for Ankhorage TypeScript proje
 
 ## What it owns
 
-`@ankhorage/devtools` is the single source of truth for these separate concerns:
+`@ankhorage/policy` is the source of truth for canonical Ankhorage policy. `@ankhorage/devtools` is the execution and synchronization layer for these repository concerns:
 
 ```text
 src/
@@ -30,8 +30,8 @@ src/
     └── vscode/
 ```
 
-- `policy`: shared repository runtime policy, including the canonical Bun version
-- `changesets`: package-resolved Changesets execution and release command policy
+- `policy`: policy application/rendering adapters that consume `@ankhorage/policy`
+- `changesets`: package-resolved Changesets execution using centrally defined commands
 - `agents`: canonical repository `AGENTS.md` rendered from stable package identity
 - `skills`: immutable Ankhorage-owned repository skills under `.agents/skills/`
 - `eslint`: shared flat ESLint configuration, automatic project profiles, and the bundled ESLint runner
@@ -41,7 +41,7 @@ src/
 - `workflows`: canonical `.github/workflows/ci.yml` and `release.yml`
 - `vscode`: canonical `.vscode/settings.json` and `extensions.json`
 
-The package owns the supported Changesets CLI, ESLint, TypeScript ESLint, Prettier, Knip, security, React, React Hooks, React Native, import/sort, unused-import, and formatting-plugin versions used by consuming repositories. It also owns the Bun runtime version used by Ankhorage repository metadata and managed workflows.
+The package owns the supported Changesets CLI, ESLint, TypeScript ESLint, Prettier, Knip, security, React, React Hooks, React Native, import/sort, unused-import, and formatting-plugin versions used by consuming repositories. The Bun/Node runtime baseline and canonical Changesets/PKGViz policy values are owned by `@ankhorage/policy` and rendered by Devtools.
 
 ## Bootstrap
 
@@ -316,7 +316,7 @@ export default createKnipConfig();
 
 ## Managed Bun runtime policy
 
-The canonical Bun policy is defined once in devtools and consumed by both package and workflow synchronization. The current policy is:
+The canonical Bun policy is defined by `@ankhorage/policy` and consumed by Devtools package and workflow synchronization. The current released policy is:
 
 <!-- devtools-bun-policy:start -->
 
@@ -328,7 +328,7 @@ packageManager    bun@1.4.2
 
 <!-- devtools-bun-policy:end -->
 
-Renovate owns the single `BUN_VERSION` literal in `src/policy/bunRuntimePolicy.ts`. Its trusted base-branch workflow invokes `bun scripts/sync-renovate-owner.ts sync repository` to regenerate `packageManager`, `@types/bun`, the Bun workflow setup versions, this documentation block, and `bun.lock`, then runs `bun scripts/sync-renovate-owner.ts status repository` to reject stale generated artifacts. Do not synchronize those values manually in a Renovate branch.
+`ankhorage/policy` owns and updates the canonical Bun and `@types/bun` literals through Renovate. A released Policy update reaches Devtools as a normal dependency update; Devtools then renders that policy into `packageManager`, `@types/bun`, workflow setup versions, this documentation block, and `bun.lock`. The trusted owner workflow uses `bun scripts/sync-renovate-owner.ts sync repository` to regenerate those artifacts and `bun scripts/sync-renovate-owner.ts status repository` to reject stale rendered state. Do not duplicate runtime policy literals in Devtools.
 
 ## Managed package contract
 
@@ -363,7 +363,7 @@ A repository participates in Changesets synchronization when `.changeset/config.
 .github/workflows/release.yml
 ```
 
-CI and Release render their `bun-version` from the same managed Bun runtime policy used for `package.json`. They also render Changesets status, version, and publish commands from the same policy that owns the synchronized package scripts. The CI workflow installs that Bun version with the frozen lockfile, builds before repository-provider validation, runs `bunx @ankhorage/ankh doctor validate .`, and conditionally runs lint, formatting, Knip, tests, typecheck, and the strict `changeset:status --since=origin/main` guard for pull requests. After a green change reaches `main`, Release uses the scoped Ankhorage Renovate Sync App token to apply Changesets versioning directly to `main` in a `chore(release)` `[skip ci]` commit and publishes without creating a second Version Packages pull request. Release publishing calls the Devtools-owned runner through the synchronized package script; it never resolves an ambient or mutable Changesets executable. Changesets v3 creates the local release tags; the managed workflow pushes those exact tags and creates any missing GitHub Releases directly, without parsing Changesets’ human-readable publish output.
+CI and Release render their `bun-version` from `@ankhorage/policy/repository`, the same policy used for `package.json`. They also render Changesets status, version, and publish commands from that central policy. The CI workflow installs that Bun version with the frozen lockfile, builds before repository-provider validation, runs `bunx @ankhorage/ankh doctor validate .`, and conditionally runs lint, formatting, Knip, tests, typecheck, and the strict `changeset:status --since=origin/main` guard for pull requests. After a green change reaches `main`, Release uses the scoped Ankhorage Renovate Sync App token to apply Changesets versioning directly to `main` in a `chore(release)` `[skip ci]` commit and publishes without creating a second Version Packages pull request. Release publishing calls the Devtools-owned runner through the synchronized package script; it never resolves an ambient or mutable Changesets executable. Changesets v3 creates the local release tags; the managed workflow pushes those exact tags and creates any missing GitHub Releases directly, without parsing Changesets’ human-readable publish output.
 
 For the **first npm publication** of a new `@ankhorage/*` package, the organization publishing credential must be able to create/publish packages in the `@ankhorage` scope. With a granular npm token, grant package permission **Read and write (publish and stage)** to the `@ankhorage` scope or **All Packages**. If initial publication fails after Changesets has already pushed the release commit, correct the npm credential and rerun Release; the current unpublished version is reused and must not be bumped again. The managed workflow diagnoses this first-publish state separately from registry/network failures.
 

package/dist/internal/readmeDocs.js

@@ -1,4 +1,4 @@
-import { bunRuntimePolicy } from '../policy/bunRuntimePolicy.js';
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 const REQUIRED_README_SNIPPETS = [
     'ankh devtools lint',
     'ankh devtools changeset',
@@ -35,9 +35,10 @@ const REQUIRED_README_SNIPPETS = [
     '<!-- devtools-bun-policy:end -->',
     'bun scripts/sync-renovate-owner.ts sync repository',
     'bun scripts/sync-renovate-owner.ts status',
-    bunRuntimePolicy.version,
-    bunRuntimePolicy.packageManager,
-    bunRuntimePolicy.typesRange,
+    '@ankhorage/policy',
+    REPOSITORY_POLICY.runtime.bun.version,
+    REPOSITORY_POLICY.runtime.bun.packageManager,
+    REPOSITORY_POLICY.runtime.bun.typesRange,
 ];
 export function getReadmeDocumentationErrors(readmeContents) {
     return REQUIRED_README_SNIPPETS.flatMap((snippet) => readmeContents.includes(snippet)

package/dist/owner/synchronizeRenovateOwnerAsync.d.ts

@@ -1,4 +1,4 @@
-/*** Synchronize or validate Renovate-owned Devtools policy artifacts. */
+/*** Synchronize or validate Renovate-owned Devtools artifacts from central repository policy. */
 export declare function synchronizeRenovateOwnerAsync(operation: OwnerSyncOperation, targetDirectory: string, options?: OwnerSyncOptions): Promise<void>;
 type OwnerSyncOperation = 'status' | 'sync';
 interface OwnerSyncOptions {

package/dist/owner/synchronizeRenovateOwnerAsync.js

@@ -1,19 +1,18 @@
 import { spawn } from 'node:child_process';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 import { resolveApmReleaseCommandAsync } from '../features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.js';
 import { resolveStructureReleaseCommandAsync } from '../features/structure-descriptor-generation/adapters/outbound/resolveStructureReleaseCommandAsync.js';
 import { applyBunRuntimePolicy } from '../policy/applyBunRuntimePolicy.js';
-import { nodeRuntimePolicy } from '../policy/bunRuntimePolicy.js';
 import { renderBunPolicyDocumentation } from '../policy/renderBunPolicyDocumentation.js';
 import { readCurrentDoctorVersion } from '../tools/workflows/readCurrentDoctorVersion.js';
 import { renderRenovateWorkflowAsync } from '../tools/workflows/renderRenovateWorkflowAsync.js';
 import { renderWorkflowAsync, } from '../tools/workflows/renderWorkflowAsync.js';
-/*** Synchronize or validate Renovate-owned Devtools policy artifacts. */
+/*** Synchronize or validate Renovate-owned Devtools artifacts from central repository policy. */
 export async function synchronizeRenovateOwnerAsync(operation, targetDirectory, options = {}) {
     const target = resolve(targetDirectory);
-    const policy = await readTargetBunPolicyAsync(target);
-    const definitions = await createManagedDefinitionsAsync(target, policy);
+    const definitions = await createManagedDefinitionsAsync(target);
     await assertDevtoolsTargetAsync(target);
     if (operation === 'sync') {
         await syncDefinitionsAsync(target, definitions);
@@ -34,18 +33,18 @@ async function assertDevtoolsTargetAsync(targetDirectory) {
         throw new Error('The Renovate owner sync target must be @ankhorage/devtools.');
     }
 }
-/*** Build the canonical owner-managed artifact definitions for the target repository. */
-async function createManagedDefinitionsAsync(targetDirectory, policy) {
+/*** Build the owner-managed artifact definitions from released central policy. */
+async function createManagedDefinitionsAsync(targetDirectory) {
     const manifest = JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
     if (!isRecord(manifest)) {
         throw new Error('Devtools package.json must contain a JSON object.');
     }
     const readme = await readFile(resolve(targetDirectory, 'README.md'), 'utf8');
-    const workflowPolicy = await createWorkflowPolicyAsync(targetDirectory, policy);
+    const workflowPolicy = await createWorkflowPolicyAsync(targetDirectory);
     return [
         {
             relativePath: 'package.json',
-            contents: serializePackageManifest(applyBunRuntimePolicy(manifest, policy)),
+            contents: serializePackageManifest(applyBunRuntimePolicy(manifest)),
         },
         {
             relativePath: '.github/workflows/ci.yml',
@@ -61,18 +60,18 @@ async function createManagedDefinitionsAsync(targetDirectory, policy) {
         },
         {
             relativePath: 'README.md',
-            contents: renderBunPolicyDocumentation(readme, policy),
+            contents: renderBunPolicyDocumentation(readme),
         },
     ];
 }
 /*** Build the self-hosted workflow policy used by Devtools owner synchronization. */
-async function createWorkflowPolicyAsync(targetDirectory, policy) {
+async function createWorkflowPolicyAsync(targetDirectory) {
     return {
         apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
         structureReleaseCommand: await resolveStructureReleaseCommandAsync(targetDirectory),
-        bunVersion: policy.version,
+        bunVersion: REPOSITORY_POLICY.runtime.bun.version,
         doctorVersion: readCurrentDoctorVersion(),
-        nodeVersion: nodeRuntimePolicy.setupVersion,
+        nodeVersion: REPOSITORY_POLICY.runtime.node.setupVersion,
     };
 }
 /*** Return owner-managed artifact paths whose current bytes differ from policy output. */
@@ -95,25 +94,6 @@ function isNodeError(error) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/*** Read the target repository's canonical Bun policy literals. */
-async function readTargetBunPolicyAsync(targetDirectory) {
-    const contents = await readFile(resolve(targetDirectory, 'src/policy/bunRuntimePolicy.ts'), 'utf8');
-    const matches = [...contents.matchAll(BUN_VERSION_PATTERN)];
-    const version = matches.length === 1 ? matches[0]?.[1] : undefined;
-    if (version === undefined) {
-        throw new Error('Expected exactly one canonical BUN_VERSION literal in the target policy.');
-    }
-    const typesMatches = [...contents.matchAll(BUN_TYPES_VERSION_PATTERN)];
-    const typesVersion = typesMatches.length === 1 ? typesMatches[0]?.[1] : undefined;
-    if (typesVersion === undefined) {
-        throw new Error('Expected exactly one canonical BUN_TYPES_VERSION literal in the target policy.');
-    }
-    return {
-        packageManager: `bun@${version}`,
-        typesRange: `^${typesVersion}`,
-        version,
-    };
-}
 /*** Synchronize or validate the target Bun lockfile through Bun itself. */
 async function runBunLockfileAsync(operation, targetDirectory) {
     const args = [
@@ -155,5 +135,3 @@ async function syncDefinitionsAsync(targetDirectory, definitions) {
         await writeFile(targetPath, contents, 'utf8');
     }
 }
-const BUN_VERSION_PATTERN = /const BUN_VERSION = '(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)';/gu;
-const BUN_TYPES_VERSION_PATTERN = /const BUN_TYPES_VERSION = '(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)';/gu;

package/dist/policy/applyBunRuntimePolicy.d.ts

@@ -1,4 +1,2 @@
-export declare function applyBunRuntimePolicy(manifest: Record<string, unknown>, policy: {
-    readonly packageManager: string;
-    readonly typesRange: string;
-}): Record<string, unknown>;
+/*** Apply the canonical Bun runtime policy to one package manifest. */
+export declare function applyBunRuntimePolicy(manifest: Record<string, unknown>): Record<string, unknown>;

package/dist/policy/applyBunRuntimePolicy.js

@@ -1,9 +1,11 @@
-export function applyBunRuntimePolicy(manifest, policy) {
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
+/*** Apply the canonical Bun runtime policy to one package manifest. */
+export function applyBunRuntimePolicy(manifest) {
     const devDependencies = toRecord(manifest.devDependencies);
-    devDependencies['@types/bun'] = policy.typesRange;
+    devDependencies['@types/bun'] = REPOSITORY_POLICY.runtime.bun.typesRange;
     return {
         ...manifest,
-        packageManager: policy.packageManager,
+        packageManager: REPOSITORY_POLICY.runtime.bun.packageManager,
         devDependencies,
     };
 }

package/dist/policy/renderBunPolicyDocumentation.d.ts

@@ -1,3 +1,2 @@
-import type { BunPolicy } from '../types/bunPolicy.js';
 /*** Render the managed Bun policy section while preserving the surrounding guide. */
-export declare function renderBunPolicyDocumentation(readme: string, policy: BunPolicy): string;
+export declare function renderBunPolicyDocumentation(readme: string): string;

package/dist/policy/renderBunPolicyDocumentation.js

@@ -1,5 +1,6 @@
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 /*** Render the managed Bun policy section while preserving the surrounding guide. */
-export function renderBunPolicyDocumentation(readme, policy) {
+export function renderBunPolicyDocumentation(readme) {
     const startIndex = readme.indexOf(README_POLICY_START);
     const endIndex = readme.indexOf(README_POLICY_END);
     if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
@@ -9,11 +10,12 @@ export function renderBunPolicyDocumentation(readme, policy) {
         readme.includes(README_POLICY_END, endIndex + README_POLICY_END.length)) {
         throw new Error('README.md must contain exactly one Devtools Bun policy marker pair.');
     }
-    const replacement = `${README_POLICY_START}\n\n${renderReadmePolicy(policy)}\n\n${README_POLICY_END}`;
+    const replacement = `${README_POLICY_START}\n\n${renderReadmePolicy()}\n\n${README_POLICY_END}`;
     return `${readme.slice(0, startIndex)}${replacement}${readme.slice(endIndex + README_POLICY_END.length)}`;
 }
 /*** Format canonical runtime and type-package versions for the guide. */
-function renderReadmePolicy(policy) {
+function renderReadmePolicy() {
+    const policy = REPOSITORY_POLICY.runtime.bun;
     return `\`\`\`text
 Bun runtime       ${policy.version}
 packageManager    ${policy.packageManager}

package/dist/policy/resolvePkgvizAuditPolicyAsync.d.ts

@@ -1,4 +1,4 @@
-/*** Resolve the centrally pinned PKGViz CI audit for repositories with analyzable source. */
+/*** Resolve the central PKGViz CI audit for repositories with analyzable source. */
 export declare function resolvePkgvizAuditPolicyAsync(targetDirectory: string): Promise<PkgvizAuditPolicy | undefined>;
 interface PkgvizAuditPolicy {
     readonly artifactName: string;

package/dist/policy/resolvePkgvizAuditPolicyAsync.js

@@ -1,14 +1,12 @@
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-/*** Resolve the centrally pinned PKGViz CI audit for repositories with analyzable source. */
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
+/*** Resolve the central PKGViz CI audit for repositories with analyzable source. */
 export async function resolvePkgvizAuditPolicyAsync(targetDirectory) {
     if (!(await hasSourceDirectoryAsync(targetDirectory)))
         return undefined;
-    return {
-        artifactName: 'pkgviz-audit',
-        artifactPath: 'pkgviz-audit.json',
-        command: 'bunx pkgviz@0.8.1 --out pkgviz-audit.json --rule cyclic-dependencies=block',
-    };
+    const { artifactName, artifactPath, command } = REPOSITORY_POLICY.pkgvizAudit;
+    return { artifactName, artifactPath, command };
 }
 /*** Detect whether the managed repository has a source tree that PKGViz can inspect. */
 async function hasSourceDirectoryAsync(targetDirectory) {

package/dist/tools/package/index.js

@@ -7,7 +7,7 @@
  * `lint:fix`, `format`, `format:check`, and `knip:check` scripts are written.
  * Unrelated manifest fields, scripts, dependencies, and metadata are preserved.
  *
- * The Bun runtime policy is shared by every repository, including devtools itself. Devtools skips
+ * The Bun runtime policy comes from @ankhorage/policy for every repository, including devtools itself. Devtools skips
  * only its consumer dependency/script normalization so it never attempts to install itself.
  *
  * Status compares only the fields owned by this contract, so unrelated repository customization
@@ -19,9 +19,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 import { applyBunRuntimePolicy } from '../../policy/applyBunRuntimePolicy.js';
-import { bunRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
-import { changesetsPolicy } from '../../policy/changesetsPolicy.js';
 const PACKAGE_PATH = 'package.json';
 const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
 const BUN_TYPES_PACKAGE_NAME = '@types/bun';
@@ -85,26 +84,26 @@ export async function syncPackageManifest(targetDirectory, devtoolsVersion, opti
 /*** Apply the Devtools-owned package scripts, dependencies, and Bun runtime policy. */
 export function applyManagedPackageContract(manifest, devtoolsVersion, changesetsConfigExists = false) {
     if (manifest.name === DEVTOOLS_PACKAGE_NAME) {
-        return applyBunRuntimePolicy(manifest, bunRuntimePolicy);
+        return applyBunRuntimePolicy(manifest);
     }
     const scripts = { ...toRecord(manifest.scripts) };
     const changesetsEnabled = isChangesetsEnabled(scripts, changesetsConfigExists);
     delete scripts.knip;
     Object.assign(scripts, STANDARD_SCRIPTS);
     if (changesetsEnabled) {
-        Object.assign(scripts, changesetsPolicy.packageScripts);
+        Object.assign(scripts, REPOSITORY_POLICY.changesets.packageScripts);
     }
     const devDependencies = removeOwnedDependencies(toRecord(manifest.devDependencies));
     const dependencies = toRecord(manifest.dependencies);
-    delete dependencies[changesetsPolicy.packageName];
-    delete devDependencies[changesetsPolicy.packageName];
+    delete dependencies[REPOSITORY_POLICY.changesets.packageName];
+    delete devDependencies[REPOSITORY_POLICY.changesets.packageName];
     applyDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion);
     return applyBunRuntimePolicy({
         ...manifest,
         ...normalizedDependencies(manifest, dependencies),
         scripts,
         devDependencies,
-    }, bunRuntimePolicy);
+    });
 }
 /*** Check whether the Devtools-owned package manifest fields match current policy. */
 export function isManagedPackageContractCurrent(manifest, devtoolsVersion, changesetsConfigExists = false) {
@@ -120,8 +119,8 @@ export function isManagedPackageContractCurrent(manifest, devtoolsVersion, chang
     const changesetsEnabled = isChangesetsEnabled(scripts, changesetsConfigExists);
     return (hasStandardScripts(scripts) &&
         DEVTOOLS_OWNED_DEV_DEPENDENCIES.every((name) => devDependencies[name] === undefined) &&
-        dependencies[changesetsPolicy.packageName] === undefined &&
-        devDependencies[changesetsPolicy.packageName] === undefined &&
+        dependencies[REPOSITORY_POLICY.changesets.packageName] === undefined &&
+        devDependencies[REPOSITORY_POLICY.changesets.packageName] === undefined &&
         hasCurrentChangesetsScripts(scripts, changesetsEnabled) &&
         hasCurrentDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion));
 }
@@ -154,8 +153,8 @@ async function readPackageManifest(targetDirectory) {
 /*** Check the Bun package manager and Bun type dependency contract. */
 function hasCurrentBunRuntimePolicy(manifest) {
     const devDependencies = toRecord(manifest.devDependencies);
-    return (manifest.packageManager === bunRuntimePolicy.packageManager &&
-        devDependencies[BUN_TYPES_PACKAGE_NAME] === bunRuntimePolicy.typesRange);
+    return (manifest.packageManager === REPOSITORY_POLICY.runtime.bun.packageManager &&
+        devDependencies[BUN_TYPES_PACKAGE_NAME] === REPOSITORY_POLICY.runtime.bun.typesRange);
 }
 /*** Place Devtools in development dependencies for every consuming repository. */
 function applyDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion) {
@@ -188,12 +187,12 @@ function hasStandardScripts(scripts) {
 /*** Check Changesets scripts when the repository participates in Changesets. */
 function hasCurrentChangesetsScripts(scripts, changesetsEnabled) {
     return (!changesetsEnabled ||
-        Object.entries(changesetsPolicy.packageScripts).every(([name, command]) => scripts[name] === command));
+        Object.entries(REPOSITORY_POLICY.changesets.packageScripts).every(([name, command]) => scripts[name] === command));
 }
 /*** Determine whether the repository participates in Changesets synchronization. */
 function isChangesetsEnabled(scripts, changesetsConfigExists) {
     return (changesetsConfigExists ||
-        Object.keys(changesetsPolicy.packageScripts).some((scriptName) => scripts[scriptName] !== undefined));
+        Object.keys(REPOSITORY_POLICY.changesets.packageScripts).some((scriptName) => scripts[scriptName] !== undefined));
 }
 /*** Serialize a package manifest using the repository formatting contract. */
 function serializePackageManifest(manifest) {

package/dist/tools/skills/assets/ankhorage-coding-rules/SKILL.md

@@ -52,16 +52,22 @@ exceptions or replaced by generic preferences from this skill.
 - Use ordinary inline comments when they explain non-obvious intent, invariants, constraints, or the
   reason behind a decision. Do not narrate self-explanatory code or duplicate what names and types
   already express.
-- Paradox documentation metadata belongs only inside `/*** ... */` comments. Use only supported
-  Paradox tags: `@readme`, `@config`, `@example`, and `@usage`. Do not use JSDoc-only tags such as
-  `@param` or `@returns` as Paradox metadata.
+- Paradox documentation metadata belongs only inside `/*** ... */` comments. The canonical tag
+  vocabulary is owned by `@ankhorage/policy`: `@readme`, `@usage`, `@config`, `@title`,
+  `@see`, and `@security`. Unsupported tag-shaped lines are invalid; `@example` does not exist.
+  Do not use JSDoc-only tags such as `@param` or `@returns` as Paradox metadata.
+- Paradox comments contain documentation prose and metadata only. Fenced or indented code blocks are
+  invalid; source examples come from real code. Inline code spans remain valid prose.
 - Add a supported Paradox tag only when it changes or usefully enriches generated documentation;
   plain function descriptions do not need tags.
 - README usage documentation must come from a real repository-root `examples/<example>/...` source
-  file. Put `@usage` in that example file's leading `/*** ... */` comment so Paradox promotes the
-  runnable example into the README Usage section. Do not create dedicated `readme-usage`,
-  `usage-readme`, `readmeUsage`, or equivalent source modules whose only purpose is feeding README
-  usage text.
+  file. A package that opts into `@usage` must have exactly one example combining `@usage`,
+  `@readme`, and `@title`; additional `@usage` examples remain full-doc-only. Do not create
+  dedicated `readme-usage`, `usage-readme`, `readmeUsage`, or equivalent source modules whose
+  only purpose is feeding README usage text.
+- Configuration documentation is optional until a package opts in. Once it does, the canonical schema
+  is `src/types/config.ts` with exactly one root type/interface carrying `@config`, `@readme`,
+  and `@title`.
 - Update documentation sources in the pull request, including repository-owned manual documentation
   outside the configured generated output. Never hand-edit generated README or Paradox artifacts.
 - Generated documentation is release-owned. Ordinary feature pull requests must not regenerate or

package/dist/tools/workflows/index.js

@@ -1,8 +1,8 @@
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 import { resolveApmReleaseCommandAsync } from '../../features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.js';
 import { resolveStructureReleaseCommandAsync } from '../../features/structure-descriptor-generation/adapters/outbound/resolveStructureReleaseCommandAsync.js';
-import { bunRuntimePolicy, nodeRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
 import { resolvePkgvizAuditPolicyAsync } from '../../policy/resolvePkgvizAuditPolicyAsync.js';
 import { readCurrentDoctorVersion } from './readCurrentDoctorVersion.js';
 import { renderRenovateConfigAsync } from './renderRenovateConfigAsync.js';
@@ -38,9 +38,9 @@ function createWorkflowDefinition(relativePath, sourcePath) {
         render: async (targetDirectory) => await renderWorkflowAsync(sourceUrl, {
             apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
             structureReleaseCommand: await resolveStructureReleaseCommandAsync(targetDirectory),
-            bunVersion: bunRuntimePolicy.version,
+            bunVersion: REPOSITORY_POLICY.runtime.bun.version,
             doctorVersion: readCurrentDoctorVersion(),
-            nodeVersion: nodeRuntimePolicy.setupVersion,
+            nodeVersion: REPOSITORY_POLICY.runtime.node.setupVersion,
             pkgvizAudit: await resolvePkgvizAuditPolicyAsync(targetDirectory),
         }),
     };
@@ -53,9 +53,9 @@ function createRenovateWorkflowDefinition() {
         render: async (targetDirectory) => await renderRenovateWorkflowAsync(sourceUrl, targetDirectory, {
             apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
             structureReleaseCommand: await resolveStructureReleaseCommandAsync(targetDirectory),
-            bunVersion: bunRuntimePolicy.version,
+            bunVersion: REPOSITORY_POLICY.runtime.bun.version,
             doctorVersion: readCurrentDoctorVersion(),
-            nodeVersion: nodeRuntimePolicy.setupVersion,
+            nodeVersion: REPOSITORY_POLICY.runtime.node.setupVersion,
         }),
     };
 }

package/dist/tools/workflows/renderWorkflowAsync.js

@@ -1,14 +1,14 @@
 import { readFile } from 'node:fs/promises';
-import { changesetsPolicy } from '../../policy/changesetsPolicy.js';
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 /*** Renders one workflow template with the canonical runtime, Doctor, and Changesets policy. */
 export async function renderWorkflowAsync(sourceUrl, policy) {
     const template = await readFile(sourceUrl, 'utf8');
     const rendered = template
         .replaceAll(BUN_VERSION_TOKEN, policy.bunVersion)
         .replaceAll(PKGVIZ_AUDIT_STEPS_TOKEN, renderPkgvizAuditSteps(policy))
-        .replaceAll(CHANGESETS_PUBLISH_COMMAND_TOKEN, changesetsPolicy.workflowCommands.publish)
-        .replaceAll(CHANGESETS_STATUS_COMMAND_TOKEN, changesetsPolicy.workflowCommands.status)
-        .replaceAll(CHANGESETS_VERSION_COMMAND_TOKEN, changesetsPolicy.workflowCommands.version)
+        .replaceAll(CHANGESETS_PUBLISH_COMMAND_TOKEN, REPOSITORY_POLICY.changesets.workflowCommands.publish)
+        .replaceAll(CHANGESETS_STATUS_COMMAND_TOKEN, REPOSITORY_POLICY.changesets.workflowCommands.status)
+        .replaceAll(CHANGESETS_VERSION_COMMAND_TOKEN, REPOSITORY_POLICY.changesets.workflowCommands.version)
         .replaceAll(DOCTOR_VERSION_TOKEN, policy.doctorVersion)
         .replaceAll('__ANKH_APM_RELEASE_COMMAND__', policy.apmReleaseCommand ?? './node_modules/.bin/ankhorage-apm-release')
         .replaceAll('__ANKH_STRUCTURE_RELEASE_COMMAND__', policy.structureReleaseCommand ?? './node_modules/.bin/ankhorage-structure')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.21.3",
-  "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
+  "version": "2.0.0",
+  "description": "Shared tooling, repository automation, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
   "bugs": {
@@ -82,10 +82,6 @@
       "types": "./dist/tools/knip/index.d.ts",
       "import": "./dist/tools/knip/index.js"
     },
-    "./policy": {
-      "types": "./dist/policy/bunRuntimePolicy.d.ts",
-      "import": "./dist/policy/bunRuntimePolicy.js"
-    },
     "./prettier": {
       "import": "./dist/tools/prettier/index.cjs",
       "require": "./dist/tools/prettier/index.cjs",
@@ -146,12 +142,13 @@
     "prettier": "^3.9.9",
     "typescript-eslint": "^8.70.1",
     "@ankhorage/contracts": "^22.8.1",
-    "typescript": "~6.0.3"
+    "typescript": "~6.0.3",
+    "@ankhorage/policy": "^0.3.1"
   },
   "devDependencies": {
     "@ankhorage/paradox": "^0.1.26",
     "@ankhorage/ankh": "^0.10.4",
-    "@ankhorage/doctor": "0.11.0",
+    "@ankhorage/doctor": "0.11.3",
     "@techstark/opencv-js": "^5.0.0-release.1",
     "@types/bun": "^1.4.1",
     "@types/node": "^26.6.2",

package/dist/policy/bunRuntimePolicy.d.ts

@@ -1,17 +0,0 @@
-export declare const bunRuntimePolicy: {
-    readonly packageManager: "bun@1.4.2";
-    readonly typesRange: "^1.4.1";
-    readonly version: "1.4.2";
-};
-/**
- * Canonical Node LTS baseline for Node-based Ankhorage tooling and CI execution.
- *
- * Bun remains the repository package manager/primary command runtime where configured;
- * this policy makes Node-based tooling deterministic instead of inheriting the ambient
- * Node version from a CI runner image.
- */
-export declare const nodeRuntimePolicy: {
-    readonly engineRange: "24.x";
-    readonly major: 24;
-    readonly setupVersion: "24";
-};

package/dist/policy/bunRuntimePolicy.js

@@ -1,25 +0,0 @@
-/**
- * Canonical runtime/tooling policies for Ankhorage repositories.
- *
- * Import these from `@ankhorage/devtools/policy` when another package needs to inspect
- * the managed Bun or Node baseline without defining an independent version authority.
- */
-const BUN_VERSION = '1.4.2';
-const BUN_TYPES_VERSION = '1.4.1';
-export const bunRuntimePolicy = {
-    packageManager: `bun@${BUN_VERSION}`,
-    typesRange: `^${BUN_TYPES_VERSION}`,
-    version: BUN_VERSION,
-};
-/**
- * Canonical Node LTS baseline for Node-based Ankhorage tooling and CI execution.
- *
- * Bun remains the repository package manager/primary command runtime where configured;
- * this policy makes Node-based tooling deterministic instead of inheriting the ambient
- * Node version from a CI runner image.
- */
-export const nodeRuntimePolicy = {
-    engineRange: '24.x',
-    major: 24,
-    setupVersion: '24',
-};

package/dist/policy/changesetsPolicy.d.ts

@@ -1,19 +0,0 @@
-export declare const changesetsPolicy: {
-    readonly packageName: "@changesets/cli";
-    readonly binaryName: "ankhorage-changeset";
-    readonly packageScripts: {
-        readonly changeset: "ankhorage-changeset";
-        readonly 'changeset:status': "ankhorage-changeset status --since=origin/main";
-        readonly 'version-packages': "ankhorage-changeset version";
-    };
-    readonly ownerPackageScripts: {
-        readonly changeset: "bun src/cli/bin/changeset.ts";
-        readonly 'changeset:status': "bun src/cli/bin/changeset.ts status --since=origin/main";
-        readonly 'version-packages': "bun src/cli/bin/changeset.ts version";
-    };
-    readonly workflowCommands: {
-        readonly status: "bun run changeset:status";
-        readonly version: "bun run version-packages";
-        readonly publish: "bun run changeset -- publish";
-    };
-};

package/dist/policy/changesetsPolicy.js

@@ -1,19 +0,0 @@
-export const changesetsPolicy = {
-    packageName: '@changesets/cli',
-    binaryName: 'ankhorage-changeset',
-    packageScripts: {
-        changeset: 'ankhorage-changeset',
-        'changeset:status': 'ankhorage-changeset status --since=origin/main',
-        'version-packages': 'ankhorage-changeset version',
-    },
-    ownerPackageScripts: {
-        changeset: 'bun src/cli/bin/changeset.ts',
-        'changeset:status': 'bun src/cli/bin/changeset.ts status --since=origin/main',
-        'version-packages': 'bun src/cli/bin/changeset.ts version',
-    },
-    workflowCommands: {
-        status: 'bun run changeset:status',
-        version: 'bun run version-packages',
-        publish: 'bun run changeset -- publish',
-    },
-};

package/dist/types/bunPolicy.d.ts

@@ -1,5 +0,0 @@
-export interface BunPolicy {
-    readonly packageManager: string;
-    readonly typesRange: string;
-    readonly version: string;
-}

package/dist/types/bunPolicy.js

@@ -1 +0,0 @@
-export {};