Skip to content

v1.0-validation-record.md

Latest commit

 

History

History
229 lines (184 loc) · 10.3 KB

v1.0-validation-record.md

File metadata and controls

229 lines (184 loc) · 10.3 KB

v1.0.0 Validation Record

Status: frozen; publication gates in progress

Date: 2026-06-09

Tag Target And Self-Referential Note

Product behavior was validated through commit d26302a (docs: refresh exact candidate validation), which itself documents content validated at c7855e07c40df5220df446d81e5639c5ecc55aa5. This frozen record and the companion CHANGELOG update are documentation-only commits that follow the validated content. A quick npm run check pass before tagging confirms no behavioral regression was introduced by these documentation commits. The tag target is the HEAD that includes this record.

  • Product version: 0.0.1
  • Graph schema version: 1.0.0
  • Branch: main
  • Repository visibility at record creation: private

V1 Release Criteria Summary

All criteria from docs/V1_RELEASE_PLAN.md section 7 are addressed below.

Packaging and installation

Criterion Status
Canonical installable skill package complete and independently runnable Passed
Scanner and renderer have testable internal boundaries Passed
V1 retains Node.js, graph JSON, self-contained HTML, SVG, vanilla JS Passed
Renderer CSS no longer requires Tailwind Passed
Claude Code user-level PowerShell installer Passed
Claude Code user-level bash installer Passed
Claude Code project-local installer Passed
Codex user-level PowerShell installer Passed
Codex user-level bash installer Passed
Codex project-local installer Passed
Existing-target refusal and explicit force behavior verified Passed
Installed files match canonical source Passed
Adversarial and installer suites pass on real Linux or WSL2 Passed (WSL2 Ubuntu)
macOS support explicitly documented Passed (documented unverified)

Runtime and safety

Criterion Status
Write-boundary contract selected, enforced, and documented Passed
Scanner handles unreadable or unusual filesystem entries predictably Passed
Generated output excluded from subsequent scans Passed
Repository-controlled text cannot inject executable HTML or JS Passed
Renderer rejects or clearly handles malformed/incompatible graphs Passed
Generated HTML has no external runtime resources Passed
Full checks do not leave tracked generated assets dirty Passed
Failure behavior does not leave misleading partial outputs Passed

Product usefulness

Criterion Status
Tree and graph views usable on bundled fixture Passed
Search, filters, selection, detail, and routing interactions work Passed
Desktop and mobile visual checks pass Passed
Copied-package behavioral evals pass across five fixture shapes Passed
Frontend and backend live-fire maps provide useful routing context Passed
Medium-repository behavior acceptable and uncertainty documented Passed
Sibling operation with codebase-orient conflict-free Passed

Documentation and trust

Criterion Status
README provides a cold-user path from acquisition to first map Passed
SKILL.md commands work from an installed package Passed
README, SKILL.md, CLI help, and architecture docs agree Passed
Claim labels and authority limits are explicit Passed
Known limitations and non-goals are explicit Passed
LICENSE, CHANGELOG.md, SECURITY.md, CODE_OF_CONDUCT.md exist Passed
V1 validation record complete and frozen before final tagging This document

Release hygiene

Criterion Status
Full local release check passes Passed
npm audit --audit-level=high passes Passed (zero vulnerabilities)
git diff --check passes Passed
Worktree clean Passed
Agent-mediated cold-user rehearsal from a disposable GitHub clone passes Passed
Exact public release-candidate checkout passes final validation matrix Passed
Public-surface sanitation passes Passed
Reachable pre-public history passes check:public:history Passed
Public release candidate passes independent cold-user validation Accepted: maintainer explicitly accepted agent-mediated rehearsal as sufficient for v1
GitHub repository settings match sibling-grade target before visibility change Manual gate - in progress
Final version identifiers and tag aligned intentionally Manual gate - in progress

Automated Evidence

All checks run from the maintainer working tree and separately from a fresh private GitHub clone.

  • npm run check: passed (working tree and fresh clone)
  • npm run check:evals: passed (working tree and WSL2)
  • npm run check:public: passed (working tree and fresh clone)
  • npm run check:public:history: passed (working tree, fresh clone, and WSL2)
  • npm run check:public:contracts: passed (working tree and fresh clone)
  • npm audit --audit-level=high: passed, zero vulnerabilities
  • git diff --check: passed
  • Worktree after checks: clean
  • CLI help (scan, render, visualize): passed from both contexts
  • Copied-package integrity check: passed
  • Installer matrix: passed
  • Generated-map interaction smoke check: passed

Platform Evidence

Platform Status
Windows with PowerShell (primary) All checks passed
WSL2 Ubuntu with Linux-native Node.js check:public, check:public:history, check:package, check:evals passed
macOS Explicitly unverified; documented limitation

WSL2 closes the Linux-native adversarial, copied-package, package-independence, and bash-installer evidence requirements. macOS is not a v1 blocker; it is documented as unverified in README limitations.

Installer Matrix Evidence

All eight install paths were exercised in disposable locations:

Tool Scope Shell Result
Claude Code user PowerShell fresh, refuse, force, execute: passed
Claude Code user bash fresh, refuse, force, execute: passed
Claude Code project PowerShell fresh, refuse, force, execute: passed
Claude Code project bash fresh, refuse, force, execute: passed
Codex user PowerShell fresh, refuse, force, execute: passed
Codex user bash fresh, refuse, force, execute: passed
Codex project PowerShell fresh, refuse, force, execute: passed
Codex project bash fresh, refuse, force, execute: passed

Behavioral Eval Evidence

Five copied-package behavioral cases from evals/cases.json, exercised via npm run check:evals using a disposable copied skill package:

Case Result
backend-service Passed
frontend-app Passed
docs-unfamiliar Passed
ambiguous-honesty Passed
sibling-orient Passed

Live-Fire Evidence

Sanitized live-fire metrics (raw artifacts outside tracked source):

Target shape Files Folders Edges Unknowns Result
backend service 7 6 16 1 Useful routing context
frontend application 8 7 17 0 Useful routing context
dispatch-sized repo (medium/large) 349 109 593 102 Navigable with scoped views and guidance

The medium/large run confirmed large-map guidance, graph controls, search, references mode, minimap, and copyable agent briefing all functioned. High-volume artifact-like areas can feel crowded; this is a known documented limitation and not a v1 blocker.

Cold-User Rehearsal Evidence

An agent-mediated cold-user rehearsal was performed from a disposable private GitHub clone. Full evidence in docs/releases/M6_PRE_PUBLIC_REHEARSAL.md.

Directly proven:

  • Codex and Claude Code user-level installs from the cloned source
  • Codex project-local install
  • Existing-target refusal without force
  • Force reinstall with stale-file removal and package-hash verification
  • Installed package invocation from outside the source checkout
  • Small target (8 files, 16 nodes, 20 edges) and medium target (100 files, 142 nodes, 274 edges)
  • Map interpretation surfaces present: claim labels, authority cues, cold-user guidance, agent briefing

Not covered by this rehearsal: fully independent external human-through-agent validation, macOS, manual GitHub UI-only surfaces.

Public Surface And History Evidence

  • History rewrite completed: private-target names, workstation paths, and author/committer identities generalized via git-filter-repo
  • check:public:history passes from working tree, fresh clone, and WSL2
  • check:public passes for tracked current tree
  • GitHub exposure audit complete: docs/releases/M6_GITHUB_EXPOSURE_AUDIT.md
  • Private-safe sibling settings applied while repository remains private
  • No unexpected branches, tags, releases, issues, PRs, Actions runs, or other exposure surfaces found

Supporting Records

Record Role
docs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md Deterministic candidate evidence, fresh-clone checks, WSL2
docs/releases/M6_PRE_PUBLIC_REHEARSAL.md Cold-user acquisition, install, invocation, and rehearsal evidence
docs/releases/MEDIUM_LARGE_PRESSURE_VALIDATION.md Medium/large map pressure and visual evidence
docs/releases/M5_VALIDATION_RECORD.md Local M5 baseline, live-fire, gitignore, and WSL2 evidence
docs/releases/M6_GITHUB_EXPOSURE_AUDIT.md GitHub exposure audit
docs/releases/M6_HISTORY_REWRITE_PLAN.md Rewrite procedure and verification
docs/releases/M6_REWRITE_DRY_RUN_RECORD.md Dry-run proof and real rewrite follow-up
docs/releases/PUBLIC_RELEASE_CHECKLIST.md Publication order and manual GitHub action checklist

Known Limitations

  • macOS is explicitly unverified. WSL2 closes the Linux-native evidence requirement. macOS is documented as unverified in the README.
  • Fully independent external human-through-agent cold-user validation was not completed. Explicitly accepted by the maintainer as sufficient for v1.
  • Manual GitHub UI-only publication gates (visibility, security features, rulesets, tag, release) are in progress at time of record creation.
  • If any commit beyond this documentation batch is chosen as the tag target, this record must be refreshed for that content.

Release Decision

All v1 release criteria are passed or explicitly accepted as sufficient. The remaining gates are manual GitHub UI actions being completed by the maintainer. This record is frozen. After the tag is published, compact docs/V1_RELEASE_PLAN.md into a short historical pointer and update docs/ai/OPEN_QUESTIONS.md to reflect publication completion.