changeledger 0.6.3 → 0.6.4

package/README.md

@@ -96,9 +96,11 @@ 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> <spec-slug> --new     # create a marked scaffold; remains pending
+# refine the scaffold and remove its marker
+changeledger graduate <id> <spec-slug> --into    # finalize an existing refined spec
 changeledger graduate <id> --skip [reason]       # record that no spec is needed
+changeledger graduate --pending                  # list unresolved graduation decisions
 changeledger archive --graduated [--dry-run]     # hide resolved changes from the board
 ```
 

package/bin/changeledger.mjs

@@ -15,7 +15,12 @@ import {
 } 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 {
+  graduate,
+  pendingGraduation,
+  scaffoldSpec,
+  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';
@@ -46,7 +51,7 @@ const USAGE = `ChangeLedger (changeledger)
   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> --new   create a spec scaffold to refine
   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
@@ -298,7 +303,8 @@ program
   .argument('[change-id]')
   .argument('[spec-slug]')
   .argument('[reason...]')
-  .option('--into', 'graduate into an existing spec')
+  .option('--new', 'create a spec scaffold without resolving graduation')
+  .option('--into', 'finalize graduation into an existing refined spec')
   .option('--skip', 'mark graduation reviewed without a spec')
   .option('--pending', 'list done changes not yet reviewed')
   .addHelpText(
@@ -306,7 +312,7 @@ program
     [
       '',
       'Examples:',
-      '  changeledger graduate <change-id> <spec-slug>',
+      '  changeledger graduate <change-id> <spec-slug> --new',
       '  changeledger graduate <change-id> <spec-slug> --into',
       '  changeledger graduate <change-id> --skip [reason]',
       '  changeledger graduate --pending',
@@ -314,7 +320,15 @@ program
   )
   .action(
     action((id, slug, reasonParts, options) => {
+      const modeCount = [options.new, options.into, options.skip, options.pending].filter(
+        Boolean,
+      ).length;
+      const modeUsage =
+        'Usage: changeledger graduate requires exactly one mode: --new, --into, --skip, or --pending';
+      if (modeCount !== 1) throw new Error(modeUsage);
+
       if (options.pending) {
+        if (id || slug || reasonParts.length) throw new Error(modeUsage);
         const items = pendingGraduation();
         if (!items.length) console.log('No changes pending graduation.');
         for (const c of items) console.log(`#${c.id}  ${c.title}`);
@@ -327,7 +341,15 @@ program
         console.log(`#${id} graduation skipped`);
         return;
       }
-      if (!id || !slug) throw new Error('Usage: changeledger graduate <change-id> <spec-slug>');
+
+      if (!id || !slug || reasonParts.length) throw new Error(modeUsage);
+      if (options.new) {
+        const file = scaffoldSpec(id, slug);
+        console.log(
+          `Created spec scaffold ${file}. Refine it, then run: changeledger graduate ${id} ${slug} --into`,
+        );
+        return;
+      }
       const file = graduate(id, slug, process.cwd(), { into: options.into });
       console.log(`Graduated #${id} → ${file}`);
     }),

package/package.json

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

package/src/commands/graduate.mjs

@@ -1,6 +1,6 @@
-// Graduates a change to a spec: scaffolds the spec file (frontmatter + a body
-// seeded from the change's Specification/Proposal) and links it back in the
-// change's Log. The final wording stays a manual/agent task.
+// Graduation is intentionally two-phase for a new spec. `scaffoldSpec` creates
+// an editable seed without resolving the change; `graduate --into` links only
+// after the durable wording has been reviewed.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,55 +13,73 @@ import { slugify } from '../slug.mjs';
 import { appendLog, setReviewed, setSpecUpdated } from '../writer.mjs';
 import { serializeScalar } from '../yaml.mjs';
 
-// `into: true` graduates into an EXISTING spec — it refreshes the spec's
-// `updated` and links it back, but leaves the body to the agent (who knows what
-// to refine). Without `into`, a new spec is scaffolded and an existing one is an
-// error. Both routes share the same change-side record (marker + reviewed).
-export function graduate(id, slug, cwd = process.cwd(), { into = false } = {}) {
-  const { config, repoRoot, file: changeFile } = resolveChange(cwd, id);
+const SPEC_SCAFFOLD_MARKER = '<!-- changeledger:spec-scaffold -->';
 
-  const specsDir = resolveSpecsDir(repoRoot, config);
+function graduationTarget(id, slug, cwd) {
+  const resolved = resolveChange(cwd, id);
+  const specsDir = resolveSpecsDir(resolved.repoRoot, resolved.config);
   const specName = `${slugify(slug)}.md`;
-  const specFile = path.join(specsDir, specName);
+  return { ...resolved, specsDir, specName, specFile: path.join(specsDir, specName) };
+}
 
-  // Validate preconditions before acquiring the change file lock — ensures no
-  // write happens at all when the existence check fails (CR1).
-  const exists = fs.existsSync(specFile);
-  if (into && !exists)
-    throw new Error(`Spec "${specName}" does not exist — drop --into to create it`);
-  if (!into && exists) throw new Error(`Spec "${specName}" already exists`);
+function requireDone(changeText) {
+  const change = parseChange(changeText);
+  if (change.frontmatter.status !== 'done') {
+    throw new Error('only done changes can be graduated/skipped');
+  }
+  return change;
+}
 
-  mutateFileAtomic(changeFile, (changeText) => {
-    const change = parseChange(changeText);
-    if (change.frontmatter.status !== 'done') {
-      throw new Error('only done changes can be graduated/skipped');
-    }
+export function scaffoldSpec(id, slug, cwd = process.cwd()) {
+  const { file: changeFile, specsDir, specName, specFile } = graduationTarget(id, slug, cwd);
+  if (fs.existsSync(specFile)) throw new Error(`Spec "${specName}" already exists`);
 
-    if (into) {
-      // Refresh the spec's updated; the body stays the agent's to edit.
-      writeFileAtomic(specFile, setSpecUpdated(fs.readFileSync(specFile, 'utf8'), nowUtc()));
-    } else {
-      const seedStage =
-        change.stages.find((s) => s.key === 'specification') ??
-        change.stages.find((s) => s.key === 'proposal');
-      const seed = seedStage ? seedStage.body : '';
-      const title = change.frontmatter.title;
-
-      const content = `---
-title: ${serializeScalar(title)}
+  const change = requireDone(fs.readFileSync(changeFile, 'utf8'));
+  const seedStage =
+    change.stages.find((stage) => stage.key === 'specification') ??
+    change.stages.find((stage) => stage.key === 'proposal');
+  const seed = seedStage ? seedStage.body : '';
+  const content = `---
+title: ${serializeScalar(change.frontmatter.title)}
 updated: ${nowUtc()}
 tags: [${change.frontmatter.type}]
 ---
 
-# ${title}
+# ${change.frontmatter.title}
 
-> Graduado del change ${id}.
+${SPEC_SCAFFOLD_MARKER}
+
+> Scaffold from change ${id}; replace this seed with durable current truth before --into.
 
 ${seed}
 `;
-      fs.mkdirSync(specsDir, { recursive: true });
-      writeFileAtomic(specFile, content);
+
+  fs.mkdirSync(specsDir, { recursive: true });
+  writeFileAtomic(specFile, content);
+  return specFile;
+}
+
+// Finalizes graduation into an EXISTING, manually refined spec. The command
+// refreshes `updated` and links it back, but never overwrites the body.
+export function graduate(id, slug, cwd = process.cwd(), { into = false } = {}) {
+  if (!into) {
+    throw new Error('graduation mode required: use --new, --into, or --skip');
+  }
+  const { file: changeFile, specName, specFile } = graduationTarget(id, slug, cwd);
+
+  if (!fs.existsSync(specFile)) {
+    throw new Error(`Spec "${specName}" does not exist — use --new to create a scaffold`);
+  }
+
+  mutateFileAtomic(changeFile, (changeText) => {
+    requireDone(changeText);
+    const specText = fs.readFileSync(specFile, 'utf8');
+    if (specText.includes(SPEC_SCAFFOLD_MARKER)) {
+      throw new Error(
+        `Spec "${specName}" still contains the scaffold marker — refine it and remove the marker before --into`,
+      );
     }
+    writeFileAtomic(specFile, setSpecUpdated(specText, nowUtc()));
 
     let text = appendLog(changeText, nowUtc(), `graduado a spec \`${specName}\``);
     text = setReviewed(text, true);

package/templates/contract/close.md

@@ -1,6 +1,8 @@
 # Closing Accepted Work
 
-The human accepted this change. Resolve persistent truth before archiving.
+The human accepted this change. Resolve persistent truth before archiving. Run
+`changeledger context <id>` after acceptance even if the base context was loaded
+earlier; this lifecycle-specific close overlay is not part of the base context.
 Changes describe a journey; `.changeledger/specs/*.md` describe the current
 capability, architecture or domain truth that code reflects.
 
@@ -15,19 +17,25 @@ tags: []
 ---
 ```
 
-Choose one graduation outcome:
-
-- `changeledger graduate <id> <spec-slug>` creates a new spec seeded from the
-  change's Specification and Proposal; refine its wording manually.
-- `changeledger graduate <id> <spec-slug> --into` links an existing spec and
-  refreshes `updated` without overwriting the spec body (the agent edits the body manually).
+Choose exactly one explicit graduation mode. A positional slug without a mode
+is an error, so words such as `skip` or `skip-*` can never silently become specs.
+
+- For a new spec, run `changeledger graduate <id> <spec-slug> --new`. This creates
+  a seed from the change's Specification or Proposal but leaves graduation
+  pending. Rewrite it as concise durable current truth and remove the explicit
+  scaffold marker. Then run `changeledger graduate <id> <spec-slug> --into` to
+  finalize it. `--into` refuses an unrefined marked scaffold.
+- For an existing spec, the agent edits its body first, then runs
+  `changeledger graduate <id> <spec-slug> --into`. It refreshes `updated`, records
+  the link and does not overwrite the body.
 - `changeledger graduate <id> --skip [reason]` records that no persistent truth
   changed.
 - `changeledger graduate --pending` lists accepted changes whose decision is
   unresolved.
 
-Graduation and skip both set `reviewed: true` on the change: it means the
-persistent-truth question was settled, not necessarily that a spec was created.
+Finalization with `--into` and skip both set `reviewed: true` on the change;
+`--new` does not. The boolean means the persistent-truth question was settled,
+not necessarily that a spec was created.
 The graduation link remains derivable from the Log marker `graduado a spec`,
 which carries the spec link, rather than from the boolean flag.
 

package/templates/contract/core.md

@@ -26,8 +26,9 @@ modifying files.
 6. For types that require review, use a fresh clean-context reviewer before
    human validation.
 7. Stop at `in-validation`. The agent never accepts on the human's behalf.
-8. After human acceptance, graduate persistent truth or record an explicit skip,
-   then archive the done change.
+8. After human acceptance, reload `changeledger context <id>` for the `done`
+   change, then graduate persistent truth or run
+   `changeledger graduate <id> --skip [reason]`; archive only after that decision.
 
 If no approved or in-progress change applies, do not silently edit repository
 files. Create or update a change, or ask the human whether a purely operational,