@event4u/agent-config 9.34.0 → 9.36.0

package/dist/agent-src/skills/testing-anti-patterns/SKILL.md

@@ -163,6 +163,27 @@ expect([403, 404]).toContain((await api.get(`/users/${otherTenantUser.id}`)).sta
 
 Deriving from seeded data is necessary but **not sufficient** — a test that only reads back the exact fields it seeded is still overfit (a mutation in the code survives it). A real test also exercises boundary (empty / null / max / Unicode), error (missing / invalid), and, on security-sensitive paths, an abuse case (IDOR, injection string, XSS payload). Coverage of *cases*, not just lines.
 
+**The adversarial variant, and it is the one that looks safest.** A *negative* test — the abuse case just named — fails the same way, but nothing about it reads as weak: it names an attack, it asserts a refusal, it goes green. It passes because **something other than the control under test** produced that refusal. Two shapes, both from one real review:
+
+- **The hostile value sits only in the argument.** A guard rejecting a path-traversing `token` was pinned by planting a fixture whose own `token` field held the *legitimate* value while `'../outside'` was passed as the argument. Downstream, an ordinary token comparison mismatched and returned exactly the expected refusal — delete the guard and the test still passes. The hostile value belongs in the **field under test**, not only in the call.
+- **The assertion cannot fail.** The same test asserted the planted file still existed after a rejected claim. The two directories were siblings, so both `../x.json` joins resolved to one path and the rename could never have moved it — a green no implementation could turn red.
+
+Gate:
+
+```
+BEFORE trusting a negative test:
+  Delete or invert the control it claims to pin. Does it FAIL?
+  RESTORE THE CONTROL IMMEDIATELY — before any other edit, before any commit.
+    The mutation is a probe, never a change. A deleted guard left deleted is
+    a shipped vulnerability produced by a test-quality check.
+  IF it still passes: it is pinning something else. Name what, then fix the test.
+  IF an assertion cannot fail for ANY implementation: delete THE ASSERTION —
+    it is decoration. Only after proving vacuity, and never to turn a red test
+    green — that is Anti-Pattern 7 below.
+```
+
+No mutation-testing rig required: comment the control out, run that one spec, put it back. A negative test nobody has ever watched fail is a claim, not evidence.
+
 ### Anti-Pattern 7 — Gaming the green (test-integrity)
 
 Symptom: a test fails, and the "fix" edits the *test* instead of the code — `.skip` / `it.skip` / `xfail` / `@Disabled` on the failing case, deleting the failing assertion, loosening `toBe(x)` to `toBeTruthy()`, or rewriting the `expected` value to whatever the (possibly buggy) code now emits. The suite goes green while the behavior stays broken — the worst outcome, because green now *hides* the bug. This is the automation-bias trap: under pressure to finish, the agent optimizes the signal (green) instead of the target (correct behavior).
@@ -211,6 +232,7 @@ This is the test-surface instance of the `autonomous-execution` N=3 / allowlist-
 - Do NOT mark a story complete until at least one test was watched failing first.
 - Do NOT hardcode an expected value the code will emit, or pin a regex to an incidental fixed date/id — derive from inputs and seeded data, and vary the input across cases.
 - Do NOT skip / `xfail` / delete a failing test, or rewrite its `expected` to the code's current output, to get a green run — fix the code, or state a real spec change in the diff.
+- Do NOT trust a negative test you have never watched fail — delete the control it pins, confirm the test goes red, restore the control immediately.
 
 ## Auto-trigger keywords
 
@@ -225,6 +247,9 @@ This is the test-surface instance of the `autonomous-execution` N=3 / allowlist-
 - gaming the green
 - skip failing test
 - test integrity
+- negative test
+- vacuous assertion
+- abuse-case test
 
 ## Provenance
 

package/dist/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/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.34.0"
+agent_config_version: "9.36.0"
 
 # --- Project identity ---
 project:

package/dist/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/dist/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/dist/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/dist/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`.',
+    ];
+}