@christang/keel 5.39.0 → 5.46.0

package/src/core/config.js

@@ -7,7 +7,13 @@ const path = require("path");
 // closed so an entry outside it can be reported by name: a free-form grant
 // cannot tell a typo from a decision, and silently dropping one leaves the
 // author believing they authorized something they did not.
-const STANDING_AUTHORIZATION_ACTIONS = ["commit", "push", "release", "archive"];
+const STANDING_AUTHORIZATION_ACTIONS = [
+  "commit",
+  "push",
+  "release",
+  "archive",
+  "continuation",
+];
 
 // The closed vocabulary of capability tiers a repository may declare for a
 // delegated task. The names describe the capability the work requires, never

package/src/core/gates.js

@@ -244,7 +244,7 @@ function taskStart(repo, options) {
   const compiled = compileTaskContract(repo, selection.change, task);
   const problems = [
     ...compiled.diagnostics,
-    ...invalidationProblems(repo, selection.content, selection.tasks),
+    ...invalidationProblems(repo, selection.content, selection.tasks, selection.change),
   ];
   // Recording the current fingerprint is idempotent: --record replaces the
   // selected task's Contract anchor whatever it holds, so reauthorizing a task
@@ -394,11 +394,21 @@ const TRACKER_REFERENCE = /\bhttps?:\/\/\S/i;
 
 // The owner forms, stated once so every refusal that lists them agrees with
 // every other and with what the checks below actually accept.
+//
+// What each form is worth is part of the sentence, because a list of accepted
+// spellings reads as a list of verified guarantees. A path is checked for
+// existence at the moment it is cited and never again; a tracker reference is
+// accepted on its shape, because a gate that fetched one would stop being
+// local and offline, which is the property its verdict rests on. Leaving that
+// unsaid is how an author comes to believe a check ran that did not (#100).
 const DURABLE_OWNER_FORMS =
   "an absolute `https://…` tracker reference, or any repo-relative path that "
-  + "exists — `keel/archive/…`, an `openspec/changes/…` artifact, or the "
-  + "repository's own ledger; `keel/HANDOFF.md` is a pointer override rather "
-  + "than an owner";
+  + "exists and outlives this change — an archived `openspec/changes/archive/…` "
+  + "artifact, `keel/archive/…`, or the repository's own ledger; "
+  + "`keel/HANDOFF.md` is a pointer override rather than an owner. A path is "
+  + "checked for existence when it is cited and is not re-checked afterwards, "
+  + "and a tracker reference is accepted on its shape because a gate runs "
+  + "offline and never fetches one";
 
 // Trailing punctuation a declared path can abut in prose. ASCII sentence marks
 // and their CJK counterparts both belong here: once the extractor stops
@@ -407,9 +417,23 @@ const DURABLE_OWNER_FORMS =
 // swallows it and the gate looks for a file that cannot exist.
 const DECLARED_PATH_TRAILING = /[.,;:!?)\]}"'\u2019\u201d\u3002\uff0c\u3001\uff1b\uff1a\uff01\uff1f\uff09\u3011\u300b\u300d\u300f]+$/;
 
-// A declared path is a run of non-whitespace holding a separator. What ends a
-// path is whitespace; what a path is *made of* is the filesystem's business,
-// and answering the first question with the second is what refused
+// A file at the repository root carries no separator, and nine of them sit at
+// this repository's root — `AGENTS.md`, `README.md`, `package.json` among them
+// — every one a legitimate owner. Requiring a separator refused them with "it
+// names neither a check nor a path", for a path whose file exists, and left
+// the author only `./AGENTS.md`: a concession to this function rather than a
+// path anyone meant (issue #107).
+//
+// The shape is a trailing extension beginning with a letter. That is what
+// keeps a bare word unrecognized — `Durable owner: pending` reported as a
+// missing file would send the author to create one — and what keeps a version
+// string out, since `5.44.0` would otherwise read as `44` with extension `0`,
+// and authors write versions in prose beside an owner.
+const ROOT_FILE_NAME = /^[^\s`]+\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+
+// A declared path is a run of non-whitespace. What ends a path is whitespace;
+// what a path is *made of* is the filesystem's business, and answering the
+// first question with the second is what refused
 // `notes/note-006-转岗最难的不是流程/note.md` by reporting that
 // `notes/note-006-` does not exist — a path nobody wrote (issue #60). It is the
 // same class as #40 on the worktree-reading side, which survived because that
@@ -425,24 +449,66 @@ function declaredPath(value) {
   const quoted = text.match(/`([^`\n]*\/[^`\n]*)`/);
   if (quoted) return quoted[1].trim() || null;
   const bare = text.match(/[^\s`]+\/[^\s`]+/);
-  if (!bare) return null;
-  return bare[0].replace(DECLARED_PATH_TRAILING, "") || null;
+  if (bare) return bare[0].replace(DECLARED_PATH_TRAILING, "") || null;
+  // The separator form is tried first and is unchanged, so nothing that
+  // resolves today resolves differently. The trim runs before the shape is
+  // judged, so a root file ending a sentence is still a root file.
+  for (const token of text.split(/\s+/)) {
+    const trimmed = token.replace(DECLARED_PATH_TRAILING, "");
+    if (trimmed && ROOT_FILE_NAME.test(trimmed)) return trimmed;
+  }
+  return null;
+}
+
+// A path inside the selected change's own directory exists now and cannot
+// exist later: archiving moves `openspec/changes/<name>/` under
+// `openspec/changes/archive/`, so the one guarantee the gate offers expires in
+// the next step of the workflow that accepted it. Measured in this repository,
+// 10 declarations name such a path and all 10 are dead; the field report
+// measured 35 of 36 (issue #100). Existence is necessary and not sufficient —
+// the same line `keel/HANDOFF.md` already sits on.
+//
+// The rule is the directory, not the file: every file under it moves together,
+// and naming `design.md` would refuse one spelling of one instance. And it is
+// *this* change's directory, not change directories in general — the protocol
+// names a new OpenSpec change as a legitimate owner of deferred work, and no
+// measured pointer has that shape.
+function insideOwnChangeDirectory(candidate, change) {
+  if (!change || !candidate) return false;
+  const prefix = `openspec/changes/${change}/`;
+  return String(candidate).replace(/^\.\//, "").startsWith(prefix);
 }
 
 // Classify a declared `Durable owner:` value. A gate runs without network, so a
 // URL is accepted on shape alone; a path is the one form it can actually check,
-// and checking it is stricter than the prefix whitelist this replaced.
-function durableOwnerVerdict(repo, value) {
+// and checking it is stricter than the prefix whitelist this replaced — for as
+// long as the path outlives the change, which `insideOwnChangeDirectory` is
+// there to decide.
+function durableOwnerVerdict(repo, value, change) {
   const owner = String(value || "").trim();
   if (!owner) return { ok: false, reason: "unrecognized" };
   if (/keel\/HANDOFF\.md/i.test(owner)) return { ok: false, reason: "handoff" };
   if (TRACKER_REFERENCE.test(owner)) return { ok: true };
   const candidate = declaredPath(owner);
   if (!candidate) return { ok: false, reason: "unrecognized" };
+  if (insideOwnChangeDirectory(candidate, change)) {
+    return { ok: false, reason: "transient", path: candidate };
+  }
   if (fs.existsSync(path.join(repo, candidate))) return { ok: true };
   return { ok: false, reason: "missing", path: candidate };
 }
 
+// The one sentence every transient refusal makes, so the three consumers say
+// it the same way. It names the cause (the directory moves) rather than the
+// symptom, because the author cannot repair a spelling problem they do not
+// have.
+function transientOwnerMessage(candidate) {
+  return `\`${candidate}\` is inside this change's own directory, which moves `
+    + "to `openspec/changes/archive/` when the change is archived — the file "
+    + "exists now and the pointer is guaranteed to break. Name something that "
+    + `outlives the change: ${DURABLE_OWNER_FORMS}.`;
+}
+
 // A finding has three dispositions and the gate recognized two. One found and
 // fixed inside the task recording it has no owner to name and nothing to
 // discard, so the only text that passed was `Discard reason:` — filing a repair
@@ -469,7 +535,7 @@ const RESOLVED_HERE = /\bresolved here\s*:[ \t]*(\S*)/gi;
 // it or the artifact that shows it. A bare marker is refused because a
 // disposition that asserts its own conclusion would be a way out of the other
 // two, and the third state would decay into the easiest exit.
-function resolutionEvidenceVerdict(repo, value, commands) {
+function resolutionEvidenceVerdict(repo, value, commands, change) {
   const evidence = String(value || "").trim();
   if (!evidence) return { ok: false, reason: "empty" };
   // The tracker form is tested before the path form: a URL contains something
@@ -484,6 +550,12 @@ function resolutionEvidenceVerdict(repo, value, commands) {
   }
   const candidate = declaredPath(evidence);
   if (!candidate) return { ok: false, reason: "unrecognized" };
+  // Resolution evidence is a file like any other and moves with the directory
+  // holding it, so it earns the same verdict rather than a second answer to
+  // the same question.
+  if (insideOwnChangeDirectory(candidate, change)) {
+    return { ok: false, reason: "transient", path: candidate };
+  }
   if (fs.existsSync(path.join(repo, candidate))) return { ok: true };
   return { ok: false, reason: "missing", path: candidate };
 }
@@ -504,13 +576,16 @@ function resolutionEvidenceMessage(verdict) {
   if (verdict.reason === "unknown-check") {
     return `${lead}${verdict.label} is not a check this task declares.${tail}`;
   }
+  if (verdict.reason === "transient") {
+    return `${lead}${transientOwnerMessage(verdict.path)}${tail}`;
+  }
   if (verdict.reason === "missing") {
     return `${lead}\`${verdict.path}\` does not exist.${tail}`;
   }
   return `${lead}it names neither a check nor a path.${tail}`;
 }
 
-function findingOwnerIsDurable(repo, findings) {
+function findingOwnerIsDurable(repo, findings, change) {
   if (/keel\/HANDOFF\.md/i.test(findings)) return false;
   if (/\b(?:explicit\s+)?discard (?:reason|rationale)\s*:/i.test(findings)) {
     return true;
@@ -520,11 +595,17 @@ function findingOwnerIsDurable(repo, findings) {
   // prose, and a finding that merely mentions the source file it concerns has
   // not thereby given that finding an owner.
   const declared = findings.match(/Durable owner:\s*(\S[^\n]*)/i);
-  if (declared) return durableOwnerVerdict(repo, declared[1]).ok;
+  if (declared) return durableOwnerVerdict(repo, declared[1], change).ok;
   const artifact = findings.match(
     /\b(openspec\/changes\/[A-Za-z0-9][A-Za-z0-9._-]*\/(?:proposal|design|tasks)\.md)(?:#\d+(?:\.\d+)*)?/i
   );
-  if (artifact && fs.existsSync(path.join(repo, artifact[1]))) return true;
+  if (
+    artifact
+    && !insideOwnChangeDirectory(artifact[1], change)
+    && fs.existsSync(path.join(repo, artifact[1]))
+  ) {
+    return true;
+  }
   // Same extractor, scoped to the archive prefix: the segment after
   // `keel/archive/` is a path like any other and was equally ASCII-bound.
   const archive = findings.match(/keel\/archive\/[^\s`]*/i);
@@ -741,7 +822,7 @@ function attributeChanged(repo, task, changedList, contract, change, tasks) {
   };
 }
 
-function completionChecks(repo, task, contract = null, changeVerify = null) {
+function completionChecks(repo, task, contract = null, changeVerify = null, change = null) {
   const problems = [];
   const commands = contract
     ? contract.capsule.verification.commands.map((item) => item.label)
@@ -900,14 +981,14 @@ function completionChecks(repo, task, contract = null, changeVerify = null) {
     const resolved = [...reviewFields.Findings.matchAll(RESOLVED_HERE)];
     if (resolved.length > 0) {
       for (const claim of resolved) {
-        const verdict = resolutionEvidenceVerdict(repo, claim[1], commands);
+        const verdict = resolutionEvidenceVerdict(repo, claim[1], commands, change);
         if (verdict.ok) continue;
         problems.push(
           problem("finding-resolution-evidence", resolutionEvidenceMessage(verdict))
         );
         break;
       }
-    } else if (!findingOwnerIsDurable(repo, reviewFields.Findings)) {
+    } else if (!findingOwnerIsDurable(repo, reviewFields.Findings, change)) {
       problems.push(
         problem(
           "finding-owner",
@@ -950,7 +1031,13 @@ function taskComplete(repo, options) {
   const contract = compileTaskContract(repo, selection.change, task);
   const usableContract = contract.diagnostics.length === 0 ? contract : null;
   const changeVerify = changeVerifyChecks(selection.content, selection.tasks);
-  const checks = completionChecks(repo, task, usableContract, changeVerify);
+  const checks = completionChecks(
+    repo,
+    task,
+    usableContract,
+    changeVerify,
+    selection.change
+  );
   checks.problems.push(...contract.diagnostics);
   const missingAnchor = missingAnchorProblem(selection, task);
   if (missingAnchor) {
@@ -1125,7 +1212,7 @@ function changeVerifyProblems(content, tasks) {
 // the author was not already holding in mind, so a list of remembered files
 // reproduces the failure; a searchable phrase is what turns the declaration
 // into a grep. What the phrase says is the agent's judgment, not the gate's.
-function invalidationProblems(repo, content, tasks) {
+function invalidationProblems(repo, content, tasks, change) {
   const heading = content.search(/^## Invalidates\s*$/m);
   if (heading < 0) {
     return [
@@ -1159,7 +1246,15 @@ function invalidationProblems(repo, content, tasks) {
   const problems = [];
   for (const entry of entries) {
     const [, id, body] = entry;
-    if (!/"[^"\n]{3,}"/.test(body)) {
+    // The quotation is read across the entry, not one line of it. An entry
+    // carries a quotation, a location, and a closure, and wraps as often as it
+    // needs to — 42 of this repository's 194 archived entries span more than
+    // one line. Requiring the quotation to fit on one refused entries that had
+    // named exactly what was asked for, and offered no repair but reflowing
+    // the text (issue #108). The bound is the entry: `entries` above splits on
+    // the next `I<n>`, so a quotation cannot reach past its own. `Findings` in
+    // this same file is already read as wrapping.
+    if (!/"[^"]{3,}"/.test(body)) {
       problems.push(
         problem(
           "invalidation-phrase",
@@ -1173,7 +1268,7 @@ function invalidationProblems(repo, content, tasks) {
     const updated = body.match(/Updated by:\s*([0-9.,\s-]+)/i);
     const declaredOwner = body.match(/Durable owner:\s*(\S[^\n]*)/i);
     const verdict = declaredOwner
-      ? durableOwnerVerdict(repo, declaredOwner[1])
+      ? durableOwnerVerdict(repo, declaredOwner[1], change)
       : { ok: false, reason: "absent" };
     const discarded = /Discard(?:ed)? (?:reason|rationale):\s*\S/i.test(body);
     if (!updated && !verdict.ok && !discarded) {
@@ -1185,6 +1280,13 @@ function invalidationProblems(repo, content, tasks) {
               + "file exists in this repository."
           )
         );
+      } else if (verdict.reason === "transient") {
+        problems.push(
+          problem(
+            "invalidation-owner-transient",
+            `${id} names ${transientOwnerMessage(verdict.path)}`
+          )
+        );
       } else if (verdict.reason === "handoff") {
         problems.push(
           problem(
@@ -1227,7 +1329,7 @@ function invalidationProblems(repo, content, tasks) {
   return problems;
 }
 
-function expectationProblems(repo, content, tasks) {
+function expectationProblems(repo, content, tasks, change) {
   const heading = content.search(/^## Expectation Coverage\s*$/m);
   if (heading < 0) {
     return [
@@ -1263,7 +1365,7 @@ function expectationProblems(repo, content, tasks) {
     const covered = body.match(/Covered by:\s*([0-9.,\s-]+)/i);
     const declaredOwner = body.match(/Durable owner:\s*(\S[^\n]*)/i);
     const verdict = declaredOwner
-      ? durableOwnerVerdict(repo, declaredOwner[1])
+      ? durableOwnerVerdict(repo, declaredOwner[1], change)
       : { ok: false, reason: "absent" };
     const discarded = /Discard(?:ed)? (?:reason|rationale):\s*\S/i.test(body);
     if (!covered && !verdict.ok && !discarded) {
@@ -1275,6 +1377,13 @@ function expectationProblems(repo, content, tasks) {
               + "file exists in this repository."
           )
         );
+      } else if (verdict.reason === "transient") {
+        problems.push(
+          problem(
+            "expectation-owner-transient",
+            `${id} names ${transientOwnerMessage(verdict.path)}`
+          )
+        );
       } else {
         problems.push(
           problem(
@@ -1378,7 +1487,8 @@ function changeClose(repo, options) {
       repo,
       task,
       contract.diagnostics.length === 0 ? contract : null,
-      changeVerify
+      changeVerify,
+      selection.change
     );
     problems.push(
       ...checks.problems.map((item) =>
@@ -1391,7 +1501,9 @@ function changeClose(repo, options) {
       )
     );
   }
-  problems.push(...expectationProblems(repo, selection.content, selection.tasks));
+  problems.push(
+    ...expectationProblems(repo, selection.content, selection.tasks, selection.change)
+  );
   problems.push(...changeVerifyProblems(selection.content, selection.tasks));
 
   const changePath = path.dirname(selection.tasksPath);

package/src/core/task-contract.js

@@ -687,9 +687,16 @@ function criticalAuthority(repo, change, reference) {
     };
   }
   const content = fs.readFileSync(designPath, "utf8");
+  // Accepted line shapes: an optional CommonMark list bullet, the identifier
+  // bare or wrapped in balanced `**`, then the dash and statement. Authors
+  // overwhelmingly write the bulleted and bold shapes (issue #49).
   const matches = [
     ...content.matchAll(
-      new RegExp(`^\\s*${reference}\\s*[—-]\\s*(.+?)\\s*$`, "gmi")
+      new RegExp(
+        `^\\s*(?:[-*+]\\s+)?(?:\\*\\*${reference}\\*\\*|${reference})`
+        + `\\s*[—-]\\s*(.+?)\\s*$`,
+        "gmi"
+      )
     ),
   ];
   if (matches.length !== 1) {
@@ -707,9 +714,11 @@ function criticalAuthority(repo, change, reference) {
           code: "unresolved-covers",
           message:
             `Unparsed Covers critical statement: ${reference}. It appears in `
-            + "design.md but not in the required shape — write it starting "
-            + `the line as \`${reference} — one-line statement\` (no leading `
-            + "`-`, `**`, or other decoration) so it can be resolved.",
+            + "design.md but not in an accepted line shape — write it as a "
+            + "line opening with the identifier and a dash, "
+            + `\`${reference} — one-line statement\`, optionally as a list `
+            + `bullet (\`- ${reference} — …\`) and/or with the identifier `
+            + `bold (\`**${reference}** — …\`).`,
         },
       };
     }
@@ -758,7 +767,17 @@ function resolveAuthority(repo, change, task) {
   }
   const entries = [...seen].sort();
   for (const entry of entries) {
-    const critical = criticalAuthority(repo, change, entry);
+    // A critical-statement reference may open its entry with a trailing
+    // annotation after a dash (`D2 — note`); the identifier resolves and the
+    // annotation stays annotation — design.md owns the statement text. The
+    // boundary after the identifier is whitespace or an em dash so that free
+    // text like `D2-compatible` does not become a reference.
+    const annotated = entry.match(/^([DFAQ]\d+)(?=\s|—)\s*[—-]\s*.+$/);
+    const critical = criticalAuthority(
+      repo,
+      change,
+      annotated ? annotated[1] : entry
+    );
     if (critical) {
       if (critical.diagnostic) diagnostics.push(critical.diagnostic);
       if (critical.authority) authority.push(critical.authority);