@event4u/agent-config 9.31.0 → 9.32.0

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

@@ -7,7 +7,9 @@
  * part of the contract).
  *
  * The step never calls an LLM. It inspects `state.ticket` (which carries
- * `input.data` after the CLI projection) and routes on shape:
+ * `input.data` after the CLI projection), shape-checks the optional
+ * `dod[]` slot (the executable definition-of-done —
+ * `src/scripts/schemas/dod.schema.json`), and routes on shape:
  *
  * - **Ticket envelope** (`id`, `title`, `acceptance_criteria`) — the
  *   R1 path. Validates the minimum viable shape and either returns
@@ -84,6 +86,15 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
             'user answers one clarifying question; the agent ' +
             're-runs `refine-prompt` against the refreshed prompt',
     },
+    {
+        code: 'malformed_dod',
+        trigger:
+            '`dod` key present but not a list, or an entry missing a ' +
+            'non-empty `id` / `check` string',
+        resolution:
+            'fix the `dod[]` entries against `src/scripts/schemas/dod.schema.json`, ' +
+            'or drop the key — the slot is optional',
+    },
     {
         code: 'prompt_ui_intent',
         trigger:
@@ -99,6 +110,27 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
 /** Route on envelope shape: ticket path or prompt path. */
 export function run(state: DeliveryState): StepResult {
     const data = state.ticket || {};
+
+    // The `dod[]` slot is shape-checked on BOTH paths before either routes, so
+    // a malformed definition-of-done cannot reach the self-fix loop that
+    // reports it. Absent key → no check, no behaviour change.
+    const dod_issues = diagnose_dod(data);
+    if (dod_issues.length > 0) {
+        const dod_ticket_id = _pyTruthy(data.id) ? _pyStr(data.id) : '(no id)';
+        return new StepResult({
+            outcome: Outcome.BLOCKED,
+            questions: [
+                `> Ticket ${dod_ticket_id} — the \`dod[]\` slot is malformed: ` + dod_issues.join('; ') + '.',
+                '> Every entry needs a non-empty `id` and a non-empty `check` ' +
+                    '(the command that proves it) — prose there cannot be run.',
+                '> 1. Fix the `dod[]` entries and re-invoke',
+                '> 2. Drop the `dod` key — the slot is optional',
+                '> 3. Abort',
+            ],
+            message: `Ticket ${dod_ticket_id} has a malformed dod[] slot: ` + dod_issues.join('; '),
+        });
+    }
+
     if (_is_prompt_envelope(data)) {
         return _run_prompt(state, data);
     }
@@ -117,6 +149,53 @@ export function run(state: DeliveryState): StepResult {
     });
 }
 
+/**
+ * Report what is wrong with an envelope's `dod[]` slot; `[]` when it is fine.
+ *
+ * Exported so the shape is testable on its own and so a caller can ask the
+ * question without triggering a halt. An absent key is valid — the slot is
+ * optional and omitting it means the author never declared a machine-checkable
+ * done-condition, which is different from declaring an empty one.
+ *
+ * `check` is required to be non-empty for the reason the schema states: the
+ * dispatcher spawns no subprocesses, so `check` is handed to an agent to run,
+ * and an agent cannot run a sentence.
+ */
+export function diagnose_dod(data: Record<string, Any>): string[] {
+    if (!_isPlainObject(data) || !('dod' in data)) {
+        return [];
+    }
+    const dod = data.dod;
+    if (!Array.isArray(dod)) {
+        return [`\`dod\` must be a list, got ${_pyTypeName(dod)}`];
+    }
+    const issues: string[] = [];
+    const seen = new Set<string>();
+    dod.forEach((entry, idx) => {
+        const position = idx + 1;
+        if (!_isPlainObject(entry)) {
+            issues.push(`entry ${position} must be an object, got ${_pyTypeName(entry)}`);
+            return;
+        }
+        const id = entry.id;
+        if (typeof id !== 'string' || !id.trim()) {
+            issues.push(`entry ${position} has no \`id\``);
+        } else if (seen.has(id)) {
+            issues.push(`entry ${position} repeats id \`${id}\``);
+        } else {
+            seen.add(id);
+        }
+        const check = entry.check;
+        if (typeof check !== 'string' || !check.trim()) {
+            issues.push(`entry ${position} has no \`check\` command`);
+        }
+        if ('proven' in entry && typeof entry.proven !== 'boolean') {
+            issues.push(`entry ${position} has a non-boolean \`proven\``);
+        }
+    });
+    return issues;
+}
+
 /**
  * True when `state.ticket` carries a prompt envelope.
  *
@@ -442,6 +521,32 @@ function _pyTruthy(value: unknown): boolean {
     return true;
 }
 
+/** Python `type(x).__name__` for the value kinds the dod diagnose path sees. */
+function _pyTypeName(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'NoneType';
+    }
+    if (typeof value === 'boolean') {
+        return 'bool';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'int' : 'float';
+    }
+    if (typeof value === 'string') {
+        return 'str';
+    }
+    if (Array.isArray(value)) {
+        return 'list';
+    }
+    if (value instanceof Set) {
+        return 'set';
+    }
+    if (value instanceof Map || _isPlainObject(value)) {
+        return 'dict';
+    }
+    return typeof value;
+}
+
 /** True for a dict-like value (mirrors Python `isinstance(x, dict)`). */
 function _isPlainObject(value: unknown): value is Record<string, unknown> {
     return (

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

@@ -17,10 +17,12 @@
  * - Must be a dict.
  * - Must carry a `verdict` key — one of `success`, `failed`,
  *   or `mixed` (targeted vs full-suite split). Anything else blocks.
- * - `failed` or `mixed` verdicts halt with the verdict as part of
- *   the surfaced message so the user decides whether to continue or
- *   stop. This follows the `verify-before-complete` rule: a bad test
- *   outcome must never be silently skipped.
+ * - `failed` or `mixed` verdicts enter the bounded self-fix loop
+ *   (`./_self_fix.ts`): the first attempts are delegated by directive, and an
+ *   exhausted or non-progressing loop exits `PARTIAL` with the verdict still
+ *   on the surface so the user decides whether to continue or stop. This
+ *   follows the `verify-before-complete` rule: a bad test outcome must never
+ *   be silently skipped, and the loop cannot report one as success.
  * - Optional keys (`targeted`, `full`, `duration_ms`,
  *   `followups`) feed the delivery report.
  */
@@ -28,6 +30,7 @@
 import type { DeliveryState} from '../../delivery_state.js';
 import { type Any, Outcome, StepResult, agent_directive } from '../../delivery_state.js';
 import { resolve_policy } from '../../persona_policy.js';
+import { decide, partial_exit, record_attempt, retry_halt, unmet_dod, verdict_signature } from './_self_fix.js';
 
 const _ALLOWED_VERDICTS = ['success', 'failed', 'mixed'] as const;
 
@@ -53,7 +56,18 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
     {
         code: 'bad_test_verdict',
         trigger: '`state.tests[\'verdict\']` is `failed` or `mixed`',
-        resolution: 'fix failures and re-run, or abort',
+        resolution:
+            'bounded self-fix loop: agent directive `fix-failing-checks` ' +
+            'while attempts remain and the verdict signature keeps changing',
+    },
+    {
+        code: 'self_fix_exhausted',
+        trigger:
+            'the self-fix budget for `test` is spent, or two consecutive ' +
+            'attempts produced an identical verdict signature',
+        resolution:
+            'PARTIAL honest exit — the red verdict stays on the surface, ' +
+            'the user decides whether to take over, override, or abort',
     },
 ];
 
@@ -156,18 +170,39 @@ function _blocked_on_shape(state: DeliveryState, issues: string[]): StepResult {
     });
 }
 
+/**
+ * Route a red test verdict through the bounded self-fix loop.
+ *
+ * Before this loop existed the function below returned a directive-free
+ * BLOCKED — a user question block — so every red cost a user round-trip even
+ * when the failure was one the agent could fix unaided. Now the first attempts
+ * are delegated and only an exhausted or non-progressing loop reaches the
+ * user, as a PARTIAL that still carries the red verdict.
+ */
 function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult {
     const ticketId = _ticketId(state);
-    return new StepResult({
-        outcome: Outcome.BLOCKED,
-        questions: [
-            `> Ticket ${ticketId} — tests reported \`${String(verdict)}\`. ` +
-                'Verification cannot proceed on a non-success verdict.',
-            '> 1. Fix the failing tests and re-run `run-tests`',
-            '> 2. Continue anyway — override (NOT recommended)',
-            '> 3. Abort',
-        ],
-        message: `Ticket ${ticketId} test verdict was \`${String(verdict)}\`, not success.`,
+    const signature = verdict_signature('test', state.tests);
+    const decision = decide(state, 'test', signature);
+
+    if (decision.kind === 'retry') {
+        record_attempt(state, 'test', signature);
+        return retry_halt({
+            lane: 'test',
+            ticket_id: ticketId,
+            verdict,
+            decision,
+            fix_hint: 'read the failing assertions, fix the cause, re-run the same filter.',
+            rerun_directive: 'run-tests',
+        });
+    }
+
+    return partial_exit({
+        lane: 'test',
+        ticket_id: ticketId,
+        verdict,
+        decision,
+        unmet: unmet_dod(state),
+        rerun_directive: 'run-tests',
     });
 }
 

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

@@ -18,9 +18,12 @@
  *   `partial`. Matches the `Outcome` vocabulary used everywhere
  *   else in the flow.
  * - A `success` verdict advances the flow to `report`.
- * - A `blocked` or `partial` verdict halts with numbered options
- *   so the user decides whether to address the findings, override
- *   (rarely appropriate), or abort.
+ * - A `blocked` or `partial` verdict enters the bounded self-fix loop
+ *   (`./_self_fix.ts`): while attempts remain and the verdict signature
+ *   keeps changing, the fix is delegated by directive. An exhausted or
+ *   non-progressing loop exits `PARTIAL` with numbered options so the user
+ *   decides whether to take over, override (rarely appropriate), or abort.
+ *   The loop never turns a non-success verdict into `SUCCESS`.
  * - Optional keys (`confidence`, `findings`, `followups`) feed
  *   the delivery report.
  */
@@ -28,6 +31,7 @@
 import type { DeliveryState} from '../../delivery_state.js';
 import { type Any, Outcome, StepResult, agent_directive } from '../../delivery_state.js';
 import { resolve_policy } from '../../persona_policy.js';
+import { decide, partial_exit, record_attempt, retry_halt, unmet_dod, verdict_signature } from './_self_fix.js';
 
 const _ALLOWED_VERDICTS = ['success', 'blocked', 'partial'] as const;
 
@@ -52,7 +56,17 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
         code: 'bad_verify_verdict',
         trigger: '`state.verify[\'verdict\']` is `blocked` or `partial`',
         resolution:
-            'address findings and re-run `/review-changes` — never bypass ' + '(see `verify-before-complete`)',
+            'bounded self-fix loop: agent directive `fix-failing-checks` ' +
+            'while attempts remain — never bypass ' + '(see `verify-before-complete`)',
+    },
+    {
+        code: 'self_fix_exhausted',
+        trigger:
+            'the self-fix budget for `verify` is spent, or two consecutive ' +
+            'attempts produced an identical verdict signature',
+        resolution:
+            'PARTIAL honest exit — the non-success verdict stays on the ' +
+            'surface; the user takes over, overrides, or aborts',
     },
 ];
 
@@ -145,19 +159,39 @@ function _blocked_on_shape(state: DeliveryState, issues: string[]): StepResult {
     });
 }
 
+/**
+ * Route a red review verdict through the bounded self-fix loop.
+ *
+ * Same shape as the `test` lane, separate counter: `autonomous-execution`
+ * resets its N=3 budget on a different validation target, and a review finding
+ * is not a failing test. `verify-before-complete` is unaffected — the loop
+ * cannot report completion, and its exhausted exit is PARTIAL with the
+ * non-success verdict still on the surface.
+ */
 function _blocked_on_bad_verdict(state: DeliveryState, verdict: Any): StepResult {
     const ticketId = _ticketId(state);
-    return new StepResult({
-        outcome: Outcome.BLOCKED,
-        questions: [
-            `> Ticket ${ticketId} — \`review-changes\` reported ` +
-                `\`${String(verdict)}\`. The delivery report cannot claim completion on a ` +
-                'non-success verdict (see `verify-before-complete`).',
-            '> 1. Address the findings and re-run `review-changes`',
-            '> 2. Continue anyway — override (NOT recommended)',
-            '> 3. Abort',
-        ],
-        message: `Ticket ${ticketId} verify verdict was \`${String(verdict)}\`, not success.`,
+    const signature = verdict_signature('verify', state.verify);
+    const decision = decide(state, 'verify', signature);
+
+    if (decision.kind === 'retry') {
+        record_attempt(state, 'verify', signature);
+        return retry_halt({
+            lane: 'verify',
+            ticket_id: ticketId,
+            verdict,
+            decision,
+            fix_hint: 'address the recorded findings, then re-run the four-judge review.',
+            rerun_directive: 'review-changes',
+        });
+    }
+
+    return partial_exit({
+        lane: 'verify',
+        ticket_id: ticketId,
+        verdict,
+        decision,
+        unmet: unmet_dod(state),
+        rerun_directive: 'review-changes',
     });
 }
 

package/src/agent-src/templates/scripts/work_engine/state.ts

@@ -220,6 +220,7 @@ export class WorkState {
     ui_polish: Dict | null;
     contract: Dict | null;
     stitch: Dict | null;
+    self_fix: Dict | null;
     halts: Dict[];
     version: number;
     persona: string;
@@ -245,6 +246,7 @@ export class WorkState {
         ui_polish?: Dict | null;
         contract?: Dict | null;
         stitch?: Dict | null;
+        self_fix?: Dict | null;
         halts?: Dict[];
         version?: number;
         persona?: string;
@@ -269,6 +271,7 @@ export class WorkState {
         this.ui_polish = opts.ui_polish ?? null;
         this.contract = opts.contract ?? null;
         this.stitch = opts.stitch ?? null;
+        this.self_fix = opts.self_fix ?? null;
         this.halts = opts.halts ?? [];
         this.version = opts.version ?? SCHEMA_VERSION;
         this.persona = opts.persona ?? 'senior-engineer';
@@ -309,6 +312,7 @@ export function to_dict(state: WorkState): Dict {
     _validate_ui_polish(state.ui_polish);
     _validate_contract(state.contract);
     _validate_stitch(state.stitch);
+    _validate_self_fix(state.self_fix);
     _validate_halts(state.halts);
     return {
         version: state.version,
@@ -324,6 +328,7 @@ export function to_dict(state: WorkState): Dict {
         ui_polish: state.ui_polish,
         contract: state.contract,
         stitch: state.stitch,
+        self_fix: state.self_fix,
         halts: [...state.halts],
         persona: state.persona,
         memory: state.memory,
@@ -406,6 +411,9 @@ export function from_dict(payload: JsonValue): WorkState {
     const stitch = payload['stitch'] ?? null;
     _validate_stitch(stitch);
 
+    const self_fix = payload['self_fix'] ?? null;
+    _validate_self_fix(self_fix);
+
     const halts = 'halts' in payload ? payload['halts'] : [];
     _validate_halts(halts);
 
@@ -422,6 +430,7 @@ export function from_dict(payload: JsonValue): WorkState {
         ui_polish: _isDict(ui_polish) ? { ...ui_polish } : null,
         contract: _isDict(contract) ? { ...contract } : null,
         stitch: _isDict(stitch) ? { ...stitch } : null,
+        self_fix: _isDict(self_fix) ? { ...self_fix } : null,
         halts: Array.isArray(halts) ? ([...halts] as Dict[]) : [],
         version: version as number,
         persona: _get(payload, 'persona', 'senior-engineer') as string,
@@ -866,6 +875,71 @@ function _validate_ui_review(ui_review: JsonValue): void {
     }
 }
 
+/**
+ * Reject malformed `self_fix` envelopes; tolerate `null` and `{}`.
+ *
+ * `null` means no red check has been seen. Once populated, each key is a lane
+ * name (`test`, `verify`) whose record may carry `attempts` (a non-negative
+ * int) and `signatures` (a list of strings). As with `ui_polish`, the schema
+ * enforces only shape: the ceiling and the no-progress floor are the handler's
+ * business (`directives/backend/_self_fix.ts`), so a state file cannot decide
+ * how many attempts are allowed.
+ *
+ * `attempts` is validated but NOT bounded here on purpose. A file carrying
+ * `attempts: 99` is well-formed and simply exhausted — rejecting it would turn
+ * a spent budget into a crash, and the loop's whole point is a clean exit.
+ */
+function _validate_self_fix(self_fix: JsonValue): void {
+    if (self_fix === null) {
+        return;
+    }
+    if (!_isDict(self_fix)) {
+        throw new SchemaError(
+            `state.self_fix must be a JSON object or null; ` +
+                `got ${pyTypeName(self_fix)}`,
+        );
+    }
+    for (const [lane, record] of Object.entries(self_fix)) {
+        if (!_isDict(record)) {
+            throw new SchemaError(
+                `state.self_fix.${lane} must be a JSON object; ` +
+                    `got ${pyTypeName(record)}`,
+            );
+        }
+        if ('attempts' in record) {
+            const attempts = record['attempts'];
+            if (
+                typeof attempts !== 'number' ||
+                typeof attempts === 'boolean' ||
+                !Number.isInteger(attempts) ||
+                attempts < 0
+            ) {
+                throw new SchemaError(
+                    `state.self_fix.${lane}.attempts must be a non-negative ` +
+                        `integer when present; got ${pyRepr(attempts)}`,
+                );
+            }
+        }
+        if ('signatures' in record) {
+            const signatures = record['signatures'];
+            if (!Array.isArray(signatures)) {
+                throw new SchemaError(
+                    `state.self_fix.${lane}.signatures must be a list when ` +
+                        `present; got ${pyTypeName(signatures)}`,
+                );
+            }
+            for (const entry of signatures) {
+                if (typeof entry !== 'string') {
+                    throw new SchemaError(
+                        `state.self_fix.${lane}.signatures entries must be ` +
+                            `strings; got ${pyTypeName(entry)}`,
+                    );
+                }
+            }
+        }
+    }
+}
+
 /**
  * Reject malformed `ui_polish` envelopes; tolerate `null` and `{}`.
  *

package/src/agent-src/templates/scripts/work_engine/state_io.ts

@@ -150,6 +150,7 @@ export function _to_delivery(work: WorkState): DeliveryState {
         contract: work.contract as Record<string, DeliveryAny> | null,
         stitch: work.stitch as Record<string, DeliveryAny> | null,
         stack: work.stack as Record<string, DeliveryAny> | null,
+        self_fix: work.self_fix as Record<string, DeliveryAny> | null,
     });
 }
 
@@ -182,6 +183,11 @@ export function _sync_back(work: WorkState, delivery: DeliveryState): void {
     work.contract = delivery.contract as Dict | null;
     work.stitch = delivery.stitch as Dict | null;
     work.stack = delivery.stack as Dict | null;
+    // Reassigned (not mutated) by `record_attempt`, so the defensive mirror
+    // above is load-bearing here rather than a no-op: without this line the
+    // attempt counter would reset on every dispatch and the loop would never
+    // reach either floor.
+    work.self_fix = delivery.self_fix as Dict | null;
 }
 
 /**

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -38,6 +38,7 @@ import {
     CAPSULE_SCHEMA_VERSION,
     validateRecycleEnvelope,
 } from '../_lib/subagent_capsule.js';
+import { collectGrounding } from '../_lib/envelope_grounding.js';
 import { atomic_write_json } from '../hooks/state_io.js';
 
 export interface RecycleResult {
@@ -61,6 +62,9 @@ export function templateEnvelope(): Record<string, unknown> {
         open_worker_envelopes: [],
         artifact_paths: ['<path to a deliverable / note / evidence file>'],
         assumptions: [],
+        next_task: '<the ONE task this envelope is written for — select content for it>',
+        suggested_skills: ['<skill the successor should invoke>'],
+        failed_approaches: ['<tried X, failed because Y — or the single entry "none">'],
     };
 }
 
@@ -123,6 +127,27 @@ export function runSessionRecycle(
     }
     if (envelope['workspace'] === undefined) envelope['workspace'] = projectRoot;
 
+    // Scripted grounding (Phase 3.3): the factual fields are READ, never
+    // composed. A model-written branch is a claim; this is a reading. The
+    // composer cannot override them — a "next_task" it got wrong is a
+    // proposal, a "head" it got wrong is a silent stale resume.
+    const grounding = collectGrounding(projectRoot);
+    // Drop the composer's factual keys UNCONDITIONALLY first. Guarding each
+    // assignment on `!== null` would leave a model-composed branch or head
+    // standing whenever the git read fails — the consumer would then compare
+    // a fabricated anchor against the real tree and produce either false
+    // drift or, worse, false silence. An unreadable fact is absent, never
+    // inherited from the composer.
+    for (const key of ['repo_identity', 'branch', 'head', 'status_summary', 'last_verify', 'uncommitted_paths']) {
+        delete envelope[key];
+    }
+    if (grounding.repo_identity !== null) envelope['repo_identity'] = grounding.repo_identity;
+    if (grounding.branch !== null) envelope['branch'] = grounding.branch;
+    if (grounding.head !== null) envelope['head'] = grounding.head;
+    if (grounding.status_summary !== null) envelope['status_summary'] = grounding.status_summary;
+    if (grounding.last_verify !== null) envelope['last_verify'] = grounding.last_verify;
+    envelope['uncommitted_paths'] = grounding.uncommitted_paths;
+
     const violations = validateRecycleEnvelope(envelope);
     if (violations.length > 0) {
         return {

package/src/scripts/_cli/handoff_generate.ts

@@ -35,6 +35,19 @@ export const WORD_CAP = 1200;
 const SNIPPET_CHARS = 200;
 const DONE_SNIPPET_CHARS = 400;
 const MAX_ERRORS = 5;
+/**
+ * Per-error cap. Above `SNIPPET_CHARS` because an error string is kept
+ * verbatim so it stays greppable — but deliberately not far above.
+ *
+ * The section competes for a fixed word cap whose trim pops the NEWEST entry
+ * first, and the newest failure is the one a successor needs. Enlarging each
+ * entry therefore makes that pre-existing trim order bite more often. 400 is
+ * twice the old truncation — enough to carry a real error line whole — while
+ * keeping the five-entry section within roughly a sixth of the cap. The
+ * pop()-newest ordering is pre-existing and is not this change's to alter;
+ * this bound is what keeps the change from amplifying it.
+ */
+const MAX_ERROR_CHARS = 400;
 const MAX_DECISIONS = 5;
 const MAX_FILES = 15;
 
@@ -325,11 +338,23 @@ export function build_handoff(
     );
 
     // Errors + fixes — failure-pattern turns, oldest→newest, last 5.
+    //
+    // Precision rule (Phase 3.1): the error string is carried VERBATIM. It
+    // used to be `_snippet`-ed like every other section, which truncates
+    // mid-string — and a truncated error cannot be grepped, matched against a
+    // tracker, or recognised when it recurs, which is the only reason to
+    // carry it at all. So the FAILURE-matching line is taken whole (capped
+    // only against an absurd single line) instead of the turn being cut at an
+    // arbitrary offset.
     const errors = _redact_items(
         toolish
             .filter((t) => FAILURE_RE.test(t.text))
             .slice(-MAX_ERRORS)
-            .map((t) => _snippet(`${t.tool ? `${t.tool}: ` : ''}${t.text}`, SNIPPET_CHARS)),
+            .map((t) => {
+                const line = t.text.split('\n').find((l) => FAILURE_RE.test(l))?.trim() ?? t.text.trim();
+                const prefix = t.tool ? `${t.tool}: ` : '';
+                return `${prefix}${line}`.slice(0, MAX_ERROR_CHARS);
+            }),
     );
 
     // Key decisions — decision-pattern assistant turns, last 5.
@@ -396,6 +421,16 @@ export function build_handoff(
         }
         for (const s of sections) {
             lines.push('', `## ${s.title}`, '');
+            if (s.title === 'Resume pointer') {
+                // Precision rules (Phase 3.1), rendered where the successor
+                // reads them rather than filed in a doc nobody opens.
+                lines.push(
+                    '> Precision contract: identify code by signature or `path:line`, never by',
+                    '> description; quote error strings verbatim; give every resume step its',
+                    '> expected outcome, so "done" is checkable rather than felt.',
+                    '',
+                );
+            }
             if (s.items.length === 0) {
                 if (s.verbatim && verbatim.withheldLines > 0) {
                     lines.push(`- [${verbatim.withheldLines} line(s) withheld by privacy floor]`);