renma 0.18.1 → 0.18.3

package/docs/internal-architecture.md

@@ -0,0 +1,296 @@
+# Renma Internal Architecture
+
+This document describes the implemented internal architecture for the 0.18.3
+maintainability release. It is contributor guidance, not a new CLI or JSON
+contract. Renma 0.18.2 remains the behavioral baseline: internal types and
+module boundaries may become clearer, but public fields, classifications,
+diagnostics, severities, exit behavior, and migration direction must not change
+as a side effect.
+
+The high-level product boundary remains in [Architecture](../architecture.md).
+Stable classification and decision fields are documented in the
+[Diagnostics Reference](diagnostics.md), and the versioned BOM contract is in
+[Repository Context BOM](repository-context-bom.md).
+
+## Dependency Flow
+
+```text
+repository files + config
+        |
+        v
+discovery + parsing + repository resolution
+        |
+        v
+RepositorySnapshot (facts and snapshot-scoped indexes)
+        |
+        +--> scan + graph --> Readiness --> BOM
+        |
+        v
+target evidence --> governance evidence --> command decision --> renderer
+```
+
+Dependencies should continue to point from low-level parsing and resolution to
+evidence, then to decisions, renderers, and command orchestration. A lower-level
+module must not import a command renderer. Commands coordinate these layers;
+they should not independently reinterpret repository layout.
+
+The dependency direction is checked in CI. Type-only imports are treated as
+architectural dependencies, so lower layers must not import command or renderer
+modules even when the import is erased at runtime.
+
+## RepositorySnapshot Is the Repository Evidence Source
+
+`collectRepositorySnapshot` in `src/repository-evidence.ts` performs one
+repository collection and creates the shared in-memory source of repository
+facts. The snapshot contains:
+
+- resolved root, configuration, configuration path, and scan count;
+- discovered artifacts and parsed documents;
+- the normalized catalog, Context Lens summary, and diagnostic partitions;
+- repository-relative paths and their captured filesystem states;
+- structural classification evidence indexed by repository-relative path;
+- a parent-Skill index used for exact parent resolution;
+- effective security-policy evidence with its provenance.
+
+The indexes belong to the snapshot. Consumers should reuse them instead of
+reparsing files or rebuilding command-specific lookup tables. A new projection
+should normally accept `RepositorySnapshot`, or the narrowest existing
+projection of it, rather than perform another discovery pass.
+
+`RepositorySnapshot` does not freeze the working tree. It records what one
+collection read, after which downstream projections operate on that collected
+state. In particular, Readiness builds its graph and scan from one snapshot,
+and BOM builds its graph, scan, Readiness evidence, policy inventory, and
+diagnostics from one snapshot. This prevents one command result from combining
+independently recollected repository states.
+
+`collectRepositoryEvidence` is a narrower compatibility projection for
+consumers such as catalog and graph. It deliberately omits parsed documents,
+sets, maps, and indexes that are implementation details.
+
+## Structural And Repository-Backed Resolution
+
+Resolution stages answer different questions and must remain separate.
+
+### Repository boundary
+
+`repositoryClassificationPath` determines whether a target can be expressed
+relative to one safe repository root. Evidence is considered in this order:
+
+1. an explicit repository root;
+2. the nearest valid `.git`, `renma.config.json`, or `.renma.json` marker;
+3. an unambiguous strong structural boundary such as `skills`, `.agents`,
+   `contexts`, `context`, `lenses`, or `tools`, plus recognized root files such
+   as `AGENTS.md`;
+4. an unresolved or ambiguous result.
+
+Current-working-directory containment is not proof of a repository boundary.
+Renma may be invoked from a parent workspace, and a target may be absolute or
+belong to a neighboring repository. Traversal outside an explicit root is
+rejected instead of being normalized into that root.
+
+The names `profiles`, `references`, `examples`, `scripts`, and `assets` are
+negative guard evidence only. They can make a later structural interpretation
+ambiguous, but they never establish a repository root by themselves. Once an
+outer strong boundary has a recognized interpretation, nested boundary-like
+names do not replace it.
+
+### Structural classification
+
+`classifyAssetPath` consumes only a normalized repository-relative path and,
+where relevant, parsed metadata type. It produces path interpretation such as
+`kind`, `scope`, `matchedRule`, `reasonCode`, `recognizedRoot`, competing rules,
+ignored nested segments, and a possible parent-Skill path.
+
+For Skill-local support, structural placement yields
+`parentResolution: "structural-candidate"`. This means only that the path has a
+canonical Skill-local shape. It does not prove that the candidate file exists,
+is unique, owns the support file, or supplies policy.
+
+### Repository-backed enrichment
+
+`buildSkillParentIndex` records all discovered Skill entrypoint candidates by
+logical Skill directory. `resolveSkillSupportParent` then returns `resolved`
+only when exactly one candidate exists; zero candidates are `missing`, and
+multiple candidates are `ambiguous`. `withResolvedSkillParent` attaches that
+result without changing the original structural kind or scope.
+
+Snapshot construction creates this parent index before catalog construction and
+passes the same instance into `buildCatalog`. Catalog ownership, target parent
+resolution, and governance enrichment therefore share one snapshot-scoped
+source rather than reconstructing equivalent indexes independently. The public
+`buildCatalog(documents, repositoryPaths)` call remains compatible and creates
+an index for standalone callers.
+
+Ownership, policy, catalog membership, and relationships also require
+repository evidence. None of them may be manufactured from path shape alone.
+
+## Shared Target Evidence
+
+`inspect` and `suggest-metadata` share the target-evidence pipeline in
+`src/evidence/target.ts`:
+
+- `collectTargetDocumentEvidence` reads one target, resolves its repository
+  boundary, parses it, and builds structural classification evidence.
+- `collectTargetRepositoryEvidence` collects the resolved repository snapshot
+  and enriches the target with catalog membership, parent resolution, policy,
+  and governance evidence.
+
+The two stages remain separate because a readable file does not guarantee a
+resolvable repository. When repository collection is unavailable, the target
+retains structural evidence but does not fall back to guessed catalog identity,
+parentage, ownership, or policy.
+
+Unavailable evidence preserves the exact boundary result:
+`repository-boundary-unresolved` and `repository-boundary-ambiguous` remain
+distinct, while a failure after a root resolves is `snapshot-unavailable`.
+
+## Classification, Governance, And Decisions
+
+These evidence layers are related, but none is a substitute for another.
+
+| Layer | Answers | Does not prove |
+| --- | --- | --- |
+| Classification | What repository path rule matched, what kind and scope result, and whether a structural or resolved parent is known | Ownership, policy, authority, or human intent |
+| Governance | Whether ownership and policy are declared, inherited, or missing, including provenance | That a proposed edit is applicable |
+| Decision | Whether a command result is deterministic, requires confirmation, is blocked, or recommends no change | A different path classification or permission to discard evidence |
+
+Ownership is explicit governance evidence. A declared local owner remains
+declared. A Skill-local file may inherit an effective owner only from exactly
+one resolved parent Skill that declares an owner. Missing or ambiguous parents
+remain unowned. Renma never derives ownership from directory names, prose, Git
+authors, or modification history.
+
+Policy provenance is tracked separately from ownership provenance. A local
+policy must not be relabeled as inherited, and an absent effective policy stays
+missing. Likewise, Renma does not infer that local support should be promoted,
+that an independent asset should be created, or that a maintainer intended an
+owner or lifecycle value. Those are human repository-design decisions.
+
+## Decisions, Renderers, And Commands
+
+Decision construction belongs in `src/decisions/`. A decision object carries
+the authoritative `decisionStatus`, stable reason code, summary, and any
+remaining human question. Candidate construction must honor that status before
+anything is presented as an applicable edit.
+
+Metadata suggestion uses pure builders in
+`src/decisions/metadata-suggestion.ts` for Skill migrations, Skill-local parent
+and governance states, unsupported targets, owner conflicts, and independent
+metadata candidates. The command retains filesystem collision checks,
+candidate assembly, next-action construction, and orchestration.
+
+Renderers in `src/renderers/` turn an already-decided result into human text.
+They may improve wording and layout, but they must not rediscover a parent,
+infer governance, change applicability, or create candidate data. JSON output
+serializes the command result directly; it is not reconstructed from rendered
+text.
+
+Command modules should stay orchestration-oriented:
+
+```text
+collect context -> build evidence -> decide -> render or serialize
+```
+
+A `no-change-recommended` decision is a successful result. It means Renma
+completed the analysis and found no supported change. The command must not
+manufacture metadata, a migration, or verification work merely to return an
+edit-shaped response.
+
+## Public JSON And Internal Working Types
+
+Public machine-readable output is protected at the serialized command boundary.
+Fields such as classification evidence, governance provenance,
+`decisionStatus`, command invocation `command` and `args`, and established
+diagnostic fields must remain compatible with 0.18.2.
+
+Internal working types have a different role. `RepositorySnapshot`, parsed
+documents, `ReadonlyMap` indexes, `ReadonlySet` repository paths, and
+intermediate target-resolution unions exist to keep implementation states
+explicit. They are not public JSON merely because they are TypeScript types.
+They may be narrowed or reorganized when behavior-focused tests prove that the
+serialized contract is unchanged.
+
+Inspect renderer DTOs live in `src/evidence/inspect.ts`, so renderers do not
+depend on command modules. `src/commands/inspect.ts` re-exports the established
+types to preserve existing TypeScript deep imports.
+
+Human-readable reasons and prompts may evolve unless a test intentionally
+protects exact wording. Stable branching must use typed fields such as
+`matchedRule`, `reasonCode`, `parentResolution`, ownership provenance, and
+`decisionStatus`, not prose parsing.
+
+## Intentional 0.18.2 Compatibility Seams
+
+Two parallel-looking paths remain intentional in 0.18.3.
+
+### Scan keeps structural parent evidence
+
+The snapshot classification index used to annotate scan findings and
+diagnostics is structural. A Skill-local scan detail may therefore retain
+`parentResolution: "structural-candidate"`. Target-oriented commands such as
+`inspect` and `suggest-metadata` enrich the same structural classification with
+snapshot-backed `resolved`, `missing`, or `ambiguous` parent evidence.
+
+Do not silently make scan annotations repository-enriched merely to make the
+implementations look uniform. The distinction preserves the 0.18.2 public
+diagnostic shape; changing it requires an explicit contract decision and
+characterization tests.
+
+### Blocked migrations retain partial diagnostic maps
+
+A blocked Agent Skills migration may retain partial
+`candidateAgentSkillsFields` and `candidateRenmaMetadata` maps. These fields are
+diagnostic evidence retained for 0.18.2 JSON compatibility, not an applicable
+patch.
+
+`decisionStatus` is authoritative. A frontmatter migration is applicable only
+when the decision is not blocked and `canonicalFrontmatter` is present.
+Blocked results must not expose canonical frontmatter or renderer patch
+instructions, and consumers must never treat the partial candidate maps as an
+override of the gate.
+
+## Fail-Closed Boundaries
+
+The following constraints are safety and compatibility invariants:
+
+- An unresolved or ambiguous repository boundary produces no guessed root,
+  catalog identity, inherited governance, or executable repository action.
+- Guard directory names are never positive repository-root evidence.
+- Repository discovery does not follow symbolic links, and a symbolic-link
+  marker does not establish a boundary.
+- Structural Skill-local placement never establishes inheritance by itself.
+- A missing or ambiguous parent supplies neither inherited ownership nor
+  inherited policy.
+- Explicit local governance is preserved as local governance.
+- A blocked decision suppresses applicable candidate metadata and canonical
+  frontmatter; renderers cannot reopen the decision.
+- A no-change decision produces no synthetic work.
+
+When one of these states looks inconvenient, preserve it and improve the
+evidence presented to the maintainer. Do not replace uncertainty with a guess.
+
+## Runtime Boundary
+
+Renma analyzes declared repository state. It does not execute Skills, select a
+Skill for a live task, assemble prompts, invoke Skill tools, observe model runs,
+or collect runtime telemetry. Static instructions and policies are evidence
+about repository content; they are not proof of runtime behavior.
+
+Future runtime signals may be imported as a separate, explicitly versioned
+evidence artifact linked to a repository snapshot or BOM. Signal production,
+collection, storage, and Skill execution remain outside this architecture.
+
+## Contributor Checklist
+
+For an internal change:
+
+1. Add or confirm a behavior-focused test for the 0.18.2 result.
+2. Reuse the snapshot and shared resolution paths before adding another
+   collector or index.
+3. Keep structural facts, repository-backed governance, decisions, and
+   rendering in their respective layers.
+4. Verify stable JSON fields and fail-closed states, not only human text.
+5. For Readiness or BOM changes, prove all derived sections use one snapshot.
+6. Run targeted tests, type checking, linting, the full test suite, build, and
+   package verification before release.

package/docs/user-manual.md

@@ -73,17 +73,20 @@ support paths:
 
 The same reserved names apply under `.agents/skills/**`.
 
-These Skill-local support directories are valid. Keep material local when it is
-specific to one Skill. Promote reusable source-of-truth knowledge to an owned
-Context Asset, or a helper shared across workflows to `tools/**`, only when
-repository evidence supports that change; Renma does not move files
+These valid support paths are structurally Skill-local. Keep material local when
+it is specific to one Skill. Promote reusable source-of-truth knowledge to an
+owned Context Asset, or a helper shared across workflows to `tools/**`, only
+when repository evidence supports that change; Renma does not move files
 automatically.
 
-Skill-local support belongs only to the nearest Skill directory. When a local
-support artifact does not declare an owner, ownership, Readiness, graph, Trust
-Graph, and BOM reporting use the nearest Skill's owner as deterministic
-effective ownership and mark it as inherited. This does not invent ownership
-for shared Context Assets or unrelated repository files.
+Renma claims a parent only after repository evidence resolves exactly one Skill
+entrypoint. When that resolved local support artifact does not declare an owner,
+ownership, Readiness, graph, Trust Graph, and BOM reporting may use the parent
+Skill's owner as deterministic effective ownership and mark it as inherited.
+Missing or ambiguous parents never inherit. See
+[classification evidence](diagnostics.md#how-to-read-classification-evidence)
+for the detailed contract. This does not invent ownership for shared Context
+Assets or unrelated repository files.
 
 Only files marked Markdown-parser eligible contribute frontmatter metadata,
 headings, links, code fences, and repeated-context evidence. Text scripts and
@@ -162,6 +165,61 @@ Review the Skill with this platform's standard Skill authoring guidance, then us
 Start by running `renma --help` and use command-specific help to choose the appropriate workflow. Make only evidence-backed changes. Do not invent owners, references, product rules, or source-of-truth claims. Preserve existing semantics unless a diagnostic or explicit requirement supports a change. Run `renma scan . --fail-on high` after editing, fix relevant diagnostics, rerun it, and summarize both resolved and remaining findings.
 ```
 
+Recommended evidence-first preflight:
+
+1. Run `renma scan . --fail-on high --format json`.
+2. Run `renma inspect <SKILL.md> --format json`.
+3. Inspect relevant local resources and referenced Context Assets.
+4. Use `renma suggest-metadata` only when retrofit or migration evidence exists.
+5. Prepare the smallest intended patch.
+6. Rerun `renma scan . --fail-on high --format json`.
+7. Stop without manufacturing work when `suggest-metadata` reports
+   `decisionStatus: "no-change-recommended"`; this currently uses
+   `suggestedMode: "no-proposal"`.
+8. Report unresolved human decisions.
+
+For one classification question, `renma inspect <target> --format json` may be
+the initial preflight. Repository-wide work should normally start with `scan`.
+
+## Context Asset Discovery Boundary
+
+`contexts/**` is the preferred independent Context Asset root and `context/**`
+remains supported. Nested directory names never override a recognized root.
+Files under canonical Skill `references/`, `profiles/`, `examples/`, `scripts/`,
+and `assets/` directories are structurally Skill-local. Renma claims one parent
+and possible inherited governance only after repository evidence resolves
+exactly one Skill under `skills/**` or `.agents/skills/**`. Supported explicit
+local metadata remains valid but is not required. See
+[classification evidence](diagnostics.md#how-to-read-classification-evidence)
+for the detailed contract.
+
+Top-level `references/**` is not a Context root. `tools/**` contains shared
+repository implementation, not Context knowledge, and `skills/**/tools/**` is
+not a canonical local support directory. Skill-local executable support belongs
+under `scripts/`.
+
+```text
+contexts/foo/references/policy.md
+  -> independent Context Asset
+
+skills/foo/references/policy.md
+  -> Skill-local Reference
+
+references/policy.md
+  -> outside the Context root
+
+tools/helper.mjs
+  -> repository implementation
+
+skills/foo/tools/helper.mjs
+  -> not canonical Skill-local support
+```
+
+Placement as independent Context is a human decision about ownership,
+lifecycle, reuse, and source of truth. Classification after placement is
+deterministic. Renma never moves a file based on content. A successful
+`no-proposal` result means no edit should be manufactured.
+
 ## User Story: Create A New Skill With Scaffold
 
 Use this flow when adding a new agent-facing Skill. Platform-native guidance
@@ -640,7 +698,19 @@ renma inspect contexts/testing/boundary-value-analysis.md --format json
 renma inspect skills/testing/spec-review/SKILL.md --lines L10-L42
 ```
 
-Use this when editing one skill or context file and you want a deterministic outline without reading the whole repository catalog. Without `--lines`, output includes file size, line count, frontmatter range, headings, code fences, links, asset relationships, and a concise Context Lens governance summary when repository context can be inferred. Use `--lines <range>` for an exact source slice; ranges can look like `L10-L42` or `10-42`.
+Use this when editing one skill or context file and you want a deterministic outline without reading the whole repository catalog. Without `--lines`, output includes file size, line count, frontmatter range, headings, code fences, links, asset relationships, and a concise Context Lens governance summary when repository context can be inferred. It also always includes `classification` with `kind`, `scope`, `matchedRule`, `reasonCode`, root or parent evidence, and concise competing rules. A Skill-local path exposes `parentAssetCandidatePath`; `parentAssetPath` appears only when `parentResolution` is `resolved`, while `missing` and `ambiguous` remain explicit fail-closed states. `governance` is separate and reports ownership, policy, and metadata provenance only from repository evidence. Unknown files and repository tools still receive classification. Use `--lines <range>` for an exact source slice; ranges can look like `L10-L42` or `10-42`. `--lines` output itself is unchanged.
+
+JSON also includes `repositoryBoundary`. Resolved results record the root,
+repository-relative path, and resolution source. Unresolved results retain a
+stable reason code and `candidateRoots`; structural ambiguity uses
+`repository-boundary-ambiguous` instead of selecting a broad ancestor.
+
+For a file target, Renma resolves a repository root from an explicit caller root,
+the nearest safe `.git` file/directory or Renma config marker, or an unambiguous
+structural boundary, in that order. Current-working-directory containment alone
+does not establish a repository. This keeps nested repositories and absolute
+targets outside the current directory deterministic without scanning an
+unrelated parent tree.
 
 ### `readiness`
 
@@ -763,7 +833,17 @@ workflow, constraints, and completion criteria with platform-native guidance;
 apply only intended metadata or migration changes; run
 `renma scan . --fail-on high`; fix relevant diagnostics; and rerun the scan.
 Context Asset output does not receive this Skill-specific authoring guidance.
-JSON retains the existing structured suggestion shape.
+JSON adds `classification`, `decisionStatus`, structured `decision` evidence,
+and safe `nextActions` to the existing suggestion fields. Each action has
+`kind` and `invocation`; execute `invocation.command` with the exact
+`invocation.args` array. `invocation.display` is for people and must not be
+parsed as the machine contract, including on paths with spaces, quotes, or
+Windows separators.
+
+When no repository root resolves, `decisionStatus` is `blocked` and Renma does
+not emit an executable `scan .` action. Establish the repository root with an
+explicit root or repository marker before verification; the caller's current
+directory is not assumed to contain the target.
 
 For Skill targets using the pre-0.16 Renma Skill format, the 0.16.0 metadata
 migration path is one-way: recognized governance and security frontmatter
@@ -771,6 +851,8 @@ becomes Agent Skills identity plus `metadata.renma.*`. Separately, `skill.md` an
 report any required entrypoint rename or move, even when their frontmatter
 already uses Agent Skills fields. For a canonical Agent Skill, `--owner` may
 instead propose an owner metadata retrofit; it never causes reverse migration.
+Skill migration `sourcePath` and `targetPath` values are repository-relative,
+including when the user invokes Renma from the parent of a nested repository.
 The normative behavior is documented in
 [Agent Skills Compatibility and Migration](agent-skills-compatibility.md).
 
@@ -785,7 +867,35 @@ invalid evidence, confirm the Skill's intent with platform-native authoring
 guidance, correct the source evidence, rerun `suggest-metadata`, then validate
 intended corrections with `renma scan . --fail-on high`.
 
-Owner metadata remains recommended but not required. Without `--owner`, `suggest-metadata` blocks owner as a suggested addition and says not to add one unless the asset already declares an owner or a maintainer provides one. With `--owner <owner>`, the command may include that owner because it was explicitly provided. If an existing asset already declares an owner, `suggest-metadata` preserves it; a different `--owner` value is treated as a human-review ownership change, not an automatic metadata suggestion. Renma does not infer owners from Git history, file paths, prose, or authors.
+Owner metadata remains recommended but not required. Without `--owner`, Renma
+does not invent an owner. With `--owner <owner>`, the command may include that
+owner because it was explicitly provided. If an existing asset already
+declares an owner, `suggest-metadata` preserves it; a different `--owner` value
+is treated as conflicting evidence and blocks a candidate. Renma does not infer
+owners from Git history, file paths, prose, or authors.
+If the explicit owner equals the existing canonical `metadata.renma.owner`, the
+result is `suggestedMode: "no-proposal"` with
+`decisionStatus: "no-change-recommended"`; no candidate metadata, canonical
+frontmatter, or patch instruction is emitted.
+
+Ordinary Skill-local support returns `suggestedMode: "no-proposal"` and
+`decisionStatus: "no-change-recommended"` when it can inherit governance from
+one resolved parent Skill. Its `candidateMetadata` is empty. A missing or
+ambiguous parent returns `decisionStatus: "blocked"`, leaves governance
+unowned or unresolved, and provides a scan/layout action instead of claiming
+inheritance. Existing explicit local owner or policy metadata is preserved
+under `skill-local-existing-metadata-preserved`; an explicit `--owner` can still
+request a supported intentional override after the parent resolves. Prompt and
+JSON output both distinguish the observed path fact, deterministic
+interpretation, recommendation, and remaining human decision. Repository tools
+and unknown paths never receive fabricated Context metadata candidates.
+
+`decisionStatus` is authoritative: `blocked` never authorizes a patch,
+`no-change-recommended` stops without a patch, `human-confirmation-required`
+identifies what must be confirmed before applying only the candidate fields,
+and `deterministic` permits the reviewed candidate. Consumers should include a
+conservative default for unknown future `suggestedMode` values rather than
+assuming every non-`no-proposal` value is applicable.
 
 ### `suggest-semantic-split`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renma",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Manage human-curated context assets for LLMs and agents in Git.",
   "license": "MIT",
   "repository": {

package/scripts/verify-package.mjs

@@ -1,25 +1,53 @@
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
 
-const cache = await mkdtemp(path.join(os.tmpdir(), "renma-npm-pack-"));
+const temporaryRoot = await mkdtemp(
+  path.join(os.tmpdir(), "renma package verification-"),
+);
+const packDirectory = path.join(temporaryRoot, "packed artifact");
+const consumerDirectory = path.join(temporaryRoot, "clean consumer");
+const cacheDirectory = path.join(temporaryRoot, "npm cache");
 
 try {
+  await mkdir(packDirectory, { recursive: true });
+  await mkdir(consumerDirectory, { recursive: true });
+  await mkdir(cacheDirectory, { recursive: true });
   const packed = spawnSync(
     "npm",
-    ["pack", "--dry-run", "--json", "--cache", cache],
+    [
+      "pack",
+      "--json",
+      "--cache",
+      cacheDirectory,
+      "--pack-destination",
+      packDirectory,
+    ],
     { cwd: process.cwd(), encoding: "utf8" },
   );
-  if (packed.error) throw packed.error;
+  if (packed.error) {
+    throw new Error(`npm pack failed: ${packed.error.message}`);
+  }
   if (packed.status !== 0) {
-    throw new Error(packed.stderr.trim() || "npm pack --dry-run failed.");
+    throw new Error(
+      `npm pack failed: ${packed.stderr.trim() || `exit code ${packed.status}`}`,
+    );
   }
 
-  const reports = JSON.parse(packed.stdout);
+  let reports;
+  try {
+    reports = JSON.parse(packed.stdout);
+  } catch {
+    throw new Error("npm pack failed: npm returned invalid JSON output.");
+  }
   const report = reports[0];
   if (!report || !Array.isArray(report.files)) {
-    throw new Error("npm pack --dry-run returned no package file list.");
+    throw new Error("npm pack returned no package file list.");
+  }
+  if (typeof report.filename !== "string" || report.filename.length === 0) {
+    throw new Error("npm pack returned no tarball filename.");
   }
   const files = new Set(report.files.map((file) => file.path));
 
@@ -27,6 +55,17 @@ try {
     "package.json",
     "README.md",
     "dist/index.js",
+    "dist/types.js",
+    "dist/types.d.ts",
+    "dist/discovery.js",
+    "dist/discovery.d.ts",
+    "dist/commands/inspect.js",
+    "dist/commands/inspect.d.ts",
+    "dist/commands/suggest-metadata.js",
+    "dist/commands/suggest-metadata.d.ts",
+    "dist/skill-migration.js",
+    "dist/skill-migration.d.ts",
+    "docs/internal-architecture.md",
     "docs/trust-graph.md",
     "docs/schemas/repository-context-bom-v2.schema.json",
     "docs/schemas/trust-graph-v2.schema.json",
@@ -62,11 +101,117 @@ try {
     }
   }
 
+  const tarballPath = path.resolve(packDirectory, report.filename);
+  const packageRoot = await installInTemporaryConsumer(
+    consumerDirectory,
+    tarballPath,
+    cacheDirectory,
+  );
+  await verifyInspectDeclarationCompatibility(packageRoot);
+  for (const modulePath of [
+    "dist/commands/inspect.js",
+    "dist/commands/suggest-metadata.js",
+    "dist/discovery.js",
+    "dist/skill-migration.js",
+  ]) {
+    try {
+      await import(pathToFileURL(path.join(packageRoot, modulePath)).href);
+    } catch (error) {
+      throw new Error(
+        `Deep import failed for ${modulePath}: ${errorMessage(error)}`,
+        { cause: error },
+      );
+    }
+  }
+
   process.stdout.write(
-    `Verified ${files.size} packaged files and every README-relative target.\n`,
+    `Verified ${files.size} packaged files, deep imports, inspect declarations, and every README-relative target.\n`,
   );
 } finally {
-  await rm(cache, { recursive: true, force: true });
+  await rm(temporaryRoot, { recursive: true, force: true });
+}
+
+async function installInTemporaryConsumer(
+  consumerDirectory,
+  tarballPath,
+  cacheDirectory,
+) {
+  await writeFile(
+    path.join(consumerDirectory, "package.json"),
+    `${JSON.stringify(
+      {
+        name: "renma-package-verification",
+        private: true,
+        type: "module",
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  const installed = spawnSync(
+    "npm",
+    [
+      "install",
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      "--package-lock=false",
+      "--cache",
+      cacheDirectory,
+      tarballPath,
+    ],
+    { cwd: consumerDirectory, encoding: "utf8" },
+  );
+  if (installed.error) {
+    throw new Error(
+      `Temporary consumer installation failed: ${installed.error.message}`,
+    );
+  }
+  if (installed.status !== 0) {
+    throw new Error(
+      `Temporary consumer installation failed: ${installed.stderr.trim() || `npm exited with code ${installed.status}`}`,
+    );
+  }
+  const packageRoot = path.join(consumerDirectory, "node_modules", "renma");
+  try {
+    await readFile(path.join(packageRoot, "package.json"), "utf8");
+  } catch (error) {
+    throw new Error(
+      `Temporary consumer installation failed: installed renma package is missing (${errorMessage(error)}).`,
+      { cause: error },
+    );
+  }
+  return packageRoot;
+}
+
+async function verifyInspectDeclarationCompatibility(packageRoot) {
+  const declarations = await readFile(
+    path.join(packageRoot, "dist/commands/inspect.d.ts"),
+    "utf8",
+  );
+  for (const typeName of [
+    "InspectOutline",
+    "InspectAssetSummary",
+    "InspectRelationship",
+    "InspectRelationshipChain",
+    "InspectSlice",
+  ]) {
+    const declared = new RegExp(
+      `export\\s+(?:interface|type)\\s+${typeName}\\b`,
+    ).test(declarations);
+    const reexported = new RegExp(
+      `export\\s+type\\s*\\{[\\s\\S]*?\\b${typeName}\\b[\\s\\S]*?\\}\\s*from`,
+    ).test(declarations);
+    if (!declared && !reexported) {
+      throw new Error(
+        `dist/commands/inspect.d.ts no longer exports ${typeName}.`,
+      );
+    }
+  }
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
 }
 
 function requirePackagedPath(files, target) {