@rowan-hiro/inkan 0.2.0 → 0.2.2

package/README.md

@@ -203,10 +203,13 @@ seal is a fact; close with dispositions, then commit the record with the
 work and include the outcome trailer; re-anchor with `inkan status` after
 context loss and leave other sessions' outcomes alone; closed outcomes are
 final and commit references are informational when reading history.
-The block carries a protocol number. `init`
+The block states policy only. It names the commands and what each call
+must carry, and leaves flag-level syntax to `inkan help`, so a CLI change
+does not bump the protocol. The block carries a protocol number. `init`
 upgrades a block it generated under an earlier protocol in place and refuses
 to overwrite a block that was edited by hand, so the policy lives in exactly
-one place. `--lang <tag>` sets the language agents should write outcome
+one place. A block stamped with a protocol newer than the installed Inkan
+is reported as such, with a prompt to upgrade the tool, not as a hand edit. `--lang <tag>` sets the language agents should write outcome
 prose in. `inkan init --claude` also creates `CLAUDE.md` as a symlink to
 `AGENTS.md`: Claude Code reads its own file name, and there is still one
 policy, not a copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowan-hiro/inkan",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Seal the authoritative outcome; keep a trustworthy record of the process.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -523,7 +523,28 @@ Outcome log: \`.inkan/outcomes/<id>.jsonl\`, one append-only file per outcome. C
 ${END_MARKER}`;
 }
 
-const PROTOCOL_VERSION = 6;
+function protocolBlockV7(lang) {
+  return `${START_MARKER}
+<!-- inkan-protocol: 7 -->
+<!-- inkan-lang: ${lang} -->
+
+## Agent protocol: sealed outcomes
+
+This repository uses Inkan (\`inkan\`, alias \`ink\`). Inkan keeps a trustworthy record of what the work was meant to deliver and what was declared at close. It does not inspect commits, run tests, or judge the result; the repository's own checks do that. Write outcome prose in ${lang}. This block states the policy; \`inkan help\` gives the command syntax.
+
+1. **Seal before durable changes.** Before changing code, configuration, documentation, or dependencies, run \`inkan status\`; if it shows an open outcome that is not your work, follow rule 4 first. Then run \`inkan begin\` with the outcome, one observable acceptance criterion at a time, and every decision record the work is bound by. File the outcome by lane only when the repository already files outcomes by lane.
+2. **The seal is a fact.** Deliver what it says. If circumstances change, do not reinterpret it: run \`inkan amend\` with the reason and the added or withdrawn criteria. The original text stays. Never question why the outcome was sealed the way it was at the time.
+3. **Close with dispositions, then commit.** Run \`inkan end\` with a disposition, met or unmet, for every live criterion and a note on what happened. Commit the outcome record with the work. Include the printed \`Inkan-Outcome: <id>\` trailer in the final paragraph of the landing commit message, beside any other trailers with no blank line between them. Never report success without closing the outcome.
+4. **Re-anchor after context loss.** Run \`inkan status\` and \`inkan log -n 3\`. An open outcome that is the work you were asked to do is your task: continue it, or close it with a note. An open outcome that is not your work belongs to another session: leave it alone. Never close, amend, or abandon an outcome you did not work on, and do not judge why it is still open. Before beginning your own outcome beside it, stop and tell the person it is there, and ask whether your work should run in its own git worktree, because separate worktrees keep each session's edits apart.
+5. **Closed outcomes are final.** Reviewing the log is reading, not re-checking. Never re-verify, re-attest, or re-close a closed outcome. If a past declaration now looks wrong, that is a new outcome with its own seal. When reading history, use commit trailers only as references. Missing trailers or unavailable referenced records are missing information, not failed outcomes or a reason to verify delivery or repair history.
+
+Decision records live in \`.inkan/decisions/\`. Their Context and Decision sections record the scenario at the time and are never edited. To challenge one, run \`inkan decision update\` with the new status and the reason, or add a new record that supersedes it.
+
+Outcome log: \`.inkan/outcomes/<id>.jsonl\`, one append-only file per outcome. Commit \`.inkan/\` with the code. Do not edit these files by hand.
+${END_MARKER}`;
+}
+
+const PROTOCOL_VERSION = 7;
 
 /**
  * The managed block for `lang` at protocol `version`, current by default.
@@ -537,6 +558,7 @@ export function protocolBlock(lang, version = PROTOCOL_VERSION) {
   if (version === 4) return protocolBlockV4(lang);
   if (version === 5) return protocolBlockV5(lang);
   if (version === 6) return protocolBlockV6(lang);
+  if (version === 7) return protocolBlockV7(lang);
   throw new InkanError(`unknown protocol version ${version}`);
 }
 
@@ -629,6 +651,15 @@ function writeProtocol(dir, lang) {
     fs.writeFileSync(agentsFile, content, 'utf8');
     return { root: dir, agentsFile, changed: true };
   }
+  // A block stamped with a protocol this tool does not know yet was written
+  // by a newer Inkan, not by hand. Say so and leave it alone.
+  const stamped = found.text.match(/<!-- inkan-protocol: (\d+) -->/);
+  const foundVersion = stamped ? Number(stamped[1]) : 0;
+  if (foundVersion > PROTOCOL_VERSION) {
+    throw new InkanError(
+      `${AGENTS_FILENAME} inkan block is protocol ${foundVersion}; this Inkan knows up to ${PROTOCOL_VERSION}. Upgrade Inkan; refusing to overwrite it`,
+    );
+  }
   throw new InkanError(`${AGENTS_FILENAME} inkan block was edited by hand; refusing to overwrite it`);
 }
 

package/src/cli.js

@@ -22,12 +22,20 @@ Commands:
       Create .inkan/ and write the agent protocol block into AGENTS.md.
       --claude also links CLAUDE.md to AGENTS.md.
   begin "<outcome>" [--accept <text>]... [--decision <id>]... [--lane <tag>]
-      Seal a new outcome; prints its id.
+      Seal a new outcome; prints its id. Repeat --accept once per
+      observable criterion; they are numbered from 1 in that order.
+      Repeat --decision once per decision record the work is bound by.
+      Use --lane only where the repository already files outcomes by lane.
   amend --reason <text> [<addition>] [--accept <text>]... [--withdraw <n>]...
         [--decision <id>]... [<id>]
       Append an amendment to the open outcome; prints the new contract hash.
+      --reason is required. Added criteria continue the numbering;
+      --withdraw takes a criterion number. The original text is kept.
   end [<id>] [--met <n>]... [--unmet <n>]... [-s abandoned] --note <text>
-      Record dispositions and close an outcome; print its commit reference.
+      Record dispositions and close an outcome; prints the Inkan-Outcome
+      trailer to put in the landing commit. Repeat --met or --unmet once
+      per live criterion number; every live criterion needs one. A value
+      may carry a note as "<n>: <text>". --note is required.
   status
       Print every open outcome.
   log [-n <count>] [--since <date>] [--grep <regex>] [--status <s>]