changeledger 0.3.0 → 0.5.0

package/AGENTS.md

@@ -5,15 +5,21 @@ under `.changeledger/changes/`, persistent truth under `.changeledger/specs/`.
 
 <!-- changeledger -->
 > [!IMPORTANT]
-> This repo uses **ChangeLedger**. Read and follow [`.changeledger/AGENTS.md`](.changeledger/AGENTS.md)
-> (the change contract). If it is missing, run `changeledger register`.
+> This repo uses **ChangeLedger**. Before creating or modifying files, run
+> `changeledger context` (or `changeledger context <change-id>`) and follow its output.
+> If the command is unavailable, stop and restore/install ChangeLedger; do not proceed from memory.
 
-The **canonical ChangeLedger contract** (the convention every consuming repo
-follows) is shipped as [`templates/AGENTS.md`](templates/AGENTS.md) and linked
-into each repo as `.changeledger/AGENTS.md`. Edit the convention there, not here.
+The canonical ChangeLedger contract is split into task-focused fragments under
+[`templates/contract/`](templates/contract/). The deterministic
+`changeledger context` command composes them; consuming repos keep only the
+bootstrap above, not a linked or copied contract.
 
 ## Project-specific notes
 
+- Product evolution follows the complexity budget and no-goals in
+  [`INTENT.md`](INTENT.md): prefer observed problems and a small deterministic,
+  local-first core; AI orchestration, memory and cloud services belong only in
+  optional integrations.
 - Managed with **pnpm**; lint/format via **Biome**. Runtime dependencies are
   allowed only when they are mature and justified: the CLI uses `yaml` for
   config/frontmatter parsing, and the viewer uses `lit-html`, `marked`,
@@ -21,5 +27,5 @@ into each repo as `.changeledger/AGENTS.md`. Edit the convention there, not here
 - `pnpm verify` (lint + test + `changeledger check`) is the full quality gate. The
   versioned `hooks/pre-commit` runs `lint-staged`, `pnpm test` and `changeledger check`
   so staged formatting stays compatible with partial commits.
-- The contract you edit for the convention is `templates/AGENTS.md` — it is the
-  artifact that `changeledger init`/`register` symlink into other repos.
+- Edit the convention in `templates/contract/`; keep each rule in one fragment
+  so task contexts compose without duplicated truth.

package/README.md

@@ -27,9 +27,10 @@ changeledger init
 changeledger view
 ```
 
-`changeledger init` creates `.changeledger/`, gives the project a stable identity and links the
-installed agent contract. The repository keeps only its configuration and
-documents; the CLI and viewer remain in the global package.
+`changeledger init` creates `.changeledger/`, gives the project a stable identity
+and installs a small context bootstrap in the project-owned `AGENTS.md`. The
+repository keeps only its configuration and documents; the CLI, viewer and
+canonical contract fragments remain in the global package.
 
 ## The workflow
 
@@ -62,8 +63,8 @@ other tools discover it through the repository's `AGENTS.md` reference.
 
 With the default Definition of Ready policy, `changeledger check` verifies that acceptance
 criteria are test-grade and mapped to actionable tasks. Repositories doing
-exploratory work can set `tdd: false`; the complete rules live in
-[`AGENTS.md`](AGENTS.md).
+exploratory work can set `tdd: false`; run `changeledger context spec` or
+`changeledger context implement` for the complete task-specific rules.
 
 ## Essential commands
 
@@ -71,7 +72,7 @@ exploratory work can set `tdd: false`; the complete rules live in
 
 ```sh
 changeledger init                         # initialize and register the current repository
-changeledger register                     # relink a moved or freshly cloned repository
+changeledger register                     # refresh registration and the context bootstrap
 changeledger view                         # view every registered project
 changeledger view .                       # view only the current project
 changeledger check [id]                   # validate the repository or one change
@@ -128,17 +129,25 @@ CI:
 changeledger check || exit 1
 ```
 
-The contract itself ships with the CLI and is linked as `.changeledger/AGENTS.md`. It is
-per-machine and gitignored, so upgrades do not leave committed copies behind.
-Run `changeledger register` after cloning, moving a repository or updating the global
-installation.
+The contract ships as task-focused fragments and is compiled on demand:
+
+```sh
+changeledger context                    # minimal non-negotiable core
+changeledger context <change-id>        # lifecycle-aware rules + selected change
+changeledger context review             # explicit task mode
+```
+
+`init` places a small fail-closed bootstrap in the project-owned `AGENTS.md`;
+there is no linked or copied contract under `.changeledger/`. Run
+`changeledger register` after upgrading to refresh that bootstrap and migrate
+legacy repositories.
 
 ## Compatibility and security
 
 - Node.js **24+**.
 - Tested on Linux, macOS and Windows.
-- On Windows, contract linking uses a symlink when permitted and falls back to a
-  copy when Developer Mode or administrator privileges are unavailable.
+- No symlink privileges are required on Windows; context fragments remain in the
+  installed package and the CLI prints them on demand.
 - The viewer binds to loopback and treats repository content as untrusted input.
   See [`SECURITY.md`](SECURITY.md) for the threat model and private reporting
   instructions.
@@ -151,7 +160,7 @@ latest `0.x` release to receive fixes.
 
 Contributions are welcome. Development setup, quality gates and repository
 conventions live in [`CONTRIBUTING.md`](CONTRIBUTING.md). The canonical agent
-contract is [`AGENTS.md`](AGENTS.md).
+contract is composed from [`templates/contract/`](templates/contract/).
 
 ## Language policy
 

package/bin/changeledger.mjs

@@ -13,6 +13,7 @@ import {
   task,
 } from '../src/commands/agent.mjs';
 import { check } from '../src/commands/check.mjs';
+import { context } from '../src/commands/context.mjs';
 import { graduate, pendingGraduation, skipGraduation } from '../src/commands/graduate.mjs';
 import { init } from '../src/commands/init.mjs';
 import { newChange } from '../src/commands/new.mjs';
@@ -24,10 +25,11 @@ import { nowUtc } from '../src/paths.mjs';
 const USAGE = `ChangeLedger (changeledger)
 
   changeledger init                          set up .changeledger/ in the current repo (+ register it)
-  changeledger register                      (re)link this repo's path in the global registry
+  changeledger register                      refresh registration and context bootstrap
   changeledger new <type> <slug> <title>     scaffold a new change (slug is the English filename)
   changeledger view [port]                   launch the local viewer (default port 4040)
   changeledger check [id] [--json]           validate the repo or one change
+  changeledger context [mode|change-id]       print deterministic task context
   changeledger status <id> <status>          move a change's lifecycle status
   changeledger discard <id> "<reason>"       discard a change (terminal; keeps the record)
   changeledger review <id> pass              independent review passed → in-validation
@@ -78,7 +80,7 @@ program
 
 program
   .command('register')
-  .description("(re)link this repo's path in the global registry")
+  .description('refresh registration and context bootstrap')
   .action(
     action(() => {
       const { id, path: p } = registerRepo();
@@ -122,6 +124,12 @@ program
     }
   });
 
+program
+  .command('context')
+  .description('print deterministic task context')
+  .argument('[mode-or-change-id]')
+  .action(action((input) => context(input)));
+
 program
   .command('status')
   .description("move a change's lifecycle status")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

package/src/check.mjs

@@ -15,9 +15,9 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
 
   checkConfig(config, (c, message) => err(c ?? { name: '.changeledger/config.yml' }, message));
 
-  const statuses = config.statuses ?? [];
-  const types = config.types ?? {};
-  const canonical = config.stages ?? [];
+  const statuses = Array.isArray(config.statuses) ? config.statuses : [];
+  const types = isMapping(config.types) ? config.types : {};
+  const canonical = Array.isArray(config.stages) ? config.stages : [];
 
   // Scope: a single change (fast, post-write check) or the whole repo.
   let targets = changes;
@@ -64,7 +64,8 @@ export function checkRepo({ config, changes, specs = [], releases = [] }, opts =
     const ordered = [...known].sort((a, b) => canonical.indexOf(a) - canonical.indexOf(b));
     if (known.join(',') !== ordered.join(',')) err(c, 'stages are out of canonical order');
 
-    const active = types[fm.type]?.stages;
+    const typeDefinition = isMapping(types[fm.type]) ? types[fm.type] : null;
+    const active = Array.isArray(typeDefinition?.stages) ? typeDefinition.stages : null;
     if (active) {
       for (const k of active)
         if (!present.includes(k)) err(c, `missing active stage "## ${k}" for type ${fm.type}`);
@@ -365,9 +366,20 @@ function misplacedVerificationSuffix(task, config) {
 }
 
 function readinessConfig(config) {
+  const readiness = isMapping(config?.readiness) ? config.readiness : null;
   return {
-    target_patterns: config?.readiness?.target_patterns ?? ['src/**'],
-    verification_patterns: config?.readiness?.verification_patterns ?? ['test/**'],
+    target_patterns:
+      readiness && 'target_patterns' in readiness
+        ? Array.isArray(readiness.target_patterns)
+          ? readiness.target_patterns
+          : []
+        : ['src/**'],
+    verification_patterns:
+      readiness && 'verification_patterns' in readiness
+        ? Array.isArray(readiness.verification_patterns)
+          ? readiness.verification_patterns
+          : []
+        : ['test/**'],
   };
 }
 
@@ -445,11 +457,21 @@ function checkConfig(config, err) {
   }
   if ('statuses' in c && !Array.isArray(c.statuses)) err(null, 'config "statuses" must be a list');
   if ('stages' in c && !Array.isArray(c.stages)) err(null, 'config "stages" must be a list');
+  if ('types' in c && !isMapping(c.types)) err(null, 'config "types" must be a mapping');
   if ('readiness' in c) checkReadinessConfig(c.readiness, err);
-  if ('release' in c) checkReleaseConfig(c.release, c.types ?? {}, err);
+  const configuredTypes = isMapping(c.types) ? c.types : {};
+  if ('release' in c) checkReleaseConfig(c.release, configuredTypes, err);
   const canonical = Array.isArray(c.stages) ? c.stages : [];
-  for (const [type, def] of Object.entries(c.types ?? {})) {
-    for (const s of def?.stages ?? []) {
+  for (const [type, def] of Object.entries(configuredTypes)) {
+    if (!isMapping(def)) {
+      err(null, `config type "${type}" must be a mapping`);
+      continue;
+    }
+    if (!Array.isArray(def.stages)) {
+      err(null, `config type "${type}": stages must be a list`);
+      continue;
+    }
+    for (const s of def.stages) {
       if (!canonical.includes(s))
         err(null, `config type "${type}" references unknown stage "${s}"`);
     }
@@ -458,6 +480,10 @@ function checkConfig(config, err) {
   }
 }
 
+function isMapping(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
 function checkReleaseConfig(release, types, err) {
   if (!release || typeof release !== 'object' || Array.isArray(release)) {
     err(null, 'config "release" must be a mapping');

package/src/commands/agent.mjs

@@ -59,7 +59,7 @@ export function status(
 }
 
 // Records the verdict of the independent review (run by a delegated subagent
-// with clean context — see AGENTS.md §6). `pass` advances to human validation;
+// with clean context — see `changeledger context review`). `pass` advances to human validation;
 // `fail` routes it back: `retry` for a defect inside the contract (the
 // implementer fixes), `block` for one that escalates to a human. Requires the
 // change to be in-review.

package/src/commands/check.mjs

@@ -22,7 +22,7 @@ export function check(args = [], cwd = process.cwd(), output = console) {
 
   const { errors, warnings } = checkRepo(repo, { id });
 
-  // Discovery validation needs the filesystem (root contract, symlink), so it
+  // Discovery validation needs the filesystem (root contract bootstrap), so it
   // lives here, not in the pure validator. Repo-wide only.
   if (!id) {
     for (const message of checkContract(repo.repoRoot, repo.changeledgerDir)) {

package/src/commands/context.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseChange } from '../change.mjs';
+import { findChangeledgerDir } from '../config.mjs';
+import { contractTemplatesDir } from '../paths.mjs';
+import { resolveChange } from '../repo.mjs';
+
+const MODES = ['implement', 'review', 'spec', 'release'];
+const MODE_CONTEXT = {
+  implement: ['core', 'implement', 'readiness'],
+  review: ['core', 'review'],
+  spec: ['core', 'spec', 'readiness'],
+  release: ['core', 'release'],
+};
+const STATUS_CONTEXT = {
+  draft: { mode: 'spec', fragments: MODE_CONTEXT.spec },
+  approved: { mode: 'implement', fragments: MODE_CONTEXT.implement },
+  'in-progress': { mode: 'implement', fragments: MODE_CONTEXT.implement },
+  'in-review': { mode: 'review', fragments: ['core', 'review'] },
+  blocked: { mode: 'blocked', fragments: ['core', 'blocked'] },
+  'in-validation': { mode: 'validation', fragments: ['core', 'validation'] },
+  done: { mode: 'close', fragments: ['core', 'close'] },
+  discarded: { mode: 'discarded', fragments: ['core', 'discarded'] },
+};
+
+function fragment(name) {
+  return fs.readFileSync(path.join(contractTemplatesDir, `${name}.md`), 'utf8').trim();
+}
+
+function compose(mode, fragments, changeText) {
+  const sections = [`Mode: ${mode}`, ...fragments.map(fragment)];
+  if (changeText) sections.push('---\n\n# Selected change\n', changeText.trim());
+  return `${sections.join('\n\n')}\n`;
+}
+
+function requireRepo(cwd) {
+  if (!findChangeledgerDir(cwd)) {
+    throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
+  }
+}
+
+export function buildContext(input, cwd = process.cwd()) {
+  requireRepo(cwd);
+  if (!input) return compose('core', ['core']);
+  if (MODES.includes(input)) return compose(input, MODE_CONTEXT[input]);
+
+  let resolved;
+  try {
+    resolved = resolveChange(cwd, input);
+  } catch {
+    throw new Error(
+      `Unknown context "${input}" — valid modes: ${MODES.join(', ')} (or pass a change id)`,
+    );
+  }
+
+  const text = fs.readFileSync(resolved.file, 'utf8');
+  const status = parseChange(text).frontmatter.status;
+  const selected = STATUS_CONTEXT[status];
+  if (!selected) throw new Error(`No context mapping for change status "${status}"`);
+  return compose(selected.mode, selected.fragments, text);
+}
+
+export function context(input, cwd = process.cwd(), output = console.log) {
+  output(buildContext(input, cwd).trimEnd());
+}

package/src/commands/init.mjs

@@ -2,20 +2,19 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeFileAtomic } from '../atomic-write.mjs';
-import { ensureGitignore, ensureReference, linkContract, rootContract } from '../contract.mjs';
+import { ensureReference, rootContract } from '../contract.mjs';
 import { templatesDir } from '../paths.mjs';
 import { register } from '../registry.mjs';
 import { serializeScalar } from '../yaml.mjs';
 
-// Sets up `.changeledger/` in the repo, gives it a stable identity, links the installed
-// AGENTS.md contract into `.changeledger/`, references it from the project's root
+// Sets up `.changeledger/`, installs the context bootstrap in the project-owned
 // AGENTS.md, and registers the repo in the global registry.
 export function init(cwd = process.cwd()) {
   const repoRoot = path.resolve(cwd);
   const changeledgerDir = path.join(repoRoot, '.changeledger');
   if (fs.existsSync(changeledgerDir)) {
     throw new Error(
-      '.changeledger/ already exists. Use `changeledger register` to (re)link this repo.',
+      '.changeledger/ already exists. Use `changeledger register` to refresh this repo.',
     );
   }
   // The root AGENTS.md is the project's own contract; we reference the tool's
@@ -34,9 +33,7 @@ export function init(cwd = process.cwd()) {
     `${fs.readFileSync(path.join(templatesDir, 'config.yml'), 'utf8')}\n# Project identity (stable; the global registry maps it to a path)\nproject_id: "${id}"\nproject_name: ${serializeScalar(name)}\n`,
   );
 
-  linkContract(changeledgerDir);
   ensureReference(repoRoot);
-  ensureGitignore(repoRoot);
 
   register({ id, name, path: repoRoot });
   return changeledgerDir;

package/src/commands/new.mjs

@@ -11,7 +11,7 @@ const LOCK_MTIME_STALE_MS = 30_000;
 
 // Scaffolds a new change file with the active stages for its type.
 // `slug` is the English filename slug (structure); `title` is the content title
-// (repo language). See AGENTS.md §7-§8.
+// (repo language). See `changeledger context spec`.
 export function newChange({ type, slug, title, owner, now }, cwd = process.cwd()) {
   const changeledgerDir = findChangeledgerDir(cwd);
   if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');

package/src/commands/register.mjs

@@ -1,12 +1,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { findChangeledgerDir, loadConfig } from '../config.mjs';
-import { ensureGitignore, ensureReference, linkContract, rootContract } from '../contract.mjs';
+import {
+  ensureReference,
+  removeLegacyContract,
+  removeLegacyGitignore,
+  rootContract,
+} from '../contract.mjs';
 import { register } from '../registry.mjs';
 
-// (Re)links the current repo's path to its config project_id in the global
-// registry, and regenerates the per-machine `.changeledger/AGENTS.md` contract link. Use
-// after moving the repo or cloning it on another machine.
+// Refreshes the repo bootstrap and registry path. Also migrates the per-machine
+// contract artifact left by legacy versions.
 export function registerRepo(cwd = process.cwd()) {
   const changeledgerDir = findChangeledgerDir(cwd);
   if (!changeledgerDir) throw new Error('Not a ChangeLedger repo. Run `changeledger init` first.');
@@ -19,8 +23,8 @@ export function registerRepo(cwd = process.cwd()) {
   const repoRoot = path.dirname(changeledgerDir);
   const name = config.project_name || path.basename(repoRoot);
 
-  linkContract(changeledgerDir);
-  ensureGitignore(repoRoot);
+  removeLegacyContract(changeledgerDir);
+  removeLegacyGitignore(repoRoot);
   if (fs.existsSync(rootContract(repoRoot))) ensureReference(repoRoot);
 
   register({ id: config.project_id, name, path: repoRoot });

package/src/commands/view.mjs

@@ -5,7 +5,16 @@ import { resolveProjects } from '../viewer/domain.mjs';
 import { createRequestListener, staticFile } from '../viewer/server/router.mjs';
 import { hostnameOf, isAuthorizedWrite, isLocalHost } from '../viewer/server/security.mjs';
 
-export { changeStatus, resolveProjects, searchProjects, serialize } from '../viewer/domain.mjs';
+export {
+  changeStatus,
+  readProjectConfig,
+  repairProjectPath,
+  resolveProjects,
+  saveProjectConfig,
+  searchProjects,
+  serialize,
+  unregisterProject,
+} from '../viewer/domain.mjs';
 export { createRequestListener, hostnameOf, isAuthorizedWrite, isLocalHost, staticFile };
 
 export async function view(args = [], cwd = process.cwd()) {

package/src/config.mjs

@@ -2,13 +2,16 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from './yaml.mjs';
 
-// Walk up from `start` looking for a `.changeledger/` directory. Returns its absolute path
-// or null if none is found.
+// Walk up from `start` looking for a project `.changeledger/config.yml`. The
+// config file is the marker: `~/.changeledger/` may exist only as global state
+// and must not be mistaken for a repository (notably when Windows temp dirs
+// live below the user's home). Returns the project data directory or null.
 export function findChangeledgerDir(start = process.cwd()) {
   let dir = path.resolve(start);
   for (;;) {
     const candidate = path.join(dir, '.changeledger');
-    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+    const config = path.join(candidate, 'config.yml');
+    if (fs.existsSync(config) && fs.statSync(config).isFile()) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) return null;
     dir = parent;

package/src/contract.mjs

@@ -1,29 +1,49 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { writeFileAtomic } from './atomic-write.mjs';
-import { agentsTemplate } from './paths.mjs';
 
-// The tool's contract (templates/AGENTS.md) is a tool artifact, not a project
-// artifact. Each repo links to the installed copy via `.changeledger/AGENTS.md` (a
-// per-machine, gitignored symlink) and points its own contract files at that
-// link. We never copy the contract (it would drift) nor commit the symlink (it
-// would dangle on another machine). See change #20260614-151759.
-
-// Project-owned contract files that should reference the linked contract. The
-// root AGENTS.md is required by `init`; CLAUDE.md is referenced when present.
 const CONTRACT_FILES = ['AGENTS.md', 'CLAUDE.md'];
-
 const MARKER = '<!-- changeledger -->';
-const REFERENCE = `${MARKER}
+const LEGACY_ENTRY = '.changeledger/AGENTS.md';
+// Exact SHA-256 digests of every historical templates/AGENTS.md payload. A
+// regular file is removed only when it is byte-identical to a contract version
+// ChangeLedger actually shipped; headings or other heuristics are not enough.
+const LEGACY_CONTRACT_HASHES = new Set([
+  '92a6d22c9985dce2d15724d20e2d5c0f1178d82dc56d28e339b72c7a27574c6f',
+  '4701b260d0cc39098f3b942ed2b1969f00a84e7b77a4e107070fedef0fda7d0d',
+  '30b3ce1768655ebee2be2b88328ba860293d8bbbe55e12a5aacc8177d7d02c9b',
+  'd36d17f99505f2b47a7ceea8f078618f652807463d5d60a83ca95f940d5a9c35',
+  '1175cc4bcc884d792cdde2338b3c72b336bcb66b47555d6e5938d756acdea635',
+  'f605adad9192286bc2cda45aebb5a12dab5b3c199924789398684b79b55811',
+  '05e06c8e9dc45ac41ff38b47075b22492c30f3f1a7019371293be10351aada77',
+  '9816e4d14f70dad268f9b89ad49094665997bf62f0b773a05fe8eed17eebc9de',
+  '1b5439055e52a1bb72f72b99cbd2842b2118776fb80e262175d584a335e07e5f',
+  '6fe7a03f699ffa875c1ef4bc2d59b451058d6ab4c3c8824cc220ae031d068480',
+  'd56ec9ef5c1bd71464d9d9bc2a772c42cce103f336ebba61106855c8011bca6f',
+  '071ed83e79589ec0362e4e99ee80cb4f7a839f2a810cf59dbf056c46e342a09c',
+  '1148a1b69ce035a695c64f0df1aaaedcbeeed669b5b774c52f7b136e9f5fe4f9',
+  '25d4508b0b60aa939e81d1e83383f90e7a41feacb6cb2f12fab6548cebb77ca1',
+  '37e1ffe059c0d26b07566597607c41d42df3e9548830d42413dd8d2afd62aa86',
+  '60519091c785977299725e4f2f3207b83828bfc56d94a989adf13bd0fc9bb174',
+  '6e201bb60337c9b0869c6c769272c82abc466330f82c662bb023a74ad0b8fa92',
+  '80e2560e01cfae87455177b54f77845b657764338d3bf3507119e3e1ff289bcd',
+  '7a126595a0b5de0b58eec9db38ee6d1654caf0b42df29d181692c382abe213c6',
+  '2e839be3ad9458feebcfd8ca979f9173b1f63b514939903ea8f9f03517528f88',
+  'f10407e809fc679d11e442d57c92a4b82d0647f06946bb42c7daccedf76873ec',
+  '99a42380f3835e1f706b986b86e58e33f12d68de4a69d94eb50845e790e05f71',
+]);
+
+export const REFERENCE = `${MARKER}
 > [!IMPORTANT]
-> This repo uses **ChangeLedger**. Read and follow \`.changeledger/AGENTS.md\` (the change
-> contract). If it is missing, run \`changeledger register\`.
+> This repo uses **ChangeLedger**. Before creating or modifying files, run
+> \`changeledger context\` (or \`changeledger context <change-id>\`) and follow its output.
+> If the command is unavailable, stop and restore/install ChangeLedger; do not proceed from memory.
 `;
 
 export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');
 export const rootContract = (repoRoot) => path.join(repoRoot, 'AGENTS.md');
 
-// A real, non-symlink file we may safely append to.
 function isPlainFile(file) {
   try {
     return fs.lstatSync(file).isFile();
@@ -32,69 +52,85 @@ function isPlainFile(file) {
   }
 }
 
-// Create (or refresh) the `.changeledger/AGENTS.md` symlink to the installed contract.
-// Idempotent and tolerant of a pre-existing/dangling link.
-export function linkContract(changeledgerDir) {
-  const link = contractLink(changeledgerDir);
-  try {
-    fs.lstatSync(link);
-    fs.unlinkSync(link);
-  } catch {
-    // no existing link — nothing to remove
-  }
-  try {
-    fs.symlinkSync(agentsTemplate, link);
-  } catch {
-    // Windows without Developer Mode/admin cannot create symlinks. Fall back to
-    // a copy so the contract is still present; `changeledger register` refreshes it if the
-    // installed contract changes.
-    writeFileAtomic(link, fs.readFileSync(agentsTemplate, 'utf8'));
-  }
-  return link;
+function replaceReference(text) {
+  const start = text.indexOf(MARKER);
+  if (start === -1) return `${text}${text.endsWith('\n') ? '' : '\n'}\n${REFERENCE}`;
+  const tail = text.slice(start).split('\n');
+  let consumed = 1;
+  while (consumed < tail.length && tail[consumed].startsWith('>')) consumed += 1;
+  const before = text.slice(0, start);
+  const after = tail.slice(consumed).join('\n').replace(/^\n+/, '');
+  return `${before}${REFERENCE}${after ? `\n${after}` : ''}`;
 }
 
-// Append the reference block to each present, non-symlink contract file unless
-// already there. Symlinks are skipped (appending would write into their target).
+// Add or replace the managed bootstrap block in project-owned agent files.
 export function ensureReference(repoRoot) {
   const touched = [];
   for (const name of CONTRACT_FILES) {
     const file = path.join(repoRoot, name);
     if (!isPlainFile(file)) continue;
     const text = fs.readFileSync(file, 'utf8');
-    if (text.includes(MARKER)) continue;
-    writeFileAtomic(file, `${text}${text.endsWith('\n') ? '' : '\n'}\n${REFERENCE}`);
+    const updated = replaceReference(text);
+    if (updated === text) continue;
+    writeFileAtomic(file, updated);
     touched.push(name);
   }
   return touched;
 }
 
-// Ensure `.changeledger/AGENTS.md` is gitignored (it is a per-machine artifact).
-export function ensureGitignore(repoRoot) {
+// Remove only artifacts known to be managed by legacy ChangeLedger versions.
+// Unknown regular files fail closed instead of being deleted.
+export function removeLegacyContract(changeledgerDir, knownHashes = LEGACY_CONTRACT_HASHES) {
+  const file = contractLink(changeledgerDir);
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    fs.unlinkSync(file);
+    return true;
+  }
+  if (stat.isFile()) {
+    const digest = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    if (knownHashes.has(digest)) {
+      fs.unlinkSync(file);
+      return true;
+    }
+  }
+  throw new Error(
+    '`.changeledger/AGENTS.md` is not a recognized legacy ChangeLedger contract; move or remove it manually, then run `changeledger register` again',
+  );
+}
+
+export function removeLegacyGitignore(repoRoot) {
   const file = path.join(repoRoot, '.gitignore');
-  const entry = '.changeledger/AGENTS.md';
-  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
-  if (text.split('\n').some((l) => l.trim() === entry)) return false;
-  writeFileAtomic(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${entry}\n`);
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  const kept = lines.filter((line) => line !== LEGACY_ENTRY);
+  if (kept.length === lines.length) return false;
+  writeFileAtomic(file, kept.join('\n'));
   return true;
 }
 
-// IO-level discovery validation (repo-wide). Returns a list of error messages.
-export function checkContract(repoRoot, changeledgerDir) {
+export function checkContract(repoRoot) {
   const errors = [];
   const root = rootContract(repoRoot);
   if (!fs.existsSync(root)) {
     errors.push('missing AGENTS.md at the repo root (ChangeLedger contract reference lives here)');
   }
-  // Every present, non-symlink contract file must carry the reference.
   for (const name of CONTRACT_FILES) {
     const file = path.join(repoRoot, name);
     if (!isPlainFile(file)) continue;
-    if (!fs.readFileSync(file, 'utf8').includes(MARKER)) {
+    const text = fs.readFileSync(file, 'utf8');
+    if (!text.includes(MARKER)) {
       errors.push(`${name} has no ChangeLedger reference — run \`changeledger register\``);
+    } else if (!text.includes(REFERENCE.trim())) {
+      errors.push(`${name} has an outdated ChangeLedger reference — run \`changeledger register\``);
     }
   }
-  if (!fs.existsSync(contractLink(changeledgerDir))) {
-    errors.push('`.changeledger/AGENTS.md` is missing or dangling — run `changeledger register`');
-  }
   return errors;
 }

package/src/paths.mjs

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 
 export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export const templatesDir = path.join(packageRoot, 'templates');
-export const agentsTemplate = path.join(templatesDir, 'AGENTS.md');
+export const contractTemplatesDir = path.join(templatesDir, 'contract');
 export const publicDir = path.join(packageRoot, 'src', 'viewer', 'public');
 
 // ISO 8601 UTC at second precision, matching the change `created`/task convention.