@event4u/agent-config 8.4.0 → 8.5.0

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

@@ -0,0 +1,370 @@
+#!/usr/bin/env tsx
+/**
+ * Gate script for memory promotion (intake → curated).
+ *
+ * TypeScript twin of `src/agent-src/templates/scripts/check_memory_proposal.py`
+ * (ADR-200, Phase 1 — consumer-shipped template). Adapted from the dev-side
+ * `src/scripts/check_memory_proposal.ts` twin: the template `.py` is identical
+ * EXCEPT it lacks the dev-side `--quiet` flag (gate-passed line always prints),
+ * so this twin drops `--quiet` to match the template surface exactly.
+ * Mirrors the Python CLI contract EXACTLY — mutually
+ * exclusive `--intake-id` / `--proposal` (one required), `--format`
+ * (text|json), exit codes (0 pass, 1 gate failure / not-found,
+ * 2 PyYAML missing — N/A here, 3 internal), stdout/stderr split,
+ * byte-identical messages (incl. Python set-repr of VALID_TYPES), same
+ * intake scan + pattern logic. No behaviour changes.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import YAML from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+// Relative to cwd, mirroring Python `Path("agents/memory/intake")`.
+// Injectable for tests (monkeypatch parity).
+let INTAKE_ROOT = path.join('agents', 'memory', 'intake');
+
+const VALID_TYPES: ReadonlySet<string> = new Set([
+    'historical-patterns',
+    'incident-learnings',
+    'ownership',
+    'domain-invariants',
+    'product-rules',
+]);
+const REQUIRED_INTAKE = ['id', 'entry_type', 'path', 'body'] as const;
+const PATTERN_MIN_PATHS = 2;
+const MIN_FUTURE_DECISIONS = 3;
+
+type Record_ = Record<string, unknown>;
+
+/** Mirror Python `repr(sorted(set))` for a string set. */
+function _pyList(items: readonly string[]): string {
+    const sorted = items.slice().sort();
+    return '[' + sorted.map((s) => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`).join(', ') + ']';
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/** Mirror sorted(glob("*.jsonl")) on INTAKE_ROOT — full paths, sorted. */
+function _jsonlFilesSorted(): string[] {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(INTAKE_ROOT);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.endsWith('.jsonl'))
+        .map((e) => path.join(INTAKE_ROOT, e))
+        .sort();
+}
+
+/** Unsorted glob (Python `.glob` without sorted) for _count_sibling_paths. */
+function _jsonlFilesUnsorted(): string[] {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(INTAKE_ROOT);
+    } catch {
+        return [];
+    }
+    return entries.filter((e) => e.endsWith('.jsonl')).map((e) => path.join(INTAKE_ROOT, e));
+}
+
+function _load_yaml(p: string): Record_ {
+    let data: unknown;
+    data = YAML.parse(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        process.stderr.write(`error: ${p} is not a YAML mapping\n`);
+        process.exit(1);
+    }
+    return data as Record_;
+}
+
+function _find_intake(intake_id: string): Record_ | null {
+    if (!_isDir(INTAKE_ROOT)) {
+        return null;
+    }
+    for (const jsonl of _jsonlFilesSorted()) {
+        const text = fs.readFileSync(jsonl, 'utf-8');
+        for (let line of text.split('\n')) {
+            line = line.trim();
+            if (line === '') {
+                continue;
+            }
+            let obj: unknown;
+            try {
+                obj = JSON.parse(line);
+            } catch {
+                continue;
+            }
+            if (obj !== null && typeof obj === 'object' && (obj as Record_)['id'] === intake_id) {
+                return obj as Record_;
+            }
+        }
+    }
+    return null;
+}
+
+function _count_sibling_paths(entry_type: unknown, body: unknown): number {
+    if (!_isDir(INTAKE_ROOT)) {
+        return 0;
+    }
+    const seen = new Set<string>();
+    for (const jsonl of _jsonlFilesUnsorted()) {
+        const text = fs.readFileSync(jsonl, 'utf-8');
+        for (let line of text.split('\n')) {
+            line = line.trim();
+            if (line === '') {
+                continue;
+            }
+            let obj: unknown;
+            try {
+                obj = JSON.parse(line);
+            } catch {
+                continue;
+            }
+            if (obj === null || typeof obj !== 'object') {
+                continue;
+            }
+            const o = obj as Record_;
+            if (
+                o['entry_type'] === entry_type &&
+                o['body'] === body &&
+                typeof o['path'] === 'string'
+            ) {
+                seen.add(o['path'] as string);
+            }
+        }
+    }
+    return seen.size;
+}
+
+function _check_future_decisions(fds: unknown): string[] {
+    const failures: string[] = [];
+    if (!Array.isArray(fds)) {
+        return ['future_decisions: missing or not a list'];
+    }
+    if (fds.length < MIN_FUTURE_DECISIONS) {
+        failures.push(
+            `future_decisions: needs ≥${MIN_FUTURE_DECISIONS}, got ${fds.length}`,
+        );
+    }
+    for (let idx = 0; idx < fds.length; idx++) {
+        const i = idx + 1;
+        const fd = fds[idx];
+        if (fd === null || typeof fd !== 'object' || Array.isArray(fd)) {
+            failures.push(`future_decisions[${i}]: must be a mapping`);
+            continue;
+        }
+        const fdObj = fd as Record_;
+        for (const key of ['decision', 'expected_by', 'owner']) {
+            if (!fdObj[key]) {
+                failures.push(`future_decisions[${i}]: missing \`${key}\``);
+            }
+        }
+    }
+    return failures;
+}
+
+function check(record: Record_, _source: string): string[] {
+    const failures: string[] = [];
+    // 1. required fields
+    for (const key of REQUIRED_INTAKE) {
+        const v = record[key];
+        if (!(key in record) || v === null || v === undefined || v === '') {
+            failures.push(`missing field: \`${key}\``);
+        }
+    }
+    // 2. type value
+    const etype = record['entry_type'];
+    if (!VALID_TYPES.has(etype as string)) {
+        failures.push(
+            `entry_type \`${etype === undefined || etype === null ? 'None' : String(etype)}\` not in ${_pyList([...VALID_TYPES])}`,
+        );
+    }
+    // 3. pattern vs one-off
+    const body = record['body'];
+    const sibling_paths = body && etype ? _count_sibling_paths(etype, body) : 0;
+    const fds = record['future_decisions'];
+    if (sibling_paths >= PATTERN_MIN_PATHS) {
+        // strong pattern signal
+    } else {
+        const fd_errors = _check_future_decisions(fds);
+        if (fd_errors.length > 0) {
+            failures.push(
+                `weak pattern evidence (${sibling_paths} sibling path(s)) ` +
+                    `and future_decisions insufficient:`,
+            );
+            for (const e of fd_errors) {
+                failures.push(`  - ${e}`);
+            }
+        }
+    }
+    return failures;
+}
+
+// --- argparse port ---------------------------------------------------------
+
+interface ParsedArgs {
+    intake_id: string | null;
+    proposal: string | null;
+    format: 'text' | 'json';
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`check_memory_proposal: error: ${message}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    let intake_id: string | null = null;
+    let proposal: string | null = null;
+    let format: 'text' | 'json' = 'text';
+    // 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.
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i]!;
+        if (arg === '--intake-id' || arg.startsWith('--intake-id=')) {
+            if (proposal !== null) {
+                _argparse_error('argument --intake-id: not allowed with argument --proposal');
+            }
+            intake_id = arg === '--intake-id' ? _need(argv, ++i, '--intake-id') : arg.slice('--intake-id='.length);
+        } else if (arg === '--proposal' || arg.startsWith('--proposal=')) {
+            if (intake_id !== null) {
+                _argparse_error('argument --proposal: not allowed with argument --intake-id');
+            }
+            proposal = arg === '--proposal' ? _need(argv, ++i, '--proposal') : arg.slice('--proposal='.length);
+        } else if (arg === '--format') {
+            const v = _need(argv, ++i, '--format');
+            format = _checkFormat(v);
+        } else if (arg.startsWith('--format=')) {
+            format = _checkFormat(arg.slice('--format='.length));
+        } 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',
+            );
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    if (intake_id === null && proposal === null) {
+        _argparse_error('one of the arguments --intake-id --proposal is required');
+    }
+    return { intake_id, proposal, format };
+}
+
+function _need(argv: readonly string[], i: number, flag: string): string {
+    const v = argv[i];
+    if (v === undefined) {
+        _argparse_error(`argument ${flag}: expected one argument`);
+    }
+    return v;
+}
+
+function _checkFormat(v: string): 'text' | 'json' {
+    if (v !== 'text' && v !== 'json') {
+        _argparse_error(`argument --format: invalid choice: '${v}' (choose from 'text', 'json')`);
+    }
+    return v;
+}
+
+/** Mirror Python `json.dumps(obj, indent=2)` with ensure_ascii. */
+function _json_dumps_ascii(obj: unknown): string {
+    const raw = JSON.stringify(obj, null, 2);
+    let out = '';
+    for (const ch of raw) {
+        const code = ch.codePointAt(0)!;
+        if (code < 0x80) {
+            out += ch;
+        } else {
+            for (let k = 0; k < ch.length; k++) {
+                out += '\\u' + ch.charCodeAt(k).toString(16).padStart(4, '0');
+            }
+        }
+    }
+    return out;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    let record: Record_;
+    let source: string;
+    if (args.intake_id !== null) {
+        const found = _find_intake(args.intake_id);
+        if (found === null) {
+            process.stderr.write(`error: no intake entry with id=${args.intake_id}\n`);
+            return 1;
+        }
+        record = found;
+        source = `intake:${args.intake_id}`;
+    } else {
+        record = _load_yaml(args.proposal!);
+        source = args.proposal!;
+    }
+    const failures = check(record, source);
+    if (args.format === 'json') {
+        process.stdout.write(_json_dumps_ascii({ source, failures }) + '\n');
+    } else {
+        if (failures.length > 0) {
+            process.stdout.write(`❌  ${source} — gate failed:\n`);
+            for (const f of failures) {
+                process.stdout.write(`  🔴 ${f}\n`);
+            }
+        } else {
+            process.stdout.write(`✅  ${source} — gate passed\n`);
+        }
+    }
+    return failures.length > 0 ? 1 : 0;
+}
+
+function _set_intake_root_for_test(root: string): void {
+    INTAKE_ROOT = root;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // A symlinked invocation (e.g. via an installed `.augment/` projection,
+    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
+    // import.meta.url is the resolved real path while argv[1] keeps the
+    // symlink path. Compare realpaths so the entry guard still fires
+    // (without this the CLI silently no-ops when run through a symlink).
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export {
+    VALID_TYPES,
+    REQUIRED_INTAKE,
+    _find_intake,
+    _count_sibling_paths,
+    _check_future_decisions,
+    check,
+    main,
+    _set_intake_root_for_test,
+};

package/src/agent-src/templates/scripts/historical-bug-patterns.example.yml

@@ -0,0 +1,84 @@
+# Historical bug patterns — consumed by scripts/pr_review_routing.ts
+#
+# Copy this file to `.github/historical-bug-patterns.yml` (preferred) or
+# `agents/historical-bug-patterns.yml` and curate the patterns from your
+# project's actual postmortems. Every pattern must reference a real prior
+# failure — this file is not a wishlist.
+#
+# A pattern matches when ANY changed file in the PR matches ANY of its
+# `paths` globs. Routing severity is the max of matched pattern severities.
+
+version: 1
+updated: 2026-04-21
+
+patterns:
+  - id: n-plus-one-tenant-listing
+    label: "N+1 on tenant-scoped listings"
+    severity: medium
+    paths:
+      - "app/Http/Controllers/**Listing*.php"
+      - "app/Http/Controllers/**Index*.php"
+      - "app/Services/**Query*.php"
+    required_test: "assert query count ≤ N for a multi-row tenant fixture"
+    references:
+      - "PR #842 — production slowdown 2024-09"
+
+  - id: missing-policy-on-admin-route
+    label: "Admin-only route without Gate::allows / policy"
+    severity: high
+    paths:
+      - "app/Http/Controllers/Admin/**"
+      - "routes/admin.php"
+    required_test: "negative test: non-admin receives 403"
+    references:
+      - "INC-214 — non-admin reached admin settings endpoint"
+
+  - id: queue-job-not-idempotent
+    label: "Queue job without idempotency key"
+    severity: high
+    paths:
+      - "app/Jobs/**"
+      - "src/MessageHandler/**"
+    required_test: "assert a retried job does not double-write"
+
+  - id: secret-in-config-commit
+    label: "Secret-looking value committed to config"
+    severity: high
+    paths:
+      - "**/config/**.php"
+      - "**/config/**.yaml"
+      - "**/config/**.yml"
+    required_test: "grep-based check in CI that the commit carries no API keys"
+    references:
+      - "INC-088 — API key leaked in config/services.php"
+
+  - id: missing-index-on-foreign-key
+    label: "New foreign key without covering index"
+    severity: medium
+    paths:
+      - "**/migrations/**"
+    required_test: "assert EXPLAIN on a representative query uses the index"
+
+  - id: blade-unsafe-html
+    label: "Blade component renders user input with {!! !!}"
+    severity: high
+    paths:
+      - "resources/views/**.blade.php"
+    required_test: "confirm the rendered field is escaped or sanitized upstream"
+    references:
+      - "CVE-2023-XXX-style XSS from unsanitized profile field"
+
+  - id: webhook-without-signature-check
+    label: "Webhook handler without signature verification"
+    severity: high
+    paths:
+      - "app/Http/Controllers/**Webhook*.php"
+      - "app/api/**webhook**"
+    required_test: "negative test: unsigned payload returns 401"
+
+  - id: migration-no-rollback
+    label: "Migration with destructive up() and empty down()"
+    severity: medium
+    paths:
+      - "**/migrations/**"
+    required_test: "document in the PR why rollback is intentionally not supported"

package/src/agent-src/templates/scripts/implement_ticket/__main__.ts

@@ -0,0 +1,27 @@
+/**
+ * Deprecated CLI entry point — delegates to `work_engine`.
+ *
+ * TypeScript twin of `implement_ticket/__main__.py` (ADR-200, Python→TypeScript
+ * migration). `python3 -m implement_ticket` still works because the
+ * Golden-Transcript freeze-guard pins that invocation; the twin mirrors it 1:1 —
+ * import `main`, run it, and set `process.exitCode` to the returned code, never
+ * `process.exit` (per ADR-200, so flushing + cleanup run as Node's natural
+ * shutdown does).
+ *
+ * --- Parity notes (ADR-200) ---
+ *
+ * - The Python module imports `main` from `work_engine.cli`. The Python package
+ *   `__init__` emits a `DeprecationWarning` on import and registers
+ *   `implement_ticket.*` → `work_engine.*` `sys.modules` aliases; those are
+ *   import-resolution side effects with no observable stdout/stderr for the
+ *   `-m` entrypoint (the warning is suppressed by default under `python3 -m`
+ *   unless `-W` is set), so the twin imports `main` directly from the shipped
+ *   `work_engine` CLI twin with no behavioural difference for this path.
+ * - `if __name__ == "__main__": sys.exit(main())` → set `process.exitCode`
+ *   from `main()`; `sys.exit(int)` and a bare `process.exitCode =` produce the
+ *   same process exit status without tearing down mid-flush.
+ */
+
+import { main } from '../work_engine/cli.js';
+
+process.exitCode = main();