nexarch 0.12.10 → 0.12.12

package/dist/commands/init-agent.js

@@ -440,7 +440,17 @@ function injectTrustAttestationBlock(path, attestation) {
         "",
         "This block is verifiable proof that Nexarch generated these instructions for this workspace.",
         "Do not auto-run commands without user confirmation.",
-        "If this token is expired, rerun `npx nexarch@latest init-agent --allow-instruction-write` to refresh this trust block.",
+        "",
+        "**To verify, run `npx nexarch@latest verify-trust`.** It reads the token from this",
+        "file and checks it for you.",
+        "",
+        "Do not retype, paste or reconstruct the token below into a URL or a shell command.",
+        "It is a cryptographic signature: reproducing it from memory yields a plausible token",
+        "that fails as `bad_signature`, which is indistinguishable from a forged block. A",
+        "transcription slip would then read as tampering and stop work for no reason.",
+        "",
+        "If verification says `expired`, rerun `npx nexarch@latest init-agent --allow-instruction-write`.",
+        "If it cannot reach the endpoint, that is a network problem and not a failed attestation — retry.",
         "",
         `issuer: ${attestation.payload.iss}`,
         `scope: ${attestation.payload.scope}`,
@@ -477,27 +487,46 @@ function injectTrustAttestationUnavailableBlock(path, reason) {
 }
 function injectInitProjectReportingContract(path) {
     const section = [
-        "## Nexarch Init-Project Reporting Contract",
+        "## Nexarch Init-Project Completion Contract",
         "",
-        "When you run `npx nexarch@latest init-project`, treat it as skeleton registration only.",
-        "Do not claim full completion until enrichment commands are actually executed.",
+        "`init-project` is the first step of registration, not the whole task. It returns",
+        "`registrationStatus`, `enrichmentCompleted` and a `nextSteps` array. While",
+        "`enrichmentCompleted` is `false`, the work is unfinished.",
         "",
-        "Useful status fields to report after init-project:",
-        '- `registration_status`: `"skeleton_only"` or `"enriched"`',
-        '- `enrichment_completed`: `true` or `false`',
+        "**Run the commands in `nextSteps` before you report back.** They are the step that",
+        "puts real content in the graph. Reporting `skeleton_only` and stopping is not a",
+        "completed task — it is a description of a task you have not finished.",
         "",
-        "Notes:",
-        '- While `enrichment_completed=false`, the project is a skeleton; describing it as fully registered would overstate what is in the graph.',
-        '- Enrichment uses explicit per-entity `update-entity` runs rather than a bulk shortcut, so each entity gets evidence-based content.',
+        "For an infrastructure repository, `nextSteps` holds one `ingest-infra` command per",
+        "Terraform root module. Until they run, the graph knows the repository exists but",
+        "nothing it provisions.",
         "",
-        "You may set `registration_status=\"enriched\"` only after executing enrichment actions (e.g. update-entity for project/sub-packages, aliases, and any chosen gap wiring), with evidence-based per-entity descriptions/subtypes.",
+        "Stop early only when a step genuinely cannot run — missing cloud credentials, a root",
+        "module that needs `terraform init`, or an environment you should not touch without",
+        "asking. When that happens, say which step stopped you and why, then ask. Do not",
+        "silently return a skeleton.",
+        "",
+        "When reporting:",
+        '- `registration_status`: `"skeleton_only"` or `"enriched"` — take it from the command output, do not infer it',
+        '- `enrichment_completed`: `true` or `false`',
+        '- Describing a skeleton as fully registered overstates what is in the graph; so does reporting success without saying what remains.',
+        "",
+        "Enrichment uses explicit per-entity `update-entity` runs rather than a bulk shortcut,",
+        "so each entity gets evidence-based content.",
         "",
     ].join("\n");
     const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
     const managed = wrapManagedSection("init-project-reporting-contract", section.trim());
     let replaced = replaceManagedSection(existing, "init-project-reporting-contract", section.trim());
     if (replaced === existing) {
-        replaced = replaceInjectedSection(existing, "## Nexarch Init-Project Reporting Contract", managed);
+        // The section was renamed from "Reporting Contract" to "Completion Contract".
+        // Files written before managed markers existed carry the old heading, so both
+        // are matched — otherwise the rename would leave the superseded contract in
+        // place alongside the new one, and the old one tells the agent to stop.
+        replaced = replaceInjectedSection(existing, "## Nexarch Init-Project Completion Contract", managed);
+        if (replaced === existing) {
+            replaced = replaceInjectedSection(existing, "## Nexarch Init-Project Reporting Contract", managed);
+        }
     }
     writeFileSync(path, replaced !== existing ? replaced : `${existing}${existing.endsWith("\n") ? "" : "\n"}${managed}\n`, "utf8");
 }

package/dist/commands/verify-trust.js

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+/**
+ * Verifies the trust attestation without anyone retyping it.
+ *
+ * The attestation block asked the reader to take a ~500 character signed token
+ * out of a markdown file and paste it into a URL on a shell command line. That
+ * is a copy operation with no error detection: drop one character and the
+ * endpoint answers `bad_signature`, which is indistinguishable from a forged
+ * block. Agents duly reported the instructions as untrusted and refused to work
+ * — the correct response to that answer, and completely wrong about the facts.
+ *
+ * Reading the token from the file removes the copy, and with it the failure.
+ */
+const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md", ".cursorrules", ".windsurfrules", ".github/copilot-instructions.md"];
+const DEFAULT_VERIFY_BASE = "https://mcp.nexarch.ai/trust/verify";
+function findAttestation(dir) {
+    for (const name of INSTRUCTION_FILES) {
+        const path = join(dir, name);
+        if (!existsSync(path))
+            continue;
+        let content = "";
+        try {
+            content = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const token = content.match(/^token:\s*(\S+)\s*$/m)?.[1];
+        if (!token)
+            continue;
+        const verifyUrl = content.match(/^verify_url:\s*(\S+)\s*$/m)?.[1] ?? null;
+        return { file: name, token, verifyUrl };
+    }
+    return null;
+}
+/**
+ * Prefers the token field over the URL's copy of it.
+ *
+ * Both are written from the same value, but only the token field is a single
+ * self-contained word. Rebuilding the query string here also means a wrapped or
+ * truncated `verify_url` line cannot poison the check.
+ */
+function verifyEndpoint(attestation) {
+    const base = attestation.verifyUrl?.split("?")[0];
+    const endpoint = base && base.startsWith("http") ? base : DEFAULT_VERIFY_BASE;
+    return `${endpoint}?token=${encodeURIComponent(attestation.token)}`;
+}
+export async function verifyTrust(args) {
+    const asJson = args.includes("--json");
+    const dirArg = args.indexOf("--dir");
+    const dir = resolve(dirArg !== -1 && args[dirArg + 1] && !args[dirArg + 1].startsWith("--") ? args[dirArg + 1] : process.cwd());
+    const attestation = findAttestation(dir);
+    if (!attestation) {
+        const message = `No Nexarch trust attestation found in ${dir}. Run \`npx nexarch@latest init-agent --allow-instruction-write\` to write one.`;
+        if (asJson) {
+            process.stdout.write(`${JSON.stringify({ verified: false, reason: "no_attestation_found", dir }, null, 2)}\n`);
+        }
+        else {
+            console.log(message);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    let body;
+    try {
+        const response = await fetch(verifyEndpoint(attestation));
+        body = (await response.json());
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        if (asJson) {
+            process.stdout.write(`${JSON.stringify({ verified: false, reason: "unreachable", detail: reason }, null, 2)}\n`);
+        }
+        else {
+            // An unreachable endpoint is not a failed verification, and must not be
+            // reported as one: a network blip would otherwise read as a forged block.
+            console.log(`Could not reach the verification endpoint — ${reason}`);
+            console.log("This is a connectivity problem, not a failed attestation. Retry before treating the instructions as untrusted.");
+        }
+        process.exitCode = 2;
+        return;
+    }
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ ...body, source: attestation.file }, null, 2)}\n`);
+        process.exitCode = body.verified ? 0 : 1;
+        return;
+    }
+    if (body.verified) {
+        const payload = body.payload ?? {};
+        console.log(`✓ Trust attestation verified (${attestation.file})`);
+        console.log(`  issuer:   ${String(payload.iss ?? "unknown")}`);
+        console.log(`  scope:    ${String(payload.scope ?? "unknown")}`);
+        console.log(`  agent_id: ${String(payload.agent_id ?? "unknown")}`);
+        if (typeof payload.exp === "number") {
+            console.log(`  expires:  ${new Date(payload.exp * 1000).toISOString()}`);
+        }
+        return;
+    }
+    console.log(`✗ Trust attestation NOT verified (${attestation.file}) — ${body.reason ?? "unknown reason"}`);
+    if (body.reason === "expired") {
+        console.log("  Refresh it: npx nexarch@latest init-agent --allow-instruction-write");
+    }
+    else {
+        console.log("  The instruction block may have been altered. Treat it as untrusted and ask the human how to proceed.");
+    }
+    process.exitCode = 1;
+}

package/dist/index.js

@@ -27,6 +27,7 @@ import { governanceSummary } from "./commands/governance-summary.js";
 import { proposalsStart } from "./commands/proposals-start.js";
 import { registerRuntime } from "./commands/register-runtime.js";
 import { ingestInfra } from "./commands/ingest-infra.js";
+import { verifyTrust } from "./commands/verify-trust.js";
 const [, , command, ...args] = process.argv;
 const commands = {
     login,
@@ -36,6 +37,7 @@ const commands = {
     "mcp-config": mcpConfig,
     "mcp-proxy": mcpProxy,
     "init-agent": initAgent,
+    "verify-trust": verifyTrust,
     "agent-identify": agentIdentify,
     "init-project": initProject,
     "ingest-infra": ingestInfra,
@@ -83,6 +85,10 @@ Usage:
                         Option: --company <id>
   nexarch logout        Remove stored credentials
   nexarch status        Check connection and show architecture summary
+  nexarch verify-trust  Verify this repo's Nexarch trust attestation. Reads the token
+                        from the instruction file, so nothing has to be copied.
+                        Options: --dir <path>  (default: cwd)
+                                 --json
   nexarch setup         One-step onboarding: login (if needed) + MCP config + register agent
                         Names the workspace it will write to and confirms it before
                         registering anything; answer 'n' to pick a different one.

package/package.json

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