changeledger 0.3.0

package/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md — ChangeLedger (project's own contract)
+
+This is the ChangeLedger repo itself. It dogfoods its own format: changes live
+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`.
+
+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.
+
+## Project-specific notes
+
+- 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`,
+  `dompurify` and `mermaid` for templating, Markdown, sanitization and diagrams.
+- `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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto Ruiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# ChangeLedger (`changeledger`)
+
+> Turn conversations into buildable changes.
+
+ChangeLedger is a local-first workflow for planning software changes with coding
+agents before implementation begins. Features, bugs, audits and refactors become
+reviewable documents with an enforced lifecycle, acceptance criteria, tasks and
+persistent product truth.
+
+Its human layer is a local viewer: instead of reading scattered Markdown files,
+you get a searchable board across all registered projects, rendered
+specifications and dependency diagrams.
+
+## Quick start
+
+ChangeLedger requires **Node.js 24 or newer**. Install the CLI globally:
+
+```sh
+npm install --global changeledger
+# or: pnpm add --global changeledger
+```
+
+In a repository that already has an `AGENTS.md`:
+
+```sh
+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.
+
+## The workflow
+
+```text
+conversation → draft → human approval → implementation → review
+             → human validation → persistent specification
+```
+
+A typical change starts like this:
+
+```sh
+changeledger new feature oauth-login "Add OAuth login"
+changeledger view
+```
+
+The agent completes the generated stages under `.changeledger/changes/`. You approve the
+draft in the viewer before implementation. From there, ChangeLedger validates
+lifecycle transitions, task traceability and the final human acceptance gate.
+When the work is done, its lasting truth graduates into `.changeledger/specs/`.
+
+The contract is agent-agnostic: Codex, Claude Code, opencode, Copilot, Cursor and
+other tools discover it through the repository's `AGENTS.md` reference.
+
+## Changes and specs
+
+- **Changes** describe a delta: why it is needed, what was learned, the chosen
+  design, acceptance criteria, implementation tasks and execution log.
+- **Specs** describe the current system after completed changes graduate. They
+  have no work lifecycle and remain concise, durable product truth.
+
+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).
+
+## Essential commands
+
+### Set up and inspect
+
+```sh
+changeledger init                         # initialize and register the current repository
+changeledger register                     # relink a moved or freshly cloned repository
+changeledger view                         # view every registered project
+changeledger view .                       # view only the current project
+changeledger check [id]                   # validate the repository or one change
+```
+
+### Work with changes
+
+```sh
+changeledger new <type> <slug> <title>    # create a draft change
+changeledger list [--status S] [--type T]
+changeledger show <id> [--json]
+changeledger status <id> <status>
+changeledger task <id> done|block <n> [reason]
+changeledger log <id> <message>
+changeledger review <id> pass
+changeledger review <id> fail --retry "<reason>"
+changeledger review <id> fail --block "<reason>"
+changeledger discard <id> <reason>
+```
+
+### Preserve completed truth
+
+```sh
+changeledger graduate <id> <spec-slug>           # create a persistent spec
+changeledger graduate <id> <spec-slug> --into    # update an existing spec's provenance
+changeledger graduate <id> --skip [reason]       # record that no spec is needed
+changeledger archive --graduated [--dry-run]     # hide resolved changes from the board
+```
+
+Run `changeledger --help` or `changeledger <command> --help` for the complete command reference.
+
+## Release planning
+
+ChangeLedger can calculate a portable SemVer release from completed changes
+without assuming a package ecosystem:
+
+```sh
+changeledger release init 0.1.0       # adopt an existing published version once
+changeledger release plan --json      # calculate the next version without writing
+changeledger release record 0.2.0     # record the calculated release manifest
+```
+
+The CLI decides which changes belong to the release and calculates their
+effective `release_impact`. The operating agent applies that version to the
+project's own surfaces—`package.json`, `pubspec.yaml`, `Cargo.toml`, Gradle,
+Xcode or a monorepo—then runs the local quality gates and release workflow.
+
+## Repository integration
+
+`changeledger check` exits non-zero on contract errors, so it can be used in Git hooks and
+CI:
+
+```sh
+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.
+
+## 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.
+- 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.
+
+## Project status
+
+ChangeLedger is usable and self-hosting, but remains **pre-1.0**. Expect the
+contract and CLI to evolve while the core workflow settles. Upgrade to the
+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).
+
+## Language policy
+
+Structure is always English: frontmatter keys, enum values, stage headings, CLI
+commands and filenames. Generated content follows the repository's configured
+`language`.

package/bin/changeledger.mjs

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import {
+  archive,
+  archiveGraduated,
+  discard,
+  list,
+  log,
+  owner,
+  review,
+  show,
+  status,
+  task,
+} from '../src/commands/agent.mjs';
+import { check } from '../src/commands/check.mjs';
+import { graduate, pendingGraduation, skipGraduation } from '../src/commands/graduate.mjs';
+import { init } from '../src/commands/init.mjs';
+import { newChange } from '../src/commands/new.mjs';
+import { registerRepo } from '../src/commands/register.mjs';
+import { initReleaseHistory, recordRelease, releasePlan } from '../src/commands/release.mjs';
+import { view } from '../src/commands/view.mjs';
+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 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 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
+  changeledger review <id> fail --retry|--block "<reason>"   review failed → in-progress|blocked
+  changeledger owner <id> <name|->           set or clear a change's owner
+  changeledger archive <id> / unarchive <id>   hide/show a change in the viewer
+  changeledger archive --graduated [--dry-run] archive done changes already graduated/skipped
+  changeledger log <id> <message>            append a timestamped Log entry
+  changeledger task <id> done|block <n> [reason]   mark a Plan task
+  changeledger list [--status S] [--type T] [--json]   list changes
+  changeledger show <id> [--json]            print a change
+  changeledger graduate <change-id> <spec-slug>   graduate a change to a new spec
+  changeledger graduate <change-id> <spec-slug> --into   graduate into an existing spec
+  changeledger graduate <change-id> --skip [reason]   mark graduation reviewed, no spec
+  changeledger graduate --pending                 list done changes not yet reviewed
+  changeledger release init <version>             initialize release history at X.Y.Z
+  changeledger release plan [--json]              calculate the next portable SemVer release
+  changeledger release record <version>           record the calculated release manifest`;
+
+const program = new Command();
+
+function action(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  };
+}
+
+program
+  .name('changeledger')
+  .description('ChangeLedger (changeledger)')
+  .helpOption('-h, --help', 'display help for command')
+  .addHelpText('after', `\n${USAGE}`);
+
+program
+  .command('init')
+  .description('set up .changeledger/ in the current repo (+ register it)')
+  .action(
+    action(() => {
+      const dir = init();
+      console.log(`Initialized ChangeLedger at ${dir}`);
+    }),
+  );
+
+program
+  .command('register')
+  .description("(re)link this repo's path in the global registry")
+  .action(
+    action(() => {
+      const { id, path: p } = registerRepo();
+      console.log(`Registered ${id} → ${p}`);
+    }),
+  );
+
+program
+  .command('new')
+  .description('scaffold a new change')
+  .argument('<type>')
+  .argument('<slug>')
+  .argument('<title...>')
+  .option('--owner <name>', 'set the initial owner')
+  .action(
+    action((type, slug, titleParts, options) => {
+      const title = titleParts.join(' ').trim();
+      const file = newChange({ type, slug, title, owner: options.owner, now: nowUtc() });
+      console.log(`Created ${file}`);
+    }),
+  );
+
+program
+  .command('view')
+  .description('launch the local viewer')
+  .argument('[args...]')
+  .action(action((args) => view(args)));
+
+program
+  .command('check')
+  .description('validate the repo or one change')
+  .argument('[id]')
+  .option('--json', 'print JSON')
+  .action((id, options) => {
+    try {
+      const args = [...(id ? [id] : []), ...(options.json ? ['--json'] : [])];
+      process.exit(check(args));
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description("move a change's lifecycle status")
+  .argument('<id>')
+  .argument('<status>')
+  .action(
+    action((id, st) => {
+      status(id, st);
+      console.log(`#${id} → ${st}`);
+    }),
+  );
+
+program
+  .command('discard')
+  .description('discard a change (terminal; keeps the record and reason)')
+  .argument('<id>')
+  .argument('<reason...>')
+  .action(
+    action((id, reasonParts) => {
+      discard(id, reasonParts.join(' ').trim());
+      console.log(`#${id} → discarded`);
+    }),
+  );
+
+program
+  .command('review')
+  .description('record an independent review verdict')
+  .argument('<id>')
+  .argument('<verdict>', 'pass|fail')
+  .argument('[reason...]')
+  .option('--retry', 'route a failed review back to in-progress')
+  .option('--block', 'route a failed review to blocked')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger review <id> pass',
+      '  changeledger review <id> fail --retry "<reason>"',
+      '  changeledger review <id> fail --block "<reason>"',
+    ].join('\n'),
+  )
+  .action(
+    action((id, verdict, reasonParts, options) => {
+      const mode = options.retry ? 'retry' : options.block ? 'block' : undefined;
+      const reason = reasonParts.join(' ').trim() || undefined;
+      review(id, verdict, { mode, reason });
+      console.log(`#${id} review ${verdict}${mode ? ` --${mode}` : ''}`);
+    }),
+  );
+
+program
+  .command('owner')
+  .description("set or clear a change's owner")
+  .argument('<id>')
+  .argument('<name>')
+  .action(
+    action((id, name) => {
+      owner(id, name);
+      console.log(`#${id} owner → ${name === '-' ? '(cleared)' : name}`);
+    }),
+  );
+
+program
+  .command('archive')
+  .description('hide a change in the viewer, or archive all graduated done changes')
+  .argument('[id]')
+  .option('--graduated', 'archive done changes already graduated or skipped')
+  .option('--dry-run', 'show what would be archived without writing')
+  .action(
+    action((id, options) => {
+      if (options.graduated) {
+        if (id) throw new Error('archive --graduated does not take an id');
+        const archived = archiveGraduated({ dryRun: options.dryRun });
+        for (const c of archived) console.log(`#${c.id} ${c.title}`);
+        console.log(
+          `${options.dryRun ? 'Would archive' : 'Archived'} ${archived.length} change(s)`,
+        );
+        return;
+      }
+      if (options.dryRun) throw new Error('--dry-run requires --graduated');
+      if (!id) throw new Error('archive requires <id> or --graduated');
+      archive(id, true);
+      console.log(`#${id} archived`);
+    }),
+  );
+
+program
+  .command('unarchive')
+  .description('show a change in the viewer')
+  .argument('<id>')
+  .action(
+    action((id) => {
+      archive(id, false);
+      console.log(`#${id} unarchived`);
+    }),
+  );
+
+program
+  .command('log')
+  .description('append a timestamped Log entry')
+  .argument('<id>')
+  .argument('<message...>')
+  .action(
+    action((id, messageParts) => {
+      log(id, messageParts.join(' ').trim());
+      console.log(`logged on #${id}`);
+    }),
+  );
+
+program
+  .command('task')
+  .description('mark a Plan task')
+  .argument('<id>')
+  .argument('<action>', 'done|block')
+  .argument('<n>')
+  .argument('[reason...]')
+  .action(
+    action((id, taskAction, nStr, reasonParts) => {
+      const n = Number(nStr);
+      task(id, taskAction, n, reasonParts.join(' ').trim());
+      console.log(`task #${n} on #${id} → ${taskAction}`);
+    }),
+  );
+
+program
+  .command('list')
+  .description('list changes')
+  .option('--status <status>', 'filter by status')
+  .option('--type <type>', 'filter by type')
+  .option('--json', 'print JSON')
+  .action(
+    action((options) => {
+      const items = list({ status: options.status, type: options.type });
+      if (options.json) {
+        console.log(JSON.stringify(items, null, 2));
+      } else {
+        for (const c of items) console.log(`${String(c.status).padEnd(12)} #${c.id}  ${c.title}`);
+      }
+    }),
+  );
+
+program
+  .command('show')
+  .description('print a change')
+  .argument('<id>')
+  .option('--json', 'print JSON')
+  .action(
+    action((id, options) => {
+      const c = show(id);
+      if (options.json) console.log(JSON.stringify(c, null, 2));
+      else console.log(`#${c.id} ${c.frontmatter.title} [${c.frontmatter.status}]`);
+    }),
+  );
+
+program
+  .command('graduate')
+  .description('graduate a done change to persistent truth')
+  .argument('[change-id]')
+  .argument('[spec-slug]')
+  .argument('[reason...]')
+  .option('--into', 'graduate into an existing spec')
+  .option('--skip', 'mark graduation reviewed without a spec')
+  .option('--pending', 'list done changes not yet reviewed')
+  .addHelpText(
+    'after',
+    [
+      '',
+      'Examples:',
+      '  changeledger graduate <change-id> <spec-slug>',
+      '  changeledger graduate <change-id> <spec-slug> --into',
+      '  changeledger graduate <change-id> --skip [reason]',
+      '  changeledger graduate --pending',
+    ].join('\n'),
+  )
+  .action(
+    action((id, slug, reasonParts, options) => {
+      if (options.pending) {
+        const items = pendingGraduation();
+        if (!items.length) console.log('No changes pending graduation.');
+        for (const c of items) console.log(`#${c.id}  ${c.title}`);
+        return;
+      }
+      if (options.skip) {
+        if (!id) throw new Error('Usage: changeledger graduate <change-id> --skip [reason]');
+        const reason = [slug, ...reasonParts].filter(Boolean).join(' ').trim();
+        skipGraduation(id, reason);
+        console.log(`#${id} graduation skipped`);
+        return;
+      }
+      if (!id || !slug) throw new Error('Usage: changeledger graduate <change-id> <spec-slug>');
+      const file = graduate(id, slug, process.cwd(), { into: options.into });
+      console.log(`Graduated #${id} → ${file}`);
+    }),
+  );
+
+const releaseCommand = program
+  .command('release')
+  .description('plan and record portable SemVer releases');
+
+releaseCommand
+  .command('init')
+  .description('initialize release history from the current published version')
+  .argument('<version>')
+  .action(
+    action((version) => {
+      const { file, manifest } = initReleaseHistory(version);
+      console.log(`Initialized release ${manifest.version} baseline → ${file}`);
+    }),
+  );
+
+releaseCommand
+  .command('plan')
+  .description('calculate the next release without writing files')
+  .option('--json', 'print a stable JSON plan')
+  .action(
+    action((options) => {
+      const plan = releasePlan();
+      if (options.json) {
+        console.log(JSON.stringify(plan, null, 2));
+        return;
+      }
+      if (!plan.releasable) {
+        console.log(
+          `No release required from ${plan.currentVersion}: ${plan.changes.length} pending change(s), highest impact none.`,
+        );
+        return;
+      }
+      console.log(`${plan.currentVersion} → ${plan.nextVersion} (${plan.impact})`);
+      for (const change of plan.changes) {
+        console.log(`  #${change.id} [${change.releaseImpact}] ${change.title}`);
+      }
+    }),
+  );
+
+releaseCommand
+  .command('record')
+  .description('record the currently calculated release')
+  .argument('<version>')
+  .action(
+    action((version) => {
+      const { file, manifest } = recordRelease(version);
+      console.log(`Recorded release ${manifest.version} → ${file}`);
+    }),
+  );
+
+if (process.argv.length <= 2) {
+  console.log(USAGE);
+} else {
+  program.parse();
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "changeledger",
+  "version": "0.3.0",
+  "description": "Turn conversations into buildable changes.",
+  "type": "module",
+  "bin": {
+    "changeledger": "bin/changeledger.mjs"
+  },
+  "homepage": "https://github.com/rarc88/changeledger#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rarc88/changeledger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rarc88/changeledger/issues"
+  },
+  "author": "Roberto Ruiz (https://github.com/rarc88)",
+  "keywords": [
+    "spec",
+    "specification",
+    "documentation",
+    "sdd",
+    "spec-driven-development",
+    "change-management",
+    "requirements",
+    "tdd",
+    "agents",
+    "ai-agents",
+    "cli",
+    "workflow"
+  ],
+  "scripts": {
+    "lint": "biome check",
+    "format": "biome check --write",
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "audit:deps": "pnpm audit --audit-level moderate",
+    "check": "node bin/changeledger.mjs check",
+    "verify": "pnpm lint && pnpm test && pnpm check",
+    "prepublishOnly": "pnpm verify"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.31.0",
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "AGENTS.md"
+  ],
+  "license": "MIT",
+  "lint-staged": {
+    "*.{js,mjs,json,jsonc,css}": "biome check --write --no-errors-on-unmatched"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "jsdom": "^29.1.1",
+    "lint-staged": "^17.0.7"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "dompurify": "^3.4.11",
+    "lit-html": "^3.3.3",
+    "marked": "^18.0.5",
+    "mermaid": "^11.15.0",
+    "yaml": "^2.9.0"
+  }
+}