@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/governance/rules/settlement.js

@@ -0,0 +1,363 @@
+/**
+ * Mechanical settlement - structured verdicts -> automatic bookings and routing
+ * (governance-mode 5.5).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Every function here is a PURE DECISION: it returns the events to book, the next route
+ * for the work package and any claims to open, and touches no state. The engine books the
+ * events through the ledger (I-G7: one accounting path) and applies the route.
+ *
+ * VALIDATION BEFORE ACCOUNTING (D-15). A submission that is incomplete or contradicts
+ * itself comes back as a `refusal` with NOTHING booked and no route - the child fixes the
+ * submission and tries again. A refusal text starts with `NOT ACCEPTED:` and says what is
+ * wrong and how to fix it; it is plain text, never an error, because an error would trip
+ * the model's retry loop. The tool layer decides how many refusals a child gets.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { claimsFromReview, claimsFromTest, findingsIntersect, fingerprintFinding, } from './claims.js';
+import { eventDef } from './events-table.js';
+import { hasBooked } from './ledger.js';
+import { detectOwnershipViolations, detectRubberStamp, detectScopeNarrowing, } from './suspicion.js';
+const NOT_ACCEPTED = 'NOT ACCEPTED: ';
+function emptyResult(route) {
+    return {
+        ok: true,
+        refusal: null,
+        events: [],
+        route,
+        claims: [],
+        reversals: [],
+        newRejections: [],
+        rejection: null,
+        notes: [],
+    };
+}
+function engineEvent(ctx, code, agentId, detail) {
+    return {
+        code,
+        agentId,
+        at: ctx.at,
+        phase: ctx.phase,
+        by: 'engine',
+        reason: `${eventDef(code).title}: ${detail}`,
+        wpId: ctx.wp.id,
+    };
+}
+function isBlocking(finding) {
+    return finding.severity === 'blocker' || finding.severity === 'major' || finding.mustFix === true;
+}
+/** The findings that make a rework mandatory: blocker, major or flagged `mustFix`. */
+export function blockingFindings(findings) {
+    return findings.filter(isBlocking);
+}
+/** The only feedback surface a DEV sees (D-7): one row per blocking finding. */
+export function deriveRequiredChanges(findings) {
+    return blockingFindings(findings).map((f) => ({
+        file: f.file,
+        issue: f.issue,
+        change: f.requiredChange,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Work submission (D17)
+// ---------------------------------------------------------------------------
+/**
+ * A DEV submission: route to review, flag D17 (scope narrowing) on the mechanical
+ * signature, and report files touched outside the WP's ownership (evidence only).
+ * D17 is appealable once; the booking carries that in its reason.
+ */
+export function settleWork(ctx, submission) {
+    const result = emptyResult({ to: 'review' });
+    const narrowing = detectScopeNarrowing({
+        wpId: ctx.wp.id,
+        contracts: ctx.contracts,
+        interfaceContracts: submission.interfaceContracts,
+    });
+    if (narrowing.flagged) {
+        const detail = `${narrowing.reason} (mechanical signature; appealable once)`;
+        result.events.push(engineEvent(ctx, 'D17', submission.identity, detail));
+    }
+    const stray = detectOwnershipViolations(submission.filesChanged, ctx.wp.files);
+    if (stray.length > 0) {
+        result.notes.push(`Ownership: ${stray.length} file(s) outside the WP: ${stray.join(', ')}.`);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Review (5.5 table 1)
+// ---------------------------------------------------------------------------
+function validateReview(ctx, sub) {
+    if (ctx.wp.assignee === null) {
+        return refuse('the work package has no developer yet.', 'Dispatch the dev stage first.');
+    }
+    const blocking = blockingFindings(sub.findings);
+    if (sub.verdict === 'PASS' && (blocking.length > 0 || sub.fixesApplied.length > 0)) {
+        return refuse('verdict PASS contradicts blocking findings or fixesApplied.', 'Use NEEDS_REWORK for blocking findings or PASS_WITH_FIXES when you fixed files.');
+    }
+    if (sub.verdict === 'PASS_WITH_FIXES') {
+        const bare = sub.fixesApplied.length === 0 || sub.fixesApplied.some((f) => !f.rationale.trim());
+        if (bare) {
+            return refuse('PASS_WITH_FIXES needs fixesApplied, each with a rationale.', 'List every file you changed with the reason, or use PASS.');
+        }
+    }
+    if (sub.verdict === 'NEEDS_REWORK' && blocking.length === 0) {
+        return refuse('NEEDS_REWORK needs at least one blocker, major or mustFix finding.', 'Add a finding with file, issue and requiredChange, or change the verdict.');
+    }
+    return unansweredAppeal(ctx, sub);
+}
+function refuse(problem, fix) {
+    return `${NOT_ACCEPTED}${problem} ${fix}`;
+}
+function unansweredAppeal(ctx, sub) {
+    const answered = new Set(sub.appealResponses.map((r) => r.findingId));
+    const missing = (ctx.appealFindingIds ?? []).filter((id) => !answered.has(id));
+    if (missing.length === 0)
+        return null;
+    return refuse(`the developer appealed finding(s) ${missing.join(', ')} and you did not answer.`, 'Add an appealResponses entry (uphold or withdraw) for each.');
+}
+function appealEffects(ctx, sub, out) {
+    const withdrawn = sub.appealResponses.filter((r) => r.decision === 'withdraw');
+    if (withdrawn.length === 0)
+        return;
+    const ids = withdrawn.map((r) => r.findingId).join(', ');
+    out.events.push(engineEvent(ctx, 'R5', sub.identity, `withdrew finding(s) ${ids} on appeal`));
+    if (ctx.wp.assignee !== null) {
+        out.reversals.push({
+            agentId: ctx.wp.assignee,
+            code: 'D5',
+            wpId: ctx.wp.id,
+            reason: `finding(s) ${ids} withdrawn on appeal`,
+        });
+    }
+    out.notes.push(`Appeal succeeded for ${ids}: R5 booked and the earlier D5 struck.`);
+}
+function reworkOutcome(ctx, sub, out) {
+    const developer = ctx.wp.assignee;
+    const required = sub.requiredChanges.length > 0 ? sub.requiredChanges : deriveRequiredChanges(sub.findings);
+    const fingerprints = [
+        ...new Set(blockingFindings(sub.findings).map((f) => fingerprintFinding(f))),
+    ];
+    out.events.push(engineEvent(ctx, 'D5', developer, `review ${sub.verdict} on ${ctx.wp.id}`));
+    if (findingsIntersect(fingerprints, ctx.wp.rejections)) {
+        out.events.push(engineEvent(ctx, 'D8', developer, 'a finding repeats an earlier rejection'));
+    }
+    out.newRejections = fingerprints.filter((fp) => !ctx.wp.rejections.includes(fp));
+    out.route = { to: 'dev', requiredChanges: required };
+    out.rejection = {
+        id: sub.id,
+        wpId: ctx.wp.id,
+        reviewer: sub.identity,
+        hasBlockerOrMajor: sub.findings.some((f) => f.severity === 'blocker' || f.severity === 'major'),
+        withdrawn: false,
+    };
+}
+/**
+ * A REVIEW submission. PASS -> D1 (+15 P) -> test; PASS_WITH_FIXES -> D2 (+5 P) -> test;
+ * NEEDS_REWORK -> D5 (-20) -> dev, plus D8 (-30) when a blocking finding repeats an
+ * earlier rejection. A withdrawn appeal finding books R5 on the reviewer and strikes the
+ * earlier D5 (one R5 per submission, not per finding, so withdrawing is not a punishment
+ * multiplier). R12 is checked on every verdict.
+ */
+export function settleReview(ctx, sub) {
+    const problem = validateReview(ctx, sub);
+    if (problem !== null)
+        return { ...emptyResult(null), ok: false, refusal: problem };
+    const out = emptyResult({ to: 'test' });
+    const developer = ctx.wp.assignee;
+    appealEffects(ctx, sub, out);
+    if (sub.verdict === 'PASS') {
+        out.events.push(engineEvent(ctx, 'D1', developer, 'review PASS with no changes'));
+    }
+    else if (sub.verdict === 'PASS_WITH_FIXES') {
+        out.events.push(engineEvent(ctx, 'D2', developer, 'review PASS_WITH_FIXES'));
+    }
+    else {
+        reworkOutcome(ctx, sub, out);
+    }
+    const stamp = detectRubberStamp({
+        assessment: sub.integrationAssessment,
+        contracts: ctx.contracts,
+        wpId: ctx.wp.id,
+    });
+    if (stamp.flagged) {
+        const detail = `${stamp.reason} (mechanical signature; appealable)`;
+        out.events.push(engineEvent(ctx, 'R12', sub.identity, detail));
+    }
+    out.claims = claimsFromReview({ wpId: ctx.wp.id, phase: ctx.phase, developer: ctx.wp.assignee, reviewer: sub.identity }, sub);
+    if (sub.excellence !== undefined) {
+        out.notes.push('Excellence nominated (D10/R8): the inspector confirms at settle.');
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Test (5.5 table 2)
+// ---------------------------------------------------------------------------
+const PLACEHOLDER_REQUIREMENT = /^(n\/?a|none|tbd|todo|unknown|missing|gap|requirement|[-. ]*)$/i;
+const MIN_REQUIREMENT_CHARS = 8;
+const MIN_SKELETON_EVIDENCE_CHARS = 10;
+/** True when a traceability row names a real requirement (not a placeholder). */
+export function isConcreteRequirement(text) {
+    const trimmed = text.trim();
+    return trimmed.length >= MIN_REQUIREMENT_CHARS && !PLACEHOLDER_REQUIREMENT.test(trimmed);
+}
+function gapRows(sub) {
+    return sub.traceability.filter((row) => row.status === 'gap');
+}
+function validateSkeleton(sub) {
+    const ratio = sub.skeletonRatio;
+    if (ratio === undefined)
+        return null;
+    if (!(ratio >= 0 && ratio <= 1)) {
+        return refuse('skeletonRatio must be between 0 and 1.', 'Report the fraction of stub bodies.');
+    }
+    const evidence = (sub.skeletonEvidence ?? '').trim();
+    if (ratio > GOV_LIMITS.skeletonRatioThreshold && evidence.length < MIN_SKELETON_EVIDENCE_CHARS) {
+        return refuse(`skeletonRatio ${ratio} is above ${GOV_LIMITS.skeletonRatioThreshold} but has no evidence.`, 'Add skeletonEvidence with the stub count (use gov_scan), or lower the ratio.');
+    }
+    return null;
+}
+function validateTest(ctx, sub) {
+    if (ctx.wp.assignee === null) {
+        return refuse('the work package has no developer yet.', 'Dispatch the dev stage first.');
+    }
+    const gaps = gapRows(sub);
+    if (sub.verdict === 'SPEC_MISMATCH' && !gaps.some((g) => isConcreteRequirement(g.requirement))) {
+        return refuse('SPEC_MISMATCH needs a traceability row with status gap and a concrete requirement.', 'Quote the missing requirement text, or use ISSUES_FOUND.');
+    }
+    if (sub.verdict === 'ALL_PASS' && gaps.length > 0) {
+        return refuse('ALL_PASS contradicts traceability rows with status gap.', 'Use SPEC_MISMATCH for missing requirements.');
+    }
+    if (sub.verdict === 'ISSUES_FOUND' && sub.issues.length === 0) {
+        return refuse('ISSUES_FOUND lists no issues.', 'Describe each defect in issues[].');
+    }
+    return validateSkeleton(sub);
+}
+function testRoute(sub) {
+    if (sub.verdict === 'ALL_PASS')
+        return { to: 'passed' };
+    const fromGaps = gapRows(sub).map((g) => ({
+        file: '(spec)',
+        issue: g.requirement,
+        change: `Implement: ${g.requirement}`,
+    }));
+    const fromIssues = sub.issues.map((i) => ({
+        file: '(unspecified)',
+        issue: i.description,
+        change: 'Fix the defect and add a regression test.',
+    }));
+    const chosen = sub.verdict === 'SPEC_MISMATCH' ? fromGaps : fromIssues;
+    const fallback = [
+        { file: '(unspecified)', issue: sub.verdict, change: 'Replace stubs with real code.' },
+    ];
+    return { to: 'dev', requiredChanges: chosen.length > 0 ? chosen : fallback };
+}
+function testVerdictEvents(ctx, sub, out) {
+    const developer = ctx.wp.assignee;
+    switch (sub.verdict) {
+        case 'ALL_PASS': {
+            out.events.push(engineEvent(ctx, 'D3', developer, 'all tests passed'));
+            const rows = sub.traceability;
+            if (rows.length > 0 && rows.every((r) => r.status === 'covered')) {
+                out.events.push(engineEvent(ctx, 'D4', developer, 'every requirement covered'));
+                out.events.push(engineEvent(ctx, 'T1', sub.identity, 'full requirement traceability'));
+            }
+            else {
+                out.notes.push('D4/T1 withheld: traceability is not 100 percent covered.');
+            }
+            return;
+        }
+        case 'SPEC_MISMATCH':
+            out.events.push(engineEvent(ctx, 'D7', developer, 'a requirement is missing'));
+            return;
+        case 'INCOMPLETE_IMPL': {
+            const skeleton = (sub.skeletonRatio ?? 0) > GOV_LIMITS.skeletonRatioThreshold;
+            const code = skeleton ? 'D11' : 'D9';
+            const detail = skeleton ? `skeleton ratio ${sub.skeletonRatio}` : 'incomplete implementation';
+            out.events.push(engineEvent(ctx, code, developer, detail));
+            return;
+        }
+        case 'ISSUES_FOUND':
+            out.notes.push('Defects go back to the developer; rework drives D5/D8, not the test.');
+            return;
+    }
+}
+/**
+ * A TEST submission. ALL_PASS -> D3, and when every traceability row is covered D4 + T1;
+ * SPEC_MISMATCH -> D7 (needs a real `gap` row); INCOMPLETE_IMPL -> D9, or D11 instead when
+ * the skeleton ratio is above 0.30 with evidence; ISSUES_FOUND books nothing itself. Any
+ * `unverified` row books T6 on the tester. Claims are opened, never booked here.
+ */
+export function settleTest(ctx, sub) {
+    const problem = validateTest(ctx, sub);
+    if (problem !== null)
+        return { ...emptyResult(null), ok: false, refusal: problem };
+    const out = emptyResult(testRoute(sub));
+    testVerdictEvents(ctx, sub, out);
+    if (sub.traceability.some((row) => row.status === 'unverified')) {
+        out.events.push(engineEvent(ctx, 'T6', sub.identity, 'a requirement is unverified'));
+    }
+    out.claims = claimsFromTest({ wpId: ctx.wp.id, phase: ctx.phase, developer: ctx.wp.assignee, reviewer: ctx.wp.reviewer }, sub);
+    if (sub.boundaryTestsWritten) {
+        out.notes.push('Boundary tests written: the inspector may award T8.');
+    }
+    return out;
+}
+const MISSED_KINDS = new Set(['missed_by_review', 'incomplete_impl']);
+function phaseEvent(input, code, who, wpId) {
+    const event = {
+        code,
+        agentId: who,
+        at: input.at,
+        phase: input.phase,
+        by: 'engine',
+        reason: `${eventDef(code).title} on ${wpId}`,
+        wpId,
+    };
+    return event;
+}
+function reviewBonus(input, out) {
+    for (const { wpId, reviewer } of input.reviewedWps) {
+        const missed = input.claims.filter((c) => c.wpId === wpId && c.phase === input.phase && MISSED_KINDS.has(c.kind));
+        if (missed.some((c) => c.status === 'open')) {
+            out.notes.push(`R1 for ${wpId} waits: a missed-defect claim is still open.`);
+            continue;
+        }
+        if (missed.some((c) => c.status === 'upheld'))
+            continue;
+        const key = `r1:${wpId}`;
+        if (hasBooked(input.state, reviewer, 'R1', key))
+            continue;
+        out.events.push({ ...phaseEvent(input, 'R1', reviewer, wpId), incidentId: key });
+    }
+}
+function validRejectionBonus(input, out) {
+    const testedOk = new Set(input.testedOkWpIds);
+    for (const r of input.rejections) {
+        if (r.withdrawn || !r.hasBlockerOrMajor || !testedOk.has(r.wpId))
+            continue;
+        const overturned = input.claims.some((c) => c.wpId === r.wpId &&
+            c.kind === 'false_positive' &&
+            c.status === 'upheld' &&
+            c.against === r.reviewer);
+        const key = `r2:${r.id}`;
+        if (overturned || hasBooked(input.state, r.reviewer, 'R2', key))
+            continue;
+        out.events.push({ ...phaseEvent(input, 'R2', r.reviewer, r.wpId), incidentId: key });
+    }
+}
+/**
+ * R1 and R2, which can only be decided once the phase's claims are ruled.
+ *
+ *  - R1 +10 (P): a WP passed review and no missed-defect / incomplete-impl claim against
+ *    that review was upheld. A still-open claim defers R1 (never pay before the ruling).
+ *  - R2 +10: a rejection with a blocker/major finding that was not withdrawn or overturned,
+ *    and whose WP later reached ALL_PASS - rework confirmed the problem was real. Paid
+ *    once per rejection (`r2:<review id>`), which is what stops a reviewer farming it.
+ */
+export function settlePhaseR1R2(input) {
+    const out = { events: [], notes: [] };
+    reviewBonus(input, out);
+    validRejectionBonus(input, out);
+    return out;
+}

package/dist/governance/rules/suspicion.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Mechanical suspicion signatures (governance-mode 5.9): scope narrowing (D17),
+ * rubber-stamp integration check (R12) and file-ownership violations.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY MECHANICAL. These are the cheap, objectively checkable shadows of two cheats the
+ * reference spec calls out: a developer who avoids shared interfaces to dodge integration
+ * blame, and a reviewer who waves integration through with a one-liner. A signature that
+ * a script can test books automatically and is appealable once; everything fuzzier is
+ * left to the inspector. The functions here only DECIDE - booking goes through the
+ * ledger like any other event.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ */
+import type { Contract, InterfaceContractCheck } from '../types.js';
+export interface Suspicion {
+    flagged: boolean;
+    /** Why it fired, or why it was exempt. English, ASCII. */
+    reason: string;
+}
+/** The only exemption phrase a reviewer may use when no contract touches the WP. */
+export declare const NO_CONTRACTS_MARKER = "NOT_APPLICABLE: no cross-module contracts";
+/** Contracts that bind `wpId` (as producer or consumer); voided contracts are ignored. */
+export declare function contractsInvolving(wpId: string, contracts: readonly Contract[]): Contract[];
+/**
+ * D17: the WP appears in `contracts`, yet the work submission's `interfaceContracts` is
+ * missing, empty, or entirely NOT_APPLICABLE.
+ */
+export declare function detectScopeNarrowing(input: {
+    wpId: string;
+    contracts: readonly Contract[];
+    interfaceContracts: readonly InterfaceContractCheck[] | undefined;
+}): Suspicion;
+/** Count sentences: segments split on terminal punctuation or newlines with real content. */
+export declare function countSentences(text: string): number;
+/** True when the text names a file path, a file name or a function signature. */
+export declare function hasConcreteReference(text: string): boolean;
+/**
+ * R12: a contract binds the reviewed WP, the integration assessment is shorter than two
+ * sentences, AND it cites no contract, path or signature. All three together - a short but
+ * specific assessment is fine, and a long vague one is the inspector's call, not a script's.
+ *
+ * A run (or WP) without contracts is exempt outright. The agreed marker phrase
+ * `NOT_APPLICABLE: no cross-module contracts` is how a reviewer says so honestly; the
+ * exemption does not DEPEND on the phrase because penalising a one-WP run's reviewer for
+ * phrasing would be a false positive of the mechanism itself.
+ */
+export declare function detectRubberStamp(input: {
+    assessment: string;
+    contracts: readonly Contract[];
+    /** The reviewed WP; absent => every live contract counts as relevant. */
+    wpId?: string;
+}): Suspicion;
+/**
+ * True when `file` is covered by one owned pattern: an exact path, a directory prefix
+ * (`src/a`, `src/a/`), or a glob. Prefix matching is on whole path segments so owning
+ * `src/a` never covers `src/ab/x.ts`.
+ */
+export declare function isOwnedPath(file: string, ownedPatterns: readonly string[]): boolean;
+/**
+ * Files the agent touched that its work package does not own. Returned in input order,
+ * de-duplicated. Evidence for the inspector, never an automatic deduction: the touched-file
+ * list is best-effort (it comes from the run's tool trace).
+ */
+export declare function detectOwnershipViolations(filesTouched: readonly string[], ownedPatterns: readonly string[]): string[];

package/dist/governance/rules/suspicion.js

@@ -0,0 +1,169 @@
+/**
+ * Mechanical suspicion signatures (governance-mode 5.9): scope narrowing (D17),
+ * rubber-stamp integration check (R12) and file-ownership violations.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY MECHANICAL. These are the cheap, objectively checkable shadows of two cheats the
+ * reference spec calls out: a developer who avoids shared interfaces to dodge integration
+ * blame, and a reviewer who waves integration through with a one-liner. A signature that
+ * a script can test books automatically and is appealable once; everything fuzzier is
+ * left to the inspector. The functions here only DECIDE - booking goes through the
+ * ledger like any other event.
+ *
+ * Pure: no I/O, no clock, no randomness.
+ */
+/** The only exemption phrase a reviewer may use when no contract touches the WP. */
+export const NO_CONTRACTS_MARKER = 'NOT_APPLICABLE: no cross-module contracts';
+/** Contracts that bind `wpId` (as producer or consumer); voided contracts are ignored. */
+export function contractsInvolving(wpId, contracts) {
+    return contracts.filter((c) => c.voided !== true && (c.producer === wpId || c.consumers.includes(wpId)));
+}
+/**
+ * D17: the WP appears in `contracts`, yet the work submission's `interfaceContracts` is
+ * missing, empty, or entirely NOT_APPLICABLE.
+ */
+export function detectScopeNarrowing(input) {
+    const bound = contractsInvolving(input.wpId, input.contracts);
+    if (bound.length === 0) {
+        return { flagged: false, reason: 'No contract involves this work package.' };
+    }
+    const checks = input.interfaceContracts ?? [];
+    if (checks.length === 0) {
+        return {
+            flagged: true,
+            reason: `Bound by ${bound.length} contract(s) but declares no interface checks.`,
+        };
+    }
+    if (checks.every((c) => c.verified === 'NOT_APPLICABLE')) {
+        return {
+            flagged: true,
+            reason: 'Every interface check is NOT_APPLICABLE although contracts bind this work package.',
+        };
+    }
+    return { flagged: false, reason: 'Interface contracts were declared and verified.' };
+}
+// ---------------------------------------------------------------------------
+// R12
+// ---------------------------------------------------------------------------
+const PATH_PATTERN = /(?:^|[\s`'"(])(?:[\w.-]+\/)+[\w.-]+/;
+const FILE_EXTENSIONS = 'tsx?|jsx?|mjs|cjs|py|go|rs|java|kt|rb|php|cs|cpp|json|ya?ml|toml|md|sql';
+const FILENAME_PATTERN = new RegExp(`\\b[\\w-]+\\.(?:${FILE_EXTENSIONS})\\b`);
+const SIGNATURE_PATTERN = /[A-Za-z_$][\w$.]*\([^()\n]*\)/;
+/** Count sentences: segments split on terminal punctuation or newlines with real content. */
+export function countSentences(text) {
+    return text
+        .split(/(?<=[.!?])\s+|\n+/)
+        .filter((segment) => (segment.match(/[A-Za-z0-9]/g) ?? []).length >= 3).length;
+}
+function mentionsContract(text, contracts) {
+    const lower = text.toLowerCase();
+    return contracts.some((c) => {
+        const name = c.name.trim().toLowerCase();
+        const id = c.id.trim().toLowerCase();
+        return (name.length >= 3 && lower.includes(name)) || (id.length >= 2 && lower.includes(id));
+    });
+}
+/** True when the text names a file path, a file name or a function signature. */
+export function hasConcreteReference(text) {
+    return PATH_PATTERN.test(text) || FILENAME_PATTERN.test(text) || SIGNATURE_PATTERN.test(text);
+}
+/**
+ * R12: a contract binds the reviewed WP, the integration assessment is shorter than two
+ * sentences, AND it cites no contract, path or signature. All three together - a short but
+ * specific assessment is fine, and a long vague one is the inspector's call, not a script's.
+ *
+ * A run (or WP) without contracts is exempt outright. The agreed marker phrase
+ * `NOT_APPLICABLE: no cross-module contracts` is how a reviewer says so honestly; the
+ * exemption does not DEPEND on the phrase because penalising a one-WP run's reviewer for
+ * phrasing would be a false positive of the mechanism itself.
+ */
+export function detectRubberStamp(input) {
+    const live = input.contracts.filter((c) => c.voided !== true);
+    const relevant = input.wpId === undefined ? live : contractsInvolving(input.wpId, input.contracts);
+    if (relevant.length === 0) {
+        const marked = input.assessment.trim().startsWith(NO_CONTRACTS_MARKER);
+        return {
+            flagged: false,
+            reason: marked
+                ? 'Exempt: no cross-module contracts (declared).'
+                : 'Exempt: no contract binds this work package.',
+        };
+    }
+    const text = input.assessment;
+    const sentences = countSentences(text);
+    if (sentences >= 2) {
+        return { flagged: false, reason: `Assessment has ${sentences} sentences.` };
+    }
+    if (mentionsContract(text, live) || hasConcreteReference(text)) {
+        return { flagged: false, reason: 'Assessment cites a contract, file or signature.' };
+    }
+    return {
+        flagged: true,
+        reason: `Assessment has ${sentences} sentence(s) and cites no contract, file or signature.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Ownership
+// ---------------------------------------------------------------------------
+function normalizePath(path) {
+    return path.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/');
+}
+const GLOB_CHARS = /[*?[]/;
+/** Translate a glob (`**`, `*`, `?`) into an anchored RegExp. `**\/` may match nothing. */
+function globToRegExp(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*' && glob[i + 1] === '*') {
+            const slash = glob[i + 2] === '/';
+            out += slash ? '(?:.*/)?' : '.*';
+            i += slash ? 2 : 1;
+        }
+        else if (ch === '*') {
+            out += '[^/]*';
+        }
+        else if (ch === '?') {
+            out += '[^/]';
+        }
+        else {
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/**
+ * True when `file` is covered by one owned pattern: an exact path, a directory prefix
+ * (`src/a`, `src/a/`), or a glob. Prefix matching is on whole path segments so owning
+ * `src/a` never covers `src/ab/x.ts`.
+ */
+export function isOwnedPath(file, ownedPatterns) {
+    const target = normalizePath(file);
+    return ownedPatterns.some((raw) => {
+        const pattern = normalizePath(raw);
+        if (pattern === target)
+            return true;
+        if (GLOB_CHARS.test(pattern))
+            return globToRegExp(pattern).test(target);
+        const dir = pattern.endsWith('/') ? pattern : `${pattern}/`;
+        return target.startsWith(dir);
+    });
+}
+/**
+ * Files the agent touched that its work package does not own. Returned in input order,
+ * de-duplicated. Evidence for the inspector, never an automatic deduction: the touched-file
+ * list is best-effort (it comes from the run's tool trace).
+ */
+export function detectOwnershipViolations(filesTouched, ownedPatterns) {
+    const seen = new Set();
+    const violations = [];
+    for (const file of filesTouched) {
+        const key = normalizePath(file);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (!isOwnedPath(file, ownedPatterns))
+            violations.push(file);
+    }
+    return violations;
+}

package/dist/governance/store/artifacts.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Artifact storage: validated submissions and reports under
+ * `<run>/artifacts/<phase>/<wpId>/<stage>-<identity>-<n>.json|.md` (governance-mode
+ * sections 8.3 and 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * IDS ARE STABLE STRINGS: `p1/dev1/review-rev1-1` = phase 1 (1-based, `p` prefix), work
+ * package `dev1`, stage `review`, written by identity `rev1`, its 1st artifact. The id is
+ * also the relative path (minus extension), so `gov_read` can resolve an id without an
+ * index and a human can find the file by eye.
+ *
+ * EVERY ARTIFACT CARRIES A VISIBILITY TAG (`work | review | test | inspector`), derived
+ * from the stage and never from content. `engine/visibility.ts` filters on it; keeping the
+ * tag in the id's stage segment means the information boundary cannot be defeated by an
+ * artifact whose body claims to be something else.
+ *
+ * Phase-level artifacts (settle / integrate reports) have no work package; they use the
+ * reserved wp segment `_phase`.
+ */
+import type { StageKind } from '../types.js';
+import type { RunStore } from './run-store.js';
+export type ArtifactKind = 'work' | 'review' | 'test' | 'inspector';
+export declare const PHASE_WP_SEGMENT = "_phase";
+export interface ArtifactRef {
+    id: string;
+    /** 1-based phase number, as shown in the id. */
+    phase: number;
+    /** Work package id, or `_phase` for phase-level reports. */
+    wpId: string;
+    stage: StageKind;
+    identity: string;
+    /** 1-based per (phase, wp, stage, identity). */
+    n: number;
+    kind: ArtifactKind;
+}
+export type ArtifactRefInput = Omit<ArtifactRef, 'id' | 'kind'>;
+/** The visibility tag of an artifact is a pure function of the stage that produced it. */
+export declare function artifactKindForStage(stage: StageKind): ArtifactKind;
+export declare function buildArtifactId(ref: ArtifactRefInput): string;
+/** Inverse of `buildArtifactId`. Returns null for anything that is not a well-formed id. */
+export declare function parseArtifactId(id: string): ArtifactRef | null;
+/** Cut `text` to at most `maxBytes` UTF-8 bytes without leaving a broken character. */
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+/**
+ * Serialize a machine-form submission within `submissionBytes`. JSON cannot be cut
+ * mid-text, so an oversized body is replaced by a small valid envelope carrying a head
+ * excerpt and the original size; the marker keeps the cut visible to every reader.
+ */
+export declare function boundedJson(value: unknown, maxBytes?: 64000): string;
+export interface WriteArtifactInput extends Omit<ArtifactRefInput, 'n'> {
+    /** The validated machine form. */
+    json: unknown;
+    /** Human-readable rendering of the same submission, if any. */
+    markdown?: string;
+}
+export type WriteArtifactResult = {
+    ok: true;
+    ref: ArtifactRef;
+    bytes: number;
+} | {
+    ok: false;
+    exhausted: boolean;
+    message: string;
+};
+export interface ReadArtifactResult {
+    ref: ArtifactRef;
+    json: unknown;
+    markdown: string | null;
+}
+/** Thin domain layer over `RunStore`'s budgeted file primitives. */
+export declare class ArtifactStore {
+    private readonly store;
+    constructor(store: RunStore);
+    /** Write `.json` (and `.md`) as artifact number n+1 for this (phase, wp, stage, who). */
+    write(runId: string, input: WriteArtifactInput): Promise<WriteArtifactResult>;
+    /** Every artifact in the run, ordered by phase, wp, stage, identity, n. */
+    list(runId: string): Promise<ArtifactRef[]>;
+    /** Resolve an id (never a path) to its content, or null if absent / malformed. */
+    read(runId: string, id: string): Promise<ReadArtifactResult | null>;
+}