@christang/keel 5.4.0 → 5.6.0

package/README.md

@@ -125,6 +125,73 @@ Set `KEEL_SESSION_PANEL=1` to draw it as a framed panel with the Keel mark inste
 default, and turning it on changes nothing but the presentation — the same status and the same
 next command are in both forms.
 
+### Standing authorization
+
+Keel asks before a repository action it has no authority for, and it asks again next session,
+because a permission granted in conversation does not survive a context reset. Declare it once in
+`keel/config.yaml` instead:
+
+```yaml
+authorize:          # accepted names: commit, push, release, archive
+  - commit
+  - push
+```
+
+A task that authors no `Autonomy boundary:` inherits the declaration, and the compiled capsule
+names `keel/config.yaml` as that entry's source so an inherited authorization is never mistaken
+for one the task decided. A task that authors its own boundary keeps it.
+
+Three things the declaration is not:
+
+- **Not a way past a gate.** It authorizes the action, never the proof. `keel gate task-complete`
+  returns exactly the same verdict, and the same failure text, whether or not you declared
+  anything.
+- **Not a trigger.** It removes a confirmation, not the step that reaches the action. Nothing
+  schedules itself, and no next task is selected for you.
+- **Not open-ended.** The four names above are the whole vocabulary. An unrecognized entry is
+  reported with the accepted names and the declaration authorizes nothing until you fix it — a
+  typo never becomes a silent grant.
+
+The block is absent by default, and a repository that declares nothing behaves exactly as it did
+before this feature existed. `keel --doctor` reports what is declared.
+
+### Decision precedents
+
+A decision you make in conversation is spent at the next context reset, and the reasoning that
+settled it — the part that would generalise to a decision you have not met yet — goes with it.
+Point Keel at a directory of precedents and it consults them instead of asking you again:
+
+```yaml
+precedents: ../my-decisions   # any path; it may live outside this repository
+```
+
+Keel ships no precedent and creates no store. It reads that directory and nothing else — it never
+clones, pulls, or reaches the network — so one directory outside your repositories can serve all of
+them, and a path that is not there behaves exactly as no declaration at all.
+
+Each precedent is a markdown file carrying an `Applies when:` header, the materiality category it
+belongs to, a status of `recorded` or `authorized`, the decision, and **the rationale**. The last is
+load-bearing: *"chose A"* applies only to the situation literally recorded, while *"chose A because
+B fails offline"* can be applied to a case nobody has seen — and recognised as not applying when the
+new case is online. A precedent with no rationale is reported incomplete and is never applied.
+
+Three rules govern how they are used:
+
+- **A precedent is cited exactly where it replaced a question.** If applying it meant you were not
+  asked something you would have been asked, the reply names it. Routine decisions are not cited,
+  so a citation always marks a decision made in your place.
+- **Only you promote one.** A precedent enters as `recorded` and is offered as a recommendation
+  while the question is still asked. It becomes `authorized` when you accept a promotion that was
+  proposed to you — never by a usage count, which would cross with nobody watching.
+- **A precedent answers a recurrence; it never reclassifies.** It can shorten a decision inside its
+  category. It cannot move a decision out of the categories that require asking you, and no
+  accumulation of precedents makes a category stop mattering.
+
+As with standing authorization, a precedent informs a decision and never substitutes for a proof:
+gates, evidence, review, and the write guard are untouched by anything in the store. The session
+start line reports the store's size and freshness only — precedent bodies load when a decision is
+actually being made.
+
 ### Full vs Lite
 
 Use **Full mode** (the OpenSpec flow above) for new features, interface or protocol changes,
@@ -160,7 +227,8 @@ Keel splits verification into two layers so a slow suite never blocks your push:
   run at CI or at `keel gate change-close`.
 
 A task's `Verify` checks stay fast; the slow or exhaustive layer belongs to the full gate, not the
-local pre-push. Declare your fast check once in `keel/config.yaml`:
+local pre-push. Declare your fast check in `keel/config.yaml`, the same file that holds your
+standing authorization:
 
 ```yaml
 fast_check: npm test -- --fast   # your project's seconds-scale check
@@ -179,7 +247,9 @@ is repo-local and reversible.
 
 ## Domain lenses
 
-Keel's core is pure process; it ships no domain knowledge of its own. Domain guidance lives in
+Keel's core is pure process; it ships no domain knowledge and no decisions of its own. Alongside
+the precedent store above, the other user-authored surface Keel loads on demand is domain guidance,
+which lives in
 **lenses** you author under `keel/lenses/*.md` in your repo. Each lens is self-describing: it
 opens with an `Applies when:` line stating the signals that trigger it (file extensions, artifact
 shapes) and carries an `Execution and review checks` section. When a change's artifacts or Touch
@@ -212,6 +282,7 @@ keel guard status --json
 keel guard clear  --json
 
 # Domain lenses — user-authored guidance in keel/lenses/
+# (the other user-authored surface is the precedent store; see above)
 keel lenses list
 keel lenses add <name> [--force]
 

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.4.0 -->
+<!-- keel:start version=5.6.0 -->
 ## Keel Bootstrap
 
 - Start every session with `keel context`; OpenSpec artifacts and Git are the only durable authority — never native memory, goals, or transcripts.

package/assets/openspec/schemas/keel-spec-driven/schema.yaml

@@ -126,8 +126,12 @@ artifacts:
       Keel agent. Keel-managed work executes in the current agent conversation;
       do not hand execution to another agent, subagent, or operator unless the
       selected task or user explicitly authorizes it.
-      Autonomy boundary defaults to hard-stop. A pre-authorized fallback must
-      state an exact reversible bound and the evidence required after use.
+      Autonomy boundary defaults to hard-stop for every action the repository
+      has not standing-authorized in `keel/config.yaml`; a declared action is
+      inherited only by a task that authored no boundary of its own, and the
+      capsule names the declaration as that entry's source. A pre-authorized
+      fallback must state an exact reversible bound and the evidence required
+      after use.
 
       Use `Coupling: none` by default. When `Coupling: required`, define one
       complete candidate, its allowed provisional failures, completion gate,

package/assets/openspec/schemas/keel-spec-driven/templates/tasks.md

@@ -2,10 +2,14 @@
      Record only task-specific authority. Omitted fields inherit versioned
      defaults: Owner is the current Keel agent, Mode is implementation, Read
      is the change proposal/design/specs/tasks plus discovered repository
-     context, Acceptance derives from Covers, autonomy defaults to hard-stop,
-     Coupling defaults to none, helpers stay read-only/evidence-only, and
-     commit, push, sync, archive, and cross-task continuation stay
-     unauthorized. Declare a field only when it differs from these defaults. -->
+     context, Acceptance derives from Covers, Coupling defaults to none, and
+     helpers stay read-only/evidence-only. Autonomy defaults to hard-stop, and
+     commit, push, sync, archive, and cross-task continuation stay unauthorized,
+     EXCEPT where `keel/config.yaml` standing-authorizes an action: a task that
+     authors no `Autonomy boundary:` inherits that declaration, and the capsule
+     names the declaration as the entry's source. A standing authorization
+     removes the confirmation, never the gate, evidence, or Review.
+     Declare a field only when it differs from these defaults. -->
 
 ## 1. <!-- Task Group Name -->
 

package/bin/keel.js

@@ -44,6 +44,11 @@ const {
   renderGuard,
   startGuard,
 } = require("../src/core/guard");
+const {
+  STANDING_AUTHORIZATION_ACTIONS,
+  readPrecedentStore,
+  readStandingAuthorization,
+} = require("../src/core/config");
 
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const PACKAGE_JSON = require(path.join(PACKAGE_ROOT, "package.json"));
@@ -1033,6 +1038,8 @@ function keelOpenSpecOverlay(action) {
           "- When implementation exposes a material expectation, acceptance boundary, or user-owned decision absent from durable authority, stop before implementing that choice, rerun `keel-align-expectations`, and reauthor the affected proposal/design/spec/task authority first.",
           "- A discovered repository fact that does not change accepted behavior or scope may be recorded and execution continues inside the existing task boundary without a product interview.",
           "- Invoke OpenSpec through `keel openspec` (for example `keel openspec validate`); a bare `openspec` command may not be on PATH.",
+          "- Consult the repository's standing authorization in `keel/config.yaml` before asking the user to confirm a repository action: a standing-authorized action proceeds without a per-occurrence confirmation, and an undeclared action still requires the confirmation it requires today.",
+          "- A standing authorization covers the action and never substitutes for a gate, evidence, or Review; it removes the confirmation, not the record, and it is not a trigger to perform the action.",
         ]
       : [
           "- The current agent owns final sync/archive decisions and must verify task evidence, follow-up ownership, and completion gates before proceeding.",
@@ -1043,6 +1050,8 @@ function keelOpenSpecOverlay(action) {
           "- Invoke OpenSpec through `keel openspec` (for example `keel openspec validate`); a bare `openspec` command may not be on PATH.",
           "- When `/opsx:sync` has already promoted the change's spec delta, run the archive with `--skip-specs` so the promoted delta is not re-applied; archive is not idempotent over an already-synced delta.",
           "- After archiving, run `keel guard clear` to drop the change's guard manifest; the read-only gate never clears it for you.",
+          "- A repository that standing-authorizes `archive` in `keel/config.yaml` does not need the per-occurrence archive confirmation; a repository that declares nothing still needs it.",
+          "- The completion gate and follow-up ownership checks still run unchanged under a standing authorization; it removes the confirmation, not the proof.",
         ];
 
   const lines = [
@@ -1344,10 +1353,12 @@ function runDoctor(options) {
 
   printTargetSurface(repo, options.target);
   printLensSurface(repo, options.target);
+  const authorizationOk = printStandingAuthorizationSurface(repo);
+  printPrecedentSurface(repo);
   printFastPrePushSurface(repo);
   printSourceRepoCliResolution(repo);
 
-  return checkStatus;
+  return authorizationOk ? checkStatus : 1;
 }
 
 // Only meaningful in Keel's own repository: a bare `keel` resolves to the
@@ -1390,6 +1401,73 @@ function gitConfigHooksPath(repo) {
   return value || null;
 }
 
+function printStandingAuthorizationSurface(repo) {
+  process.stdout.write("\nStanding authorization:\n");
+  const { declared, unknown } = readStandingAuthorization(repo);
+  if (unknown.length > 0) {
+    printDoctorLine(
+      "authorize",
+      "failed",
+      `keel/config.yaml declares unrecognized ${
+        unknown.length === 1 ? "action" : "actions"
+      }: ${unknown.join(", ")}; accepted names are `
+        + `${STANDING_AUTHORIZATION_ACTIONS.join(", ")}. The whole declaration `
+        + "authorizes nothing until it is corrected"
+    );
+    return false;
+  }
+  printDoctorLine(
+    "authorize",
+    declared.length > 0 ? "ok" : "none",
+    declared.length > 0
+      ? `declared in keel/config.yaml: ${declared.join(", ")}`
+      : "undeclared; every action stays hard-stop"
+  );
+  for (const action of STANDING_AUTHORIZATION_ACTIONS) {
+    printDoctorLine(
+      action,
+      declared.includes(action) ? "authorized" : "not authorized"
+    );
+  }
+  return true;
+}
+
+function printPrecedentSurface(repo) {
+  process.stdout.write("\nPrecedent store:\n");
+  const store = readPrecedentStore(repo);
+  if (store.precedents.length === 0) {
+    printDoctorLine(
+      "precedents",
+      "none",
+      store.declared
+        ? `declared at ${store.declared}, which holds no precedents here; `
+          + "an absent store behaves exactly as an undeclared one"
+        : "undeclared; no precedent informs any decision"
+    );
+    return;
+  }
+  const authorized = store.precedents.filter(
+    (item) => item.status === "authorized"
+  ).length;
+  printDoctorLine("precedents", String(store.precedents.length), store.declared);
+  printDoctorLine(
+    "authorized",
+    String(authorized),
+    `${store.precedents.length - authorized} recorded, offered as a `
+      + "recommendation rather than applied"
+  );
+  const incomplete = store.precedents.filter((item) => !item.complete);
+  printDoctorLine(
+    "incomplete",
+    String(incomplete.length),
+    incomplete.length > 0
+      ? `missing a Rationale, so not applicable to any decision: ${incomplete
+        .map((item) => item.name)
+        .join(", ")}`
+      : "every precedent states why, which is the part that transfers"
+  );
+}
+
 function printFastPrePushSurface(repo) {
   process.stdout.write("\nFast pre-push surface:\n");
   const fastCheck = readFastCheck(repo);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@christang/keel",
   "displayName": "Keel",
   "description": "Keel OpenSpec execution discipline CLI for Claude Code, Codex, and OpenCode.",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/plugins/keel/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "description": "Keel OpenSpec execution discipline: stateless continuity, task capsules, deterministic gates, and expectation alignment for Codex and Claude Code.",
   "author": {
     "name": "TanglmChris",

package/plugins/keel/scripts/session-start.js

@@ -53,6 +53,61 @@ function emit(context, humanMessage) {
 // at session start is the one who must not mistake a projection for authority.
 const DISPOSABLE = "Disposable projection; OpenSpec and Git are the authority.";
 
+// A pointer, never a body. The store grows without bound while the precedents
+// relevant to any one session are a small subset, and this hook pays its cost
+// on every session including post-compaction reinjection. Counts and freshness
+// tell the agent the store exists and how stale it is; the precedents
+// themselves load when a decision is actually being made.
+//
+// The reader is inlined rather than required from src/core because this script
+// ships inside the plugin and must run without the CLI package resolvable.
+function precedentPointer(cwd) {
+  let declared = null;
+  try {
+    const configPath = path.join(cwd, "keel", "config.yaml");
+    if (!fs.existsSync(configPath)) return null;
+    for (const line of fs.readFileSync(configPath, "utf8").split(/\r?\n/)) {
+      const stripped = line.trim();
+      if (stripped.startsWith("#")) continue;
+      const match = stripped.match(/^precedents\s*:\s*(.+?)\s*$/);
+      if (match) {
+        declared = match[1];
+        break;
+      }
+    }
+    if (!declared) return null;
+    const resolved = path.isAbsolute(declared)
+      ? declared
+      : path.resolve(cwd, declared);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+      return `precedent store declared at ${declared} but absent here; `
+        + "no precedent informs any decision.";
+    }
+    const files = fs
+      .readdirSync(resolved)
+      .filter((name) => name.endsWith(".md") && name !== "README.md");
+    let authorized = 0;
+    let newest = 0;
+    for (const name of files) {
+      const full = path.join(resolved, name);
+      if (/^-\s*Status:\s*authorized/mi.test(fs.readFileSync(full, "utf8"))) {
+        authorized += 1;
+      }
+      const mtime = fs.statSync(full).mtimeMs;
+      if (mtime > newest) newest = mtime;
+    }
+    const synced = newest
+      ? new Date(newest).toISOString().slice(0, 10)
+      : "never";
+    return `precedents: ${files.length} (${authorized} authorized, `
+      + `last synced ${synced}); bodies load at the decision, not here.`;
+  } catch {
+    // The projection never blocks a session. An unreadable store is the same
+    // as no store for this hook's purposes.
+    return null;
+  }
+}
+
 // The Keel mark. A keel is the carina, the ridge on a bird's sternum, so the
 // animal that literally has one is a bird. Every cell is drawn from
 // U+2580–U+259F — the same block-element family as the host's own startup
@@ -238,6 +293,8 @@ function main() {
         + "does not guess among candidates."
     );
   }
+  const pointer = precedentPointer(cwd);
+  if (pointer) lines.push(`- ${pointer}`);
   lines.push(`- report this state ${DISCLOSURE}; it authorizes nothing.`);
   emit(lines.join("\n"), panel(human));
   return 0;

package/plugins/keel/skills/keel-align-expectations/SKILL.md

@@ -40,6 +40,37 @@ Accepted alignment routes to existing OpenSpec owners; create no separate alignm
 - specs own observable requirements and positive/negative/edge/failure scenarios.
 - tasks.md owns Covers, verification strategy and checks, scope, and stop boundaries that reference the accepted authority instead of duplicating chat prose.
 
+## Decision precedents
+
+When the repository declares a precedent store, consult the precedent matching a decision before
+escalating it, and record a new precedent when the user decides something the store does not cover.
+A precedent store is user-authored and never bundled; a repository that declares none behaves
+exactly as one without this section.
+
+Record the reasoning, not only the conclusion. "Chose A" applies only to the situation literally
+recorded; "chose A because B fails offline" can be applied to a case nobody has seen yet, and — just
+as important — recognised as *not* applying when the new case is online. Only the reasoning transfers.
+A precedent with no rationale is incomplete and is not applied.
+
+Three rules govern use:
+
+- **Cite only where you replaced a question.** Name the precedent you applied exactly when, without
+  it, you would otherwise have interrupted the user. Decisions that would not have interrupted them
+  are not cited, so that a citation always marks a decision made in the user's place rather than
+  running commentary.
+- **Promotion is the user's act.** A precedent enters as `recorded` and is offered as a
+  recommendation while the question is still asked. To make one applicable without asking, propose
+  the promotion and name the precedent; it changes only when the user accepts. There is no usage
+  count, age, or other threshold that promotes anything, because a threshold crosses with nobody
+  watching.
+- **A precedent answers a recurrence; it never reclassifies.** It may shorten a decision inside its
+  materiality category by supplying the recorded answer and its reasoning. It never moves a decision
+  out of the categories that require asking, and no accumulation of precedents makes a category
+  immaterial. A decision that resembles a precedent but sits in a different category is not a match.
+
+A precedent informs a decision and never substitutes for a proof: gates, evidence, Review, and the
+write guard are untouched by anything in the store.
+
 ## Domain lenses
 
 When the change signals a specific domain, look in `keel/lenses/` for a lens whose `Applies when:` header matches, and read only that lens before asking domain questions; do not load unrelated lenses. When no lens matches, or the repo defines none, proceed on the domain-agnostic path. Lenses are user-authored; scaffold the bundled starting points with `keel lenses add` (web, hardware, hardware-dsl).