nexarch 0.13.5 → 0.13.7

package/dist/commands/init-agent.js

@@ -507,6 +507,36 @@ export function instructionInjectionDetail(registrationOk, staleAttestationTarge
         return `updated ${agentConfigResults.length} instruction target file(s)`;
     return "no runtime instruction target matched this repository (non-fatal; create AGENTS.md/CLAUDE.md or configure a generic target)";
 }
+/**
+ * Summarises the per-target attestation writes into the check's ok/detail.
+ *
+ * This used to be `trustAttestation?.ok`, which was the *first* target's mint
+ * result, reported under plural wording ("instruction file(s)") as if it
+ * covered them all. On Paul's 20 September setup run that printed a green
+ * "minted and injected into instruction file(s)" while only AGENTS.md was
+ * refreshed: CLAUDE.md and .cursorrules kept an attestation that had expired
+ * 22 minutes earlier, under the pre-ADR-0112 `instruction_injection` scope.
+ * The two agents that then read CLAUDE.md cold reported it as an injection
+ * attempt, which is the correct reading of what was in front of them.
+ *
+ * Green here now requires every target to have been verified on disk after
+ * writing, and a failure names the files rather than hiding behind a count.
+ */
+export function summariseAttestationOutcomes(outcomes) {
+    if (outcomes.length === 0)
+        return { ok: true, detail: "" };
+    const failures = outcomes.filter((outcome) => !outcome.ok);
+    if (failures.length === 0) {
+        return { ok: true, detail: `minted and injected into ${outcomes.length} instruction file(s)` };
+    }
+    const named = failures
+        .map((failure) => `${basename(failure.path)} (${failure.reason ?? "unknown"})`)
+        .join(", ");
+    return {
+        ok: false,
+        detail: `${outcomes.length - failures.length}/${outcomes.length} instruction file(s) attested; failed: ${named}`,
+    };
+}
 export function buildTrustAttestationSection(instructionFile, attestation) {
     if (!attestation.token || !attestation.payload)
         return null;
@@ -1292,6 +1322,7 @@ export async function initAgent(args) {
     let unsafeReattestationTargetCount = 0;
     let trustAttestation = null;
     let trustAttestationAttempted = false;
+    const attestationOutcomes = [];
     if (registration.ok) {
         try {
             // Save identity so check-in can find the agent key
@@ -1385,7 +1416,9 @@ export async function initAgent(args) {
             // section can carry different text (different templateCode per
             // runtime), and the attestation has to bind to the exact bytes it
             // covers — see ADR-0112. `trustAttestation` keeps the first result for
-            // the JSON summary field; every target still gets its own token.
+            // the JSON summary field; every target still gets its own token, and
+            // every target's write is recorded and verified independently so one
+            // success can no longer stand in for the batch.
             for (const r of attestationTargets) {
                 let targetAttestation;
                 try {
@@ -1397,18 +1430,38 @@ export async function initAgent(args) {
                 }
                 if (!trustAttestation)
                     trustAttestation = targetAttestation;
-                try {
-                    if (targetAttestation.ok) {
-                        injectTrustAttestationBlock(r.path, targetAttestation);
+                if (!targetAttestation.ok) {
+                    const reason = targetAttestation.reason ?? "unknown";
+                    try {
+                        injectTrustAttestationUnavailableBlock(r.path, reason);
                     }
-                    else {
-                        injectTrustAttestationUnavailableBlock(r.path, targetAttestation.reason ?? "unknown");
+                    catch {
+                        // Best-effort notice only; the recorded outcome below is what the check reports.
                     }
+                    attestationOutcomes.push({ path: r.path, ok: false, reason: `mint failed (${reason})` });
+                    continue;
+                }
+                try {
+                    injectTrustAttestationBlock(r.path, targetAttestation);
                     injectInitProjectReportingContract(r.path);
                 }
-                catch {
-                    // non-fatal
+                catch (error) {
+                    // Previously swallowed as "non-fatal", which is how a failed write
+                    // reported as a minted-and-injected success.
+                    attestationOutcomes.push({
+                        path: r.path,
+                        ok: false,
+                        reason: `write failed (${error instanceof Error ? error.message : "unknown"})`,
+                    });
+                    continue;
                 }
+                // Returning without throwing is not proof the block landed: a replace
+                // that matched nothing writes the file unchanged. Re-read and confirm
+                // the file now carries a current, correctly-scoped attestation.
+                const staleness = trustAttestationStaleness(r.path);
+                attestationOutcomes.push(staleness
+                    ? { path: r.path, ok: false, reason: `write did not take (${staleness})` }
+                    : { path: r.path, ok: true });
             }
         }
     }
@@ -1428,14 +1481,18 @@ export async function initAgent(args) {
                 : identityCapture.detail,
     });
     const instructionsAlreadyConfigured = agentConfigResults.length > 0 && agentConfigResults.every((r) => r.status === "already_present");
+    const attestationSummary = summariseAttestationOutcomes(attestationOutcomes);
+    /** Renewed means every attested target verified on disk, not that one mint succeeded. */
+    const attestationRenewed = attestationOutcomes.length > 0 && attestationSummary.ok;
     checks.push({
         name: "agent.instructions.injection",
         ok: !registration.ok || unsafeReattestationTargetCount === 0 && (!instructionsWriteAllowed || agentConfigResults.length > 0),
-        detail: instructionInjectionDetail(registration.ok, staleAttestationTargetCount, mismatchedAttestationTargetCount, unsafeReattestationTargetCount, instructionsWriteAllowed, Boolean(trustAttestation?.ok), instructionsAlreadyConfigured, agentConfigResults),
+        detail: instructionInjectionDetail(registration.ok, staleAttestationTargetCount, mismatchedAttestationTargetCount, unsafeReattestationTargetCount, instructionsWriteAllowed, attestationRenewed, instructionsAlreadyConfigured, agentConfigResults),
     });
     checks.push({
         name: "agent.trust.attestation",
         ok: !registration.ok || (unsafeReattestationTargetCount === 0
+            && attestationSummary.ok
             && ((staleAttestationTargetCount === 0 && !trustAttestationAttempted) || Boolean(trustAttestation?.ok))),
         detail: !registration.ok
             ? "skipped (registration failed)"
@@ -1451,9 +1508,7 @@ export async function initAgent(args) {
                                 ? agentConfigResults.length > 0
                                     ? "already current (no refresh needed)"
                                     : "skipped (no instruction target written)"
-                                : trustAttestation?.ok
-                                    ? "minted and injected into instruction file(s)"
-                                    : `unavailable (${trustAttestation?.reason ?? "unknown"})`,
+                                : attestationSummary.detail,
     });
     checks.push({
         name: "technology.components",
@@ -1537,6 +1592,10 @@ export async function initAgent(args) {
                 }
                 : null,
             trustAttestation,
+            // Per-target truth. `trustAttestation` above is only the first target's
+            // mint result, kept for back-compat; this is what says whether each
+            // instruction file actually ends up carrying a current attestation.
+            trustAttestationTargets: attestationOutcomes,
             companyId: creds.companyId,
             registry: { version: registry.release.version, registryVersion: registry.registryVersion, publishedAt: registry.release.publishedAt },
             agentConfigs: agentConfigResults,

package/dist/commands/policy-audit-results.js

@@ -91,13 +91,20 @@ Options:
             console.log(`  State:     ${run.auditState} — required rules ${requiredPct} pass` +
                 (required ? ` (${required.pass ?? 0} of ${required.total ?? 0}, ${required.partial ?? 0} partial, ${required.fail ?? 0} fail)` : "") +
                 `; advisory findings: ${run.advisoryIssueCount ?? 0} (do not affect state)`);
+            if ((run.criticalIssueCount ?? 0) > 0 || (run.highIssueCount ?? 0) > 0) {
+                console.log(`  Severity:  ${run.criticalIssueCount ?? 0} critical, ${run.highIssueCount ?? 0} high open finding(s)`);
+            }
+            if ((run.unscoredSeverityCount ?? 0) > 0) {
+                console.log(`  Unrated:   ${run.unscoredSeverityCount} finding(s) have no severity assigned`);
+            }
         }
         for (const control of run.controls ?? []) {
             console.log(`\n  - ${control.controlName} (${control.controlId})`);
             for (const rule of control.rules ?? []) {
                 const qualifier = rule.requirementQualifier ? ` ${rule.requirementQualifier}` : "";
                 const level = rule.requirementLevel ? ` [${rule.requirementLevel}${qualifier}]` : "";
-                console.log(`    • [${rule.result}] ${rule.ruleName}${level} (${rule.ruleId})`);
+                const ranking = [rule.severity, rule.effort, rule.exploitability].filter(Boolean).join(", ");
+                console.log(`    • [${rule.result}] ${rule.ruleName}${level} (${rule.ruleId})${ranking ? ` {${ranking}}` : ""}`);
                 if (rule.rationale)
                     console.log(`        ${rule.rationale}`);
                 if (Array.isArray(rule.missingRequirements) && rule.missingRequirements.length > 0) {
@@ -105,6 +112,12 @@ Options:
                         console.log(`        - missing: ${String(m)}`);
                     }
                 }
+                if (Array.isArray(rule.fileRefs) && rule.fileRefs.length > 0) {
+                    for (const ref of rule.fileRefs) {
+                        const loc = ref.line !== undefined && ref.line !== null ? `${ref.path}:${ref.line}` : ref.path;
+                        console.log(`        - ${loc}${ref.note ? ` — ${ref.note}` : ""}`);
+                    }
+                }
             }
         }
     }

package/dist/commands/policy-audit-submit.js

@@ -44,21 +44,36 @@ function loadIdentityAgentKey() {
         return null;
     }
 }
+function isSeverity(value) {
+    return value === "low" || value === "medium" || value === "high" || value === "critical";
+}
+function isEffort(value) {
+    return value === "hours" || value === "days" || value === "weeks";
+}
+function isExploitability(value) {
+    return value === "theoretical" || value === "plausible" || value === "confirmed";
+}
 function parseFindingToken(token) {
-    const [policyControlId, policyRuleId, resultRaw, rationaleRaw, missingRaw] = token.split("|");
+    const [policyControlId, policyRuleId, resultRaw, rationaleRaw, missingRaw, severityRaw] = token.split("|");
     const result = (resultRaw ?? "").trim().toLowerCase();
     if (!policyControlId?.trim() || !policyRuleId?.trim() || !result) {
-        throw new Error("Each --finding must be: <policyControlId>|<policyRuleId>|<pass|partial|fail>|<rationale>|<missing1;missing2>");
+        throw new Error("Each --finding must be: <policyControlId>|<policyRuleId>|<pass|partial|fail>|<rationale>|<missing1;missing2>|<severity>");
     }
     if (result !== "pass" && result !== "partial" && result !== "fail") {
         throw new Error(`Invalid finding result '${resultRaw}'. Use pass|partial|fail.`);
     }
+    const severityInput = severityRaw?.trim().toLowerCase();
+    if (severityInput && !isSeverity(severityInput)) {
+        throw new Error(`Invalid severity '${severityRaw}'. Use low|medium|high|critical.`);
+    }
+    const severity = severityInput && isSeverity(severityInput) ? severityInput : undefined;
     return {
         policyControlId: policyControlId.trim(),
         policyRuleId: policyRuleId.trim(),
         result,
         ...(rationaleRaw?.trim() ? { rationale: rationaleRaw.trim() } : {}),
         ...(missingRaw?.trim() ? { missingRequirements: missingRaw.split(";").map((m) => m.trim()).filter(Boolean) } : {}),
+        ...(severity ? { severity } : {}),
     };
 }
 function parseFindings(args) {
@@ -100,12 +115,26 @@ function parseFindings(args) {
                 : Array.isArray(value.missing_requirements)
                     ? value.missing_requirements.map(String)
                     : undefined;
+            const severity = isSeverity(value.severity) ? value.severity : undefined;
+            const effort = isEffort(value.effort) ? value.effort : undefined;
+            const exploitability = isExploitability(value.exploitability) ? value.exploitability : undefined;
+            const confidence = typeof value.confidence === "number" ? value.confidence : undefined;
+            const fileRefs = Array.isArray(value.fileRefs)
+                ? value.fileRefs
+                : Array.isArray(value.file_refs)
+                    ? value.file_refs
+                    : undefined;
             return {
                 policyControlId,
                 policyRuleId,
                 result,
                 ...(rationale ? { rationale } : {}),
                 ...(missingRequirements ? { missingRequirements } : {}),
+                ...(severity ? { severity } : {}),
+                ...(effort ? { effort } : {}),
+                ...(exploitability ? { exploitability } : {}),
+                ...(confidence !== undefined ? { confidence } : {}),
+                ...(fileRefs ? { fileRefs } : {}),
             };
         });
     }
@@ -126,7 +155,7 @@ Options:
   --command-id <id>          Required command id
   --application-ref <key>    Required application reference key (e.g. application:bad-driving)
   --agent-key <key>          Optional agent key (defaults from identity)
-  --finding <controlId|ruleId|result|rationale|missing1;missing2>   Repeatable
+  --finding <controlId|ruleId|result|rationale|missing1;missing2|severity>   Repeatable
   --findings-json <json>     JSON array of findings
   --findings-file <path>     Path to JSON array of findings
   --json                     Print JSON response
@@ -135,6 +164,12 @@ Notes:
   - Findings are rule-level (policyRuleId is required).
   - You can submit partial findings multiple times for the same command.
   - Get valid rule ids with: nexarch policy-controls --entity <application:key> --json
+  - Rate severity (low|medium|high|critical), effort (hours|days|weeks) and
+    exploitability (theoretical|plausible|confirmed) per finding where you can —
+    these decide how findings get ranked. --finding's severity is its 6th field;
+    --findings-json/--findings-file also accept effort, exploitability,
+    confidence (0-1) and fileRefs ([{path, line, note}]) per finding.
+    Omit rather than guess.
 `);
         return;
     }
@@ -180,6 +215,12 @@ Notes:
             console.log(`Required rules: ${pct} pass, ${result.summary.requiredIssueCount} issue(s) — these decide the audit state`);
             console.log(`Advisory findings: ${result.summary.advisoryIssueCount ?? 0} (recommended/informational; recorded, not gating)`);
         }
+        if ((result.summary.criticalIssueCount ?? 0) > 0 || (result.summary.highIssueCount ?? 0) > 0) {
+            console.log(`Severity: ${result.summary.criticalIssueCount ?? 0} critical, ${result.summary.highIssueCount ?? 0} high (open findings rated by the submitting agent)`);
+        }
+        if ((result.summary.unscoredSeverityCount ?? 0) > 0) {
+            console.log(`Unrated for severity: ${result.summary.unscoredSeverityCount} finding(s) — consider adding severity so this run can be ranked`);
+        }
         if ((result.summary.remainingRules ?? 0) > 0) {
             console.log(`Remaining rules to submit: ${result.summary.remainingRules}`);
         }

package/dist/commands/policy-audit-template.js

@@ -50,6 +50,11 @@ Options:
 
 Output shape is ready for:
   nexarch policy-audit-submit --findings-file <path.json>
+
+Each entry includes empty severity/effort/exploitability/confidence/fileRefs
+placeholders. Fill them in for every partial/fail finding -- they decide how
+findings get ranked and reported. Leave a field blank/empty rather than
+guess; policy-audit-submit drops anything that isn't a valid value.
 `);
         return;
     }
@@ -76,6 +81,13 @@ Output shape is ready for:
         result: defaultResult,
         rationale: "",
         missingRequirements: [],
+        // Fill in for partial/fail findings -- see --help. Left blank rather
+        // than defaulted, so an unrated finding stays honestly unrated.
+        severity: "",
+        effort: "",
+        exploitability: "",
+        confidence: null,
+        fileRefs: [],
     })));
     if (findings.length === 0) {
         console.error("error: no rules found for selected controls/entity");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.13.5",
+  "version": "0.13.7",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",