nexarch 0.12.31 → 0.12.34

package/dist/commands/login.js

@@ -6,8 +6,22 @@ import { saveCredentials } from "../lib/credentials.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { selectFromList } from "../lib/prompt-select.js";
 const NEXARCH_URL = "https://nexarch.ai";
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+// Mirrors AGENT_CAPABILITY_PROFILES in web/src/lib/mcp-agents.ts — the
+// server is the actual authority on what each profile grants; this is just
+// the same labels/descriptions shown in the enrollment UI, reused here so
+// the CLI prompt and the web form agree about what "Worker" means.
+const PROFILE_CHOICES = [
+    { value: "observer", label: "Observer", description: "Read graph, policies, and governance context. Cannot write or claim work." },
+    { value: "contributor", label: "Contributor", description: "Observer, plus proposing entities/relationships and new applications." },
+    { value: "worker", label: "Worker", description: "Contributor, plus checking in, claiming, and completing commands." },
+    { value: "delivery", label: "Delivery", description: "Worker, plus activating proposed applications." },
+];
+async function promptCapabilityProfile() {
+    return selectFromList("Select a capability profile for this credential:", PROFILE_CHOICES, "worker");
+}
 function printLoginBanner() {
     const logo = String.raw `
         ######        ######
@@ -136,10 +150,14 @@ export async function login(args) {
     const state = generateState();
     const port = await findFreePort();
     const requestedCompany = getArgValue(args, "--company");
-    const qp = new URLSearchParams({ port: String(port), state });
+    const requestedProfile = getArgValue(args, "--profile");
+    const isCapabilityProfile = (value) => PROFILE_CHOICES.some((c) => c.value === value);
+    const profile = isCapabilityProfile(requestedProfile) ? requestedProfile : await promptCapabilityProfile();
+    const qp = new URLSearchParams({ port: String(port), state, profile });
     if (requestedCompany)
         qp.set("company", requestedCompany);
     const authUrl = `${NEXARCH_URL}/auth/cli?${qp.toString()}`;
+    console.log(`\nCapability profile: ${profile}`);
     console.log("Opening Nexarch in your browser…");
     console.log(`\n  ${authUrl}\n`);
     console.log("If the browser did not open, copy the URL above and paste it in manually.\n");

package/dist/lib/prompt-select.js

@@ -0,0 +1,72 @@
+import readline from "readline";
+/**
+ * Arrow-key single-select prompt. No dependency — this package has none for
+ * a reason (see package.json), and Node's own readline keypress events cover
+ * the whole interaction: up/down to move, enter to confirm, ctrl+c to abort.
+ *
+ * Falls back to `defaultValue` without prompting when stdin/stdout isn't a
+ * TTY (piped input, --non-interactive runs, CI) — the same guard setup.ts
+ * already uses for its yes/no prompt.
+ */
+export async function selectFromList(title, choices, defaultValue) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return defaultValue;
+    }
+    const defaultIndex = choices.findIndex((c) => c.value === defaultValue);
+    let index = defaultIndex >= 0 ? defaultIndex : 0;
+    let linesDrawn = 0;
+    const render = () => {
+        if (linesDrawn > 0) {
+            readline.moveCursor(process.stdout, 0, -linesDrawn);
+            readline.cursorTo(process.stdout, 0);
+            readline.clearScreenDown(process.stdout);
+        }
+        const lines = [
+            `${title} (↑/↓ to move, enter to select)`,
+            ...choices.flatMap((choice, i) => {
+                const selected = i === index;
+                const pointer = selected ? "❯ " : "  ";
+                const label = selected ? `\x1b[1m${choice.label}\x1b[0m` : choice.label;
+                return [`${pointer}${label}`, `    ${choice.description}`];
+            }),
+        ];
+        process.stdout.write(lines.join("\n") + "\n");
+        linesDrawn = lines.length;
+    };
+    return new Promise((resolve) => {
+        readline.emitKeypressEvents(process.stdin);
+        const wasRaw = process.stdin.isRaw;
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        const cleanup = () => {
+            process.stdin.removeListener("keypress", onKeypress);
+            process.stdin.setRawMode(Boolean(wasRaw));
+            process.stdin.pause();
+        };
+        const onKeypress = (_str, key) => {
+            if (!key)
+                return;
+            if (key.ctrl && key.name === "c") {
+                cleanup();
+                console.log();
+                process.exit(130);
+            }
+            if (key.name === "up") {
+                index = (index - 1 + choices.length) % choices.length;
+                render();
+                return;
+            }
+            if (key.name === "down") {
+                index = (index + 1) % choices.length;
+                render();
+                return;
+            }
+            if (key.name === "return") {
+                cleanup();
+                resolve(choices[index].value);
+            }
+        };
+        render();
+        process.stdin.on("keypress", onKeypress);
+    });
+}

package/dist/lib/skills.js

@@ -104,6 +104,18 @@ skill is the check-in → claim → complete loop for working that queue.
 - \`nexarch_check_in\` previews pending commands and draft/proposed
   applications for this agent. It does **not** claim or change anything —
   safe to call any time, including proactively at the start of a session.
+- If you already know which application you're operating in — you're
+  working inside its repo, or it was named earlier in this conversation —
+  pass it as \`applicationContext: { accessibleApplicationRefs: ["application:<ref>"] }\`
+  on this **first** call. Without it, every command comes back
+  \`claimable: false\` (\`claimReason: "application_context_required_for_claim"\`)
+  even if you could otherwise claim it, and you'll need a second check-in
+  call with that same ref before \`nexarch_claim_command_by_id\` will work —
+  a wasted round trip when the application was knowable up front.
+- If you don't yet know the application, call check-in bare first. Each
+  returned command carries \`target_entity_key\` (e.g.
+  \`"application:veri_viva_platform_website"\`) — call check-in again with
+  that as \`accessibleApplicationRefs\` before trying to claim it.
 - Report exactly what check-in found. Don't reinterpret "check in" as
   registration (\`init-agent\`) or as a general health check
   (\`nexarch_get_governance_summary\`) — they're different actions.
@@ -112,13 +124,37 @@ skill is the check-in → claim → complete loop for working that queue.
 
 ## Working a command
 
+Claiming is a commitment, not a checkbox. Don't claim a command unless
+you're about to do the three steps below in the same turn — a claimed
+command that's never executed or closed out sits there looking done while
+blocking that queue slot, which is worse than never having claimed it.
+
 1. Only claim a specific command with \`nexarch_claim_command_by_id\` when the
    human explicitly wants it worked — check-in surfacing a command is not
-   itself permission to claim it.
-2. Do the work the command describes.
+   itself permission to claim it, and neither is check-in itself: claiming
+   is a separate, deliberate call you make because you're about to act.
+2. **Execute \`command.resolved_playbook_text\` from the claim response** —
+   that field is the actual task. \`command.instructions\` is a different
+   field and is almost always \`null\`; don't mistake its emptiness for "no
+   work to do."
 3. Close it out: \`nexarch_complete_command\` on success, or
-   \`nexarch_fail_command\` with a reason if it couldn't be done. Never leave a
-   claimed command unresolved at the end of a session.
+   \`nexarch_fail_command\` with a reason if it couldn't be done. Never end a
+   turn with a command still claimed and nothing else called.
+
+## If check-in shows a command you can't claim
+
+Claiming/completing/failing a command needs the \`mcp:work:commands\` scope —
+a separate, higher capability profile ("worker" or above) than what does the
+graph writing (\`mcp:write:discovery\`, granted from "contributor" up). A
+credential can see pending commands and still lack the scope to claim one;
+check-in's response says so explicitly when that's the case
+(\`claimReason: "credential_missing_work_scope"\`). If you hit this: still do
+the work if it's clearly what's needed, but say in your summary that you
+couldn't formally claim/complete the command, and that a human needs to
+either handle it in the workspace or reissue your credential with the
+"worker" profile. Don't call \`nexarch_claim_command_by_id\` speculatively —
+if your tools/list doesn't include it, your credential doesn't have the
+scope, and the call will fail.
 
 ## Ground rules
 
@@ -177,6 +213,83 @@ evidence — never invent a compliance status that isn't stored.
   what you found and let the human decide, same as the reuse-before-build
   principle elsewhere in Nexarch.
 `;
+const DECISION_RECORDS_SKILL_BODY = `---
+name: nexarch-decision-records
+description: Record an architectural decision in Nexarch, or check what's already been decided about something. Use when a decision is being made (a technology, pattern, or approach chosen over alternatives), when ADR/RFC documents are found in a repository, when asked what's already been decided about a topic, or when a new decision replaces an older one. Requires the Nexarch MCP tools (nexarch_*).
+---
+
+# Nexarch Decision Records
+
+Decisions are first-class in Nexarch: \`decision_record\` entities linked to
+whatever they concern via \`decides\`, reviewed in the workspace's Decisions
+page, and optionally promoted into workspace-wide policy by a human. This
+skill is for recording one as it happens — mining a whole repository's ADR
+history systematically is a separate, human-triggered Decision Review
+command from the application's page in the workspace.
+
+## Before recording
+
+\`nexarch_resolve_reference\` / \`nexarch_list_entities\` for an existing
+\`decision_record\` covering the same choice — match by name/summary first.
+Reuse and refresh it rather than creating a duplicate for the same decision.
+
+## Recording a decision
+
+\`entityTypeCode: "decision_record"\`. Two attributes are strictly required —
+MCP rejects the write with \`INVALID_DECISION_RECORD_PAYLOAD\` if either is
+missing or empty, with no fallback to \`description\` (ADR-0101):
+
+- \`attributes.decision.summary\` — one sentence naming what was chosen.
+- \`attributes.decision.detail\` — the fuller rationale, cited to its evidence.
+
+Never invent a decision from a technology's mere presence — it must trace to
+an actual stated reason someone chose it over an alternative.
+
+### Optional fields — add them when the evidence actually supports them
+
+All additive; a decision recorded with only summary/detail is still
+completely valid. Leave a field unset rather than guessing it:
+
+- \`attributes.source.repositoryUrl\` / \`.commit\` / \`.path\` / \`.lines\` — where
+  the decision was found, so the workspace can show exact evidence and
+  detect when it drifts from what's now in the repo.
+- \`attributes.decision.status\` — one of \`unknown\` / \`proposed\` / \`accepted\`
+  / \`deprecated\` / \`superseded\` / \`rejected\`, only when the source states it
+  explicitly.
+- \`attributes.decision.rationale\` — the "why", as its own field, when it's
+  distinguishable from the alternatives/consequences discussion.
+- \`attributes.decision.alternatives\` — array of \`{"option": "...",
+  "whyRejected": "..."}\` for alternatives the source explicitly names and
+  explains rejecting. Don't invent alternatives the source never mentions.
+- \`attributes.decision.consequences\` — array of plain-string trade-offs the
+  source explicitly states.
+- \`attributes.decision.supersededByRef\` — the \`entityRef\` of the
+  \`decision_record\` that replaces this one, only when the source explicitly
+  says so. Setting this on an upsert automatically flags the old decision as
+  superseded in the workspace — you don't need to touch the old record
+  yourself.
+
+### Linking
+
+\`decision_record -> decides -> <application | technology_component |
+platform | api | other ontology-valid target>\` — the most specific existing
+entity the decision actually concerns. Only link to entities that already
+exist; this skill records decisions, it doesn't discover architecture. If
+nothing ontology-valid exists yet to link to, still record the decision and
+say so rather than skipping it or inventing a target.
+
+## Ground rules
+
+- A decision being implemented is not the same as a decision being followed
+  correctly — recording one here says nothing about whether the code
+  actually conforms. That's \`nexarch_submit_decision_conformance\` (see the
+  \`nexarch-governance-review\` skill), a separate, evidence-based check.
+- Conflicts, duplicates, and workspace-wide promotion of a decision are
+  reviewed by a human in the workspace UI, not something to resolve or
+  decide yourself — your job is accurate recording and evidenced linking.
+- End with a one-line summary: what was recorded or reused, and what (if
+  anything) couldn't be linked.
+`;
 export const SKILLS = [
     {
         templateCode: "nexarch_claude_code_skill_v1",
@@ -198,6 +311,11 @@ export const SKILLS = [
         dirName: "nexarch-governance-review",
         fallbackBody: GOVERNANCE_REVIEW_SKILL_BODY,
     },
+    {
+        templateCode: "nexarch_decision_records_skill_v1",
+        dirName: "nexarch-decision-records",
+        fallbackBody: DECISION_RECORDS_SKILL_BODY,
+    },
 ];
 const RUNTIME_SKILLS_ROOT = {
     "claude-code": [".claude", "skills"],

package/package.json

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