@event4u/agent-config 14.12.0 → 14.14.0

package/dist/agent-src/templates/scripts/check_memory_proposal.ts

@@ -217,6 +217,7 @@ interface ParsedArgs {
     intake_id: string | null;
     proposal: string | null;
     format: 'text' | 'json';
+    quiet: boolean;
 }
 
 function _argparse_error(message: string): never {
@@ -228,6 +229,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
     let intake_id: string | null = null;
     let proposal: string | null = null;
     let format: 'text' | 'json' = 'text';
+    let quiet = false;
     // argparse reports a mutually-exclusive conflict against the SECOND-seen
     // arg at the point it is parsed (order-sensitive), so check inline rather
     // than after the loop.
@@ -248,10 +250,12 @@ function parse_args(argv: readonly string[]): ParsedArgs {
             format = _checkFormat(v);
         } else if (arg.startsWith('--format=')) {
             format = _checkFormat(arg.slice('--format='.length));
+        } else if (arg === '--quiet') {
+            quiet = true;
         } else if (arg === '-h' || arg === '--help') {
             process.stdout.write(
                 'usage: check_memory_proposal [-h] (--intake-id INTAKE_ID | --proposal PROPOSAL)\n' +
-                    '                             [--format {text,json}]\n',
+                    '                             [--format {text,json}] [--quiet]\n',
             );
             process.exit(0);
         } else {
@@ -261,7 +265,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
     if (intake_id === null && proposal === null) {
         _argparse_error('one of the arguments --intake-id --proposal is required');
     }
-    return { intake_id, proposal, format };
+    return { intake_id, proposal, format, quiet };
 }
 
 function _need(argv: readonly string[], i: number, flag: string): string {
@@ -322,7 +326,9 @@ function main(argv?: readonly string[]): number {
                 process.stdout.write(`  🔴 ${f}\n`);
             }
         } else {
-            process.stdout.write(`✅  ${source} — gate passed\n`);
+            if (!args.quiet) {
+                process.stdout.write(`✅  ${source} — gate passed\n`);
+            }
         }
     }
     return failures.length > 0 ? 1 : 0;

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

@@ -246,6 +246,74 @@ function _pad2(v: string): string {
  * (`agents/memory/<type>.yml` or `<type>/entries.yml` with an `entries:`
  * list), so consumers can adopt either.
  */
+const _CURATED_STATUS_EXCLUDE: ReadonlySet<string> = new Set(['deprecated', 'archived', 'superseded']);
+
+/** Mirror Python `entry.get("status") in _CURATED_STATUS_EXCLUDE`. */
+function _statusExcluded(entry: Record<string, unknown>): boolean {
+    const status = entry['status'];
+    return typeof status === 'string' && _CURATED_STATUS_EXCLUDE.has(status);
+}
+
+
+/*
+ * Staleness, ported from `src/scripts/memory_lookup.ts` on 2026-08-26
+ * (`road-to-memory-twin-reconciliation` 2.2, verdict `dev-side-correct`).
+ *
+ * The template previously had NO staleness handling at all — `grep -c stale`
+ * returned 0 — so a consumer retrieved curated entries whose own
+ * `review_after_days` window had expired, with nothing saying so. `check_memory`
+ * required both fields on every entry the whole time; only retrieval ignored
+ * them.
+ *
+ * Portable by construction: Date math and a regex, no `_lib` import.
+ */
+function _today(): Date {
+    const now = new Date();
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+
+function _parseIsoDate(s: string): Date | null {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+    if (!m) {
+        return null;
+    }
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const d = Number(m[3]);
+    if (mo < 1 || mo > 12 || d < 1 || d > 31) {
+        return null;
+    }
+    const date = new Date(Date.UTC(y, mo - 1, d));
+    // Reject overflow (e.g. 2026-02-31 → March), matching fromisoformat's strictness.
+    if (date.getUTCFullYear() !== y || date.getUTCMonth() !== mo - 1 || date.getUTCDate() !== d) {
+        return null;
+    }
+    return date;
+}
+
+function _pyStrDateLike(lv: unknown): string {
+    if (lv instanceof PyTimestamp) {
+        return lv.pyStr;
+    }
+    return _pyStr(lv);
+}
+
+function _isStale(entry: Record<string, unknown>, today: Date): boolean {
+    const lv = entry['last_validated'];
+    const rad = entry['review_after_days'];
+    // Python: `not lv or not isinstance(rad, int)`. PyYAML ints land as JS
+    // numbers; booleans are int in Python but excluded here as the common path.
+    if (!lv || typeof rad !== 'number' || !Number.isInteger(rad)) {
+        return false;
+    }
+    const validated = _parseIsoDate(_pyStrDateLike(lv));
+    if (validated === null) {
+        return false;
+    }
+    const days = Math.round((today.getTime() - validated.getTime()) / 86_400_000);
+    return days > rad;
+}
+
 function* _iter_curated_entries(mtype: string): Generator<[string, Record<string, unknown>]> {
     const type_dir = path.join(MEMORY_ROOT, mtype);
     const single_file = path.join(MEMORY_ROOT, `${mtype}.yml`);
@@ -254,6 +322,9 @@ function* _iter_curated_entries(mtype: string): Generator<[string, Record<string
         const entries = _isPlainObject(data) ? data['entries'] : null;
         for (const e of Array.isArray(entries) ? entries : []) {
             if (_isPlainObject(e)) {
+                if (_statusExcluded(e)) {
+                    continue;
+                }
                 yield [single_file, e];
             }
         }
@@ -266,11 +337,17 @@ function* _iter_curated_entries(mtype: string): Generator<[string, Record<string
             if (Array.isArray(entries)) {
                 for (const e of entries) {
                     if (_isPlainObject(e)) {
+                        if (_statusExcluded(e)) {
+                            continue;
+                        }
                         yield [yml, e];
                     }
                 }
             } else if (_isPlainObject(data) && data['id']) {
                 // Flat, one-entry-per-file layout (content-addressed).
+                if (_statusExcluded(data)) {
+                    continue;
+                }
                 yield [yml, data];
             }
         }
@@ -454,6 +531,7 @@ function _cross_repo_hits(keys: string[], limit: number): Hit[] {
  */
 export function retrieve(types: string[], keys: string[], limit = 5): Hit[] {
     const repo_hits: Hit[] = [];
+    const today = _today();
     for (const mtype of types) {
         if (mtype === KNOWLEDGE_TYPE) {
             for (const [p, entry] of _iter_knowledge_entries()) {
@@ -488,6 +566,14 @@ export function retrieve(types: string[], keys: string[], limit = 5): Hit[] {
             continue;
         }
         for (const [p, entry] of _iter_curated_entries(mtype)) {
+            // A curated entry past its own `review_after_days` window is not
+            // retrieved. The dev side additionally reports it under `skipped`;
+            // this copy has no `retrieve_with_meta`, so it filters silently —
+            // the exclusion is the behaviour that matters, the report is the
+            // richer surface.
+            if (_isStale(entry, today)) {
+                continue;
+            }
             repo_hits.push(new Hit(String(entry['id'] ?? ''), mtype, 'curated', String(p), _score(entry, keys), entry));
         }
         for (const [p, entry] of _iter_intake_entries(mtype)) {

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

@@ -29,6 +29,7 @@
 
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -217,6 +218,45 @@ export interface SignalRecord {
  * 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 class ProvenanceRefusedError extends Error {}
+
+// lint-store-boundary: ignore — the provenance gate must RECOGNISE the global root to refuse it
+const _GLOBAL_STORE_MARKER = `.event4u${path.sep}agent-config`;
+
+export function _origin_is_global(origin: string): boolean {
+    if (!origin.includes('/') && !origin.includes(path.sep) && !origin.startsWith('~')) {
+        return false; // symbolic origins ('agent', 'claude', 'cursor', …) are not paths
+    }
+    const expanded = origin.startsWith('~')
+        ? path.join(os.homedir(), origin.slice(1)) // lint-store-boundary: ignore — the gate itself must recognise the global root
+        : origin;
+    let resolved: string;
+    try {
+        resolved = path.resolve(expanded);
+    } catch {
+        return false;
+    }
+    return resolved.includes(_GLOBAL_STORE_MARKER) || /(^|[\\/])\.event4u([\\/]|$)/.test(origin);
+}
+
+export function _assert_project_writable(record: { origin: string; subject?: unknown }): void {
+    if (record.subject === 'user') {
+        throw new ProvenanceRefusedError(
+            'provenance gate: subject: user records live global-only and may ' +
+                'never be written into a tracked project artifact (ADR-130).',
+        );
+    }
+    if (_origin_is_global(record.origin)) {
+        throw new ProvenanceRefusedError(
+            `provenance gate: origin resolves into the user-global store ` +
+                `(${record.origin}) — refused entry into tracked project intake (ADR-130).`,
+        );
+    }
+}
+
+/**
+ * Append a signal entry. Returns the written record, or null when skipped.
+ */
 export function emit(
     entry_type: string,
     p: string,
@@ -255,6 +295,10 @@ export function emit(
             }
         }
     }
+    if (!('subject' in record)) {
+        record.subject = 'project'; // additive default (ADR-130)
+    }
+    _assert_project_writable(record as { origin: string; subject?: unknown });
     fs.mkdirSync(INTAKE_ROOT, { recursive: true });
     const target = _monthly_file();
     fs.appendFileSync(target, `${_jsonDumpsUnicode(record)}\n`, 'utf-8');

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

@@ -16,6 +16,9 @@
  * Flow:
  *
  * - `plan` outcome is not `success` → BLOCKED on precondition.
+ * - no RED evidence on `state.tests` → BLOCKED with
+ *   `@agent-directive: observe-red` so the agent writes and observes the
+ *   failing test for the next single behaviour BEFORE any production edit.
  * - `state.changes` empty → BLOCKED with `@agent-directive:
  *   apply-plan` so the agent applies the plan.
  * - `state.changes` populated but malformed (entries missing
@@ -26,6 +29,26 @@
  * `docs/contracts/implement-ticket-flow.md#deliverystate-the-only-shared-object`
  * — each entry is a dict with at least a `path`; optional
  * `lines` / `purpose` feed the delivery report.
+ *
+ * RED evidence lives at `state.tests.red` and is the engine-side carrier for
+ * the test-first default in `rules/think-before-action.md`. Two accepted
+ * shapes, and nothing else counts:
+ *
+ * - one observation, or a list of them, each a dict with a non-empty
+ *   `behaviour` and a `failure_class` from `_RED_FAILURE_CLASSES` — the three
+ *   valid RED classes the `test-driven-development` skill admits (a failing
+ *   assertion, a missing target, a contract failure). A broken fixture, a
+ *   syntax error in the test, a missing unrelated dependency and a runner
+ *   fault are NOT RED and are rejected by that same contract, not here.
+ * - `{exempt: "<reason>"}` — the recorded override for work the skill's
+ *   *Do NOT use when* list already excludes (scaffolding, generated files,
+ *   documentation). Recorded, never silent: an absent key is not an exemption.
+ *
+ * The gate is per behaviour, not per run: it names the behaviour it is waiting
+ * on and re-fires for the next one. It does NOT detect a batch — an agent that
+ * front-loads every test for the feature satisfies it, and the eval that fails
+ * a one-test-phase-then-one-code-phase plan is the control for that, not this
+ * step.
  */
 
 import type { DeliveryState} from '../../delivery_state.js';
@@ -39,6 +62,13 @@ export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
         trigger: '`plan` outcome is not `success`',
         resolution: 're-run `/implement-ticket` from the start',
     },
+    {
+        code: 'no_red_evidence',
+        trigger: '`state.tests.red` carries neither an observed failing test for a ' +
+            'behaviour nor a recorded exemption',
+        resolution: 'agent directive `observe-red` → write the failing test for the ' +
+            'next single behaviour, observe it fail, record it',
+    },
     {
         code: 'empty_changes_delegate',
         trigger: '`state.changes` empty — plan not applied yet',
@@ -68,6 +98,13 @@ export function run(state: DeliveryState): StepResult {
         return _blocked_on_precondition(state);
     }
 
+    // Test-first, enforced where the engine can see it: no production work is
+    // emitted for a behaviour whose failing test has not been observed.
+    const redIssue = _diagnose_red(state.tests);
+    if (redIssue !== null) {
+        return _blocked_on_missing_red(state, redIssue);
+    }
+
     if (!_pyTruthy(state.changes)) {
         return _delegate_to_apply_plan(state);
     }
@@ -98,6 +135,59 @@ function _diagnose_changes(changes: Any[]): string[] {
     return issues;
 }
 
+/** The three RED classes the `test-driven-development` mode contract admits. */
+const _RED_FAILURE_CLASSES = ['assertion', 'missing_target', 'contract'] as const;
+
+/**
+ * `null` when `state.tests` carries usable RED evidence, else the complaint.
+ *
+ * Absent is a complaint, not an exemption — the whole point of the gate.
+ */
+function _diagnose_red(tests: Any): string | null {
+    if (!_isPlainObject(tests)) {
+        return 'no `state.tests.red` recorded';
+    }
+    const red = (tests as Record<string, unknown>).red;
+    if (!_pyTruthy(red)) {
+        return 'no `state.tests.red` recorded';
+    }
+    if (_isPlainObject(red) && _pyTruthy((red as Record<string, unknown>).exempt)) {
+        return null;
+    }
+    const observations = Array.isArray(red) ? red : [red];
+    for (const obs of observations) {
+        if (!_isPlainObject(obs)) {
+            return 'a `red` observation is not a dict';
+        }
+        const o = obs as Record<string, unknown>;
+        if (typeof o.behaviour !== 'string' || _pyStrip(o.behaviour).length === 0) {
+            return 'a `red` observation names no `behaviour`';
+        }
+        if (!_RED_FAILURE_CLASSES.includes(o.failure_class as (typeof _RED_FAILURE_CLASSES)[number])) {
+            return (
+                `\`red\` observation for \`${_pyStrip(o.behaviour)}\` has ` +
+                `\`failure_class\` outside ${_RED_FAILURE_CLASSES.join(', ')}`
+            );
+        }
+    }
+    return null;
+}
+
+function _blocked_on_missing_red(state: DeliveryState, issue: string): StepResult {
+    const ticketId = _ticketId(state);
+    return new StepResult({
+        outcome: Outcome.BLOCKED,
+        questions: [
+            agent_directive('observe-red', { ticket: ticketId }),
+            `> Ticket ${ticketId} — implement gate refused: ${issue}. Write the ` +
+                'failing test for the next single behaviour and observe it fail first.',
+            '> 1. Continue — write and run that one failing test',
+            '> 2. Record an exemption — `state.tests.red = {exempt: "<reason>"}`',
+        ],
+        message: `Ticket ${ticketId} needs an observed failing test before production work: ${issue}.`,
+    });
+}
+
 function _delegate_to_apply_plan(state: DeliveryState): StepResult {
     const ticketId = _ticketId(state);
     return new StepResult({

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

@@ -45,6 +45,17 @@ export const SUPPORTED_KINDS: ReadonlyArray<string> = ['ticket', 'prompt'];
 // test, verify, report). The leaf name is the dispatcher slot key; in Python
 // it is derived via `step.__name__.rsplit(".", 1)[-1]` — hardcoded here since
 // the modules are imported statically.
+//
+// `implement` stays BEFORE `test`, deliberately, and the order is not the
+// test-after instruction it looks like. The tuple is linear and runs once per
+// flow, so moving `test` in front of `implement` would buy exactly one test
+// phase followed by one code phase — batch-TDD, which is the second
+// anti-pattern rather than a fix for the first. Test-first is enforced INSIDE
+// `implement` instead: `./implement.ts` refuses to emit production work for a
+// behaviour whose failing test has not been observed (`state.tests.red`), so
+// the discipline is per behaviour while the tuple stays per flow. The `test`
+// slot here is the whole-suite verdict that gates `verify`, never the first
+// time a test is written.
 const _STEPS: ReadonlyArray<[string, { run: Step; AMBIGUITIES: ReadonlyArray<Record<string, string>> }]> = [
     ['refine', refine],
     ['memory', memory],

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

@@ -25,6 +25,13 @@
  *   be silently skipped, and the loop cannot report one as success.
  * - Optional keys (`targeted`, `full`, `duration_ms`,
  *   `followups`) feed the delivery report.
+ * - `red` is NOT a verdict. It is the per-behaviour RED evidence
+ *   `./implement.ts` gates on, written before any production edit, and it
+ *   says nothing about the suite. A `state.tests` carrying `red` and no
+ *   `verdict` therefore means the runner has not been invoked for the suite
+ *   yet → delegate, exactly as an empty `state.tests` does. A `verdict` that
+ *   is present and unrecognised still blocks on shape; this is a
+ *   not-yet-run case, never a relaxed verdict check.
  */
 
 import type { DeliveryState} from '../../delivery_state.js';
@@ -86,7 +93,7 @@ export function run(state: DeliveryState): StepResult {
     }
 
     const tests = state.tests;
-    if (!_pyTruthy(tests)) {
+    if (!_pyTruthy(tests) || _isRedOnly(tests)) {
         return _delegate_to_run_tests(state, policy.widen_tests);
     }
 
@@ -104,6 +111,21 @@ export function run(state: DeliveryState): StepResult {
     return new StepResult({ outcome: Outcome.SUCCESS });
 }
 
+/**
+ * True when `state.tests` carries only the pre-implement RED record.
+ *
+ * `red` is written by the `implement` gate's `observe-red` directive; it is
+ * evidence about one behaviour's first failing run, not a suite verdict. Only
+ * a MISSING `verdict` routes here — a present-but-wrong one still blocks.
+ */
+function _isRedOnly(tests: Any): boolean {
+    if (!_isPlainObject(tests)) {
+        return false;
+    }
+    const d = tests as Record<string, unknown>;
+    return !('verdict' in d) && _pyTruthy(d.red);
+}
+
 function _diagnose_tests(tests: Any): string[] {
     if (!_isPlainObject(tests)) {
         return [`state.tests must be a dict, got ${_pyTypeName(tests)}`];

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

@@ -33,7 +33,16 @@ import { type Any, Outcome, StepResult, agent_directive } from '../../delivery_s
 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;
+/**
+ * DERIVED, never re-declared. `delivery_state.ts` is the step vocabulary's
+ * declaration for the template tree (templates are self-contained by contract
+ * and may not import from `src/scripts/`, so the registry mirrors it rather
+ * than the other way round). Spelling the three values again here made this the
+ * THIRD copy, and a third copy is how one vocabulary becomes two truths --
+ * which is the defect the outcome-vocabulary reconciliation was opened to fix.
+ * Found by the widened duplicate detector, 2026-08-30.
+ */
+const _ALLOWED_VERDICTS = Object.values(Outcome) as ReadonlyArray<Outcome>;
 
 /** Declared ambiguity surfaces. Advisory personas skip this step entirely. */
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [

package/dist/agent-src/templates/scripts/work_engine/directives/mixed/stitch.ts

@@ -20,7 +20,11 @@ import {
 /** Agent directive that drives end-to-end smoke scenarios. */
 export const INTEGRATION_TEST_DIRECTIVE = 'integration-test';
 
-const _ALLOWED_VERDICTS: ReadonlyArray<string> = ['success', 'blocked', 'partial'];
+/**
+ * DERIVED, never re-declared — see the note in `directives/backend/verify.ts`.
+ * This was the fourth copy of the step vocabulary.
+ */
+const _ALLOWED_VERDICTS: ReadonlyArray<string> = Object.values(Outcome);
 
 export const AMBIGUITIES: ReadonlyArray<Record<string, string>> = [
     {

package/dist/agent-src/templates/scripts/work_engine/stack/runner.ts

@@ -236,7 +236,7 @@ export function resolve_toolchain(
         quality.push(..._php_quality(project_root, composer, wrappers));
     }
     if (has_package) {
-        runners.push(..._js_runners(pkg, wrappers));
+        runners.push(..._js_runners(pkg, wrappers, _package_manager(project_root, pkg)));
         quality.push(..._js_quality(pkg, wrappers));
     }
     if (has_python) {
@@ -347,7 +347,7 @@ function _php_runners(root: string, composer: Manifest, wrappers: Wrappers): Run
     ];
 }
 
-function _js_runners(pkg: Manifest, wrappers: Wrappers): RunnerResult[] {
+function _js_runners(pkg: Manifest, wrappers: Wrappers, manager: string): RunnerResult[] {
     const deps = _all_dependencies(
         pkg,
         'dependencies',
@@ -383,17 +383,17 @@ function _js_runners(pkg: Manifest, wrappers: Wrappers): RunnerResult[] {
 
     // e2e runner — separate bucket, excluded unless --include-e2e.
     if ('@playwright/test' in deps || 'playwright' in deps) {
-        const cmd = _script_command(scripts, ['test:e2e', 'e2e', 'playwright']) || 'npx playwright test';
+        const cmd = _script_command(scripts, ['test:e2e', 'e2e', 'playwright'], manager) || 'npx playwright test';
         out.push(
             new RunnerResult('js', 'playwright', cmd, SPEED_E2E, HIGH, '@playwright/test in package deps'),
         );
     } else if ('cypress' in deps) {
-        const cmd = _script_command(scripts, ['test:e2e', 'e2e', 'cypress']) || 'npx cypress run';
+        const cmd = _script_command(scripts, ['test:e2e', 'e2e', 'cypress'], manager) || 'npx cypress run';
         out.push(new RunnerResult('js', 'cypress', cmd, SPEED_E2E, HIGH, 'cypress in package deps'));
     }
 
     // slow bucket — an explicit slow/integration script.
-    const slow_cmd = _script_command(scripts, ['test:slow', 'test:integration']);
+    const slow_cmd = _script_command(scripts, ['test:slow', 'test:integration'], manager);
     if (slow_cmd) {
         out.push(
             new RunnerResult(
@@ -487,19 +487,100 @@ function _task_runner_wrappers(root: string, pkg: Manifest): Wrappers {
     }
     const scripts: Manifest = _isDict(pkg.scripts) ? pkg.scripts : {};
     if (_isDict(scripts) && 'test' in scripts) {
-        out['js-test'] = `${_package_manager(root)} test`;
+        out['js-test'] = `${_package_manager(root, pkg)} test`;
     }
     return out;
 }
 
-function _package_manager(root: string): string {
-    if (_is_file(path.join(root, 'pnpm-lock.yaml'))) {
-        return 'pnpm';
+/**
+ * Lockfile → manager, in the order `monorepo-workspace/SKILL.md` § 1 states.
+ * Kept as data rather than a chain of ifs so `PACKAGE_MANAGER_BRANCHES` below
+ * can assert the count against the documented one.
+ */
+const LOCKFILE_MANAGERS: ReadonlyArray<readonly [string, string]> = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['package-lock.json', 'npm'],
+];
+
+/**
+ * The five branches `monorepo-workspace/SKILL.md` § 1 specifies, named so a
+ * test can assert none went missing. The skill is the contract and it was
+ * already correct; this list exists because the code implemented three of the
+ * five and nothing noticed.
+ */
+export const PACKAGE_MANAGER_BRANCHES: readonly string[] = [
+    'packageManager',
+    'pnpm',
+    'yarn',
+    'bun',
+    'npm',
+] as const;
+
+export interface PackageManagerResolution {
+    /** The resolved manager, or `null` when the cascade deliberately refuses. */
+    manager: string | null;
+    /** Which branch answered — one of `PACKAGE_MANAGER_BRANCHES`, or `'ambiguous'`. */
+    via: string;
+    /** Non-empty when the cascade refuses: the reported finding. */
+    finding: string;
+}
+
+/**
+ * Resolve the package manager per `monorepo-workspace/SKILL.md` § 1.
+ *
+ * Two behaviours the previous three-branch version did not have, and both are
+ * in the skill rather than invented here:
+ *
+ *  - `packageManager` in the root `package.json` is the DECLARATION and wins
+ *    when present, because it is what Corepack enforces. A lockfile is an
+ *    inference; a declaration is not.
+ *  - **Two lockfiles is a finding, not a tie to break.** The old code returned
+ *    `pnpm` for a repository carrying both `pnpm-lock.yaml` and `yarn.lock`,
+ *    silently picking the first branch it tested. That is a guess presented as
+ *    an answer, and the skill says to report both and stop.
+ */
+export function _resolve_package_manager(
+    root: string,
+    pkg?: Manifest,
+): PackageManagerResolution {
+    const declared = pkg === undefined ? undefined : pkg['packageManager'];
+    if (typeof declared === 'string' && declared.trim() !== '') {
+        // `pnpm@9.1.0` → `pnpm`. Corepack's own format.
+        const name = declared.trim().split('@')[0] as string;
+        if (name !== '') {
+            return { manager: name, via: 'packageManager', finding: '' };
+        }
+    }
+    const present = LOCKFILE_MANAGERS.filter(([file]) => _is_file(path.join(root, file)));
+    const distinct = [...new Set(present.map(([, mgr]) => mgr))];
+    if (distinct.length > 1) {
+        return {
+            manager: null,
+            via: 'ambiguous',
+            finding:
+                `two package-manager lockfiles present (${present.map(([f]) => f).join(', ')}) ` +
+                'and no `packageManager` declaration — report both and stop, per ' +
+                'monorepo-workspace SKILL.md § 1',
+        };
     }
-    if (_is_file(path.join(root, 'yarn.lock'))) {
-        return 'yarn';
+    if (distinct.length === 1) {
+        const mgr = distinct[0] as string;
+        return { manager: mgr, via: mgr, finding: '' };
     }
-    return 'npm';
+    return { manager: 'npm', via: 'npm', finding: '' };
+}
+
+/**
+ * The resolved manager as a bare string for command construction. Falls back to
+ * `npm` on the ambiguous case so a caller building a command string still gets
+ * one — the FINDING is what carries the ambiguity, and a caller that needs it
+ * calls `_resolve_package_manager` directly.
+ */
+function _package_manager(root: string, pkg?: Manifest): string {
+    return _resolve_package_manager(root, pkg).manager ?? 'npm';
 }
 
 // --------------------------------------------------------------------------
@@ -580,10 +661,17 @@ function _script_uses(scripts: Manifest, name: string, tool: string): boolean {
     return typeof value === 'string' && value.includes(tool);
 }
 
-function _script_command(scripts: Manifest, names: string[]): string {
+/**
+ * Build a `<manager> run <script>` command for the first matching script name.
+ *
+ * `manager` used to be hardcoded `npm`. Every command the work engine hands an
+ * agent for verification inherited that, so a pnpm or yarn repository was told
+ * to run a command its lockfile contradicts.
+ */
+function _script_command(scripts: Manifest, names: string[], manager: string): string {
     for (const name of names) {
         if (typeof scripts[name] === 'string') {
-            return `npm run ${name}`;
+            return `${manager} run ${name}`;
         }
     }
     return '';