@event4u/agent-config 15.0.0 → 16.1.0

package/dist/agent-src/templates/roadmaps.md

@@ -64,6 +64,16 @@ that was never a judgement call.
     "Target release: X.Y.Z", never plan git tags or deprecation dates. Release
     and tag decisions belong to the user and are taken outside the roadmap.
     This is enforced by [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
+
+    **What the prohibition does not reach — a state, not a schedule.** The five
+    sentences above are unchanged and stay the rule: a roadmap does not decide
+    *when* or *in which version* work ships. It MUST, however, declare any
+    intentionally unreleasable intermediate tree state, together with the
+    machine-verified condition that clears it, per rule 28. Naming a state that
+    must not be published is not a release decision — it is a fact about the tree
+    that the release path has no other way to learn, and today cannot learn: the
+    release entry points read no roadmap at all. Declaring the state is
+    mandatory; deciding what to do about it at a cut is still the operator's.
 14. **No automatic branch switches mid-roadmap.** Roadmap work runs on the
     branch the user is on. If a separate branch (spike, hotfix, experiment)
     would be genuinely useful, the agent may propose it **once** while
@@ -231,6 +241,32 @@ that was never a judgement call.
     edge source stays the single one already defined above; `relates:` never
     becomes a second dependency source.
 
+    **Sibling block, same frontmatter — `delivery:`.** Optional, and unlike
+    `execution:` it describes what happens to the BRANCH rather than to the
+    run's interaction pattern:
+
+    ```yaml
+    delivery:
+      pr_topology: stacked      # single (default) | stacked
+    ```
+
+    `pr_topology: stacked` declares a dependent series of pull requests. It is
+    a plan the owner writes before execution and is **never** chosen by the
+    agent and never asked about at roadmap creation — see the `delivery:` block
+    in `agent-settings.template.yml`, where all three keys are Class C for that
+    reason. A roadmap declaring `stacked` owes a `## PR plan` section naming
+    the series and the order; `single` owes nothing, which is why it is the
+    default.
+
+    **Not yet a live override, and this is the honest state rather than an
+    omission.** `load_agent_settings` has four layers and none of them is a
+    roadmap, so a `delivery:` block here is read by no code today. It is
+    documented now because the key it mirrors is Class C — the owner has to
+    have a place to write the plan that is not an agent-writable setting — and
+    the cascade layer that would read it is scheduled by ADR-268, not yet
+    built. Until it is, treat a `delivery:` block here as a note to the next
+    human reader rather than as configuration.
+
     An explicit `relates: []` is a complete answer and the common one, but only
     when it carries the probe's `scanned:` line as its justification:
 
@@ -301,6 +337,13 @@ that was never a judgement call.
     step gated by a specific blocker may cross-reference it inline:
     `- [ ] … <!-- blocked-by: <blocker-id> -->`.
 
+    **A blocker stops execution; a hold stops publication.** The two are not
+    interchangeable and never substitute for one another. A blocker says the work
+    cannot proceed and is cleared by a person; a release hold (rule 28) says the
+    work may proceed but its intermediate tree state must not ship, and is
+    cleared by a checkbox whose `verify:` a machine runs. A roadmap that is
+    merely unfinished has neither — incompleteness is not a release condition.
+
     **A user-decision blocker's annotation records whether the question
     was actually put.** Where the blocker's `Owner:` is the maintainer,
     the user or the owner, the marker carries an `asked:` field —
@@ -400,6 +443,22 @@ that was never a judgement call.
     on nothing until an author declares a class and there is no backlog
     to grandfather.
 
+    **A judgement call is never parked here.** A blocker records a decision
+    the agent **correctly did not own**. A technical judgement call — two
+    valid architectures, a dependency trade-off, an unclear boundary with no
+    new product semantics — is not one of those: it routes back through the
+    closure pass and is resolved at the lowest rung that owns it (evidence,
+    convention, the agent, an independent session, the council, the team),
+    then recorded as a `## Decisions` row per rule 27. A technical decision
+    does not become owner-owned because it is hard (ADR-268 § 10).
+
+    An entry MAY declare `- **Ownership:** <class>`, and when it does the
+    class must be one of the three owner-owned ones — `product-owned`,
+    `business-owned`, `destructive-owned`. A technical class there is the
+    parked judgement call this retires, and `lint_roadmap_blockers` reds it.
+    The field is optional and HARD rather than ratcheted, on the same
+    no-backlog-to-grandfather ground as `Class:`.
+
     **Legacy fallback.** A body-level `> Blocked until <condition>`
     note (the follow-up-roadmap convention from rule 17) is parsed by
     the dashboard generator as one implicit roadmap-level blocker
@@ -582,6 +641,126 @@ that was never a judgement call.
     tracked estate; blocking is earned by tracked-scope evidence, not
     assumed).
 
+27. **A ready roadmap carries no unresolved decision — it carries a
+    `## Decisions` table.** A plan enters execution as an **execution
+    contract**: every foreseeable decision closed before the first step,
+    so a long run never meets a question planning could have closed.
+
+    The section is a six-column table, and the two vocabularies in it are
+    closed sets:
+
+    ```markdown
+    ## Decisions
+
+    | ID | ownership | resolved by | decision | evidence | revisit if |
+    |---|---|---|---|---|---|
+    | D1 | contested-technical | council:2026-09-13 | NDJSON on disk | streaming read at bounded RSS | the reader stops streaming |
+    ```
+
+    `ownership` is one of the eight ownership classes — `deterministic`,
+    `reversible-technical`, `contested-technical`, `critical-technical`,
+    `product-owned`, `business-owned`, `destructive-owned`,
+    `spend-exhaustion`. The axis is **ownership, not impact**: a technical
+    decision does not become owner-owned because it is hard
+    (ADR-268 § 10). `resolved by` is one of `evidence`, `agent`,
+    `independent:<session or model>`, `council:<record>`, `team:<record>`,
+    `owner` — the prefixed forms carry their record, because a resolver
+    with no record is a claim rather than a resolution.
+
+    `revisit if` names the condition that reopens the row. Execution reads
+    the table **before any step**, and a closed decision is re-asked only
+    when its `revisit if` condition became true — not because a context
+    reset lost it, which is the repeat the ask census counts.
+
+    Enforced by `lint_decision_classes`: in a ready roadmap an unresolved
+    marker (`TBD`, *to be decided*, *decide later*, *open question*)
+    outside the section is a finding, and the same marker resolved into a
+    row is not. `## Blockers` is the other discharge — a five-field
+    structured blocker IS the record of a decision the agent correctly did
+    not own, so an open item there is not an unclosed one.
+
+    The section is owed where there is a decision to record. A plan that
+    closed everything inline carries no table and no marker, and is
+    complete; an empty table written to satisfy a template records
+    nothing, exactly as rule 25 says of a perfunctory pre-mortem.
+
+28. **Release holds — declare an unreleasable intermediate state, or there is
+    not one.** A roadmap whose intermediate tree state must not be published
+    declares that state in a `## Release holds` section. Nothing else in the
+    repository can express it, and the release path reads no roadmap today, so
+    an undeclared unreleasable state is invisible to every release boundary.
+
+    **Non-goal, stated first because it is the failure mode closest to hand:
+    roadmap *incompleteness* is never a release condition.** An unfinished
+    roadmap does not block a release, has never blocked one, and must not start
+    to. A hold is a positive declaration about a named tree state, never a side
+    effect of open checkboxes.
+
+    **Authoring order — `re-sequence → guard → hold`, in that order.** A hold is
+    the last resort, not the first tool:
+
+    1. **Re-sequence.** Can the phases be cut so that no intermediate state is
+       broken? A continuous shape needs no hold and is always preferred.
+    2. **Guard.** Can the half-built surface be hidden behind a flag, an unwired
+       entry point, or a default that keeps it inert? A guarded state is
+       publishable and needs no hold.
+    3. **Hold.** Only when neither works. Every hold entry therefore carries a
+       mandatory `Why not a guard:` field naming the concrete reason the guard
+       rung failed. A hold entry without it is malformed and reddens CI.
+
+    **Entry shape** (one entry per hold, inside `## Release holds`):
+
+    ```markdown
+    ## Release holds
+
+    ### hold: <kebab-id>
+    - **Channel:** all             <!-- all | latest -->
+    - **Opened by:** <phase.step>  <!-- the checkbox whose [x] opens the window -->
+    - **Cleared by:** <phase.step> <!-- the checkbox whose [x] closes it -->
+    - **State:** {the one sentence naming what is broken in the tree while open.}
+    - **Why not a guard:** {why rung 2 failed, concretely.}
+    ```
+
+    **Marker grammar.** Both named steps carry an inline marker so the binding is
+    readable from the checkbox and not only from the section:
+    `- [ ] … <!-- opens-hold: <hold-id> -->` and
+    `- [ ] … <!-- clears-hold: <hold-id> -->`. The clearing step MUST carry a
+    `verify:` field (rule 23) — a hold cleared by an unverified flip is a hold
+    cleared by assertion.
+
+    **Channel vocabulary.** `all` (the default, and what an omitted `Channel:`
+    parses to) refuses every cut. `latest` refuses a stable `X.Y.Z` cut and
+    permits a `-next.N` prerelease, for a state safe to publish to an opt-in
+    channel but not to the default one. There is no third value and no override:
+    a plain `X.Y.Z` cut is never silently converted to a prerelease, and the
+    choice between finishing the clearing step, cutting `-next.N`, and using a
+    release line stays the operator's.
+
+    **State table.** A hold is in exactly one of four states, and only the first
+    is publishable:
+
+    | State | How it is reached | Release boundary |
+    |---|---|---|
+    | `unopened` | the opening checkbox is not `[x]` | permits |
+    | `open` | opener `[x]`, clearer not `[x]` | **refuses**, per `Channel:` |
+    | `cleared` | both `[x]` | permits |
+    | `not-evaluable` | the declaration is malformed, the file unreadable, or the evaluator errored or timed out | **refuses**, always, on every channel |
+
+    `not-evaluable` refusing is the load-bearing row: there is no path on which
+    "could not evaluate" reads as safe. A malformed declaration additionally
+    reddens normal CI, so a broken hold cannot fail open by being unparseable.
+
+    **Per-folder lifecycle.** A window does not disappear by moving the file.
+    A roadmap with an open window may not be moved to `archive/` or `skipped/` —
+    the move is refused naming the hold id. It may be moved to `later/`, and the
+    open window is then named in the `entry_condition.what` part; it still lists
+    and still refuses. Deletion is a known residual, not a mitigation: rule 12
+    already forbids it and no gate can see a file that is gone.
+
+    **No versions inside a hold entry.** Rule 13's prohibition applies inside
+    `## Release holds` exactly as it does everywhere else. A hold names a *state*
+    and its clearing *checkbox*; it never names a version, a tag, or a date.
+
 ---
 
 ## Quality Gates (remote CI by default)
@@ -672,6 +851,15 @@ complexity: lightweight
 - [ ] {Observable, testable criterion}
 - [ ] All quality gates pass (PHPStan, Rector, tests)
 
+<!-- ## Decisions — INCLUDE when the closure pass closed a decision this
+     plan would otherwise have met mid-run (rule 27). OMIT entirely when
+     nothing was open: an empty table records nothing.
+## Decisions
+
+| ID | ownership | resolved by | decision | evidence | revisit if |
+|---|---|---|---|---|---|
+| D1 | {ownership class} | {resolver} | {what was decided} | {file:line, record, probe} | {condition that reopens it} | -->
+
 <!-- ## Blockers — INCLUDE ONLY when a gate exists that only the user /
      a maintainer can clear (decision, external dependency, evidence
      threshold, soak window). OMIT entirely when there are none — see

package/dist/agent-src/templates/scripts/work_engine/directives/backend/_self_fix.ts

@@ -78,6 +78,41 @@ export const VOLATILE_KEYS: ReadonlyArray<string> = [
 /** Why the loop stopped, or that it has budget left. */
 export type SelfFixKind = 'retry' | 'exhausted' | 'no_progress';
 
+/**
+ * `SelfFixKind` in the vocabulary a reader can aggregate across surfaces.
+ *
+ * `Outcome.PARTIAL` says the loop stopped without a green; it cannot say
+ * whether the budget ran out or the target stopped moving, and those want
+ * different responses — a bigger budget against the first, a different
+ * approach against the second. Until now the distinction left this module only
+ * inside a free-text `message`, so the continuation hook's stops were
+ * countable and this loop's were not.
+ *
+ * The two values are members of `RunTerminalState`, whose authoritative
+ * declaration is `src/scripts/_lib/outcome_vocabularies.ts:RUN_TERMINAL_STATES`
+ * and whose prose home is `contexts/execution/terminal-states.md`. They are
+ * written as literals rather than imported because this file is a TEMPLATE:
+ * it ships into consumer projects that have no `src/scripts/_lib` to import
+ * from, and reaching across that boundary would break every install. It is a
+ * two-member projection across a packaging boundary, not a second vocabulary —
+ * nothing here may add a member the registry does not have.
+ */
+export const RUN_TERMINAL_BY_KIND: Readonly<Record<Exclude<SelfFixKind, 'retry'>, string>> = {
+    exhausted: 'exhausted',
+    no_progress: 'stagnated',
+};
+
+/**
+ * The run-terminal value for a decision, or `null` while the loop is still live.
+ *
+ * `retry` has no terminal by construction — the loop has not stopped — and the
+ * null is returned rather than defaulted so a caller cannot accidentally stamp
+ * a terminal value onto a run that is still going.
+ */
+export function run_terminal_for(kind: SelfFixKind): string | null {
+    return kind === 'retry' ? null : RUN_TERMINAL_BY_KIND[kind];
+}
+
 /** Verdict of {@link decide} — pure, so the caller owns every mutation. */
 export interface SelfFixDecision {
     kind: SelfFixKind;
@@ -147,6 +182,27 @@ export function record_attempt(state: DeliveryState, lane: string, signature: st
     state.self_fix = container;
 }
 
+/**
+ * Stamp the lane's run-terminal value onto `state.self_fix`.
+ *
+ * Written into the state the module already owns and the dispatcher already
+ * persists, rather than onto `StepResult` — `StepResult` carries `outcome`,
+ * `questions` and `message` and is shared by every directive in the engine, so
+ * widening it for one loop's stop reason would be a change to all of them.
+ *
+ * A `retry` decision writes nothing: the loop has not stopped, and a terminal
+ * value recorded mid-loop would be read as one by anything aggregating the
+ * field.
+ */
+export function record_run_terminal(state: DeliveryState, lane: string, decision: SelfFixDecision): void {
+    const run_terminal = run_terminal_for(decision.kind);
+    if (run_terminal === null) return;
+    const container = _pyTruthy(state.self_fix) ? (state.self_fix as Record<string, Any>) : {};
+    const lane_state = _lane_state(state, lane);
+    container[lane] = { ...lane_state, run_terminal };
+    state.self_fix = container;
+}
+
 /** DoD entries the agent has not recorded as proven. Never inferred. */
 export function unmet_dod(state: DeliveryState): Array<Record<string, Any>> {
     const dod = (state.ticket ?? {})['dod'];
@@ -213,8 +269,11 @@ export function partial_exit(args: {
     decision: SelfFixDecision;
     unmet: Array<Record<string, Any>>;
     rerun_directive: string;
+    /** Written the run-terminal value onto, when the caller has the state in hand. */
+    state?: DeliveryState;
 }): StepResult {
-    const { lane, ticket_id, verdict, decision, unmet, rerun_directive } = args;
+    const { lane, ticket_id, verdict, decision, unmet, rerun_directive, state } = args;
+    if (state !== undefined) record_run_terminal(state, lane, decision);
     const reason =
         decision.kind === 'no_progress'
             ? `two consecutive attempts produced an identical \`${lane}\` verdict, ` +
@@ -244,7 +303,8 @@ export function partial_exit(args: {
         ],
         message:
             `Ticket ${ticket_id} ${lane} verdict is \`${String(verdict)}\` after ` +
-            `${decision.attempts} self-fix attempt(s) (${decision.kind}); exiting PARTIAL.`,
+            `${decision.attempts} self-fix attempt(s) (${decision.kind}); exiting PARTIAL ` +
+            `(run_terminal: ${String(run_terminal_for(decision.kind))}).`,
     });
 }
 

package/dist/agent-src/templates/scripts/work_engine/directives/backend/test.ts

@@ -225,6 +225,7 @@ function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult
         decision,
         unmet: unmet_dod(state),
         rerun_directive: 'run-tests',
+        state,
     });
 }
 

package/dist/agent-src/templates/scripts/work_engine/directives/backend/verify.ts

@@ -201,6 +201,7 @@ function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult
         decision,
         unmet: unmet_dod(state),
         rerun_directive: 'review-changes',
+        state,
     });
 }
 

package/dist/cli-delegate/check_update_banner.js

@@ -123,6 +123,44 @@ function carveOutKeys() {
   return SETTINGS_CARVE_OUT.map((c) => c.key);
 }
 
+// src/scripts/_lib/settings_renamed_keys.ts
+var RENAMED_KEYS = /* @__PURE__ */ new Map([
+  ["planning.challenge_on_create", "planning.closure_pass"]
+]);
+var _warned = /* @__PURE__ */ new Set();
+function _read(tree, dotted) {
+  let cur = tree;
+  for (const part of dotted.split(".")) {
+    if (cur === null || typeof cur !== "object" || Array.isArray(cur)) return void 0;
+    cur = cur[part];
+  }
+  return cur;
+}
+function _write(tree, dotted, value) {
+  const parts = dotted.split(".");
+  let cur = tree;
+  for (const part of parts.slice(0, -1)) {
+    const next = cur[part];
+    if (next === null || typeof next !== "object" || Array.isArray(next)) cur[part] = {};
+    cur = cur[part];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+function applyRenamedKeys(layer) {
+  for (const [oldKey, newKey] of RENAMED_KEYS) {
+    const oldValue = _read(layer, oldKey);
+    if (oldValue === void 0) continue;
+    if (_read(layer, newKey) === void 0) _write(layer, newKey, oldValue);
+    if (_warned.has(oldKey)) continue;
+    _warned.add(oldKey);
+    process.stderr.write(
+      `\u26A0\uFE0F  settings: \`${oldKey}\` was renamed to \`${newKey}\`. The old key still works for one minor; rename it in your .agent-settings.yml.
+`
+    );
+  }
+  return layer;
+}
+
 // src/scripts/_lib/agent_settings.ts
 var _require = createRequire(import.meta.url);
 var Logger = class {
@@ -426,9 +464,9 @@ function load_agent_settings(options = {}) {
   }
   const cascade = _resolve_cascade_paths(cwd, project_path);
   const merged = template_defaults(template_path ?? void 0);
-  _deep_merge(merged, user_global_filtered);
+  _deep_merge(merged, applyRenamedKeys(user_global_filtered));
   for (const p of cascade) {
-    const layer = _read_yaml(p) ?? {};
+    const layer = applyRenamedKeys(_read_yaml(p) ?? {});
     if (Object.keys(layer).length > 0) {
       _deep_merge(merged, layer);
     }