@aikdna/kdna-cli 0.25.1 → 0.26.1

package/README.md

@@ -11,6 +11,11 @@ handled by KDNA Studio CLI and Studio Core.
 KDNA Core v1 does not require a public registry, marketplace, quality badge, or
 signature system. The current first-run path uses local `.kdna` files.
 
+Authorization and runtime-load decisions are defined in `aikdna/kdna`, not in
+this repository. `kdna plan-load` is the CLI diagnostic surface for that
+contract and MUST call the LoadPlan API from `@aikdna/kdna-core` instead of
+deriving authorization state directly from manifest fields.
+
 ## Install
 
 ```bash
@@ -23,8 +28,10 @@ npm install -g @aikdna/kdna-cli
 kdna demo minimal ./minimal
 kdna inspect ./minimal
 kdna validate ./minimal
+kdna plan-load ./minimal --json
 kdna pack ./minimal ./minimal.kdna
-kdna validate ./minimal.kdna
+kdna validate ./minimal.kdna --runtime
+kdna plan-load ./minimal.kdna --json
 kdna load ./minimal.kdna --profile=compact --as=prompt
 ```
 
@@ -49,6 +56,9 @@ Successful validation returns:
 | `kdna demo minimal <dir>` | Create a minimal v1 source directory |
 | `kdna inspect <path>` | Inspect a v1 source dir or `.kdna` container |
 | `kdna validate <path>` | Validate format, schema, payload, checksums, and load contract |
+| `kdna plan-load <path> --json` | Return the Core LoadPlan before runtime load |
+| `kdna plan-load <path> --json --has-password` | Diagnose password-authorized load state |
+| `kdna plan-load <path> --json --entitlement-status active` | Diagnose receipt/entitlement load state |
 | `kdna pack <source-dir> <output.kdna>` | Pack a v1 source directory |
 | `kdna unpack <input.kdna> <output-dir>` | Unpack a v1 container |
 | `kdna load <path> --profile=<index|compact|scenario|full> --as=<json|prompt>` | Render judgment context for agents or tools |
@@ -62,8 +72,17 @@ Use Studio CLI to create formal v1 `.kdna` assets:
 ```bash
 npm install -g @aikdna/kdna-studio-cli
 kdna-studio create my_domain --name @yourscope/my_domain
-kdna-studio migrate ./my_domain --format v1 --out ./my_domain.kdna
-kdna validate ./my_domain.kdna
+kdna-studio card add my_domain axiom \
+  --field one_sentence="Prefer specific evidence over broad claims" \
+  --field full_statement="When reviewing content, prefer specific evidence over broad claims because unsupported generalizations make the judgment impossible to verify or improve." \
+  --field why="Broad claims hide the actual reason for a judgment, so reviewers cannot tell whether the conclusion is evidence based, reusable, or merely plausible sounding." \
+  --field applies_when='["reviewing content"]' \
+  --field does_not_apply_when='["pure formatting"]' \
+  --field failure_risk="generic advice"
+kdna-studio card approve my_domain --all --by expert --statement "I confirm this judgment."
+kdna-studio export my_domain --format v1 --out ./my_domain.kdna
+kdna validate ./my_domain.kdna --runtime
+kdna plan-load ./my_domain.kdna --json
 kdna load ./my_domain.kdna --profile=compact --as=prompt
 ```
 
@@ -79,10 +98,38 @@ New integrations should use the v1 Core route:
 source or Studio project
 → v1 .kdna container
 → kdna validate
+→ kdna plan-load
 → kdna load
 → agent/runtime context
 ```
 
+## Runtime Authorization Contract
+
+The source of truth is `aikdna/kdna`:
+
+- `specs/kdna-authorization-contract.md`
+- `schema/load-plan.schema.json`
+- `conformance/authorization/cases.json`
+- `conformance/authorization/goldens/*.loadplan.json`
+
+This CLI is a diagnostic control plane. It may display, validate, and transport
+LoadPlan results, but it must not define access modes, entitlement profiles,
+issue codes, crypto profiles, or fail-closed policy independently.
+
+Current local authorization path:
+
+```bash
+kdna validate ./asset.kdna --json
+kdna plan-load ./asset.kdna --json
+kdna plan-load ./asset.kdna --json --has-password
+kdna plan-load ./asset.kdna --json --entitlement-status active
+kdna load ./asset.kdna --profile=compact --as=prompt
+```
+
+`plan-load` requires a version of `@aikdna/kdna-core` that exports the LoadPlan
+v1 API. Until that dependency is released and installed, the command fails with
+a version-gate error instead of falling back to duplicated CLI-side parsing.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "description": "KDNA CLI — runtime control plane for verifying, installing, loading, comparing, publishing, and auditing existing .kdna assets.",
   "type": "commonjs",
   "bin": {
@@ -55,7 +55,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aikdna/kdna-core": "^0.11.0"
+    "@aikdna/kdna-core": "^0.12.0"
   },
   "optionalDependencies": {
     "ajv": "^8.20.0",

package/skills/kdna-loader/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: kdna-loader
-description: Discover and load KDNA judgment frameworks from installed .kdna assets when the task requires domain-specific judgment (review, diagnosis, critique, classification, strategy) where the same input could legitimately be interpreted multiple ways. Skip for pure formatting, factual lookup, code execution, or mechanical transformations. This skill is the entire interface to KDNA — domains themselves are not separate skills.
+description: Discover and load installed KDNA `.kdna` assets through the kdna CLI when the task requires domain-specific judgment (review, diagnosis, critique, classification, strategy) where the same input could legitimately be interpreted multiple ways. Skip for pure formatting, factual lookup, code execution, or mechanical transformations. This skill is the entire interface to KDNA — domains themselves are not separate skills.
 ---
 
 # KDNA Loader
 
 KDNA (Knowledge DNA) is a portable format for encoding domain judgment.
-Each KDNA domain is a small JSON bundle (~5–30 KB) that describes how
+Each KDNA domain is a `.kdna` cognitive asset that describes how
 an expert thinks inside one domain: the principles they reason from,
 the misunderstandings they avoid, the questions they ask themselves
 before deciding.
@@ -17,10 +17,28 @@ this skill provides the **routing and protocol**, KDNA provides the
 **judgment material**.
 
 This skill is the **only** KDNA-related skill. Domains themselves are
-not registered as skills — they live as `.kdna` assets under `~/.kdna/packages/` and
-are discovered on demand. Whether the user has 1 domain installed or
+not registered as skills — they are installed as `.kdna` assets and
+are discovered through the CLI on demand. Whether the user has 1 domain installed or
 100, this skill is the single entry point.
 
+## Core Principle: No KDNA is better than wrong KDNA
+
+Loading a mismatched domain is not just "unhelpful" — it is harmful.
+It produces **Judgment Contamination**: the agent classifies problems
+incorrectly, assigns wrong priorities, applies wrong risk models, and
+offers wrong recommendations — all with the false confidence of having
+"loaded expert judgment."
+
+*No KDNA*: the agent uses model capability, tools, MCP, project files,
+and normal prompts. It may lack domain-specific judgment, but it is
+not polluted by incorrect judgment.
+
+*Wrong KDNA*: the agent applies a mismatched framework — e.g., diagnosing
+a website design task through a team management lens, or treating a
+price question as an editing issue. The output is worse than baseline.
+
+**When in doubt, skip.** This is the first law of KDNA routing.
+
 ---
 
 ## Part 1 — Decide whether KDNA applies at all
@@ -59,19 +77,23 @@ The user should never see "I considered loading KDNA but didn't."
 Do **not** assume any specific domains exist. Ask the CLI every time.
 
 ```bash
-kdna available --json
+kdna load <file.kdna> --profile=index --as=json
+```
+
+When an MCP runtime is available, use:
+
+```text
+kdna.available-local
 ```
 
-Returns a compact JSON array — one entry per installed domain — with:
-`name`, `version`, `judgment_version`, `status`, `description`,
-`core_insight`, `keywords`, `applies_when` (flattened across all
-axioms), `does_not_apply_when` (flattened), `failure_risks`. Yanked
-domains are excluded automatically.
+The current v1 path discovers local `.kdna` files or v1 source
+directories, then inspects their index profile. Legacy installations may
+also expose `kdna available --json`; treat that as a compatibility path,
+not the v1 source of truth.
 
-This is your **only** discovery interface. Do not inspect `~/.kdna/packages/` manually, unzip `.kdna` files,
-or `cat` internal JSON entries directly — the CLI is the supported contract
-between this skill and the KDNA file format. The on-disk layout may
-change; `kdna available` will not.
+The supported contract is the CLI/MCP loader, not hand-reading internal
+JSON files. Do not inspect `~/.kdna/packages/` or `cat` payload files
+directly unless the user explicitly asks for debugging.
 
 If the command returns `[]` or fails (CLI not installed) → no KDNA
 available → answer normally, mention installation only if the user is
@@ -81,12 +103,13 @@ asking about KDNA itself.
 
 ## Part 3 — Evaluate fit (per candidate domain)
 
-`kdna available --json` already gave you each domain's `applies_when`
-and `does_not_apply_when` (flattened across all axioms). For each
-domain in the list, decide whether it fits the current task by
-**reading the language**, not by token matching.
+The index profile or MCP local inventory gives you each domain's title,
+summary, keywords, and profile availability. For each candidate, load
+the compact profile only after the task plausibly fits. Decide whether
+it fits by **reading the language**, not by token matching.
 
-For a hint signal (optional, low-trust), you can also call:
+For a hint signal (optional, low-confidence), legacy installations may
+also support:
 
 ```bash
 kdna match "<task in user's own words>" --json
@@ -124,18 +147,27 @@ what you'd produce if you loaded the domain? If yes, skip it.
 
 ---
 
-## Part 4 — Selection
+## Part 4 — Selection (7-State Router)
 
-After evaluating, you should usually have:
+After evaluating against `applies_when`, `does_not_apply_when`, and
+`failure_risks`, classify into one of 7 states:
 
-- **0 fits** → do not load KDNA. Answer normally.
-- **1 fit** → load it.
-- **2+ fits** → prefer the narrowest match. If two domains take
-  genuinely different stances on the task, surface the choice:
-  > "Two installed domains could apply here: @aikdna/writing
-  > (structural diagnosis) and @yourorg/copy_polish (line-level
-  > polish). Which judgment frame should I use?"
-  > Do **not** silently blend.
+| State | Condition | Action |
+|-------|-----------|--------|
+| **SKIP_NO_JUDGMENT_NEEDED** | Task is mechanical: format, translate, lookup, execute | Answer normally. Do not mention KDNA. |
+| **SKIP_NO_LOCAL_DOMAIN** | Task may need judgment, but no installed domain covers it | Answer normally. Only mention KDNA if user explicitly asks. |
+| **SKIP_WEAK_FIT** | A domain is weakly related but insufficiently matches | Answer normally. Trace notes "weak match, skipped." |
+| **REJECT_NEGATIVE_MATCH** | A domain's `does_not_apply_when` explicitly excludes this task | Block loading. Respect the author's boundary. |
+| **ASK_AMBIGUOUS_DOMAIN** | 2+ domains could apply but with different judgment frameworks | Ask user to choose. Do **not** silently blend. |
+| **LOAD_STRONG_FIT** | One local domain strongly matches and validates | Load it. |
+| **BLOCK_INTEGRITY_FAILED** | Domain matches but validation, checksum, parsing, or runtime loading fails | Block loading. Notify if appropriate. |
+
+**Rule: Negative Match First.** Check `does_not_apply_when` before
+checking `applies_when`. A domain that says "not for visual design"
+must be excluded before evaluating whether it matches "design task."
+
+**Rule: When in doubt, skip.** Weak fit → skip. Ambiguous without
+clear user preference → ask, don't guess. Integrity failure → block.
 
 Never load more than one domain as primary. A secondary domain can
 constrain (e.g. `@aikdna/agent_safety` always advises on irreversible
@@ -143,12 +175,27 @@ actions), but the primary judgment frame is always one.
 
 ---
 
-## Part 5 — Load
+## Part 5 — Plan, then Load (v1 & legacy)
+
+Once selected, ask the runtime for a LoadPlan before loading:
+
+```bash
+kdna plan-load <file.kdna> --json
+```
 
-Once selected, load the domain via the CLI:
+If the LoadPlan does not return `can_load_now=true`, do not load the asset.
+Follow `required_action` and `issues[].code` instead. Remote assets are
+recognized but unsupported until the runtime provides a remote projection
+implementation.
+
+Only after `can_load_now=true`, load the domain via the official KDNA CLI.
+Two paths are supported:
 
 ```bash
-kdna load @scope/name
+kdna load <file.kdna> --profile=compact --as=prompt
+kdna load <source-dir> --profile=compact --as=prompt
+
+Legacy installed domains may still support: kdna load @scope/name
 ```
 
 The default output (`--as=prompt`) is a compact text rendering
@@ -157,17 +204,12 @@ optimized for system-prompt injection: axioms with their
 banned terms, misunderstandings, and self-checks. Typically
 ~30–50% smaller than the raw JSON.
 
-Other output modes:
+Use `--as=prompt` for normal loading. For raw inspection (debugging only):
 
 ```bash
-kdna load @scope/name --as=json   # raw Core + Patterns JSON
-kdna load @scope/name --as=raw    # concatenated raw file contents
+kdna dev decode domain.kdna --reveal
 ```
 
-Use `--as=prompt` for normal loading. Use `--as=json` only when you
-genuinely need to inspect the structure (e.g. user is debugging the
-domain itself).
-
 **Token discipline**: the prompt output already includes everything
 the agent needs to apply judgment. Do not also `cat` the optional
 files (`KDNA_Scenarios.json`, `KDNA_Cases.json`, etc.) unless the
@@ -181,8 +223,8 @@ stages.
 You have now internalized the domain's judgment surface. From this
 point on:
 
-1. **Adopt the axioms as your reasoning frame** — reason _from_
-   them, not _around_ them.
+1. **Adopt the axioms as your reasoning frame** — reason *from*
+   them, not *around* them.
 2. **Honour the boundaries** — for each axiom you'd apply, confirm
    the task is in `applies_when` AND not in `does_not_apply_when`.
 3. **Pre-check failure_risk** — before producing output, ask:
@@ -215,62 +257,16 @@ KDNA does not override:
 
 ---
 
-## Safety & Governance
-
-KDNA domains influence agent judgment. The loader MUST apply safety rules before loading any domain.
-
-### Loading Priority
-
-When KDNA is loaded, the agent MUST respect this priority order:
-
-1. System safety policy (highest — cannot be overridden)
-2. Legal and compliance requirements
-3. User's explicit intent
-4. KDNA domain judgment
-5. Tool/skill instructions (lowest)
-
-KDNA MUST NOT override system safety policies, legal requirements, or the user's explicit refusal to apply domain judgment.
-
-### Risk-Level Checks
-
-Before loading a KDNA domain, check its risk level in `kdna.json` or `KDNA_CARD.json`:
-
-| Risk Level          | Loading Behavior                               |
-| ------------------- | ---------------------------------------------- |
-| **R0** (Low)        | Load silently                                  |
-| **R1** (Medium)     | Load silently; log                             |
-| **R2** (High)       | Warn user before loading; require confirmation |
-| **R3** (Restricted) | Reject loading unless explicitly authorized    |
-
-### Signature & Trust Checks
-
-- Yanked domains: **REJECT** loading (domain has been withdrawn for safety)
-- Deprecated domains: warn; suggest replacement if `replaced_by` is set
-- Unsigned domains: warn; load only if user confirms
-- Unknown scope domains: warn; load only if user confirms
-
-### Runtime Logging
-
-Every KDNA load MUST be logged with:
-
-- Domain name and version
-- Risk level
-- Signature status
-- Which axioms were triggered
-- Which misunderstandings were avoided
-- Self-check pass rate
-
-This enables audit and accountability.
-
 ## Failure handling
 
-| Situation                                              | What to do                                                                                                                    |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
-| `kdna` CLI not installed                               | Skip KDNA. Answer normally. Mention installation only if user asks about KDNA itself.                                         |
-| `kdna available --json` returns `[]`                   | No domains installed. Skip KDNA.                                                                                              |
-| `kdna load <name>` exits non-zero                      | That domain is broken (yanked, missing files, parse error). Try next candidate or skip KDNA. The error message tells you why. |
-| User explicitly asks for a domain that isn't installed | Tell them, suggest `kdna install <name>`. Do not fabricate the domain.                                                        |
-| Two domains' stances directly conflict on the task     | Surface to user. Do not blend.                                                                                                |
+| Situation | What to do |
+|---|---|
+| `kdna` CLI not installed | Skip KDNA. Answer normally. Mention installation only if user asks about KDNA itself. |
+| No local v1 assets are found | No domains installed. Skip KDNA. |
+| `kdna plan-load <asset>` returns `can_load_now=false` | Do not load. Follow `required_action` and `issues[].code`. |
+| `kdna load <name>` exits non-zero | That domain is broken (validation, authorization, parse, or runtime loading failure). Try next candidate or skip KDNA. The error message tells you why. |
+| User explicitly asks for a domain that isn't installed | Tell them, suggest `kdna install <name>`. Do not fabricate the domain. |
+| Two domains' stances directly conflict on the task | Surface to user. Do not blend. |
 
 ---
 
@@ -293,11 +289,12 @@ Otherwise, stay silent about the loading mechanics.
 
 ## What this skill is NOT
 
-- Not a list of available KDNA domains (those are installed `.kdna` assets, discovered on demand)
-- Not a registry browser (use `kdna list --available` CLI)
-- Not a domain creator. Agents may draft judgment proposals, but trusted `.kdna`
-  assets must be Human Locked and compiled by KDNA Studio or a
-  Studio-compatible compiler.
+- Not a list of available KDNA domains (those are installed `.kdna` assets,
+  discovered on demand through the CLI)
+- Not a registry browser. Legacy registry commands are compatibility-only.
+- Not a domain creator. Agents may draft judgment proposals or candidate cards,
+  but formal `.kdna` assets are created through the official KDNA Studio toolchain.
+  compile/export.
 - Not an auto-loader that runs on every request — you decide per
   request whether the task needs KDNA at all
 

package/src/cli.js

@@ -89,6 +89,8 @@ Start here:
 Core v1:
   inspect  <path>                   Inspect v1 source dir or .kdna container
   validate <path>                   Validate v1 source dir or .kdna container
+  plan-load <path>                  Return a LoadPlan before runtime load
+                                  Add --has-password or --entitlement-status for diagnostics
   pack     <src> <out>              Deterministic pack into .kdna container
   unpack   <in>  <out>              Extract .kdna container
 
@@ -109,6 +111,8 @@ function showHelpAdvanced() {
 Core v1:
   inspect  <path>                   Inspect v1 source dir or .kdna container
   validate <path>                   Validate v1 source dir or .kdna container
+  plan-load <path> [--has-password] [--entitlement-status <status>]
+                                  Return a LoadPlan before runtime load
   pack     <src> <out>              Deterministic pack into .kdna container
   unpack   <in>  <out>              Extract .kdna container
   demo     minimal <dir> [--force]  Create a minimal v1 fixture
@@ -271,6 +275,33 @@ switch (cmd) {
     );
     break;
   }
+  case 'plan-load': {
+    const v1Target = args.filter((a) => !a.startsWith('--'))[1];
+    if (!v1Target) error('Usage: kdna plan-load <path> [--json] [--has-password] [--entitlement-status <status>]', EXIT.INPUT_ERROR);
+    const core = require('@aikdna/kdna-core');
+    const abs = require('node:path').resolve(v1Target);
+    if (!(core.isV1SourceDir(abs) || core.detectContainerFormat(abs) === 'v1')) {
+      error('plan-load requires a KDNA Core v1 source dir or .kdna container', EXIT.INPUT_ERROR);
+    }
+    if (typeof core.planLoad !== 'function') {
+      error(
+        'kdna plan-load requires @aikdna/kdna-core with the LoadPlan v1 API. Update @aikdna/kdna-core before enabling runtime authorization diagnostics.',
+        EXIT.PROVIDER_ERROR,
+      );
+    }
+    const entitlementStatusIndex = args.indexOf('--entitlement-status');
+    const entitlementStatus = entitlementStatusIndex >= 0 ? args[entitlementStatusIndex + 1] : null;
+    const allowedEntitlementStatuses = new Set(['active', 'expired', 'revoked', 'offline_grace']);
+    if (entitlementStatusIndex >= 0 && !allowedEntitlementStatuses.has(entitlementStatus)) {
+      error('Invalid --entitlement-status. Use active, expired, revoked, or offline_grace.', EXIT.INPUT_ERROR);
+    }
+    const plan = core.planLoad(v1Target, {
+      hasPassword: args.includes('--has-password'),
+      entitlement: entitlementStatus ? { status: entitlementStatus } : undefined,
+    });
+    console.log(JSON.stringify(plan, null, 2));
+    process.exit(plan.state === 'invalid' ? 1 : 0);
+  }
   case 'pack': {
     const v1Target = args.filter((a) => !a.startsWith('--'))[1];
     if (v1Target) {

package/templates/standard-domain/USAGE.md

@@ -45,8 +45,9 @@ kdna verify ./.
 
 # 7. Export and verify the local v1 asset
 KDNA_IDENTITY_DIR=~/.kdna/identity-official \
-  kdna validate ./dist/your-domain.kdna
+  kdna validate ./dist/your-domain.kdna --runtime
 
+kdna plan-load ./dist/your-domain.kdna --json
 kdna load ./dist/your-domain.kdna --profile=compact --as=prompt
 ```