nexarch 0.12.9 → 0.12.11

package/dist/commands/init-agent.js

@@ -477,27 +477,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.",
+        "",
+        "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.",
         "",
-        "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.',
+        "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.",
         "",
-        "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.",
+        "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/init-project-infra.js

@@ -25,6 +25,36 @@ async function confirm(question) {
         rl.close();
     }
 }
+/**
+ * The ingest runs that still have to happen, one per root module.
+ *
+ * Registration records the repository; it does not record the estate. Only
+ * state does that, and state is per root module — seven of them here, each
+ * needing its own Terraform run. Naming this as a list of commands rather than
+ * a paragraph of advice is the difference between an agent finishing the job
+ * and an agent reporting "skeleton_only" and stopping, which is exactly what
+ * happened when the handoff lived only in prose at the end of a real run.
+ */
+function nextStepsFor(projectRef, detection) {
+    return detection.rootModules.map((root) => ({
+        rootModule: root.relative,
+        environment: root.environmentHint,
+        initialised: root.initialised,
+        command: `nexarch ingest-infra --dir ${root.relative} --project-ref ${projectRef}`,
+    }));
+}
+/** Prints the per-root ingest commands, the part that actually populates the graph. */
+function printNextSteps(steps, registered) {
+    if (steps.length === 0)
+        return;
+    console.log(`\n${registered ? "Registered" : "Would register"} the repository — the estate itself is not in the graph yet.`);
+    console.log(`Each of the ${steps.length} root modules holds its own state and needs its own ingest:\n`);
+    for (const step of steps) {
+        const notes = [step.environment ? `${step.environment} environment` : "shared stack", step.initialised ? "initialised" : "run `terraform init` here first"].join(", ");
+        console.log(`    # ${step.rootModule} — ${notes}`);
+        console.log(`    ${step.command}`);
+    }
+}
 /**
  * Shows what a real run would write.
  *
@@ -35,8 +65,19 @@ async function confirm(question) {
  */
 function reportDryRun(params) {
     const { asJson, projectRef, detection, entities, relationships } = params;
+    const nextSteps = nextStepsFor(projectRef, detection);
     if (asJson) {
-        process.stdout.write(`${JSON.stringify({ ok: true, dryRun: true, wrote: false, projectRef, detection, plan: { entities, relationships } }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            dryRun: true,
+            wrote: false,
+            projectRef,
+            registrationStatus: "skeleton_only",
+            enrichmentCompleted: false,
+            detection,
+            plan: { entities, relationships },
+            nextSteps,
+        }, null, 2)}\n`);
         return;
     }
     console.log(`\nWould write ${entities.length} entit${entities.length === 1 ? "y" : "ies"}:`);
@@ -47,7 +88,11 @@ function reportDryRun(params) {
         for (const rel of relationships)
             console.log(`    ${rel.fromEntityRef} --${rel.relationshipTypeCode}--> ${rel.toEntityRef}`);
     }
-    console.log(`\nNothing was written. Re-run without --dry-run to register.`);
+    // The dry run used to stop here, which made registration look like the whole
+    // job: a reader saw four entities and no hint that seven ingest runs were the
+    // actual work. A preview has to preview the handoff too.
+    printNextSteps(nextSteps, false);
+    console.log(`\nNothing was written. Re-run without --dry-run to register, then run the commands above.`);
 }
 export async function runInfrastructureOnboarding(options, detection) {
     const { dir, nameOverride, asJson, nonInteractive, skipIngest, dryRun } = options;
@@ -132,15 +177,9 @@ export async function runInfrastructureOnboarding(options, detection) {
     // the map up front — rather than letting the caller discover it through a
     // failure — is what lets an agent finish the job unaided.
     const roots = detection.rootModules;
-    if (!asJson && roots.length > 1) {
-        console.log(`\nThis repository has ${roots.length} root modules, each with its own state.`);
-        console.log("Ingest them one at a time — every root module is a separate estate:\n");
-        for (const root of roots) {
-            const notes = [root.environmentHint ? `${root.environmentHint} environment` : "shared stack", root.initialised ? "initialised" : "run `terraform init` here first"].join(", ");
-            console.log(`    # ${root.relative} — ${notes}`);
-            console.log(`    nexarch ingest-infra --dir ${root.relative} --project-ref ${projectRef}`);
-        }
-    }
+    const nextSteps = nextStepsFor(projectRef, detection);
+    if (!asJson && roots.length > 1)
+        printNextSteps(nextSteps, true);
     let ingested = false;
     if (!skipIngest && roots.length <= 1) {
         const shouldIngest = nonInteractive ? false : await confirm("\nRead the current state and populate the graph now?");
@@ -156,9 +195,23 @@ export async function runInfrastructureOnboarding(options, detection) {
             }
         }
     }
+    // Registration alone is a skeleton, and saying so in the payload keeps the
+    // caller's report honest: the numbers it needs to decide "am I finished?"
+    // come from the command that did the work, not from a convention it half
+    // remembers.
+    const outstanding = ingested ? nextSteps.filter((step) => step.rootModule !== "." && roots.length > 1) : nextSteps;
     const { file, snippet } = ciSnippetFor(detection.ciSystem, detection.ciFile);
     if (asJson) {
-        process.stdout.write(`${JSON.stringify({ ok: true, projectRef, detection, ingested, ci: { file, snippet } }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({
+            ok: true,
+            projectRef,
+            registrationStatus: outstanding.length > 0 ? "skeleton_only" : "enriched",
+            enrichmentCompleted: outstanding.length === 0,
+            detection,
+            ingested,
+            nextSteps: outstanding,
+            ci: { file, snippet },
+        }, null, 2)}\n`);
         return;
     }
     console.log(`\nInfrastructure changes continuously, so ingestion belongs in the pipeline, not in someone's memory.`);
@@ -166,5 +219,9 @@ export async function runInfrastructureOnboarding(options, detection) {
     console.log(snippet);
     console.log(`\nNEXARCH_TOKEN is a service credential — create one in the workspace under`);
     console.log(`Discovery → Agents, then store it as a masked CI variable.`);
+    if (outstanding.length > 0) {
+        console.log(`\nThis run registered the repository only. Until the ${outstanding.length} ingest command${outstanding.length === 1 ? "" : "s"} above`);
+        console.log(`have run, the graph knows the repo exists but nothing it provisions.`);
+    }
 }
 export { detectInfrastructureProject };

package/package.json

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