nexarch 0.13.5 → 0.13.8

package/dist/commands/init-agent.js

@@ -344,7 +344,8 @@ export function canonicalTargetKey(filePath) {
  * consent from the dry-run result before calling again with `dryRun: false`
  * to actually write — see the ADR-0112 note at the call site.
  */
-function injectAgentConfigs(registry, runtimeCodes, dryRun) {
+/** Exported for regression coverage of the empty-return bug documented at its tail. */
+export function injectAgentConfigs(registry, runtimeCodes, dryRun) {
     const templateByCode = new Map(registry.instructionTemplates.map((t) => [t.code, t]));
     const sortedTargets = [...registry.instructionTargets]
         .filter((target) => target.matchMode === "exact")
@@ -437,7 +438,17 @@ function injectAgentConfigs(registry, runtimeCodes, dryRun) {
         if (perRuntimeResults.length > 0)
             return [...existingResults, ...perRuntimeResults.filter((result, index, arr) => arr.findIndex((item) => canonicalTargetKey(item.path) === canonicalTargetKey(result.path)) === index)];
     }
-    return [];
+    // Not `[]`. When every runtime's target was already collected into
+    // `existingMatches` — which is the steady state once a repo has been set up
+    // once — the per-runtime loop `continue`s on all of them and
+    // `perRuntimeResults` comes back empty. Returning [] here threw away the
+    // results already computed above, the caller read that as "no instruction
+    // files" and fell back to injectGenericAgentConfig, and from then on only
+    // the generic target (AGENTS.md) was ever seen. Paul's CLAUDE.md and
+    // .cursorrules were invisible to staleness checking and attestation refresh
+    // from the second setup run onward, which is how they kept an expired
+    // `instruction_injection` block while the handshake reported all green.
+    return existingResults;
 }
 function trustAttestationStaleness(path) {
     if (!existsSync(path))
@@ -507,6 +518,75 @@ 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)";
 }
+/**
+ * Every instruction file the registry recognises that actually exists in this
+ * repo, deduplicated the way the rest of this module keys paths.
+ *
+ * This is the denominator for the coverage guard below. It is deliberately
+ * computed straight from the registry and the filesystem rather than from
+ * whatever the injection path happened to return, because the bug it guards
+ * against was the injection path silently returning fewer files than exist.
+ */
+export function existingInstructionFilePaths(registry) {
+    const seen = new Set();
+    const paths = [];
+    for (const target of registry.instructionTargets) {
+        if (target.matchMode !== "exact")
+            continue;
+        const filePath = join(process.cwd(), target.filePathPattern);
+        const key = canonicalTargetKey(filePath);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (existsSync(filePath))
+            paths.push(filePath);
+    }
+    return paths;
+}
+/**
+ * Instruction files that exist on disk but were never evaluated for staleness.
+ *
+ * "already current (no refresh needed)" is only honest about files somebody
+ * looked at. When the injection path under-reports its targets, the attestation
+ * check evaluates a subset and reports green for the whole repo — which is
+ * exactly how two of Paul's three files kept an expired, wrongly-scoped block
+ * through a clean setup run. A non-empty result here fails the check rather
+ * than letting it speak for files it never opened.
+ */
+export function unevaluatedInstructionFiles(onDisk, evaluated) {
+    const evaluatedKeys = new Set(evaluated.map((result) => canonicalTargetKey(result.path)));
+    return onDisk.filter((path) => !evaluatedKeys.has(canonicalTargetKey(path)));
+}
+/**
+ * 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 +1372,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 +1466,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 +1480,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,32 +1531,40 @@ export async function initAgent(args) {
                 : identityCapture.detail,
     });
     const instructionsAlreadyConfigured = agentConfigResults.length > 0 && agentConfigResults.every((r) => r.status === "already_present");
+    const uncoveredInstructionFiles = registration.ok
+        ? unevaluatedInstructionFiles(existingInstructionFilePaths(registry), agentConfigResults)
+        : [];
+    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
+            && uncoveredInstructionFiles.length === 0
+            && attestationSummary.ok
             && ((staleAttestationTargetCount === 0 && !trustAttestationAttempted) || Boolean(trustAttestation?.ok))),
         detail: !registration.ok
             ? "skipped (registration failed)"
-            : unsafeReattestationTargetCount > 0
-                ? "managed section does not match the published template; re-run with --allow-instruction-write"
-                : staleAttestationTargetCount > 0 && !attestationWriteAllowed
-                    ? `${mismatchedAttestationTargetCount > 0 ? "mismatched" : "stale"}; re-run with --reattest`
-                    : instructionsAlreadyConfigured && !attestationWriteAllowed
-                        ? "skipped (already configured)"
-                        : !attestationWriteAllowed
-                            ? "skipped (consent not granted)"
-                            : !trustAttestationAttempted
-                                ? 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"})`,
+            : uncoveredInstructionFiles.length > 0
+                ? `${uncoveredInstructionFiles.length} instruction file(s) on disk were never evaluated (${uncoveredInstructionFiles.map((path) => basename(path)).join(", ")}); their attestations are unverified`
+                : unsafeReattestationTargetCount > 0
+                    ? "managed section does not match the published template; re-run with --allow-instruction-write"
+                    : staleAttestationTargetCount > 0 && !attestationWriteAllowed
+                        ? `${mismatchedAttestationTargetCount > 0 ? "mismatched" : "stale"}; re-run with --reattest`
+                        : instructionsAlreadyConfigured && !attestationWriteAllowed
+                            ? "skipped (already configured)"
+                            : !attestationWriteAllowed
+                                ? "skipped (consent not granted)"
+                                : !trustAttestationAttempted
+                                    ? agentConfigResults.length > 0
+                                        ? "already current (no refresh needed)"
+                                        : "skipped (no instruction target written)"
+                                    : attestationSummary.detail,
     });
     checks.push({
         name: "technology.components",
@@ -1537,6 +1648,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

@@ -37,19 +37,24 @@ export async function policyAuditTemplate(args) {
     const defaultResult = (parseOptionValue(args, "--default-result") ?? "fail").toLowerCase();
     const selectedControlIds = new Set(parseMultiOptionValues(args, "--control-id"));
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
-        console.log(`
-Usage:
-  nexarch policy-audit-template --entity <application:key> [options]
-
-Options:
-  --entity <key>                 Required (e.g. application:bad-driving)
-  --control-id <uuid>            Optional repeatable filter (selected controls only)
-  --default-result <value>       pass|partial|fail (default: fail)
-  --output, --out <path.json>    Write findings array to file
-  --json                         Print JSON to stdout
-
-Output shape is ready for:
-  nexarch policy-audit-submit --findings-file <path.json>
+        console.log(`
+Usage:
+  nexarch policy-audit-template --entity <application:key> [options]
+
+Options:
+  --entity <key>                 Required (e.g. application:bad-driving)
+  --control-id <uuid>            Optional repeatable filter (selected controls only)
+  --default-result <value>       pass|partial|fail (default: fail)
+  --output, --out <path.json>    Write findings array to file
+  --json                         Print JSON to stdout
+
+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,39 +1,39 @@
-{
-  "name": "nexarch",
-  "version": "0.13.5",
-  "description": "Your architecture workspace for AI delivery.",
-  "keywords": [
-    "nexarch",
-    "mcp",
-    "architecture",
-    "ai"
-  ],
-  "license": "MIT",
-  "author": "Nexarch <hello@nexarch.ai>",
-  "homepage": "https://nexarch.ai",
-  "engines": {
-    "node": ">=18"
-  },
-  "type": "module",
-  "bin": {
-    "nexarch": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "tsc",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts && tsx scripts/test-search-icons.ts && tsx scripts/test-paste-login.ts"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "tsx": "^4",
-    "typescript": "^5"
-  },
-  "dependencies": {
-    "yaml": "^2.9.0"
-  }
-}
+{
+  "name": "nexarch",
+  "version": "0.13.8",
+  "description": "Your architecture workspace for AI delivery.",
+  "keywords": [
+    "nexarch",
+    "mcp",
+    "architecture",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Nexarch <hello@nexarch.ai>",
+  "homepage": "https://nexarch.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "bin": {
+    "nexarch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts && tsx scripts/test-search-icons.ts && tsx scripts/test-paste-login.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}