Skip to content

v1-contract-decisions.md

Latest commit

 

History

History
235 lines (173 loc) · 8.78 KB

v1-contract-decisions.md

File metadata and controls

235 lines (173 loc) · 8.78 KB
Raw

V1 Contract Decisions

Status: accepted for v1.0.0

Date: 2026-06-05

Context

Before runtime modularization begins, v1 needs explicit decisions for:

  • where public commands may write;
  • how product and graph-schema versions relate;
  • which files form the canonical installed runtime; and
  • which CSS file is authoritative.

The current implementation proves the product loop, but its development conveniences are not yet safe or coherent enough to become the installed-skill contract unchanged.

Implemented write surface

Command or script Current writes Classification
skills/codebase-visualize/scripts/scan.mjs --target <target> fixed graph path public atomic write
skills/codebase-visualize/scripts/render.mjs --target <target> fixed map path public atomic write
skills/codebase-visualize/scripts/visualize.mjs --target <target> fixed graph and map paths public atomic writes
scripts/demo.mjs fixture docs/ai/visualize/* repository development write
scripts/check.mjs disposable package-check writes plus all writes performed by demo.mjs repository validation write
scripts/check-live-target.mjs none; scans an environment-selected local repository with an injected no-op writer optional repository-only smoke check
scripts/check-render-output.mjs none read-only check
scripts/check-ascii.mjs none read-only check

Public commands reject unsupported arguments before writing. Internal APIs can accept injected writers for isolated repository checks without exposing an arbitrary-output public escape hatch.

Decision 1: strict public write boundary

All installed/public runtime commands will use a strict namespace:

<target>/docs/ai/visualize/codebase-graph.json
<target>/docs/ai/visualize/codebase-map.html

Public runtime commands will not accept arbitrary output paths.

Target public command shape:

visualize --target <target>  # scan then render
scan --target <target>       # write the fixed graph path
render --target <target>     # read the fixed graph path and write the fixed map path

The exact executable filenames may change during implementation. The behavioral contract may not.

Enforcement rules

  • Resolve the target and intended output paths before creating directories or writing files.
  • Reject a write when the resolved output is not inside the resolved <target>/docs/ai/visualize/ directory.
  • Reject unsupported custom-output arguments rather than silently ignoring them.
  • Fail with a clear message and non-zero exit status before the first write.
  • Do not leave partial graph or HTML files after a rejected command.

Development-test consequence

Repository-only tests must not preserve an arbitrary-output public escape hatch. They should instead:

  • copy or construct disposable target repositories under the OS temp directory;
  • run public commands against those disposable targets; or
  • call internal testable modules directly when testing serialization or rendering behavior.

Rendering an arbitrary archived graph outside a target namespace is deferred. A future explicit offline-inspection tool may be designed separately if real use demonstrates the need.

Decision 2: version model

V1 uses two independent version lines.

Current version audit

Identifier Current value Current authority
Repository/package version 0.0.1 package.json and package-lock.json
Scanner version 0.2.0 constant in skills/codebase-visualize/lib/scanner.mjs
Renderer version 0.3.3 constant in skills/codebase-visualize/lib/renderer.mjs
Graph schema version 1.0.0 constant in skills/codebase-visualize/lib/scanner.mjs
Repository release tag none no tags currently exist

These independent values describe real development history. Product and schema versioning rules are documented, and the renderer validates schema compatibility and required relationships before writing HTML.

Product/runtime version

One SemVer product version represents the released skill and installed runtime.

skills/codebase-visualize/lib/version.mjs is the target canonical runtime version source. Release tooling and checks must keep package.json, release documentation, generated map presentation, and the release tag aligned with it.

The scanner and renderer do not keep independently managed product versions. Their behavior ships together as one skill package.

Product/runtime version changes:

  • major: incompatible installed-skill or public-command contract change;
  • minor: backward-compatible feature or meaningful behavior addition;
  • patch: backward-compatible fix or documentation/release correction.

Graph schema version

The graph schema has an independent SemVer version because schema compatibility is different from product-release compatibility.

Schema version changes:

  • major: existing consumers cannot safely interpret the graph;
  • minor: backward-compatible fields or semantics are added;
  • patch: clarification or correction that does not change compatible shape.

The stable v1 graph contract is 1.0.0. It was promoted after required fields, relationships, filesystem uncertainty, and compatibility checks were frozen in M3.

Compatibility behavior

  • Generated graphs record both schema_version and producer_version.
  • The v1 renderer supports schema major version 1.
  • Same-major additive fields may be ignored when they are optional.
  • Missing required fields or unsupported schema major versions fail clearly.
  • Compatibility validation happens before HTML output is written.
  • The renderer does not claim compatibility merely because JSON parsing succeeded.

The current scanner_version field may be retained temporarily during migration for compatibility, but producer_version is the v1 product-level metadata field.

Decision 3: canonical installed-package topology

The canonical runtime lives entirely under the installable skill directory:

skills/codebase-visualize/
  SKILL.md
  scripts/
    scan.mjs
    render.mjs
    visualize.mjs
  lib/
    version.mjs
    schema.mjs
    scanner.mjs
    renderer.mjs
    runtime.mjs
    commands.mjs
  assets/
    renderer.css

The filenames may be refined during implementation, but the authority boundary is fixed:

  • runtime behavior has one canonical source under skills/codebase-visualize/;
  • the installed package runs without the source repository's package.json, node_modules, fixtures, styles, or repository-only checks;
  • root package.json development commands invoke the canonical skill scripts;
  • root scripts/ contains repository-only checks, demos, build/migration helpers, and installers;
  • root runtime copies of scanner, renderer, or renderer CSS are removed rather than retained as mirrors.

Implementation status:

  • The canonical scanner, renderer, version source, and required CSS asset now live under skills/codebase-visualize/.
  • Root development commands invoke the canonical scripts.
  • Root runtime copies have been removed.
  • scripts/check-package-integrity.mjs proves a copied skill package can scan and render independently and rejects reintroduced root runtime copies.
  • Scanner, renderer, command, and runtime/path responsibilities are extracted into testable internal modules.
  • Thin public adapters implement scan, render, and visualize.
  • Fixed namespace paths and atomic replacement are enforced.

Decision 4: CSS source of truth

The v1 canonical style source is:

skills/codebase-visualize/assets/renderer.css

It is authored plain CSS and is embedded directly by the canonical renderer.

Migration rules:

  • Preserve the current visual language during the move.
  • Compare generated maps visually before and after migration.
  • Remove Tailwind, its build script, its generated CSS artifact, and its development dependencies after parity is verified.
  • Do not introduce a second generated or mirrored CSS source.

Implementation status:

  • The canonical asset is authored directly and embedded by the renderer.
  • Tailwind, its repository build script, its source mirror, and its development dependencies have been removed.
  • The runtime CSS bytes were preserved during migration for visual parity.

Remaining implementation questions

The following details remain intentionally open:

  • graph-size upper-bound behavior beyond the M5 medium-repository evidence.

None of these open details changes the accepted write-boundary, versioning, runtime-authority, or CSS-authority decisions.

Discovery conclusion

M1 runtime architecture, M2 installers, M3 schema/safety hardening, M4 behavioral evaluation, and the M5 local documentation/validation baseline are implemented and verified. M6 owns public-exposure cleanup, exact-candidate validation, independent cold-user evidence, and v1 publication.