renma 0.18.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renma",
-  "version": "0.18.2",
+  "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) {