@event4u/agent-config 9.34.0 → 9.36.0

package/src/agent-src/scripts/roadmap_gates.ts

@@ -46,6 +46,13 @@
  *   ./agent-config gates --all      # every open blocker, grouped by owner
  *   ./agent-config gates --json     # machine-readable
  *   ./agent-config gates --reply    # reply-close form; empty when none
+ *   ./agent-config gates --pending  # staged actions awaiting confirmation
+ *
+ * `--pending` reads a different source — the staged-confirmation store, not the
+ * roadmap tree — and stays out of `--reply` on purpose. ADR-222 fixes the
+ * reply-close form at exactly ONE decision rendered in full; folding a second
+ * source into it would silently change which decision "the one" is, and that
+ * contract is not this step's to move.
  */
 
 import * as path from 'node:path';
@@ -58,6 +65,8 @@ import {
     blocker_needs_user as needsUser,
     type Blocker,
 } from './update_roadmap_progress.js';
+import { listPending } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.js';
+import type { StagedAction } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -327,6 +336,89 @@ function renderJson(entries: readonly Entry[], all: boolean): string {
     );
 }
 
+/**
+ * `--pending`: staged actions awaiting a human confirmation.
+ *
+ * A second source under the same verb, and the reason it belongs here rather
+ * than in a new command is the verb's own definition — "open decisions that
+ * need you, as actions". A staged irreversible action IS one, and the most
+ * literal kind: the roadmap blockers above are decisions a human owes a plan,
+ * this is a decision a human owes an action that is already loaded and waiting.
+ *
+ * Expired stages are counted, never listed as actionable. An expired stage
+ * cannot execute (`stageStatus` derives that from the clock, not from a sweep
+ * having run), so rendering it beside a live one would put two rows in front of
+ * the reader where only one is a decision.
+ */
+function renderPending(root: string, now: number): string {
+    const rows = listPending(root, now);
+    const live = rows.filter((r) => r.status === 'pending');
+    const expired = rows.filter((r) => r.status === 'expired');
+    const lines: string[] = [];
+
+    if (live.length === 0) {
+        lines.push(
+            expired.length === 0
+                ? 'No staged actions awaiting confirmation.'
+                : `Nothing awaits your confirmation. ${expired.length} stage` +
+                      `${expired.length !== 1 ? 's' : ''} expired unconfirmed — the action never fired.`,
+        );
+        return lines.join('\n') + '\n';
+    }
+
+    lines.push(
+        `${live.length} staged action${live.length !== 1 ? 's' : ''} await` +
+            `${live.length === 1 ? 's' : ''} your confirmation` +
+            (expired.length > 0 ? ` · ${expired.length} expired unconfirmed` : ''),
+    );
+    let n = 0;
+    for (const { stage } of live) {
+        n += 1;
+        lines.push(...renderStage(stage, n));
+    }
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+
+function renderStage(stage: StagedAction, index: number): string[] {
+    const head = `${index} · ${stage.action}`;
+    const tail = `token: ${stage.token}`;
+    const dashes = Math.max(3, WIDTH - head.length - tail.length - 6);
+    return [
+        '',
+        `── ${head} ${'─'.repeat(dashes)} ${tail}`.trimEnd(),
+        // The object is the first field on purpose: an approval that does not
+        // name the exact object is the thing non-destructive-by-default forbids,
+        // so it is what the reader must see before anything else.
+        ...field('Object:', stage.object),
+        ...field('Staged by:', stage.source),
+        ...field('Expires:', stage.expires_at),
+    ];
+}
+
+function renderPendingJson(root: string, now: number): string {
+    const rows = listPending(root, now);
+    return (
+        JSON.stringify(
+            {
+                awaitingYou: rows.filter((r) => r.status === 'pending').length,
+                expired: rows.filter((r) => r.status === 'expired').length,
+                staged: rows.map(({ stage, status }) => ({
+                    token: stage.token,
+                    action: stage.action,
+                    object: stage.object,
+                    source: stage.source,
+                    stagedAt: stage.staged_at,
+                    expiresAt: stage.expires_at,
+                    status,
+                })),
+            },
+            null,
+            2,
+        ) + '\n'
+    );
+}
+
 function _isDir(p: string): boolean {
     try {
         return fs.statSync(p).isDirectory();
@@ -340,8 +432,8 @@ function _isDir(p: string): boolean {
  * `agents/roadmaps`, otherwise fall back to the git toplevel (monorepo
  * sub-project support).
  */
-function _resolveRepoRoot(start: string): string {
-    if (_isDir(path.join(start, 'agents', 'roadmaps'))) {
+function _resolveRepoRoot(start: string, marker = path.join('agents', 'roadmaps')): string {
+    if (_isDir(path.join(start, marker))) {
         return start;
     }
     try {
@@ -351,7 +443,7 @@ function _resolveRepoRoot(start: string): string {
             timeout: 10_000,
         });
         const top = (r.stdout || '').trim();
-        if (r.status === 0 && top !== '' && _isDir(path.join(top, 'agents', 'roadmaps'))) {
+        if (r.status === 0 && top !== '' && _isDir(path.join(top, marker))) {
             return top;
         }
     } catch {
@@ -365,6 +457,18 @@ function main(argv?: readonly string[]): number {
     const all = args.includes('--all');
     const json = args.includes('--json');
     const reply = args.includes('--reply');
+    const pending = args.includes('--pending');
+
+    // `--pending` resolves against `agents/runtime/`, not `agents/roadmaps/`,
+    // and is answered BEFORE the roadmaps-directory exit below: a staged action
+    // is independent of whether this project plans in roadmaps at all, so
+    // "no roadmaps here" is not an answer to "what awaits my confirmation".
+    if (pending) {
+        const root = _resolveRepoRoot(process.cwd(), path.join('agents', 'runtime'));
+        const now = Date.now();
+        process.stdout.write(json ? renderPendingJson(root, now) : renderPending(root, now));
+        return 0;
+    }
 
     const repoRoot = _resolveRepoRoot(process.cwd());
     const roadmapRoot = path.join(repoRoot, 'agents', 'roadmaps');
@@ -412,5 +516,16 @@ if (_isCliEntry()) {
     process.exitCode = main();
 }
 
-export { main, needsUser, regroupTodo, wrap, collectEntries, render, renderJson, renderReply };
+export {
+    main,
+    needsUser,
+    regroupTodo,
+    wrap,
+    collectEntries,
+    render,
+    renderJson,
+    renderReply,
+    renderPending,
+    renderPendingJson,
+};
 export type { Entry };

package/src/agent-src/templates/AGENTS.md

@@ -14,7 +14,7 @@
 ## Pointers
 
 - **Filling out this AGENTS.md** — section templates, capability bullets, multi-agent entry flow, monorepo layout: [`consumer-agents-md-guide`](.augment/contexts/contracts/consumer-agents-md-guide.md).
-- **Behavior rules (always active)** — [`.augment/rules/`](.augment/rules/). Kernel rules are **immutable**; tighten only via the override registry.
+- **Behavior rules** (9 always-on; rest routed) — [`.augment/rules/`](.augment/rules/). Kernel rules are **immutable**; tighten only via the override registry.
 - **Skills (on-demand expertise)** — domain skills surfaced by description, invoked on trigger match: [`.augment/skills/`](.augment/skills/).
 - **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).
 - **Project-specific docs** — your own architecture notes, roadmaps, sessions, contexts: [`agents/`](agents/).

package/src/agent-src/templates/scripts/memory_lookup.ts

@@ -388,8 +388,7 @@ function* _iter_knowledge_entries(): Generator<[string, Record<string, unknown>]
 /**
  * Naive relevance score: max over keys of (glob-match | substring).
  *
- * Good enough for the `absent` path where retrieval is best-effort.
- * The `present` path returns a real score from agent-memory.
+ * Retrieval is best-effort by design — this is the only scoring path.
  */
 export function _score(entry: Record<string, unknown>, keys: string[]): number {
     if (keys.length === 0) {

package/src/agent-src/templates/scripts/memory_signal.ts

@@ -214,10 +214,8 @@ export interface SignalRecord {
 /**
  * Append a signal entry. Returns the written record, or null when skipped.
  *
- * On `present` backend, routing to the package is a no-op here today —
- * the package adapter is wired in `road-to-agent-memory-integration.md`
- * Phase 3. For now, the file path is the single source of truth so
- * merge-safety is preserved in every mode.
+ * The file path is the single source of truth: there is no external backend
+ * to route to, so merge-safety holds in every mode.
  */
 export function emit(
     entry_type: string,

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/decision_gate.ts

@@ -41,6 +41,22 @@ type Any = unknown;
 
 const _BLOCK_REASON_PREFIX = 'decision_gate';
 
+/**
+ * Stage an action for confirmation and return the surface lines that name it.
+ *
+ * An injected collaborator rather than a direct import of
+ * `staged_confirmation_store.js`, for two reasons. The gate is called from a
+ * hook bus with no repo root and no clock of its own, and — the load-bearing
+ * one — an absent stager keeps the `ask` path byte-identical to what ships
+ * today. The confirmation primitive is deliberately UNBOUND until blocker
+ * `confirmation-degraded-host-semantics` is decided (5 of 8 hosts have no
+ * `pre_tool_use` slot), so reaching it has to be an explicit opt-in and not a
+ * behaviour change that arrives with an upgrade.
+ */
+export interface ConfirmationStager {
+    stage(input: { action: string; object: string; source: string }): readonly string[];
+}
+
 /**
  * Evaluate decision-engine gates on every `AFTER_STEP`.
  *
@@ -49,9 +65,11 @@ const _BLOCK_REASON_PREFIX = 'decision_gate';
  */
 export class DecisionGateHook {
     private readonly _settings: DecisionEngineSettings;
+    private readonly _stager: ConfirmationStager | null;
 
-    constructor(settings: DecisionEngineSettings) {
+    constructor(settings: DecisionEngineSettings, stager: ConfirmationStager | null = null) {
         this._settings = settings;
+        this._stager = stager;
     }
 
     /** Register the gate callback on `AFTER_STEP`. */
@@ -109,10 +127,22 @@ export class DecisionGateHook {
                 DecisionGateHook._surface(decision, 'ask_timeout'),
             );
         }
-        throw new HookHalt(
-            `${_BLOCK_REASON_PREFIX}:${decision.gate_id}`,
-            DecisionGateHook._surface(decision),
-        );
+        // `stop` and `ask` share this exit: both halt, which is the policy —
+        // ask and action are strictly sequential, so an interactive gate does
+        // not act while it asks. What `ask` adds, and only when a stager is
+        // injected, is a token on the surface so the answer can be matched to
+        // THIS question and consumed exactly once. The halt reason is
+        // deliberately unchanged: it is the identity downstream readers match on.
+        let surface = DecisionGateHook._surface(decision);
+        if (action === 'ask' && this._stager !== null) {
+            const extra = this._stager.stage({
+                action: `work_engine:advance:${decision.gate_id}`,
+                object: `phase ${decision.phase}`,
+                source: _BLOCK_REASON_PREFIX,
+            });
+            surface = [...surface, '', ...extra];
+        }
+        throw new HookHalt(`${_BLOCK_REASON_PREFIX}:${decision.gate_id}`, surface);
     }
 
     // -- formatting helpers -------------------------------------------

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/staged_confirmation.ts

@@ -0,0 +1,252 @@
+/**
+ * Staged confirmation — the pure half of exactly-once confirmed execution.
+ *
+ * `src/rules/non-destructive-by-default.md` already carries the whole policy:
+ * an irreversible action is confirmed on THIS turn, ask and action are strictly
+ * sequential ("Never act while asking"), and the approval names the exact
+ * object. What the tree had no mechanism for is the *sequencing itself* — a
+ * staged action, a confirmation that matches it, and the guarantee that a
+ * second approval of the same stage does not fire the action twice.
+ *
+ * Two properties carry that guarantee, and they are split across two files on
+ * purpose:
+ *
+ *   - **Identity is derived, not invented.** {@link stageAction} hashes the
+ *     action, the exact object, and a caller-supplied nonce into a token, so a
+ *     confirmation can only match the stage it was issued for. Restaging the
+ *     same object under a fresh nonce yields a different token — an approval
+ *     never carries over to "the next one like it".
+ *   - **The claim is atomic, and it lives in the store.** Nothing here can be
+ *     exactly-once by itself: two processes reading the same `pending` record
+ *     and both deciding "execute" is a check-then-act race no pure function can
+ *     close. This module decides WHAT the outcome should be;
+ *     `staged_confirmation_store.ts` makes the transition atomic with a
+ *     directory rename, which either succeeds once or fails.
+ *
+ * Nothing binds on this yet, deliberately. `pre_tool_use` exists on 3 of 8
+ * platform rows (`hook_manifest.yaml`), so a guard that claimed to enforce
+ * confirmation would be prose on the other five while reading like a control —
+ * the failure `src/rules/ui-audit-gate.md` names about its own scope. The
+ * decision is deferred behind blocker `confirmation-degraded-host-semantics`;
+ * until it lands, callers opt in explicitly.
+ *
+ * Pure: no filesystem, no clock, no randomness. `now` and `nonce` are
+ * parameters so a test pins a whole lifecycle without faking globals.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Lifecycle of one staged action. `expired` is not a stored state — it is
+ * derived from the clock by {@link stageStatus}, so a stale pending record
+ * cannot read as awaiting-approval merely because nobody swept it.
+ */
+export type StageState = 'pending' | 'confirmed' | 'declined';
+
+/** What {@link confirmOnce} concluded. Only `execute` authorizes the action. */
+export type ConfirmOutcome =
+    | 'execute'
+    | 'already-confirmed'
+    | 'expired'
+    | 'declined'
+    | 'token-mismatch';
+
+/**
+ * The `on_block_fallback` vocabulary from
+ * `work_engine/scoring/decision_engine.ts` (`stop` / `warn`, default `stop`),
+ * reused rather than re-invented: this module extends that gate's ask path, so
+ * a second fallback vocabulary would be a second contract to keep in sync.
+ */
+export type NonInteractiveFallback = 'stop' | 'warn';
+
+/**
+ * Default staging window. A confirmation the user never gives must not sit in
+ * the store as an approval waiting to be collected: an abandoned stage that
+ * stays valid indefinitely is a pre-approved irreversible action, which is the
+ * opposite of what the policy asks for. Fifteen minutes is long enough for a
+ * human to read the surface and answer, short enough that a turn which ended
+ * hours ago cannot authorize anything.
+ */
+export const STAGE_TTL_MS = 15 * 60 * 1000;
+
+export interface StagedAction {
+    /** Confirmation token — derived, never guessable from the object alone. */
+    readonly token: string;
+    /** What would fire: a command name, a skill slug, a concern id. */
+    readonly action: string;
+    /**
+     * The exact object the approval names — a path, a URL, a recipient, an
+     * amount. The policy's "names the exact object" clause lives here, which is
+     * why it is required rather than optional: a stage with no object is a
+     * category confirmation, and the rule forbids exactly that.
+     */
+    readonly object: string;
+    /** Who staged it — the surface a `gates --pending` reader needs. */
+    readonly source: string;
+    readonly staged_at: string;
+    readonly expires_at: string;
+    readonly state: StageState;
+    /** Set on the transition out of `pending`, never rewritten afterwards. */
+    readonly resolved_at?: string;
+}
+
+/** ISO-8601 seconds, matching the runtime records already in the tree. */
+function iso(ms: number): string {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+/**
+ * Derive the confirmation token.
+ *
+ * The nonce is a parameter and not read from a clock or an RNG here, so the
+ * derivation is reproducible in a test. It is also what makes two stages of the
+ * same object distinct: without it, approving a delete of `x` once would
+ * produce a token that matches every future delete of `x`.
+ *
+ * The separator is NUL, written as an escape sequence and never as a raw byte.
+ * NUL is the right separator — it cannot occur in an action, a path or a nonce,
+ * so no two different triples concatenate to the same string. A RAW NUL in a
+ * text source would make git, grep and file(1) treat the whole file as binary
+ * and skip it silently, which `lint_hidden_unicode` blocks on; the escape keeps
+ * the domain separation and leaves the file readable by every tool.
+ */
+export function deriveToken(action: string, object: string, nonce: string): string {
+    return createHash('sha256')
+        .update(`${action}\u0000${object}\u0000${nonce}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+
+/** Stage an action. Returns the record; it is the caller's job to persist it. */
+export function stageAction(args: {
+    action: string;
+    object: string;
+    source: string;
+    nonce: string;
+    now: number;
+    ttlMs?: number;
+}): StagedAction {
+    const ttl = args.ttlMs ?? STAGE_TTL_MS;
+    return {
+        token: deriveToken(args.action, args.object, args.nonce),
+        action: args.action,
+        object: args.object,
+        source: args.source,
+        staged_at: iso(args.now),
+        expires_at: iso(args.now + ttl),
+        state: 'pending',
+    };
+}
+
+/**
+ * Effective status at `now` — `expired` is derived, not stored.
+ *
+ * A pending record past its `expires_at` reads as `expired` even though no
+ * sweep has run, so the guarantee does not depend on a pruner having been
+ * called. Prune is housekeeping; this is the decision.
+ */
+export function stageStatus(stage: StagedAction, now: number): StageState | 'expired' {
+    if (stage.state === 'pending' && Date.parse(stage.expires_at) <= now) {
+        return 'expired';
+    }
+    return stage.state;
+}
+
+export function isExpired(stage: StagedAction, now: number): boolean {
+    return stageStatus(stage, now) === 'expired';
+}
+
+/**
+ * Decide what a confirmation attempt means. `execute` — and only `execute` —
+ * authorizes the action, and it is returned at most once per stage because the
+ * caller writes the returned record back before acting.
+ *
+ * The token is compared in full: a confirmation for a different stage is
+ * `token-mismatch` rather than a silent no-op, because a mismatch is a real
+ * signal (a stale surface, a copied token) and swallowing it would hide it.
+ */
+export function confirmOnce(
+    stage: StagedAction,
+    token: string,
+    now: number,
+): { outcome: ConfirmOutcome; stage: StagedAction } {
+    if (token !== stage.token) {
+        return { outcome: 'token-mismatch', stage };
+    }
+    const status = stageStatus(stage, now);
+    if (status === 'confirmed') {
+        return { outcome: 'already-confirmed', stage };
+    }
+    if (status === 'declined') {
+        return { outcome: 'declined', stage };
+    }
+    if (status === 'expired') {
+        return { outcome: 'expired', stage };
+    }
+    return {
+        outcome: 'execute',
+        stage: { ...stage, state: 'confirmed', resolved_at: iso(now) },
+    };
+}
+
+/** Decline a stage. Idempotent for the same reason `confirmOnce` is. */
+export function declineStage(
+    stage: StagedAction,
+    token: string,
+    now: number,
+): { declined: boolean; stage: StagedAction } {
+    if (token !== stage.token || stageStatus(stage, now) !== 'pending') {
+        return { declined: false, stage };
+    }
+    return { declined: true, stage: { ...stage, state: 'declined', resolved_at: iso(now) } };
+}
+
+/**
+ * What a non-interactive context does with a stage.
+ *
+ * Both fallbacks REFUSE — `decision_engine`'s `stop` and `warn` differ in how
+ * loudly they surface, never in whether the gated thing proceeds, and a staged
+ * irreversible action is the last place to invent an auto-approve. Naming the
+ * `warn` case explicitly is the point: a reader looking for the permissive
+ * branch finds it absent on purpose.
+ */
+export function nonInteractiveDecision(fallback: NonInteractiveFallback): {
+    execute: false;
+    surface: 'halt' | 'warn';
+} {
+    return { execute: false, surface: fallback === 'warn' ? 'warn' : 'halt' };
+}
+
+/**
+ * The confirmation surface, in the numbered-options shape
+ * `src/rules/user-interaction.md` requires. Returned as lines rather than
+ * written, so the same text serves a hook halt, a CLI pane, and a chat reply.
+ *
+ * `confirmWith` / `declineWith` are the caller's channel and are NOT defaulted
+ * to a command name. Which channel confirms a staged action is precisely what
+ * blocker `confirmation-degraded-host-semantics` has not decided — a
+ * `pre_tool_use` reply on three hosts, prose on the other five — and printing
+ * an invocation that does not exist yet would put a false instruction into a
+ * shipped surface. Until a binding caller supplies one, the surface names the
+ * token and says plainly that no channel is wired.
+ */
+export function confirmationSurface(
+    stage: StagedAction,
+    channel?: { confirmWith?: string; declineWith?: string },
+): string[] {
+    const confirm = channel?.confirmWith;
+    const decline = channel?.declineWith;
+    return [
+        `Confirmation required: ${stage.action}`,
+        `Object: ${stage.object}`,
+        `Staged by: ${stage.source} · token ${stage.token} · expires ${stage.expires_at}`,
+        confirm === undefined
+            ? `1) Confirm — quote token ${stage.token} back to the caller that staged it.`
+            : `1) Confirm — ${confirm}`,
+        decline === undefined
+            ? '2) Decline — say so; the stage is resolved without firing.'
+            : `2) Decline — ${decline}`,
+        '3) Do nothing — the stage expires and the action never fires.',
+        'Pending stages: `agent-config gates --pending`.',
+    ];
+}