@christang/keel 5.20.0 → 5.39.0

package/README.md

@@ -198,21 +198,40 @@ The last thing a loop needs is permission to *start*. Declare which issues may b
 being asked about:
 
 ```yaml
-triage:             # issue labels that admit work; absent means nothing does
-  - auto
+triage:             # either source admits; absent means nothing does
+  labels:           # labels the issue carries
+    - auto
+  issues:           # issue numbers, declared here rather than on the issue
+    - 62
 ```
 
+A bare list directly under `triage:` still means labels, so a declaration written before the second
+source existed keeps its exact meaning.
+
 ```bash
-gh issue view 42 --json labels --jq '[.labels[].name]|join(",")' | xargs keel triage --labels
+gh issue view 42 --json labels,number \
+  --jq '"--labels \([.labels[].name]|join(",")) --issue \(.number)"' \
+  | xargs keel triage
 ```
 
 **Keel never fetches the issue.** You pass what `gh` returned, and the evaluation stays local,
 offline and deterministic — the same properties that make every other Keel answer worth trusting.
+At least one of `--labels` / `--issue` is required; supplying neither is asking for a fetch. A
+`triage:` block Keel cannot fully read admits nothing at all and names the entry that failed —
+granting the readable half would grant the entries beside your typo.
+
+**One issue is the unit, in both sources.** A person applies a label, or types a number, for one
+specific issue, so the policy admits a class you curate one issue at a time — not a guess about
+which issues look easy, which is exactly the judgement that should not be automated.
+
+They differ in **where your decision is written down**, which is why both exist:
 
-A **label** is the unit on purpose. A person applies one to one issue, so the policy admits a class
-you curate one issue at a time — not a guess about which issues look easy, which is exactly the
-judgement that should not be automated. Keel cannot check that a human applied the label; if your
-automation can label issues, this declaration is wider than it looks.
+- A **label** records it on the issue. In a repository whose issues come from other people, that
+  means an operations switch sits in the vocabulary you asked reporters to classify with, visible
+  and editable by whoever filed it. Keel also cannot check that a human applied it; if your
+  automation can label issues, that source is wider than it looks.
+- An **issue number** records it in your own file. The reporter never sees it, only a committer can
+  change it, it shows up in a diff, and you can revoke one entry without touching the rest.
 
 **Admission answers "may this begin" and nothing after it.** Alignment still escalates every
 material choice, every gate still runs, and the write guard still binds. In particular:
@@ -324,8 +343,8 @@ keel lenses list
 keel lenses add <name> [--force]
 
 # Unattended triage — may this issue start work without asking?
-# Keel never fetches the issue; pass what gh returned.
-keel triage --labels <l1,l2> [--json]
+# Keel never fetches the issue; pass what gh returned. At least one of the two.
+keel triage [--labels <l1,l2>] [--issue <n>] [--json]
 
 # Install / maintenance
 keel --init | --install | --check | --doctor | --uninstall  [--target <t>] [--dry-run]

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.20.0 -->
+<!-- keel:start version=5.39.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/templates/tasks.md

@@ -17,7 +17,7 @@
 
 - [ ] 1.1 <!-- Task description -->
   - Covers:
-    - <source expectation: spec scenario as `capability / requirement or scenario heading`, hidden-knowledge assumption, domain lens requirement, or critical D<n>/F<n>/A<n>/Q<n>; a Q<n> that OPENS an entry is an open question and requires an authorized fallback, while one named inside an entry about a fact is a citation and does not>
+    - <source expectation: spec authority as `capability / requirement` or `capability / requirement / scenario` — a scenario is named in the THIRD segment, never the second, hidden-knowledge assumption, domain lens requirement, or critical D<n>/F<n>/A<n>/Q<n>; a Q<n> that OPENS an entry is an open question and requires an authorized fallback, while one named inside an entry about a fact is a citation and does not>
   - Touch:
     - <path>
   - Verify:
@@ -50,6 +50,7 @@
       - Scope check: pending
       - Findings: pending
     - Blocker: none
+    - Reauthorizations: none
 
 <!-- Exceptional boundaries are declared only when they differ from defaults:
      - Mode: diagnose-only or repo-action (both with `Touch: none`), or plan-first.
@@ -87,6 +88,7 @@
       - Scope check: pending
       - Findings: pending
     - Blocker: none
+    - Reauthorizations: none
 
 ## 3. <!-- Task Group Name -->
 
@@ -117,6 +119,7 @@
       - Scope check: pending
       - Findings: pending
     - Blocker: none
+    - Reauthorizations: none
 
 ## Invalidates
 

package/bin/keel.js

@@ -97,6 +97,7 @@ Usage:
   keel gate task-start|task-complete|change-close [repo] [--change name] [--task id] [--action sync|archive] [--base git-ref] [--no-guard] [--record] [--json]
   keel guard start|status|clear [repo] [--change name] [--task id] [--force] [--json]
   keel lenses list|add [name] [repo] [--force]
+  keel triage [repo] [--labels <l1,l2>] [--issue <n>] [--json]
   keel openspec [args...]
   keel --init [repo] [--target claude|codex|opencode] [--dry-run] [--force-template-update]
   keel --install [repo] [--target claude|codex|opencode] [--dry-run] [--force-template-update] [--with-git-hooks]
@@ -134,6 +135,8 @@ Examples:
   keel lenses list
   keel lenses add web
   keel lenses add web --force
+  keel triage --labels auto
+  keel triage --issue 42
   keel --init
   keel --install
   keel --install --target codex
@@ -187,6 +190,7 @@ function parseArgs(argv) {
     lensesSubcommand: null,
     lensName: null,
     labels: null,
+    issue: null,
     openspecArgs: [],
     force: false,
     projectionEvent: null,
@@ -238,6 +242,10 @@ function parseArgs(argv) {
       parsed.labels = argv[++index] || "";
       continue;
     }
+    if (arg === "--issue" && parsed.action === "triage") {
+      parsed.issue = argv[++index] || "";
+      continue;
+    }
     if (arg === "openspec" && parsed.action === null && parsed.repo === null) {
       parsed.action = "openspec";
       parsed.openspecArgs = argv.slice(index + 1);
@@ -559,14 +567,25 @@ function parseArgs(argv) {
     fail("lens subcommands apply only to keel lenses");
   }
   if (parsed.action === "triage") {
-    if (parsed.labels === null) {
+    // At least one attribute, rather than labels specifically: a repository
+    // that admits by issue number alone should not have to pass an empty label
+    // list to be answered. The requirement stays because Keel never fetches the
+    // issue, so a caller supplying nothing is expecting a fetch.
+    if (parsed.labels === null && parsed.issue === null) {
       fail(
-        "keel triage requires --labels; Keel never fetches the issue, so pass "
-          + "what `gh issue view --json labels` returned"
+        "keel triage requires --labels or --issue; Keel never fetches the "
+          + "issue, so pass what `gh issue view --json labels,number` returned"
       );
     }
-  } else if (parsed.labels !== null) {
-    fail("--labels applies only to keel triage");
+    if (parsed.issue !== null && !/^[1-9]\d*$/.test(parsed.issue)) {
+      fail(
+        `--issue takes an issue number as a bare number, such as --issue 62; `
+          + `got ${parsed.issue || "nothing"}`
+      );
+    }
+  } else {
+    if (parsed.labels !== null) fail("--labels applies only to keel triage");
+    if (parsed.issue !== null) fail("--issue applies only to keel triage");
   }
   if (parsed.noGuard && parsed.action !== "gate") {
     fail("--no-guard applies only to keel gate task-start");
@@ -1188,6 +1207,70 @@ function mergeOpenSpecSurfaceOverlay(content, action) {
   return `${content}${separator}${overlay}`;
 }
 
+// The block plus the whitespace the merge above inserted in front of it, and
+// nothing else. Removing only the marked span leaves the separator behind, and
+// the file it is left in belongs to OpenSpec — so the match takes the newlines
+// immediately before the block and the one that closes it, and the replacement
+// puts a single newline back. A blank line anywhere else in the file is not
+// this code's business.
+const OPENSPEC_SURFACE_OVERLAY_REMOVE_RE =
+  /\n*<!--\s*keel:openspec-surface-overlay(?:\s+[^>]*)?\s*-->[\s\S]*?<!--\s*keel:openspec-surface-overlay:end\s*-->[ \t]*\n?/;
+
+function stripOpenSpecSurfaceOverlay(content) {
+  let next = content;
+  // A loop rather than one replace: the merge only ever writes one block, so a
+  // file carrying two is already unexpected, and leaving one of them behind is
+  // the outcome this is cheapest to rule out.
+  while (OPENSPEC_SURFACE_OVERLAY_RE.test(next)) {
+    next = next.replace(OPENSPEC_SURFACE_OVERLAY_REMOVE_RE, (match, offset) =>
+      offset === 0 ? "" : "\n"
+    );
+  }
+  return next;
+}
+
+function removeOpenSpecSurfaceOverlay(repo, target, options = {}) {
+  const counts = {
+    removed: 0,
+    absent: 0,
+    missing: 0,
+  };
+
+  for (const surface of openspecOverlaySurfacesForTarget(target, repo)) {
+    // `keel --install` without `--init` never creates the OpenSpec surfaces,
+    // so a repository can legitimately reach uninstall with none of them.
+    if (!fs.existsSync(surface.path)) {
+      counts.missing += 1;
+      continue;
+    }
+    const content = fs.readFileSync(surface.path, "utf8");
+    const next = stripOpenSpecSurfaceOverlay(content);
+    if (next === content) {
+      counts.absent += 1;
+      continue;
+    }
+    counts.removed += 1;
+    if (options.dryRun) {
+      process.stdout.write(
+        `keel: would remove OpenSpec ${surface.action} overlay from ${surface.path}\n`
+      );
+      continue;
+    }
+    fs.writeFileSync(surface.path, next, "utf8");
+  }
+
+  // Always reported, including `removed=0`: an uninstall that found nothing to
+  // clean and an uninstall that never looked leave the same tree behind, and
+  // the second one is the defect this exists to close.
+  process.stdout.write(
+    `keel: ${options.dryRun ? "would remove " : ""}OpenSpec ${overlayActionLabel()} `
+      + `overlay removed=${counts.removed} absent=${counts.absent} `
+      + `missing=${counts.missing}\n`
+  );
+
+  return { status: 0, ...counts };
+}
+
 function refreshOpenSpecSurfaceOverlay(repo, target, options = {}) {
   const surfaces = openspecOverlaySurfacesForTarget(target, repo);
   const counts = {
@@ -1223,7 +1306,7 @@ function refreshOpenSpecSurfaceOverlay(repo, target, options = {}) {
 
   if (counts.refreshed > 0 || counts.current > 0) {
     process.stdout.write(
-      `keel: ${options.dryRun ? "would refresh " : ""}OpenSpec apply/archive `
+      `keel: ${options.dryRun ? "would refresh " : ""}OpenSpec ${overlayActionLabel()} `
         + `overlay refreshed=${counts.refreshed} current=${counts.current} `
         + `missing=${counts.missing}\n`
     );
@@ -1547,17 +1630,9 @@ function gitConfigHooksPath(repo) {
 
 function printStandingAuthorizationSurface(repo) {
   process.stdout.write("\nStanding authorization:\n");
-  const { declared, unknown } = readStandingAuthorization(repo);
+  const { declared, unknown, message } = 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"
-    );
+    printDoctorLine("authorize", "failed", message);
     return false;
   }
   printDoctorLine(
@@ -1578,12 +1653,31 @@ function printStandingAuthorizationSurface(repo) {
 
 function printTriageSurface(repo) {
   process.stdout.write("\nUnattended triage:\n");
-  const { labels } = readTriagePolicy(repo);
+  const { labels, issues, unreadable } = readTriagePolicy(repo);
+  // An unreadable declaration is reported as broken rather than as absent. The
+  // owner who typed it needs to know their file is the reason nothing runs,
+  // which "undeclared" would tell them is not the case.
+  if (unreadable.length > 0) {
+    printDoctorLine(
+      "triage",
+      "unreadable",
+      `keel/config.yaml declares triage entries Keel could not read — `
+        + `${unreadable.join(", ")}; no issue starts work unattended until the `
+        + "declaration is corrected"
+    );
+    return;
+  }
+  // Only the declared sources are named. Naming a source with nothing under it
+  // would read as a policy that exists, on the one surface asked to answer
+  // "what may start work here" in a single line.
+  const declared = [];
+  if (labels.length > 0) declared.push(`issues labelled ${labels.join(", ")}`);
+  if (issues.length > 0) declared.push(`issues numbered ${issues.join(", ")}`);
   printDoctorLine(
     "triage",
-    labels.length > 0 ? "ok" : "none",
-    labels.length > 0
-      ? `issues labelled ${labels.join(", ")} may start work unattended; `
+    declared.length > 0 ? "ok" : "none",
+    declared.length > 0
+      ? `${declared.join(", and ")} may start work unattended; `
         + "admission decides nothing after it, and no declaration authorizes a merge"
       : "undeclared; no issue starts work unattended"
   );
@@ -1876,7 +1970,7 @@ function runAction(options) {
       .split(",")
       .map((label) => label.trim())
       .filter(Boolean);
-    const verdict = triageIssue(repo, labels);
+    const verdict = triageIssue(repo, labels, options.issue);
     const payload = {
       schemaVersion: 1,
       command: "triage",
@@ -2004,7 +2098,18 @@ function runAction(options) {
   }
 
   if (options.action === "clear" || options.action === "uninstall") {
-    return runPython(INSTALL_SCRIPT, installerArgs(options, ["--uninstall"]));
+    const uninstallStatus = runPython(
+      INSTALL_SCRIPT,
+      installerArgs(options, ["--uninstall"])
+    );
+    if (uninstallStatus !== 0) {
+      return uninstallStatus;
+    }
+    return removeOpenSpecSurfaceOverlay(
+      path.resolve(options.repo || process.cwd()),
+      options.target,
+      { dryRun: options.dryRun }
+    ).status;
   }
 
   if (options.action === "check") {

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.20.0",
+  "version": "5.39.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.20.0",
+  "version": "5.39.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.20.0",
+  "version": "5.39.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/skills/keel-align-expectations/SKILL.md

@@ -73,24 +73,10 @@ write guard are untouched by anything in the store.
 
 ## Unattended runs
 
-Work enters an unattended run only by the repository's declared triage policy — an issue carrying a
-label listed under `triage:` in `keel/config.yaml`, evaluated with `keel triage --labels <labels>`.
-Pass what `gh` returned; Keel never fetches the issue. Admission comes from that declaration and
-never from a precedent, however much triage history the store accumulates: whether an issue becomes
-work is a materiality decision, and a precedent may not move one out of that list.
-
-Admission answers "may this begin" and decides nothing after it. Alignment still escalates material
-choices, the gates still run, and the write guard still binds.
-
-An unattended run may triage, author, implement, verify, push where `authorize:` permits, and
-**open a pull request**. It **may not merge** one — merging is where an unreviewed decision becomes
-the project's history, and no declaration in Keel authorizes it.
-
-Stopping at a decision the user must make is the **designed boundary rather than a failure**.
-Report where the run stopped and why. Do not widen the triage policy to stop it happening.
-
-**Keel schedules nothing.** `/loop`, cron, and CI triggers belong to the host runtime; Keel's part
-is making each step decidable with authority.
+The admission rule, what admission does and does not authorize, the open-a-pull-request/no-merge
+boundary, and that Keel schedules nothing are stated once, in this repository's `AGENTS.md`, under
+its own `## Unattended runs` section. Read the boundary there — this skill states no separate copy,
+so the two surfaces cannot drift against each other.
 
 ## Domain lenses
 

package/plugins/keel/skills/keel-review-checklist/SKILL.md

@@ -23,7 +23,7 @@ Read the selected OpenSpec proposal, design, specs, tasks, diff, and command evi
 - For a red-green strategy (`vertical-tdd`, `regression-first`), confirm concrete per-label `.red` and `.green` Evidence exists for the same check; evidence-first tasks instead name their observable proof.
 - A failure message must **name the actual cause** of what it reports. Watch for one condition guarding **two distinct failures** — `if result is None or result["status"] != expected` reports the first failure's message when the second one happened, sending the reader to a place with no problem in it. Split the condition. No gate can judge this: deciding whether a sentence misleads needs a model, so it stays here.
 - When two tasks in the change declared the same Touch set under a red-green strategy — `keel gate task-start` warns about this — ask whether they turned out to be **one behavior** split in half. The tell is that the first task's minimal implementation was wrong in the field, or that the second had no honest red left because the first already made its checks pass. The gate can only see the shape; by completion you can see the outcome, which is the only point at which this is answerable.
-- Scope attribution is now the gate's job by default: `keel gate task-complete` compares the worktree against the dirty set `task-start` recorded and refuses a path outside Touch, so a `pass` is evidence about scope rather than silence about it. Two cases still need you. When the gate reports paths as *unattributed* — no recorded set, because the manifest predates the field or the guard was cleared — nothing was checked and the review is the only scope evidence. And a path already dirty when the task started is never attributed even if the task changed it again, so read the gate's silence about such a path as absence of a check rather than absence of a write.
+- Scope attribution is now the gate's job by default: `keel gate task-complete` compares the worktree against the dirty set `task-start` recorded and refuses a path outside Touch, so a `pass` is evidence about scope rather than silence about it. Two cases still need you. When the gate reports paths as *unattributed* — no recorded set, because the manifest predates the field or the guard was cleared — nothing was checked and the review is the only scope evidence. And a path already dirty when the task started stays unattributed only while its content matches what was recorded then; if the task changed it again, the gate attributes it — so read the gate's silence about such a path as evidence its content was never touched again, not as an unconditional exemption.
 - For `Coupling: required`, confirm one complete candidate reached its completion gate and generated artifacts are aligned.
 
 ## Semantic Review

package/scripts/install_to_repo.py

@@ -129,7 +129,20 @@ TASKS_COMMIT_STATUS_PATTERNS = (
 # verbatim inside the lookahead, so the token that matches is the token that
 # always matched, minus the all-decimal ones.
 _HASH_SHAPED_TOKEN = r"\b(?=[0-9a-f]{7,40}\b)[0-9a-f]*[a-f][0-9a-f]*\b"
-_HASH_CONTEXT_WORD = r"(?:commit|提交|合入|master|main|HEAD|hash|哈希)"
+# A context word has to be a word. Matched anywhere on the line, `main` was
+# supplied by `remaining`, `domain`, and `maintains`, and `head` by `heading`
+# — and the tokens sitting beside those words in this repository's own
+# history are `sha256:` contract anchors, not commit identifiers (#65).
+# The inflections are spelled out rather than left to a prefix match: they are
+# the words an author writes about the act this rule exists to catch, and the
+# stricter list that drops `committed` and `hashes` would cost real refusals.
+# The Chinese words carry no boundary because none is definable between two
+# word characters — `\b提交\b` matches neither `已提交` nor `未提交`, which are
+# exactly what the wording rule is for.
+_HASH_CONTEXT_WORD = (
+    r"(?:\b(?:commits?|committed|committing|master|main|HEAD|hash(?:es)?)\b"
+    r"|提交|合入|哈希)"
+)
 TASKS_CONTEXTUAL_HASH_RE = re.compile(
     rf"(?i){_HASH_CONTEXT_WORD}.*{_HASH_SHAPED_TOKEN}|"
     rf"{_HASH_SHAPED_TOKEN}.*{_HASH_CONTEXT_WORD}"
@@ -662,6 +675,35 @@ def is_tasks_rule_line(line: str) -> bool:
     )
 
 
+# The task contract compiler's own field bound, from `parseTasks()` in
+# `src/core/task-contract.js`: a field starts at a two-space `- Name:` line and
+# holds every line until the next one. Keeping the two readers on one rule is
+# what stops a line being a Covers entry for the compiler and prose for this
+# check.
+TASKS_FIELD_LABEL_RE = re.compile(r"^ {2}- ([A-Za-z][A-Za-z /-]+):")
+
+
+def covers_field_lines(content: str) -> set[int]:
+    """1-based line numbers inside a `Covers` field.
+
+    A Covers entry is a citation — its segments must resolve to a requirement
+    or scenario that exists in a spec — so naming a requirement about dirty
+    worktrees or commit identifiers is not recording one. Read as prose, those
+    citations left an author no repair but to rename the requirement, which is
+    what 5.19.0 did and what #65 reports. Every citation is written on a line
+    below the label, so the exempt region is the field and not the label line.
+    """
+    inside = False
+    lines: set[int] = set()
+    for number, line in enumerate(content.splitlines(), start=1):
+        label = TASKS_FIELD_LABEL_RE.match(line)
+        if label is not None:
+            inside = label.group(1) == "Covers"
+        if inside:
+            lines.add(number)
+    return lines
+
+
 def check_tasks_semantics(repo: Path) -> list[str]:
     changes_root = repo / OPENSPEC_ROOT / "changes"
     if not changes_root.is_dir():
@@ -682,8 +724,9 @@ def check_tasks_semantics(repo: Path) -> list[str]:
                 line = line_number_for_offset(content, match.start())
                 errors.append(f"{relative}:{line}: {message}")
 
+        cited = covers_field_lines(content)
         for line_number, line in enumerate(content.splitlines(), start=1):
-            if is_tasks_rule_line(line):
+            if is_tasks_rule_line(line) or line_number in cited:
                 continue
             for pattern, message in TASKS_COMMIT_STATUS_PATTERNS:
                 if pattern.search(line):