nexarch 0.12.44 → 0.13.1

package/dist/commands/init-project.js

@@ -5,7 +5,7 @@ import { basename, join, relative, resolve as resolvePath } from "node:path";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
-import { detectInfrastructureProject } from "../lib/terraform-detect.js";
+import { detectInfrastructureProject } from "../lib/iac-detect.js";
 import { runInfrastructureOnboarding } from "./init-project-infra.js";
 import { detectDataProject } from "../lib/data-project-detect.js";
 import { runDataProjectOnboarding } from "./init-project-data.js";
@@ -1165,7 +1165,36 @@ function extractHost(input) {
         return null;
     }
 }
-export function scoreApplicationCandidate(app, projectName, repoUrl) {
+/**
+ * Item 6: agent-authored descriptions read like commit messages — framework
+ * names, folder layout, build tooling. The reader is an architect, a new joiner
+ * or someone deciding whether to reuse the thing, and none of them work on this
+ * code. Stated once here and referenced from every step that asks for a
+ * description, because a rule stated in one of five steps is not a rule the
+ * model reliably follows.
+ */
+export const DESCRIPTION_GUIDANCE = "Write descriptions for someone who does not work on this code — an architect, a new joiner, or"
+    + " someone deciding whether to reuse it. One or two sentences: what it does for the business, who"
+    + " uses it, and what it owns. Name a technology only when the technology is the point (a Postgres"
+    + " connection pooler), not as a substitute for purpose."
+    + ' Good: "Takes card payments for the online store and is the system of record for refunds."'
+    + ' Poor: "Next.js 16 app with Drizzle ORM and a REST API under /api."';
+/** The project's declared homepage, used to tell a repository scan and a website
+ * onboarding run that they are describing the same application. */
+export function readDeclaredHomepage(dir) {
+    try {
+        const pkgPath = join(dir, "package.json");
+        if (!existsSync(pkgPath))
+            return null;
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const homepage = typeof pkg.homepage === "string" ? pkg.homepage.trim() : "";
+        return homepage ? homepage : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function scoreApplicationCandidate(app, projectName, repoUrl, homepageUrl = null) {
     const entityRef = app.entityRef ?? app.externalKey ?? null;
     if (!entityRef)
         return null;
@@ -1186,17 +1215,86 @@ export function scoreApplicationCandidate(app, projectName, repoUrl) {
         score += 0.25;
         reasons.push("ref_matches_project");
     }
-    const repoHost = extractHost(repoUrl);
     const appWebsite = typeof app.attributes?.website_url === "string" ? app.attributes.website_url : null;
     const appWebsiteHost = extractHost(appWebsite);
-    if (repoHost && appWebsiteHost && repoHost === appWebsiteHost) {
+    // The project's declared homepage, not its repository URL. Comparing the repo
+    // host against a website host compares "gitlab.com" with "nexarch.ai" and can
+    // never match, which is why an application registered by website onboarding
+    // and the same application registered by a repository scan scored as
+    // unrelated and both ended up in the graph.
+    const homepageHost = extractHost(homepageUrl);
+    if (homepageHost && appWebsiteHost && homepageHost === appWebsiteHost) {
         score += 0.5;
         reasons.push("website_host_exact");
     }
+    // Kept as a weak signal: a self-hosted estate can legitimately register a
+    // repository host as an application's website.
+    const repoHost = extractHost(repoUrl);
+    if (repoHost && appWebsiteHost && repoHost === appWebsiteHost) {
+        score += 0.15;
+        reasons.push("repo_host_matches_website");
+    }
     if (score <= 0)
         return null;
     return { entityRef, name: app.name, score: Math.min(1, score), reasons };
 }
+/**
+ * For each detected name, the entity_refs of what declares it.
+ *
+ * Sent with name resolution so that a name not yet in the catalogue is recorded
+ * against the thing that depends on it. Without it, adding `elkjs` to the
+ * catalogue later added it to every workspace that had seen it -- attached to
+ * nothing, because the sighting only knew the repository, and on a first scan
+ * not even that.
+ *
+ * Only application-like packages are dependents: the re-resolve job writes the
+ * edge directly, and a shared library depending on a technology is not an edge
+ * the ontology draws. A monorepo's root manifest is repository tooling, not a
+ * deployable, so it has no dependent; a single-package repository's root is
+ * the application.
+ */
+export function dependentRefsForNames(params) {
+    const refs = new Map();
+    const declare = (name, ref) => {
+        if (!refs.has(name))
+            refs.set(name, new Set());
+        refs.get(name).add(ref);
+    };
+    for (const sp of params.subPackages) {
+        if (!isApplicationLikeEntityType(sp.entityType) || !sp.externalKey)
+            continue;
+        for (const dep of sp.depSpecs)
+            declare(dep.name, sp.externalKey);
+    }
+    if (params.rootDependentRef) {
+        for (const name of params.rootDepNames)
+            declare(name, params.rootDependentRef);
+    }
+    return Object.fromEntries([...refs].map(([name, set]) => [name, [...set].sort()]));
+}
+/**
+ * Existing applications that resemble a repository, for a monorepo.
+ *
+ * Scored on the repository, not on each deployable: per-deployable name
+ * scoring reports the wrong thing. A CLI whose npm name is the product name
+ * scores as a duplicate of the product's website, and short names like "web"
+ * match anything they happen to be a substring of.
+ *
+ * `ownRefs` are this repository's own deployables. They exist on a re-run and
+ * every one contains the repository name, so without excluding them a second
+ * scan reports the repository as a duplicate of itself.
+ */
+export function similarApplicationsForRepository(apps, params) {
+    return apps
+        .filter((app) => {
+        const ref = app.entityRef ?? app.externalKey;
+        return Boolean(ref) && !params.ownRefs.has(ref);
+    })
+        .map((app) => scoreApplicationCandidate(app, params.repositoryName, params.repoUrl, params.homepageUrl))
+        .filter((match) => Boolean(match))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 5);
+}
 // ─── Main command ─────────────────────────────────────────────────────────────
 export async function initProject(args) {
     const asJson = parseFlag(args, "--json");
@@ -1266,6 +1364,7 @@ export async function initProject(args) {
                     nonInteractive: parseFlag(args, "--non-interactive"),
                     skipIngest: parseFlag(args, "--no-ingest"),
                     dryRun,
+                    tool: parseOptionValue(args, "--tool"),
                 }, infrastructure);
             }
             return;
@@ -1284,6 +1383,7 @@ export async function initProject(args) {
                 nonInteractive: parseFlag(args, "--non-interactive"),
                 skipIngest: parseFlag(args, "--no-ingest"),
                 dryRun,
+                tool: parseOptionValue(args, "--tool"),
             }, infrastructure);
             return;
         }
@@ -1358,11 +1458,17 @@ export async function initProject(args) {
         console.log("\nResolving against reference library…");
     const allResolveResults = [];
     const BATCH_SIZE = 200;
+    const dependentRefsByName = dependentRefsForNames({
+        subPackages,
+        rootDepNames,
+        rootDependentRef: isMonorepo ? null : projectExternalKey,
+    });
     logProgress("resolve.start", `count=${detectedNames.length}, batchSize=${BATCH_SIZE}`);
     for (let i = 0; i < detectedNames.length; i += BATCH_SIZE) {
         const batch = detectedNames.slice(i, i + BATCH_SIZE);
         logProgress("resolve.batch", `${Math.floor(i / BATCH_SIZE) + 1}/${Math.ceil(detectedNames.length / BATCH_SIZE)} size=${batch.length}`);
-        const raw = await callMcpProfiled("nexarch_resolve_reference", { names: batch, companyId: creds.companyId }, { batchSize: batch.length });
+        const dependentRefs = Object.fromEntries(batch.filter((name) => dependentRefsByName[name]?.length).map((name) => [name, dependentRefsByName[name]]));
+        const raw = await callMcpProfiled("nexarch_resolve_reference", { names: batch, companyId: creds.companyId, projectRef: projectEntityKey, dependentRefs }, { batchSize: batch.length });
         const data = parseToolText(raw);
         allResolveResults.push(...data.results);
     }
@@ -1371,7 +1477,7 @@ export async function initProject(args) {
     const unresolvedItems = allResolveResults.filter((r) => !r.resolved);
     if (!asJson) {
         console.log(`  Resolved  : ${resolvedItems.length}/${detectedNames.length}`);
-        console.log(`  Candidates: ${unresolvedItems.length} unresolved (logged to reference candidates)`);
+        console.log(`  Candidates: ${unresolvedItems.length} detected dependencies not yet in the Nexarch catalogue`);
     }
     if (dryRun) {
         const output = {
@@ -1434,6 +1540,8 @@ export async function initProject(args) {
     const repoUrl = (repoUrlOverride ? normalizeRepoUrl(repoUrlOverride) ?? repoUrlOverride : null) ?? detectedRepo?.url ?? null;
     const sourceVcsType = detectedRepo?.vcsType ?? "unknown";
     const sourceProvider = detectedRepo?.provider ?? "unknown";
+    const declaredHomepage = readDeclaredHomepage(dir);
+    let similarApplications = [];
     if (projectConstruct && isMonorepo && (applicationRefOverride || forceCreateApplication) && !asJson) {
         console.log("\nNote: monorepo detected — no root application is created (ADR 8a); --application-ref/--create-application apply only to single-package repositories.");
     }
@@ -1470,9 +1578,14 @@ export async function initProject(args) {
             const apps = (appsData.entities ?? []).filter((e) => (e.entityRef ?? e.externalKey));
             if (apps.length > 0) {
                 const matches = apps
-                    .map((a) => scoreApplicationCandidate(a, displayName, repoUrl))
+                    .map((a) => scoreApplicationCandidate(a, displayName, repoUrl, declaredHomepage))
                     .filter((m) => Boolean(m))
                     .sort((a, b) => b.score - a.score);
+                // Captured for the JSON output. Until this existed the branch below was
+                // guarded by `!asJson`, so an agent -- which always runs --json -- got a
+                // result with no hint that a similar application already existed, and
+                // reported the new proposal as if nothing resembled it.
+                similarApplications = matches.slice(0, 5);
                 const suggested = matches.length > 0 ? matches[0] : null;
                 const highConfidence = suggested && suggested.score >= 0.85;
                 // ADR 8d: the interactive "Choose target application" prompt is gone.
@@ -1498,6 +1611,37 @@ export async function initProject(args) {
             }
         }
     }
+    // The branch above is gated on !isMonorepo, so for a monorepo -- including
+    // this repository -- the duplicate check never ran at all. Paul's 16
+    // September test registered web, mcp-gateway and nexarch-cli into a
+    // workspace that already held "nexarch.ai website" from onboarding, and
+    // nothing was flagged: item 17's homepage scoring simply never executed.
+    //
+    // Scored at REPOSITORY level, not per deployable. Name scoring per deployable
+    // is worse than silence here: the CLI's npm name is literally "nexarch", so it
+    // scores 0.5 against the website and would be reported as its duplicate, and
+    // "web" matches only because it is a substring of "website". The repository
+    // name is the honest signal, and which deployable (if any) is the same system
+    // is a judgement for a human -- the step below says so.
+    if (projectConstruct && isMonorepo && !forceCreateApplication) {
+        // This repository's own deployables exist on a re-run, and every one of
+        // them contains the repository name. Without excluding them, a second run
+        // reports the repo as a duplicate of itself.
+        const ownRefs = new Set(subPackages.map((sp) => sp.externalKey));
+        const appsRaw = await callMcpProfiled("nexarch_list_entities", { entityTypeCode: "application", status: "active", limit: 500, companyId: creds.companyId }, { entityTypeCode: "application", limit: 500, phase: "monorepo.similar" });
+        similarApplications = similarApplicationsForRepository(parseToolText(appsRaw).entities ?? [], {
+            repositoryName: displayName,
+            repoUrl,
+            homepageUrl: declaredHomepage,
+            ownRefs,
+        });
+        if (similarApplications.length > 0 && !asJson) {
+            console.log("\nExisting applications resemble this repository — one of its deployables may already be registered:");
+            for (const match of similarApplications) {
+                console.log(`  - ${match.name} (${match.entityRef}) score=${match.score.toFixed(2)} [${match.reasons.join(", ")}]`);
+            }
+        }
+    }
     logProgress(projectConstruct ? "project.target" : "application.target", projectConstruct ? (isMonorepo ? projectEntityKey : `${projectEntityKey} + ${projectExternalKey}`) : projectExternalKey);
     // In refresh mode, snapshot the current graph state for this project before writing,
     // so we can diff what changed and surface stale relationships to the agent.
@@ -1873,11 +2017,57 @@ export async function initProject(args) {
         // so agents using --json receive the same mandatory instructions as text-mode agents.
         const pendingSteps = [];
         let stepNum = 1;
+        // First, because it is the one step that can make the rest unnecessary: if
+        // this application already exists under another name, everything after this
+        // enriches a duplicate. The scan has always computed these matches; until
+        // now it printed them only in human mode, so the agent never saw them.
+        const matchList = similarApplications
+            .map((m) => `${m.name} (${m.entityRef}, score ${m.score.toFixed(2)}, ${m.reasons.join(", ")})`)
+            .join("; ");
+        if (similarApplications.length > 0 && isMonorepo) {
+            // --application-ref does not apply to a monorepo (the CLI says so above),
+            // so the single-repo remedy would hand the agent a command that does
+            // nothing. The resolution here is a merge, which a human does on the
+            // application page.
+            pendingSteps.push({
+                step: stepNum++,
+                action: "review_similar_applications",
+                instruction: `${similarApplications.length} existing application${similarApplications.length === 1 ? "" : "s"} in this`
+                    + ` workspace resemble${similarApplications.length === 1 ? "s" : ""} this repository: ${matchList}.`
+                    + " One of the deployables just registered may be the same system — for example a web app registered"
+                    + " earlier from its public website. Tell the human which deployable you think matches and why, before"
+                    + " enriching anything. The new deployables are PROPOSED, so nothing is broken yet; if one is a"
+                    + " duplicate, the human merges the two with \"Merge with…\" on the application's page.",
+                notes: [
+                    "Do not report the registration as complete without mentioning these.",
+                    "The match is on the repository, not a specific deployable: say which one you believe it is, and why.",
+                    "A human decides which is the same application — do not merge or decline on your own judgement.",
+                ],
+            });
+        }
+        else if (similarApplications.length > 0) {
+            pendingSteps.push({
+                step: stepNum++,
+                action: "review_similar_applications",
+                instruction: `${similarApplications.length} existing application${similarApplications.length === 1 ? "" : "s"} in this`
+                    + ` workspace resemble${similarApplications.length === 1 ? "s" : ""} the one just registered: ${matchList}.`
+                    + " Tell the human about these before enriching anything. This registration was created as a"
+                    + " PROPOSED application and is not in the canonical graph yet, so nothing is broken — but if one of"
+                    + " these is the same application, it should be mapped rather than duplicated.",
+                commandTemplates: {
+                    mapInstead: `nexarch init-project --dir . --application-ref "<entityRef from the list above>"`,
+                },
+                notes: [
+                    "Do not report the registration as complete without mentioning these.",
+                    "A human decides which is the same application — do not merge or decline on your own judgement.",
+                ],
+            });
+        }
         if (projectConstruct) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "describe_project",
-                instruction: `Give the project (repository) entity a meaningful display name (not the raw directory name "${projectDirName}") and a short description of what lives in this repo.`,
+                instruction: `Give the project (repository) entity a meaningful display name (not the raw directory name "${projectDirName}") and a short description of what lives in this repo. ${DESCRIPTION_GUIDANCE}`,
                 command: `nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "..." --description "..."`,
             });
         }
@@ -1897,8 +2087,8 @@ export async function initProject(args) {
                 step: stepNum++,
                 action: "classify_sub_packages",
                 instruction: projectConstruct
-                    ? `For each sub-package in classifyPackages, run update-entity to confirm type/subtype/name/description. The sourced_from relationship to the project is wired automatically — no structural add-relationship is needed. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo) and the old key's sourced_from should be retired.`
-                    : `For each sub-package in classifyPackages: (1) run update-entity to confirm type/subtype/name/description, then (2) immediately run add-relationship to wire the structural relationship. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo). Always run update-entity before add-relationship for each package.`,
+                    ? `For each sub-package in classifyPackages, run update-entity to confirm type/subtype/name/description. ${DESCRIPTION_GUIDANCE} The sourced_from relationship to the project is wired automatically — no structural add-relationship is needed. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo) and the old key's sourced_from should be retired.`
+                    : `${DESCRIPTION_GUIDANCE} For each sub-package in classifyPackages: (1) run update-entity to confirm type/subtype/name/description, then (2) immediately run add-relationship to wire the structural relationship. The external key includes the entity type as a prefix — if you change the entity type, the key changes (e.g. application_component:foo → application:foo). Always run update-entity before add-relationship for each package.`,
                 commandTemplates: projectConstruct
                     ? {
                         updateEntity: `nexarch update-entity --key "<subPackageExternalKey>" --entity-type "<entityType>" --subtype "<subtype>" --name "..." --description "..."`,
@@ -1923,7 +2113,10 @@ export async function initProject(args) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "discover_functions",
-                instruction: `Review the codebase to identify discrete application functions (what the application does). Examine named modules, route layout, service boundaries, and any architecture documentation. Register functions as application_function entities with subtype core_function (primary business function), supporting_function (auxiliary/enablement), integration_function (external connectivity), or data_function (data processing). Only register functions clearly evidenced by the codebase — do not invent them.`,
+                instruction: `Review the codebase to identify discrete application functions (what the application does). ` +
+                    `Examine named modules, route layout, service boundaries, and any architecture documentation. ` +
+                    `Register functions as application_function entities with subtype core_function (primary business function), supporting_function (auxiliary/enablement), integration_function (external connectivity), or data_function (data processing). ` +
+                    `Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE}`,
                 commandTemplates: {
                     updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`,
                     addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}_<function_slug>" --to ${projectConstruct && isMonorepo ? '"<owning application key from classifyPackages>"' : `"${projectExternalKey}"`} --type part_of`,
@@ -2127,7 +2320,7 @@ export async function initProject(args) {
         }
         if (unresolvedItems.length > 0) {
             lines.push("");
-            lines.push(`UNRESOLVED (${unresolvedItems.length} names not matched in reference library):`);
+            lines.push(`${unresolvedItems.length} detected dependencies are not yet in the Nexarch catalogue. They will be added to your graph automatically once they are:`);
             const sample = unresolvedItems.slice(0, 20).map((r) => r.input);
             lines.push(`  ${JSON.stringify(sample)}`);
             if (unresolvedItems.length > 20)
@@ -2168,7 +2361,7 @@ export async function initProject(args) {
             lines.push(`     Examine named modules, route layout, service boundaries, and any architecture documentation.`);
             lines.push(`     Use subtype core_function (primary business function), supporting_function (auxiliary/enablement),`);
             lines.push(`     integration_function (external connectivity), or data_function (data processing).`);
-            lines.push(`     Only register functions clearly evidenced by the codebase — do not invent them.`);
+            lines.push(`     Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE}`);
             lines.push(`     For each one found:`);
             const fnOwnerTarget = projectConstruct && isMonorepo ? '"<owning application key from CLASSIFY_THESE>"' : `"${projectExternalKey}"`;
             lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`);
@@ -2238,6 +2431,7 @@ export async function initProject(args) {
         },
         resolved: resolvedItems.length,
         unresolved: unresolvedItems.length,
+        similarApplications,
         entityErrors: entitiesResult.errors ?? [],
         relationshipErrors: relsResult?.errors ?? [],
         enrichmentRequired,

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

@@ -20,15 +20,15 @@ function parseToolText(result) {
 export async function policyAuditResults(args) {
     const asJson = parseFlag(args, "--json");
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
-        console.log(`
-Usage:
-  nexarch policy-audit-results --entity <applicationEntityRef> [--limit <1-10>] [--json]
-
-Options:
-  --entity <key>      Required application reference (e.g. application:my-service).
-                      Aliases: --entity-ref, --application-ref, --application-key
-  --limit <n>         Number of most recent runs to return (default 1, max 10)
-  --json              Print JSON response
+        console.log(`
+Usage:
+  nexarch policy-audit-results --entity <applicationEntityRef> [--limit <1-10>] [--json]
+
+Options:
+  --entity <key>      Required application reference (e.g. application:my-service).
+                      Aliases: --entity-ref, --application-ref, --application-key
+  --limit <n>         Number of most recent runs to return (default 1, max 10)
+  --json              Print JSON response
 `);
         return;
     }
@@ -85,10 +85,18 @@ Options:
             console.log(`  Summary:   ${summary.passCount ?? 0} pass, ${summary.partialCount ?? 0} partial, ${summary.failCount ?? 0} fail` +
                 (summary.totalRules !== undefined ? ` (of ${summary.totalRules})` : ""));
         }
+        if (run.auditState) {
+            const required = summary?.byLevel?.required;
+            const requiredPct = run.requiredPassRate === null || run.requiredPassRate === undefined ? "n/a" : `${Math.round(run.requiredPassRate * 100)}%`;
+            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)`);
+        }
         for (const control of run.controls ?? []) {
             console.log(`\n  - ${control.controlName} (${control.controlId})`);
             for (const rule of control.rules ?? []) {
-                const level = rule.requirementLevel ? ` [${rule.requirementLevel}]` : "";
+                const qualifier = rule.requirementQualifier ? ` ${rule.requirementQualifier}` : "";
+                const level = rule.requirementLevel ? ` [${rule.requirementLevel}${qualifier}]` : "";
                 console.log(`    • [${rule.result}] ${rule.ruleName}${level} (${rule.ruleId})`);
                 if (rule.rationale)
                     console.log(`        ${rule.rationale}`);

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

@@ -118,23 +118,23 @@ function parseFindings(args) {
 export async function policyAuditSubmit(args) {
     const asJson = parseFlag(args, "--json");
     if (parseFlag(args, "--help") || parseFlag(args, "-h")) {
-        console.log(`
-Usage:
-  nexarch policy-audit-submit --command-id <id> --application-ref <key> [options]
-
-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
-  --findings-json <json>     JSON array of findings
-  --findings-file <path>     Path to JSON array of findings
-  --json                     Print JSON response
-
-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
+        console.log(`
+Usage:
+  nexarch policy-audit-submit --command-id <id> --application-ref <key> [options]
+
+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
+  --findings-json <json>     JSON array of findings
+  --findings-file <path>     Path to JSON array of findings
+  --json                     Print JSON response
+
+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
 `);
         return;
     }
@@ -173,5 +173,15 @@ Notes:
         console.log(`Run ID: ${result.runId}`);
     if (result.summary) {
         console.log(`Summary: ${result.summary.passCount ?? 0} pass, ${result.summary.partialCount ?? 0} partial, ${result.summary.failCount ?? 0} fail`);
+        if (result.summary.requiredIssueCount !== undefined) {
+            const pct = result.summary.requiredPassRate === null || result.summary.requiredPassRate === undefined
+                ? "n/a"
+                : `${Math.round(result.summary.requiredPassRate * 100)}%`;
+            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.remainingRules ?? 0) > 0) {
+            console.log(`Remaining rules to submit: ${result.summary.remainingRules}`);
+        }
     }
 }

package/dist/commands/policy-controls.js

@@ -45,7 +45,8 @@ export async function policyControls(args) {
             continue;
         }
         for (const rule of rules) {
-            const level = rule.requirementLevel ? ` [${rule.requirementLevel}]` : "";
+            const qualifier = rule.requirementQualifier ? ` ${rule.requirementQualifier}` : "";
+            const level = rule.requirementLevel ? ` [${rule.requirementLevel}${qualifier}]` : "";
             console.log(`  • ${rule.name} (${rule.id})${level}`);
         }
     }

package/dist/commands/verify-trust.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "fs";
 import { join, resolve } from "path";
-import { createHash } from "node:crypto";
+import { hashRegisteredSection } from "../lib/trust.js";
 /**
  * Verifies the trust attestation without anyone retyping it.
  *
@@ -15,17 +15,6 @@ import { createHash } from "node:crypto";
  */
 const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md", ".cursorrules", ".windsurfrules", ".github/copilot-instructions.md"];
 const DEFAULT_VERIFY_BASE = "https://mcp.nexarch.ai/trust/verify";
-/**
- * Recomputes the hash of the "agent-registration" managed section exactly as
- * `nexarch init-agent` hashed it before minting — see ADR-0112. Returns null
- * when the file has no such section (nothing for content_hash to cover).
- */
-function hashRegisteredSection(content) {
-    const match = content.match(/<!-- nexarch:agent-registration:start -->\n([\s\S]*?)\n<!-- nexarch:agent-registration:end -->/);
-    if (!match)
-        return null;
-    return createHash("sha256").update(match[1].trim(), "utf8").digest("hex");
-}
 function findAttestation(dir) {
     for (const name of INSTRUCTION_FILES) {
         const path = join(dir, name);

package/dist/index.js

@@ -13,6 +13,7 @@ import { updateEntity } from "./commands/update-entity.js";
 import { addRelationship } from "./commands/add-relationship.js";
 import { registerAlias } from "./commands/register-alias.js";
 import { resolveNames } from "./commands/resolve-names.js";
+import { feedback } from "./commands/feedback.js";
 import { listEntities } from "./commands/list-entities.js";
 import { listRelationships } from "./commands/list-relationships.js";
 import { checkIn } from "./commands/check-in.js";
@@ -56,6 +57,7 @@ const commands = {
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
     "resolve-names": resolveNames,
+    feedback,
     "list-entities": listEntities,
     "list-relationships": listRelationships,
     "register-runtime": registerRuntime,
@@ -137,7 +139,7 @@ Usage:
   nexarch init-agent    Run handshake + mandatory agent registration in graph (advanced/manual)
                         Options: --agent-id <id> --bind-to-external-key <key>
                                  --bind-relationship-type <code> --redact-hostname
-                                 --json --strict
+                                 --reattest --json --strict
   nexarch agent identify
                       Capture richer coding-agent identity metadata
                       Options: --agent-id <id> --provider <provider> --model <model>
@@ -170,6 +172,7 @@ Usage:
                                --batch-size <n>  upsert batch size (default: 10)
                                --profile  include timing/profile data in JSON output
                                --dry-run  preview without writing
+                               --tool <terraform|opentofu>  select the IaC state CLI
                                --json
   nexarch update-project
                       Re-scan a previously registered project directory, refresh
@@ -224,6 +227,12 @@ Usage:
                       results before calling add-relationship.
                       Options: --names <csv>  (required, e.g. "vercel,neon")
                                --json
+  nexarch feedback
+                      Report a Nexarch usability problem or tool error.
+                      Options: --kind <usability|error>  (required)
+                               --summary <text>           (required, one line)
+                               --detail <text> --severity <low|medium|high>
+                               --surface <page|tool|command> --json
   nexarch list-entities
                       List entities from the workspace graph.
                       Options: --type <entityTypeCode>

package/dist/lib/ansible-detect.js

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+import { environmentFromPath } from "./iac-detect.js";
+const SCAN_DEPTH = 8;
+const IGNORED = new Set([".git", "node_modules", ".venv", "venv", "dist", "build", ".next"]);
+const YAML = /\.ya?ml$/i;
+function walk(dir, depth = 0, files = []) {
+    if (depth > SCAN_DEPTH)
+        return files;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (IGNORED.has(entry))
+            continue;
+        const full = join(dir, entry);
+        try {
+            if (statSync(full).isDirectory())
+                walk(full, depth + 1, files);
+            else
+                files.push(full);
+        }
+        catch { /* unreadable paths are not evidence */ }
+    }
+    return files;
+}
+function hasPlaybookShape(file) {
+    if (!YAML.test(file))
+        return false;
+    try {
+        const text = readFileSync(file, "utf8");
+        return /^\s*-?\s*hosts\s*:/m.test(text) && /^\s*(tasks|roles|pre_tasks|post_tasks|handlers)\s*:/m.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+function normalise(repoDir, file) {
+    return relative(repoDir, file).split(sep).join("/");
+}
+/**
+ * The environment an inventory is for, from its path.
+ *
+ * Terraform gets this from a root module directory or a workspace. Ansible has
+ * neither, and this is the gap the plan called out as the hard part: the
+ * environment lives in how the inventory is filed. `inventories/production/hosts`
+ * and `inventory/prod.ini` both say it plainly, so the filename is consulted as
+ * well as the directories -- which is where `environmentFromPath` alone stops,
+ * since a Terraform root module is always a directory.
+ *
+ * The vocabulary is deliberately shared with `environmentFromPath` rather than
+ * copied: two lists of environment names drift, and then the same repository
+ * reports different environments depending on which tool read it.
+ */
+export function environmentFromInventoryPath(relativePath) {
+    const fromDirectories = environmentFromPath(relativePath);
+    if (fromDirectories)
+        return fromDirectories;
+    const base = (relativePath.split("/").at(-1) ?? "").replace(/\.(ini|ya?ml|json)$/i, "");
+    return base ? environmentFromPath(base) : null;
+}
+/**
+ * Detects Ansible from corroborating repository evidence.
+ *
+ * A YAML file containing `hosts:` is not enough: application configuration
+ * regularly has the same vocabulary. Like IaC detection, a playbook needs a
+ * second operational signal (inventory, roles, configuration, or collection)
+ * before it can change onboarding behaviour.
+ */
+export function detectAnsibleProject(repoDir) {
+    const files = walk(repoDir);
+    const relativeFiles = files.map((file) => normalise(repoDir, file));
+    const playbookFiles = files.filter(hasPlaybookShape).map((file) => normalise(repoDir, file)).sort();
+    const inventoryFiles = relativeFiles.filter((file) => {
+        const base = file.split("/").at(-1) ?? "";
+        return /(^|\/)(inventory|inventories)(\/|$)/i.test(file) || /^(hosts|inventory)(\.ini|\.ya?ml)?$/i.test(base);
+    }).sort();
+    const roleDirectories = relativeFiles
+        .filter((file) => /(^|\/)roles\/[^/]+\/(tasks|handlers|defaults|vars)\/main\.ya?ml$/i.test(file))
+        .map((file) => file.replace(/\/(tasks|handlers|defaults|vars)\/main\.ya?ml$/i, ""))
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .sort();
+    const collectionDirectories = relativeFiles
+        .filter((file) => /(^|\/)collections\/requirements\.ya?ml$/i.test(file) || /(^|\/)galaxy\.ya?ml$/i.test(file))
+        .map((file) => file.replace(/\/(requirements|galaxy)\.ya?ml$/i, ""))
+        .filter((value, index, values) => values.indexOf(value) === index)
+        .sort();
+    const hasConfig = existsSync(join(repoDir, "ansible.cfg"));
+    const signals = [];
+    if (playbookFiles.length)
+        signals.push(`${playbookFiles.length} playbook${playbookFiles.length === 1 ? "" : "s"}`);
+    if (inventoryFiles.length)
+        signals.push(`${inventoryFiles.length} inventory file${inventoryFiles.length === 1 ? "" : "s"}`);
+    if (roleDirectories.length)
+        signals.push(`${roleDirectories.length} role${roleDirectories.length === 1 ? "" : "s"}`);
+    if (collectionDirectories.length)
+        signals.push(`${collectionDirectories.length} collection declaration${collectionDirectories.length === 1 ? "" : "s"}`);
+    if (hasConfig)
+        signals.push("ansible.cfg");
+    const environments = [...new Set(inventoryFiles.map(environmentFromInventoryPath).filter((e) => Boolean(e)))].sort();
+    if (environments.length)
+        signals.push(`environments: ${environments.join(", ")}`);
+    const corroborated = inventoryFiles.length > 0 || roleDirectories.length > 0 || collectionDirectories.length > 0 || hasConfig;
+    return { isAnsible: playbookFiles.length > 0 && corroborated, signals, playbookFiles, inventoryFiles, environments, roleDirectories, collectionDirectories };
+}