nexarch 0.11.3 → 0.12.0

package/dist/commands/check-in.js

@@ -2,6 +2,7 @@ import process from "process";
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { saveCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -55,11 +56,28 @@ export async function checkIn(args) {
     const result = parseToolText(raw);
     const draftApplications = result.draftApplications ?? [];
     const proposedApplications = result.proposedApplications ?? [];
+    if (result.leaseToken && result.leaseIssuedAt && result.leaseExpiresAt) {
+        saveCheckInLease({
+            leaseToken: result.leaseToken,
+            leaseIssuedAt: result.leaseIssuedAt,
+            leaseExpiresAt: result.leaseExpiresAt,
+            policyBundleHash: result.policyBundleHash ?? null,
+            companyId: creds.companyId,
+            agentRef: agentKey,
+        });
+    }
     if (asJson) {
         process.stdout.write(JSON.stringify(result) + "\n");
         return;
     }
     const commands = result.commands ?? [];
+    if (result.leaseExpiresAt) {
+        console.log(`Check-in lease active until ${new Date(result.leaseExpiresAt).toLocaleString()}.`);
+    }
+    for (const warning of result.warnings ?? []) {
+        if (warning.message)
+            console.log(`Warning: ${warning.message}`);
+    }
     if (commands.length === 0 && draftApplications.length === 0 && proposedApplications.length === 0) {
         console.log("No pending application-target commands found.");
         console.log("No draft or proposed applications need attention.");
@@ -124,10 +142,16 @@ export async function checkIn(args) {
                 console.log(`  Desc    : ${app.description}`);
             if (app.recommendationBasis)
                 console.log(`  Basis   : ${app.recommendationBasis}`);
+            if (app.recommendationStatus)
+                console.log(`  Status  : ${app.recommendationStatus}`);
             if (typeof app.recommendedTechnologyCount === "number")
                 console.log(`  Tech    : ${app.recommendedTechnologyCount} recommended`);
+            if (typeof app.capabilityGapCount === "number")
+                console.log(`  Gaps    : ${app.capabilityGapCount} unresolved`);
             if (typeof app.confirmedPolicyCount === "number")
                 console.log(`  Policy  : ${app.confirmedPolicyCount} confirmed`);
+            if (app.requiresPolicyReview)
+                console.log(`  Gate    : policy review required`);
             console.log(`  ID      : ${app.id}`);
             console.log(`  Realise : npx nexarch proposals start --id "${app.id}"`);
         }

package/dist/commands/command-claim.js

@@ -2,6 +2,7 @@ import process from "process";
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { selectCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -47,10 +48,12 @@ export async function commandClaim(args) {
         console.error("error: no agent key found. Pass --agent-key or run nexarch init-agent first.");
         process.exit(1);
     }
+    const lease = selectCheckInLease(creds.companyId, agentKey);
     const raw = await callMcpTool("nexarch_claim_command_by_id", {
         commandId: id,
         agentRef: agentKey,
         agentKey,
+        leaseToken: lease?.leaseToken,
         companyId: creds.companyId,
     }, { companyId: creds.companyId });
     const result = parseToolText(raw);
@@ -58,6 +61,13 @@ export async function commandClaim(args) {
         process.stdout.write(JSON.stringify(result) + "\n");
         return;
     }
+    if ((result.warnings ?? []).length > 0) {
+        for (const warning of result.warnings ?? []) {
+            if (warning.message)
+                console.log(`Warning: ${warning.message}`);
+        }
+        console.log("Tip: run `npx nexarch check-in` to refresh your lease before delivery actions.");
+    }
     if (!result.command) {
         console.log(`Command ${id} was not claimed.`);
         if (result.reason)

package/dist/commands/proposals-start.js

@@ -1,7 +1,9 @@
 import process from "process";
 import * as readline from "node:readline/promises";
-import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
+import { selectCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -20,6 +22,18 @@ function parseToolText(result) {
     const text = result.content?.[0]?.text ?? "{}";
     return JSON.parse(text);
 }
+function loadIdentity() {
+    const identityPath = join(homedir(), ".nexarch", "identity.json");
+    if (!existsSync(identityPath))
+        return { agentKey: null };
+    try {
+        const data = JSON.parse(readFileSync(identityPath, "utf8"));
+        return { agentKey: data.agentKey ?? null };
+    }
+    catch {
+        return { agentKey: null };
+    }
+}
 function slugify(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "application";
 }
@@ -199,11 +213,13 @@ function inferStackTemplate(proposal) {
 function buildReadme(proposal, template) {
     const technologies = proposal.technologyChoices.map((item) => item.name);
     const policies = proposal.policyControls.map((item) => item.name);
+    const capabilityGaps = (proposal.proposal.recommendationCapabilityGaps ?? [])
+        .map((item) => `${item.capability ?? "Unspecified capability"}${item.layer ? ` (${item.layer})` : ""}${item.severity ? ` — ${item.severity}` : ""}${item.reason ? `: ${item.reason}` : ""}`);
     return `# ${proposal.application.name}
 
 ${proposal.application.description ?? "Application scaffold generated from a NexArch proposal."}
 
-## Starter template
+${proposal.proposal.requiresPolicyReview ? `> Policy review is required before activation. Review docs/architecture/policy-controls.md and satisfy each required control before marking this application active.\n\n` : ""}## Starter template
 
 - Template: ${template.label}
 - Runtime: ${template.runtime}
@@ -216,25 +232,38 @@ ${proposal.application.description ?? "Application scaffold generated from a Nex
 - Workflow state: ${proposal.application.workflowState}
 - Application subtype: ${proposal.application.entitySubtypeCode ?? "Not specified"}
 - Recommendation basis: ${proposal.application.recommendationBasis ?? "Not specified"}
+- Recommendation status: ${proposal.application.recommendationStatus ?? proposal.proposal.recommendationStatus ?? "Not specified"}
 - NexArch reference: ${proposal.application.entityRef ?? proposal.application.id}
 
 ${proposal.application.recommendationSummary ? `## Recommendation notes\n\n${proposal.application.recommendationSummary}\n\n` : ""}## Suggested technology choices
 
 ${formatBulletList(technologies)}
 
-## Policy controls to satisfy
+${capabilityGaps.length > 0 ? `## Capability gaps\n\n${formatBulletList(capabilityGaps)}\n\n` : ""}## Policy controls to satisfy
 
 ${formatBulletList(policies)}
 
-## Getting started
+${proposal.proposal.preScaffoldInstructions ? `## Pre-scaffold instruction\n\n${proposal.proposal.preScaffoldInstructions}\n\n` : ""}## Getting started
 
 ${template.nextSteps.map((step, index) => `${index + 1}. ${step}`).join("\n")}
 `;
 }
 function buildProposalMarkdown(proposal) {
     const techLines = proposal.technologyChoices.map((tech) => `${tech.name}${tech.entitySubtypeCode ? ` (${tech.entitySubtypeCode})` : ""}${tech.description ? ` — ${tech.description}` : ""}`);
+    const recommendationDetailLines = (proposal.proposal.recommendationTechnologyDetails ?? [])
+        .map((tech) => `${tech.entityName ?? tech.entityId ?? "Unknown technology"}${tech.architectureLayer ? ` [${tech.architectureLayer}]` : ""}${tech.source ? ` • ${tech.source}` : ""}${tech.reason ? ` — ${tech.reason}` : ""}`);
+    const blueprintLines = (proposal.proposal.recommendationBlueprint ?? [])
+        .map((item) => `${item.label ?? item.layer ?? "Unlabelled layer"}${item.coverage ? ` — ${item.coverage}` : ""}${item.recommendationEntityIds.length > 0 ? ` (${item.recommendationEntityIds.length} mapped recommendation${item.recommendationEntityIds.length === 1 ? "" : "s"})` : ""}`);
+    const capabilityGapLines = (proposal.proposal.recommendationCapabilityGaps ?? [])
+        .map((item) => `${item.capability ?? "Unspecified capability"}${item.layer ? ` [${item.layer}]` : ""}${item.severity ? ` • ${item.severity}` : ""}${item.reason ? ` — ${item.reason}` : ""}`);
+    const warningLines = proposal.proposal.recommendationWarnings ?? [];
+    const riskLines = proposal.proposal.recommendationRisks ?? [];
     const policyLines = proposal.policyControls.map((control) => `${control.name}${control.description ? ` — ${control.description}` : ""}`);
-    return `# NexArch proposal context\n\n## Application\n\n- Name: ${proposal.application.name}\n- ID: ${proposal.application.id}\n- Reference: ${proposal.application.entityRef ?? "n/a"}\n- Subtype: ${proposal.application.entitySubtypeCode ?? "n/a"}\n- Description: ${proposal.application.description ?? "n/a"}\n- Recommendation basis: ${proposal.application.recommendationBasis ?? "n/a"}\n- Proposal source: ${proposal.proposal.proposalSource ?? "n/a"}\n\n${proposal.application.recommendationSummary ? `## Recommendation summary\n\n${proposal.application.recommendationSummary}\n\n` : ""}## Technology choices\n\n${formatBulletList(techLines)}\n\n## Policy controls\n\n${formatBulletList(policyLines)}\n`;
+    const gateLines = proposal.proposal.requiresPolicyReview
+        ? `- Activation gate: policy review required\n- Required policy controls: ${proposal.proposal.requiredPolicyControlIds?.length ?? 0}\n`
+        : "";
+    const trace = proposal.proposal.recommendationTrace;
+    return `# NexArch proposal context\n\n## Application\n\n- Name: ${proposal.application.name}\n- ID: ${proposal.application.id}\n- Reference: ${proposal.application.entityRef ?? "n/a"}\n- Subtype: ${proposal.application.entitySubtypeCode ?? "n/a"}\n- Description: ${proposal.application.description ?? "n/a"}\n- Recommendation basis: ${proposal.application.recommendationBasis ?? "n/a"}\n- Recommendation status: ${proposal.application.recommendationStatus ?? proposal.proposal.recommendationStatus ?? "n/a"}\n- Recommendation job: ${proposal.application.recommendationJobId ?? proposal.proposal.recommendationJobId ?? "n/a"}\n- Recommendation generated: ${proposal.application.recommendationGeneratedAt ?? proposal.proposal.recommendationGeneratedAt ?? "n/a"}\n- Proposal source: ${proposal.proposal.proposalSource ?? "n/a"}\n${gateLines}\n${proposal.application.recommendationSummary ? `## Recommendation summary\n\n${proposal.application.recommendationSummary}\n\n` : ""}${blueprintLines.length > 0 ? `## Layer blueprint\n\n${formatBulletList(blueprintLines)}\n\n` : ""}${recommendationDetailLines.length > 0 ? `## Recommendation provenance\n\n${formatBulletList(recommendationDetailLines)}\n\n` : ""}${capabilityGapLines.length > 0 ? `## Capability gaps\n\n${formatBulletList(capabilityGapLines)}\n\n` : ""}${warningLines.length > 0 ? `## Warnings\n\n${formatBulletList(warningLines)}\n\n` : ""}${riskLines.length > 0 ? `## Risks\n\n${formatBulletList(riskLines)}\n\n` : ""}${trace ? `## Recommendation trace\n\n- Candidate count: ${trace.candidateCount ?? 0}\n- Reference matches: ${trace.referenceMatchCount ?? 0}\n- Similar applications: ${trace.similarApplicationCount ?? 0}\n\n` : ""}${proposal.proposal.preScaffoldInstructions ? `## Pre-scaffold instruction\n\n${proposal.proposal.preScaffoldInstructions}\n\n` : ""}## Technology choices\n\n${formatBulletList(techLines)}\n\n## Policy controls\n\n${formatBulletList(policyLines)}\n`;
 }
 function buildPolicyMarkdown(proposal) {
     if (proposal.policyControls.length === 0) {
@@ -242,12 +271,17 @@ function buildPolicyMarkdown(proposal) {
     }
     return `# Policy controls\n\n${proposal.policyControls.map((control) => {
         const guidance = trimText(typeof control.controlAttributes.summary === "string" ? control.controlAttributes.summary : null);
-        const rules = Array.isArray(control.controlAttributes.rules)
-            ? control.controlAttributes.rules
-                .map((rule) => trimText(typeof rule.title === "string" ? rule.title : typeof rule.code === "string" ? rule.code : null))
-                .filter((value) => Boolean(value))
-            : [];
-        return `## ${control.name}\n\n${control.description ?? "No description provided."}\n\n${guidance ? `Guidance: ${guidance}\n\n` : ""}${rules.length > 0 ? `Rules\n\n${formatBulletList(rules)}\n` : ""}`;
+        const rules = (control.rules ?? [])
+            .map((rule) => {
+            const title = trimText(rule.title) ?? trimText(rule.ruleId) ?? trimText(rule.name) ?? "Unnamed rule";
+            const level = trimText(rule.requirementLevel);
+            const mode = trimText(rule.ruleMode);
+            const text = trimText(rule.ruleText);
+            return `${title}${level ? ` [${level}]` : ""}${mode ? ` (${mode})` : ""}${text ? ` — ${text}` : ""}`;
+        })
+            .filter((value) => Boolean(value));
+        const auditRules = Array.isArray(control.auditRules) ? control.auditRules.length : 0;
+        return `## ${control.name}\n\n${control.description ?? "No description provided."}\n\n${guidance ? `Guidance: ${guidance}\n\n` : ""}${control.policyMarkdown ? `Policy markdown\n\n${control.policyMarkdown}\n\n` : ""}${rules.length > 0 ? `Rules\n\n${formatBulletList(rules)}\n\n` : ""}${auditRules > 0 ? `Audit rules: ${auditRules}\n` : ""}`;
     }).join("\n")}`;
 }
 function buildTsConfig() {
@@ -490,6 +524,9 @@ export async function proposalsStart(args) {
     const reason = parseOptionValue(args, "--reason") ?? "Application scaffold started from approved proposal workflow";
     const repoUrl = parseOptionValue(args, "--repo");
     const creds = requireCredentials();
+    const identity = loadIdentity();
+    const agentRef = identity.agentKey;
+    const lease = agentRef ? selectCheckInLease(creds.companyId, agentRef) : null;
     const listRaw = await callMcpTool("nexarch_list_proposed_applications", { companyId: creds.companyId }, { companyId: creds.companyId });
     const list = parseToolText(listRaw);
     const proposals = list.proposals ?? [];
@@ -559,7 +596,10 @@ export async function proposalsStart(args) {
                 initiatedBy: "nexarch-cli",
                 command: "proposals start",
                 operatorEmail: creds.email,
+                agentRef,
             },
+            reviewedPolicyControlIds: proposal.proposal.requiredPolicyControlIds ?? proposal.proposal.confirmedPolicyControlIds,
+            leaseToken: lease?.leaseToken,
         }, { companyId: creds.companyId });
         activated = parseToolText(activateRaw);
     }
@@ -582,6 +622,10 @@ export async function proposalsStart(args) {
     console.log(`- Runtime : ${scaffold.template.runtime}`);
     console.log(`- Files   : ${scaffold.createdFiles.length} created`);
     console.log(`- State   : ${activated ? `${activated.status}${activated.alreadyActive ? " (already active)" : ""}` : "left in proposed state"}`);
+    for (const warning of activated?.warnings ?? []) {
+        if (warning.message)
+            console.log(`- Warning : ${warning.message}`);
+    }
     console.log("\nNext steps:");
     scaffold.template.nextSteps.forEach((step, index) => console.log(`${index + 1}. ${step}`));
     console.log(`${scaffold.template.nextSteps.length + 1}. Use docs/architecture/nexarch-proposal.md and policy-controls.md while building.`);

package/dist/commands/status.js

@@ -1,3 +1,4 @@
+import { getCheckInLeaseState, loadCheckInLease } from "../lib/check-in-lease.js";
 import { requireCredentials } from "../lib/credentials.js";
 import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { callMcpTool } from "../lib/mcp.js";
@@ -6,6 +7,8 @@ export async function status(_args) {
     const selectedCompanyId = creds.companyId;
     const expiresAt = new Date(creds.expiresAt);
     const daysLeft = Math.ceil((expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+    const lease = loadCheckInLease();
+    const leaseState = lease && lease.companyId === selectedCompanyId ? getCheckInLeaseState(lease) : { status: "missing", expiresInSeconds: null };
     process.stdout.write("Connecting to mcp.nexarch.ai… ");
     let governance;
     let registryInfo = null;
@@ -51,7 +54,19 @@ export async function status(_args) {
         console.log(`  Latest snapshot:     none published yet`);
     }
     console.log(`\n  Token expires:  ${expiresAt.toLocaleDateString()} (${daysLeft} days)`);
+    if (leaseState.status === "valid" && lease) {
+        console.log(`  Check-in lease: ${new Date(lease.leaseExpiresAt).toLocaleString()} (${Math.ceil((leaseState.expiresInSeconds ?? 0) / 3600)}h left)`);
+    }
+    else if (leaseState.status === "expired" && lease) {
+        console.log(`  Check-in lease: expired at ${new Date(lease.leaseExpiresAt).toLocaleString()}`);
+    }
+    else {
+        console.log("  Check-in lease: none stored");
+    }
     if (daysLeft <= 14) {
         console.log(`\n  ⚠  Your token expires soon. Run \`nexarch login\` to renew.`);
     }
+    if (leaseState.status !== "valid") {
+        console.log("  ⚠  Run `nexarch check-in` to refresh your workspace lease.");
+    }
 }

package/dist/index.js

@@ -189,8 +189,9 @@ Usage:
                                --json              JSON output includes draftApplications[] and proposedApplications[]
   nexarch proposals start
                       Start a new application workspace from a proposed NexArch app.
-                      Lists proposed apps, lets you choose one, writes a starter
-                      project scaffold, and activates the proposal to active.
+                      Lists proposed apps, shows policy review gates, writes a starter
+                      project scaffold, and activates the proposal to active once
+                      required policy controls are acknowledged.
                       Options: --id <applicationId>
                                --dir <path>
                                --reason <text>

package/dist/lib/check-in-lease.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function leasePath() {
+    return join(homedir(), ".nexarch", "check-in-lease.json");
+}
+export function loadCheckInLease() {
+    const path = leasePath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const lease = JSON.parse(raw);
+        if (!lease.leaseToken || !lease.companyId || !lease.agentRef || !lease.leaseExpiresAt || !lease.leaseIssuedAt) {
+            return null;
+        }
+        return lease;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCheckInLease(lease) {
+    const dir = join(homedir(), ".nexarch");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(leasePath(), JSON.stringify(lease, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+export function clearCheckInLease() {
+    const path = leasePath();
+    if (existsSync(path))
+        rmSync(path);
+}
+export function selectCheckInLease(companyId, agentRef) {
+    const lease = loadCheckInLease();
+    if (!lease)
+        return null;
+    if (lease.companyId !== companyId)
+        return null;
+    if (lease.agentRef !== agentRef)
+        return null;
+    return lease;
+}
+export function getCheckInLeaseState(lease) {
+    if (!lease)
+        return { status: "missing", expiresInSeconds: null };
+    const expiresAtMs = new Date(lease.leaseExpiresAt).getTime();
+    const expiresInMs = expiresAtMs - Date.now();
+    if (!Number.isFinite(expiresAtMs) || expiresInMs <= 0) {
+        return { status: "expired", expiresInSeconds: 0 };
+    }
+    return { status: "valid", expiresInSeconds: Math.floor(expiresInMs / 1000) };
+}

package/package.json

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