@event4u/agent-config 8.9.0 → 8.11.0

package/src/scripts/lint_knowledge_scale.ts

@@ -166,6 +166,36 @@ export function runChecks(root: string): Warning[] {
         });
     }
 
+    // 6. Contested cards — surface knowledge cards flagged `contested: true`
+    //    (set when `check_memory_contradiction.ts` fires) so a weak / disputed
+    //    claim stays visibly weak across sessions instead of silently hardening.
+    const cardsDir = path.join(root, 'agents', 'knowledge');
+    const contested = listFiles(cardsDir, ['.md'])
+        .filter((f) => {
+            const base = path.basename(f).toLowerCase();
+            return base !== 'readme.md' && base !== 'index.md';
+        })
+        .filter((f) => {
+            let text: string;
+            try {
+                text = fs.readFileSync(f, 'utf-8');
+            } catch {
+                return false;
+            }
+            // frontmatter-scoped: `contested: true` on its own line near the top.
+            return /^\s*contested:\s*true\s*$/m.test(text.slice(0, 2000));
+        })
+        .map((f) => path.basename(f));
+    if (contested.length > 0) {
+        warnings.push({
+            rule: 'contested-cards',
+            metric: `${contested.length}/0`,
+            message:
+                `${contested.length} knowledge card(s) carry \`contested: true\`: ${contested.join(', ')}. ` +
+                'Resolution path: reconcile each against its `contradictions: [id]` list (human-judged) — a contested claim must not be cited as settled until resolved.',
+        });
+    }
+
     // 5. Hot-context budget.
     const hotContext = path.join(root, 'agents', 'runtime', 'state', 'hot-context.md');
     let hotText = '';

package/src/scripts/lint_originality_shingles.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env tsx
+/**
+ * lint_originality_shingles — mechanical re-skin detector for the artifact
+ * corpus (road-to-opt-subagent-harvest P1.3).
+ *
+ * Compares every pair of skills / personas / subagents by entity-neutralized
+ * 8-word shingle overlap. Two artifacts that differ only in the named
+ * framework, product, or persona ("re-skins") share almost all shingles once
+ * entities are masked — exactly the near-duplicate class a human review
+ * misses at 200+ files. Slots beside `persona-governance` / `skill-quality`.
+ *
+ * Sibling of `lint_skill_originality` (ADR-096), NOT a replacement: that
+ * gate runs bag-of-words Jaccard over SKILLS with pack-domain severity;
+ * this one masks entities and compares 8-word PHRASES across skills +
+ * personas + subagents — the re-skin that only swaps "Laravel" for
+ * "Django" scores LOW on plain token-Jaccard (different entity tokens)
+ * and HIGH here. Run both.
+ *
+ * Modes:
+ *   default             report-only — prints the top overlapping pairs,
+ *                       always exits 0 (first-run calibration mode).
+ *   --threshold <pct>   exits 1 when any pair's overlap (Jaccard, %) is
+ *                       >= pct and the pair is not allowlisted below.
+ *   --top <n>           rows to print (default 15).
+ *   --quiet             suppress the report (threshold mode still fails).
+ *
+ * Known-legitimate pairs (shared scaffolding, sibling carve-outs) are
+ * allowlisted inline with reasons — same >20-entries policy as every other
+ * allowlist in this repo.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(_HERE, '..', '..');
+
+const SHINGLE_LEN = 8;
+
+/** Entity mask — named stacks/products/personas collapse to one token so a
+ *  re-skin that only swaps the entity still matches. Lowercase input. */
+const ENTITY_RE = new RegExp(
+    '\\b(laravel|symfony|django|rails|react|vue|angular|nextjs|next\\.js|nuxt|' +
+        'nestjs|express|fastify|flask|fastapi|spring|eloquent|doctrine|prisma|' +
+        'pest|phpunit|jest|vitest|pytest|phpstan|rector|ecs|prettier|eslint|' +
+        'mypy|tsc|php|python|typescript|javascript|node|go|rust|ruby|java|' +
+        'tailwind|blade|livewire|flux|jira|sentry|grafana|terraform|terragrunt|' +
+        'traefik|docker|aws|stripe|openai|anthropic|claude|gemini|gpt)\\b',
+    'g',
+);
+
+interface Doc {
+    id: string;
+    shingles: Set<string>;
+}
+
+interface AllowPair {
+    a: string;
+    b: string;
+    reason: string;
+}
+
+/** Sibling artifacts that legitimately share scaffolding. Keep < 20. */
+const ALLOWLIST: AllowPair[] = [
+    // Populated from calibration runs; empty on first ship — the default
+    // mode is report-only, so no entry is needed until a threshold is armed.
+];
+
+function _normalize(body: string): string[] {
+    // strip fenced code, frontmatter, markdown syntax; mask entities.
+    let text = body.replace(/^---\n[\s\S]*?\n---\n/, '');
+    text = text.replace(/```[\s\S]*?```/g, ' ');
+    text = text.toLowerCase();
+    text = text.replace(ENTITY_RE, '§entity§');
+    text = text.replace(/[^a-z0-9§]+/g, ' ');
+    return text.split(' ').filter((w) => w.length > 0);
+}
+
+function _shingles(words: string[]): Set<string> {
+    const out = new Set<string>();
+    for (let i = 0; i + SHINGLE_LEN <= words.length; i++) {
+        out.add(words.slice(i, i + SHINGLE_LEN).join(' '));
+    }
+    return out;
+}
+
+function _collect(): Doc[] {
+    const docs: Doc[] = [];
+    const push = (id: string, file: string): void => {
+        let body: string;
+        try {
+            body = fs.readFileSync(file, 'utf-8');
+        } catch {
+            return;
+        }
+        const sh = _shingles(_normalize(body));
+        if (sh.size >= 20) {
+            docs.push({ id, shingles: sh });
+        }
+    };
+    const skillsDir = path.join(REPO, 'src', 'skills');
+    for (const d of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (d.isDirectory()) {
+            push(`skill:${d.name}`, path.join(skillsDir, d.name, 'SKILL.md'));
+        }
+    }
+    const personasDir = path.join(REPO, 'src', 'personas');
+    if (fs.existsSync(personasDir)) {
+        const walk = (dir: string, prefix: string): void => {
+            for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, d.name);
+                if (d.isDirectory() && !d.name.startsWith('_')) {
+                    walk(full, prefix);
+                } else if (d.isFile() && d.name.endsWith('.md') && d.name !== 'README.md') {
+                    push(`persona:${path.basename(d.name, '.md')}`, full);
+                }
+            }
+        };
+        walk(personasDir, 'persona');
+    }
+    const subagentsDir = path.join(REPO, 'src', 'subagents');
+    if (fs.existsSync(subagentsDir)) {
+        for (const f of fs.readdirSync(subagentsDir)) {
+            if (f.endsWith('.md') && !f.startsWith('_')) {
+                push(`subagent:${path.basename(f, '.md')}`, path.join(subagentsDir, f));
+            }
+        }
+    }
+    return docs;
+}
+
+function _jaccardPct(a: Set<string>, b: Set<string>): number {
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    let inter = 0;
+    for (const s of small) {
+        if (large.has(s)) inter++;
+    }
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : (100 * inter) / union;
+}
+
+function _allowlisted(a: string, b: string): boolean {
+    return ALLOWLIST.some(
+        (p) => (p.a === a && p.b === b) || (p.a === b && p.b === a),
+    );
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let threshold: number | null = null;
+    let top = 15;
+    let quiet = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i] as string;
+        if (arg === '--threshold') threshold = Number(argv[++i]);
+        else if (arg === '--top') top = Number(argv[++i]);
+        else if (arg === '--quiet') quiet = true;
+    }
+
+    const docs = _collect();
+    const pairs: Array<{ a: string; b: string; pct: number }> = [];
+    for (let i = 0; i < docs.length; i++) {
+        for (let j = i + 1; j < docs.length; j++) {
+            const pct = _jaccardPct((docs[i] as Doc).shingles, (docs[j] as Doc).shingles);
+            if (pct > 0.5) {
+                pairs.push({ a: (docs[i] as Doc).id, b: (docs[j] as Doc).id, pct });
+            }
+        }
+    }
+    pairs.sort((x, y) => y.pct - x.pct);
+
+    if (!quiet) {
+        process.stdout.write(
+            `originality-shingles: ${docs.length} docs · ${SHINGLE_LEN}-word entity-masked shingles\n`,
+        );
+        for (const p of pairs.slice(0, top)) {
+            process.stdout.write(`  ${p.pct.toFixed(1).padStart(5)}%  ${p.a}  ↔  ${p.b}\n`);
+        }
+        if (pairs.length === 0) {
+            process.stdout.write('  no pair above 0.5% overlap\n');
+        }
+    }
+
+    if (threshold !== null && Number.isFinite(threshold)) {
+        const offenders = pairs.filter((p) => p.pct >= (threshold as number) && !_allowlisted(p.a, p.b));
+        if (offenders.length > 0) {
+            process.stderr.write(
+                `❌  originality-shingles: ${offenders.length} pair(s) at or above ${threshold}% overlap:\n`,
+            );
+            for (const p of offenders.slice(0, top)) {
+                process.stderr.write(`    ${p.pct.toFixed(1)}%  ${p.a} ↔ ${p.b}\n`);
+            }
+            return 1;
+        }
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(fileURLToPath(import.meta.url));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/orchestration_record.ts

@@ -11,6 +11,7 @@
  *     --spawn-count 1 --token-delta -72000 --provenance measured \
  *     --tier-chosen lite --tier-source inferred --task-class read-only-fanout \
  *     [--tiers sonnet,opus] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
+ *     [--first-pass-success true|false] [--escalated true|false] \
  *     [--dir <audit-dir>] [--dry-run]
  *
  * Read by `src/scripts/orchestration_savings_report.ts`.
@@ -65,6 +66,19 @@ function str(flags: Flags, key: string): string | undefined {
     return typeof v === 'string' ? v : undefined;
 }
 
+/**
+ * Parse an explicit boolean flag value. `--key true|false` → boolean; a bare
+ * `--key` counts as `true`; any other value is passed through so the lib's
+ * non-boolean validation rejects it with a clear error.
+ */
+function bool(flags: Flags, key: string): boolean | undefined {
+    const v = flags[key];
+    if (v === undefined) return undefined;
+    if (v === true || v === 'true') return true;
+    if (v === 'false') return false;
+    return v as unknown as boolean; // invalid string → caught by the lib's typeof validation
+}
+
 function int(flags: Flags, key: string): number | undefined {
     const v = str(flags, key);
     if (v === undefined) return undefined;
@@ -98,12 +112,15 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         tier_chosen: str(flags, 'tier-chosen') as TierChosen | undefined,
         tier_source: str(flags, 'tier-source') as TierSource | undefined,
         task_class: str(flags, 'task-class'),
+        dispatch_mode: str(flags, 'dispatch-mode') as never,
         task_size_estimate: int(flags, 'task-size-estimate'),
         wall_clock_ms: int(flags, 'wall-clock-ms'),
         dispatch_tokens: int(flags, 'dispatch-tokens'),
         session_tier: str(flags, 'session-tier'),
         dispatch_outcome: str(flags, 'dispatch-outcome') as DispatchOutcome | undefined,
         verify_mode: str(flags, 'verify-mode') as VerifyMode | undefined,
+        first_pass_success: bool(flags, 'first-pass-success'),
+        escalated: bool(flags, 'escalated'),
         phase: str(flags, 'phase') as LinePhase | undefined,
         outcome: str(flags, 'outcome') as LineOutcome | undefined,
         confidence_band: str(flags, 'confidence-band') as Band | undefined,

package/src/scripts/orchestration_savings_report.ts

@@ -5,6 +5,11 @@
  * and prints an aggregate token-savings report. Read-only; no network, no
  * mutation. Handles a missing/empty audit dir gracefully.
  *
+ * QUALITY × COST PAIRING (council verdict): the savings figures never render
+ * without the quality columns (first_pass_success_rate / escalation_rate).
+ * When ≥ 20 lines in the window carry the quality fields the real rates
+ * render; below 20 the columns render as "n/a (n=<count>)" beside savings.
+ *
  * Usage:
  *   ./scripts-run src/scripts/orchestration_savings_report \
  *     [--dir <path>] [--format text|json] [--weights lite=1,medium=5,high=15]
@@ -77,13 +82,41 @@ export function readAuditLines(dir: string): AuditLine[] {
     return lines;
 }
 
-function renderText(r: SavingsReport, dir: string): string {
+/** Dispatches carrying the quality fields at/above this render the real rates; below, "n/a (n=<count>)". */
+export const QUALITY_GATE_MIN_LINES = 20;
+
+function pct(v: number): string {
+    return `${(v * 100).toFixed(0)}%`;
+}
+
+/**
+ * Render the paired cost × quality block. Council verdict: savings NEVER render
+ * without the quality columns — at n ≥ QUALITY_GATE_MIN_LINES the real rates
+ * render; below, the quality columns render as "n/a (n=<count>)" alongside the
+ * savings figures. There is no savings-only render path.
+ */
+function renderPairedCostQuality(r: SavingsReport): string[] {
+    const q = r.quality;
+    const gated = q.quality_lines >= QUALITY_GATE_MIN_LINES;
+    const fps = gated && q.first_pass_success_rate !== null
+        ? `${pct(q.first_pass_success_rate)} (n=${q.first_pass_lines})`
+        : `n/a (n=${q.first_pass_lines})`;
+    const esc = gated && q.escalation_rate !== null
+        ? `${pct(q.escalation_rate)} (n=${q.escalated_lines})`
+        : `n/a (n=${q.escalated_lines})`;
+    return [
+        '  cost × quality (paired — never savings alone):',
+        `    net token_delta: ${r.net_token_delta} (negative = net saved)   | first_pass_success_rate: ${fps}`,
+        `    tokens saved: ${r.tokens_saved} · tokens added: ${r.tokens_added}   | escalation_rate: ${esc}`,
+    ];
+}
+
+export function renderText(r: SavingsReport, dir: string): string {
     const out: string[] = [];
     out.push('Orchestration savings report');
     out.push(`  source: ${dir}`);
     out.push(`  dispatches: ${r.dispatches}  (total spawns: ${r.total_spawns})`);
-    out.push(`  net token_delta: ${r.net_token_delta}  (negative = net saved)`);
-    out.push(`  tokens saved: ${r.tokens_saved}   tokens added: ${r.tokens_added}`);
+    out.push(...renderPairedCostQuality(r));
     out.push(`  provenance: measured ${r.by_provenance.measured.dispatches} (Δ ${r.by_provenance.measured.net_token_delta}) · estimated ${r.by_provenance.estimated.dispatches} (Δ ${r.by_provenance.estimated.net_token_delta})`);
     out.push(`  measured share: ${(r.measured_share * 100).toFixed(0)}%`);
     if (Object.keys(r.by_tier).length) {

package/src/scripts/schemas/agent-settings.schema.json

@@ -84,6 +84,17 @@
         }
       }
     },
+    "code_style": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "docblocks": {
+          "type": "string",
+          "enum": ["minimal", "full"],
+          "description": "Consumed by the code-comment-discipline rule. minimal (default) = no signature-mirroring docblocks; docblocks only for machine-relevant precision (generics, array shapes) or genuine why-context. full = exported public library surface may carry one-line summary docblocks; the redundancy ban still holds."
+        }
+      }
+    },
     "tokens": {
       "type": "object",
       "additionalProperties": true,

package/src/scripts/second_brain_retrieval.ts

@@ -38,6 +38,7 @@ import {
     _setMemoryRoot,
     retrieve,
 } from './memory_lookup.js';
+import { sanitize_text } from './_lib/retrieval_sanitize.js';
 import { scoreTask } from './second_brain_score.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -67,11 +68,19 @@ export function bindStore(): void {
     _setIntakeRoot(path.join(STORE_DIR, 'intake-none'));
 }
 
-export function loadCorpus(): { type: string; k: number; tasks: RetrievalTask[] } {
+export function loadCorpus(): {
+    type: string;
+    k: number;
+    tasks: RetrievalTask[];
+    stale_ids?: string[];
+    poisoned_ids?: string[];
+} {
     const doc = YAML.parse(fs.readFileSync(path.join(STORE_DIR, 'retrieval-corpus.yml'), 'utf-8')) as {
         type: string;
         k: number;
         tasks: RetrievalTask[];
+        stale_ids?: string[];
+        poisoned_ids?: string[];
     };
     return doc;
 }
@@ -162,11 +171,17 @@ export function signTestP(wins: number, losses: number): number {
 
 export async function run(opts: { mode: 'dry-run' | 'live'; host: string; seeds: number }): Promise<Record<string, unknown>> {
     bindStore();
-    const { type, k, tasks } = loadCorpus();
+    const { type, k, tasks, stale_ids = [], poisoned_ids = [] } = loadCorpus();
+    const staleSet = new Set(stale_ids);
+    const poisonedSet = new Set(poisoned_ids);
     const apiKey = opts.mode === 'live' ? load_anthropic_key() : '';
     const placebo = _placeboBodies(type);
 
     let precisionHits = 0;
+    let topkSlots = 0;
+    let staleHits = 0;
+    let poisonedRetrieved = 0;
+    let poisonedNeutralized = 0;
     let tieSetSum = 0;
     const perTask: Array<Record<string, unknown>> = [];
     const armPass: Record<Arm, number> = { 'retrieval-off': 0, 'retrieval-on': 0, placebo: 0 };
@@ -177,6 +192,18 @@ export async function run(opts: { mode: 'dry-run' | 'live'; host: string; seeds:
     for (const task of tasks) {
         const { topk, rank, tieSetSize } = retrieveFor(task, type, k);
         const ids = topk.map((r) => r.id);
+        topkSlots += topk.length;
+        for (const hit of topk) {
+            if (staleSet.has(hit.id)) staleHits += 1;
+            if (poisonedSet.has(hit.id)) {
+                poisonedRetrieved += 1;
+                // Rejection = the sanitize floor strips every hidden-instruction
+                // vector before the body could reach a prompt.
+                const clean = sanitize_text(hit.body);
+                if (!/[​-‏‪-‮⁦-⁩]/u.test(clean)) poisonedNeutralized += 1;
+            }
+        }
+
         const neededInTopK = rank >= 0 && rank < k;
         if (neededInTopK) precisionHits += 1;
         tieSetSum += tieSetSize;
@@ -226,6 +253,21 @@ export async function run(opts: { mode: 'dry-run' | 'live'; host: string; seeds:
         k,
         store: 'internal/bench/second-brain/retrieval-store/ (5 needed + 19 distractors, keyword-overlapping confusers)',
         precision_at_k: precisionAtK,
+        // road-to-proof-under-real-conditions Phase 5 — retrieval quality pair:
+        // stale_hit_rate: fraction of retrieved top-k slots occupied by
+        // SUPERSEDED store entries (lower is better; the substrate has no
+        // recency/supersede weighting yet, so a non-zero rate is the honest
+        // baseline the FTS5/recency activation path improves on).
+        stale_hit_rate: topkSlots ? staleHits / topkSlots : 0,
+        stale_hits: staleHits,
+        topk_slots: topkSlots,
+        // poisoned_rejection_rate: of poisoned entries that WERE retrieved,
+        // the fraction whose hidden-instruction vectors the sanitize floor
+        // strips (target 1.0; null when none was retrieved this run).
+        poisoned_rejection_rate: poisonedRetrieved ? poisonedNeutralized / poisonedRetrieved : null,
+        poisoned_retrieved: poisonedRetrieved,
+        poisoned_neutralized: poisonedNeutralized,
+
         precision_hits: precisionHits,
         mean_tie_set_size: meanTieSet,
         discrimination_note:

package/src/scripts/self_review_gate.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    classifyBlocking,
+    gateVerdict,
+    isReviewablePath,
+    renderReview,
+    type Finding,
+} from './self_review_gate.js';
+
+const f = (severity: Finding['severity'], kind: Finding['kind']): Finding => ({
+    severity,
+    kind,
+    title: `${severity} ${kind}`,
+    detail: 'x',
+});
+
+describe('classifyBlocking', () => {
+    it('blocks security + high and claim + critical', () => {
+        expect(classifyBlocking(f('high', 'security'))).toBe(true);
+        expect(classifyBlocking(f('critical', 'claim'))).toBe(true);
+    });
+    it('does not block low/medium security, or any style/correctness', () => {
+        expect(classifyBlocking(f('medium', 'security'))).toBe(false);
+        expect(classifyBlocking(f('low', 'claim'))).toBe(false);
+        expect(classifyBlocking(f('critical', 'style'))).toBe(false);
+        expect(classifyBlocking(f('high', 'correctness'))).toBe(false);
+    });
+});
+
+describe('gateVerdict', () => {
+    const blocking = [f('high', 'security')];
+    it('advisory (default shipped mode) never blocks, even with a blocking finding', () => {
+        expect(gateVerdict(blocking, { enforce: false })).toBe(0);
+    });
+    it('enforce blocks only on a merge-blocking finding', () => {
+        expect(gateVerdict(blocking, { enforce: true })).toBe(2);
+        expect(gateVerdict([f('critical', 'style')], { enforce: true })).toBe(0);
+        expect(gateVerdict([], { enforce: true })).toBe(0);
+    });
+});
+
+describe('isReviewablePath', () => {
+    it('skips generated projections + lockfiles, keeps source', () => {
+        expect(isReviewablePath('dist/agent-src/skills/x/SKILL.md')).toBe(false);
+        expect(isReviewablePath('.augment/rules/x.md')).toBe(false);
+        expect(isReviewablePath('.windsurfrules')).toBe(false);
+        expect(isReviewablePath('package-lock.json')).toBe(false);
+        expect(isReviewablePath('src/rules/x.md')).toBe(true);
+        expect(isReviewablePath('src/scripts/y.ts')).toBe(true);
+    });
+});
+
+describe('renderReview', () => {
+    it('carries the HUMAN REVIEW REQUIRED banner + the floor-not-human-review caveat', () => {
+        const out = renderReview([], false);
+        expect(out).toContain('HUMAN REVIEW REQUIRED');
+        expect(out).toContain('not** independent human review');
+    });
+    it('advisory phrasing says WOULD block, enforce phrasing says blocking', () => {
+        const blocking = [f('high', 'security')];
+        expect(renderReview(blocking, false)).toContain('WOULD block');
+        expect(renderReview(blocking, true)).toContain('merge-blocking');
+    });
+});