@christang/keel 5.66.0 → 5.68.0

package/README.md

@@ -295,6 +295,34 @@ decision either — routing decides whether a change exists, so there is nothing
 to; what Keel does is make sure the rule and your exceptions are in front of the agent when it
 decides.
 
+### How much guidance the agent loads
+
+Keel's skills carry two kinds of content, and their value moves in opposite directions. *How to do it*
+— how to split a task, what order to run things in — matters less the stronger the executor is. *Make
+yourself falsifiable* — red then green, the failure literal a check predicts, the fingerprint, whether
+a `Durable owner:` reference actually exists — matters more, because a strong executor produces
+confident work and those are the checks that can contradict it.
+
+So the stepwise half of a skill lives in a `guidance.md` beside it, and a repository can say it does
+not need that half:
+
+```yaml
+executor_tier: high
+```
+
+The default is `standard`, which reads the guidance; an absent or misspelled declaration reads it too,
+so the worst an unconfigured repository does is pay for a read. `keel context` and `keel --doctor`
+report the tier.
+
+**The tier reaches guidance and nothing else** — no gate, criterion, evidence requirement, or Review
+changes with it. That is not a promise in this README: a guidance file is checked to contain none of
+the words Keel states criteria in, so a tier can only ever skip a file that decides nothing. Deciding
+what to skip is a declaration rather than the agent's own call on purpose — "do I need this help?" is
+the judgement a weak executor gets most wrong, and it would be answering it about itself.
+
+One skill is split today, `keel-run-single-task-goal`, and its body is 11% smaller for it. The other
+five are almost entirely criteria, so splitting them would move the half that has to stay.
+
 ## How the agent uses these
 
 You rarely type the commands below. The point of Keel is that the discipline runs itself:
@@ -316,6 +344,41 @@ wiring, and `keel --init` whenever it tells you the repository is behind its ins
 protocol version lives in your `AGENTS.md`, and updating the package does not move it.
 Everything below is the vocabulary the agent uses on your behalf.
 
+### When the right answer is "nothing changed"
+
+A refactor, a move, a flow upgrade that claims the numbers hold — the correct evidence for these is
+*zero difference*, and red-green has no shape for it. The repository that reported this had a task
+whose `tasks.md` said "this one has no honest red" several times, and re-recorded its contract twice
+trying to fit. The criterion was right; it had nowhere to live.
+
+```
+- Verify:
+  - Strategy: equivalence
+  - Base: origin/main
+  - Fields: wns, tns, cell_count
+  - M1: node compare.js --base --head reports every field equal
+```
+
+`equivalence` owes no red. Its criterion is that base and head agree on the fields you named, which is
+*stronger* than red-green — it also catches the change that incidentally moved a result. What the gate
+checks is every way that shape can look complete and compare nothing: a missing `Base:` or `Fields:`,
+an empty field set, a ref that resolves to nothing, and a `Base:` that resolves to HEAD.
+
+It is not a way out of red-green. A task declaring `equivalence` while covering a scenario its own
+change *adds* is refused unless a sibling task covers that same entry under a red-green strategy —
+behavior that is new is not behavior that is unchanged, and a task cannot prove both.
+
+And Evidence no longer has to retell the output:
+
+```
+- M1: artifact openspec/changes/<change>/evidence/compare.json sha256:9f2c…
+```
+
+The gate checks the file is there and the digest matches, and refuses a path outside the change's own
+directory, because archiving moves that directory and the pointer would break. Keel hashes the bytes
+and reads nothing inside them — the claim stays yours, and what the digest buys is that the file your
+reviewer opens is the file you meant.
+
 ## Verification layering
 
 Keel splits verification into two layers so a slow suite never blocks your push:

package/assets/bootstrap/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- keel:start version=5.66.0 -->
+<!-- keel:start version=5.68.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/bin/keel.js

@@ -49,6 +49,7 @@ const {
   readPrecedentStore,
   readStandingAuthorization,
   readFullModePaths,
+  readExecutorTier,
   fullModePathsUnreadableMessage,
   readTriagePolicy,
   triageIssue,
@@ -1731,6 +1732,7 @@ function runDoctor(options) {
   printPrecedentSurface(repo);
   printTriageSurface(repo);
   printRoutingSurface(repo);
+  printExecutorTierSurface(repo);
   printFastPrePushSurface(repo);
   printSourceRepoCliResolution(repo);
 
@@ -1855,6 +1857,24 @@ function printRoutingSurface(repo) {
   for (const entry of paths) printDoctorLine(entry.path, "Full", entry.reason);
 }
 
+// Reported whether or not it is declared, because the default is the state a
+// reader most needs to see: a repository that declared nothing is loading every
+// skill's guidance and has no other surface that says so.
+function printExecutorTierSurface(repo) {
+  process.stdout.write("\nExecutor tier:\n");
+  const { declared, tier, unknown, message } = readExecutorTier(repo);
+  if (unknown.length > 0) {
+    printDoctorLine("executor_tier", "unreadable", message);
+    return;
+  }
+  printDoctorLine(
+    "executor_tier",
+    tier,
+    (declared ? "declared in keel/config.yaml" : "undeclared; the default")
+      + " - affects which skill guidance is read and nothing else"
+  );
+}
+
 function printTriageSurface(repo) {
   process.stdout.write("\nUnattended triage:\n");
   const { labels, issues, unreadable } = readTriagePolicy(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.66.0",
+  "version": "5.68.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -1,6 +1,6 @@
 {
   "name": "keel",
-  "version": "5.66.0",
+  "version": "5.68.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.66.0",
+  "version": "5.68.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-run-single-task-goal/SKILL.md

@@ -13,16 +13,13 @@ metadata:
 
 Activate a native goal or subagent runtime to execute exactly one authorized OpenSpec task end to end, while OpenSpec, Git, the task-capsule fingerprint, and deterministic Keel gates stay the only durable authority. The current agent remains the sole holder of write authority and owns Review, gate invocation, the task checkbox, and completion. Where delegation is declared, an authorized delegate may write inside the `Touch` boundary that authority already defined and acquires none of those decisions; the current agent re-runs each `M<n>` check itself before recording Evidence, because a delegate's reported result is a claim and the byte-identity check that validates a read-only helper cannot apply to a writer. A native evaluator declaring success never marks or reports the task complete.
 
-## Authoritative sources and provenance
+## Guidance
 
-These official runtime docs are linked as authoritative references, not copied. Their text and trademarks belong to their owners; Keel paraphrases only the activation semantics it needs and bundles none of their prose.
+Read `guidance.md` beside this file before proceeding, unless `keel/config.yaml` declares `executor_tier: high` — it holds the runtime references, the manual sequence, and the per-target detail. Every criterion is here, so an absent or unreadable declaration costs a read and nothing else.
 
-- Codex goal-following: https://learn.chatgpt.com/use-cases/follow-goals
-- Codex subagents: https://developers.openai.com/codex/subagents
-- Claude goal execution: https://code.claude.com/docs/en/goal
-- Claude subagents: https://code.claude.com/docs/en/sub-agents
+## License
 
-License note: this skill is distributed under the Keel package license (UNLICENSED, all rights reserved by the author). Linking the official docs does not relicense them; do not paste their content into Keel artifacts.
+License note: the Keel package license (UNLICENSED, all rights reserved by the author). Linking the official runtime docs relicenses nothing; their provenance is recorded beside the links and their content is never pasted into Keel artifacts.
 
 ## When to activate
 
@@ -60,9 +57,8 @@ Helpers are optional, read-only evidence producers and never a second writer. Co
 
 ## Manual fallback
 
-When native activation is unavailable — no plugin, disabled hooks, managed policy, missing trust, or an unsupported surface — do not fake activation. Run the same lifecycle by hand: `keel gate task-start`, `keel project goal ... --json` for the view, implement, surface evidence, `keel gate task-complete`, then check the box. The manual loop preserves the identical single-task lifecycle and stop boundary.
+When native activation is unavailable, do not fake activation: run the identical lifecycle by hand. The manual loop preserves the same single-task boundary and the same stop boundary; its steps are in `guidance.md`.
 
 ## Target activation
 
-- Codex: where a callable goal/subagent surface exists, activate one bounded goal for the selected task and use subagents only as bounded read-only helpers. Without a callable surface, paste the exact `keel project goal` command and treat the capability as advisory.
-- Claude: activate one `/goal` whose condition stays within the 4,000-character budget; the evaluator is transcript-only, so surface command and gate evidence explicitly. If hooks are disabled, policy blocks activation, or trust is missing, report the manual fallback.
+Claude and Codex only. Activate exactly one bounded goal for the selected task; a native evaluator declaring success never marks or reports the task complete. The per-target detail is in `guidance.md`.

package/plugins/keel/skills/keel-run-single-task-goal/guidance.md

@@ -0,0 +1,30 @@
+# keel-run-single-task-goal — guidance
+
+How to carry out the lifecycle. Every criterion is in `SKILL.md`; nothing here decides whether a task
+may start, pass, or complete.
+
+## Authoritative runtime references
+
+Provenance: linked, not copied. Their text and trademarks belong to their owners, and Keel paraphrases
+only the activation semantics it needs. License note: see `SKILL.md`.
+
+- Codex goal-following: https://learn.chatgpt.com/use-cases/follow-goals
+- Codex subagents: https://developers.openai.com/codex/subagents
+- Claude goal execution: https://code.claude.com/docs/en/goal
+- Claude subagents: https://code.claude.com/docs/en/sub-agents
+
+## Running the lifecycle by hand
+
+Native activation can be unavailable — no plugin, disabled hooks, managed policy, missing trust, or an
+unsupported surface. Type the same numbered steps `SKILL.md` lists, in the same order: `keel gate task-start`, record the
+fingerprint, `keel project goal … --json` for the view, implement inside `Touch`, surface every result
+in the transcript, `keel gate task-complete`, check the box. What changes is who types them.
+
+## Per-target activation notes
+
+- **Codex**: where a callable goal or subagent surface exists, activate one bounded goal for the
+  selected task and use subagents only as bounded read-only helpers. Without a callable surface, paste
+  the exact `keel project goal` command and treat the capability as advisory.
+- **Claude**: activate one `/goal` whose condition fits the 4,000-character budget. The evaluator sees
+  the transcript only, so command and gate evidence has to appear there explicitly. If hooks are
+  disabled, policy blocks activation, or trust is missing, the manual sequence above applies.

package/plugins/keel/skills/keel-tdd-or-test-first/SKILL.md

@@ -20,10 +20,13 @@ Read the selected task's compiled capsule: resolved Acceptance, Verify strategy
 - `regression-first`: an observable defect; reproduce it through the public interface first, then prove the fix with the same check.
 - `characterization` / `snapshot-characterization`: deterministic or generated outputs kept stable by byte or snapshot comparison; not downgraded to build success.
 - `rendered-behavior`: interactive surfaces exercised through the real rendered interface; strict red-green optional by cost.
-- `evidence-first`: docs, configuration, or diagnosis work whose checks state the observable artifact or evidence instead of a red-green loop.
+- `equivalence`: work whose criterion is that a measured result does not change — a refactor, a move, a flow upgrade claiming the numbers hold. It declares `Base:` (a resolvable git ref) and `Fields:` (the compared field set) beside `Strategy:` and owes no red; the A/B command is an ordinary `M<n>` check. `keel gate task-start` refuses a missing `Base:` or `Fields:`, an empty field set, an unresolvable ref, and a `Base:` that is HEAD, because an A/B against itself always agrees. A task covering a scenario its own change *adds* is refused unless a sibling task covers that same entry under a red-green strategy: behavior that is new is not behavior that is unchanged.
+- `evidence-first`: docs, configuration, or diagnosis work whose checks state the observable artifact or evidence instead of a red-green loop. It is scoped by an absence — nothing here can fail first — which is why it is not the home for `equivalence` work, whose criterion is stronger than red-green rather than missing.
 
 Red-green strategies (`vertical-tdd`, `regression-first`) must record concrete per-label `.red` and `.green` Evidence entries for the same check; `keel gate task-complete` rejects absent or pending entries.
 
+A check's Evidence may read `artifact <path> sha256:<digest>` instead of retelling the output. `keel gate task-complete` checks the file exists and the digest matches, and refuses a path outside the change's own directory — archiving moves that directory, so a pointer outside it breaks. Keel hashes the bytes and reads nothing inside them: the claim the artifact supports stays yours.
+
 ## Domain lenses
 
 When the change's proposal/design/specs or the task's Touch extensions signal a domain, consult the matching lens's `Execution and review checks` section from `keel/lenses/` — the lens whose `Applies when:` header matches — before finalizing the strategy and the first check, and load only that one. When no lens matches, load nothing.