spec: version the toolkit as a unit (Toolkit-Version anchored to /VERSION)#10
Merged
Conversation
…xceptions prior art - users-guide.md: expand per-repo skill install (symlink for dev vs vendored-copy-with-pinned-commit for a contributing design) + the 'skills load at session start, restart to invoke' caveat. - PNA_Spec.md § Building a PNA: promote 'validation, not certification' to a first-class framing statement (cross-links CONTRIBUTING + SKILL; ties in exceptions reported by AC/EX ID, not graded). - prior_art.md: new § 9 — behavioral exceptions, consent propagation (TCF/UMA/Kantara/macaroons), graded assurance (EAL/ASVS/SLSA/EARL), and legible labeling (nutrition labels/model cards/datasheets); finding that the mechanics have precedent but the exception-as-class-concept is novel. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
richbodo
force-pushed
the
docs/toolkit-dx-improvements
branch
from
d6f1ff5 to
393bd08
Compare
…RSION) The whole toolkit — spec, contracts, skill, lint, templates — is now versioned as one unit, equal to the spec version, so 'which toolkit am I building against?' resolves to a name, not just a git SHA. - /VERSION = 0.1.0-draft (single source of truth). - Every versioned artifact carries a 'Toolkit-Version: 0.1' stamp in its native format (md blockquote; # / -- / // comments; JSON $comment). - lint-spec-ids.py enforces presence + minor-match against /VERSION. - CONTRIBUTING § Versioning: the version covers the toolkit as a unit and all contribution shapes (reference design / AC-exception-solution / spec-doc change); releases git-tagged; designs declare the Toolkit-Version they built against. - ARCHITECTURE_TEMPLATE: design version field relabeled to Toolkit-Version. Revalidated against the now-named version: lint green across the chain (25 AC IDs, 12/12 contracts, 1 exception, toolkit 0.1). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the duplicate Spec-Version: metadata field now that the toolkit is versioned as a unit. PNA_Spec/axes/use_cases keep one version block (Toolkit-Version + prose); the version a design *declares* is Toolkit-Version everywhere (SKILL, CONTRIBUTING, users-guide, ARCHITECTURE_TEMPLATE, llms.txt). Generic 'spec version' evolution prose (CHANGELOG, future-spec-version notes) and the design-side fellows Architecture copy are intentionally left for a separate pass. Lint green: toolkit version 0.1. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Repo-wide once-over removing dangling 'spec version' language in favor of 'toolkit version' (the toolkit is what's versioned as a unit; the PNA Spec is a document within it). Covers CONTRIBUTING, README, llms.txt, users-guide, plans, reference-design records + the fellows Architecture copy, the spec files' future-version prose, three contract description strings, and retitles CHANGELOG to 'PNT Changelog'. Document references to 'the spec' and the JSON contract $id URIs are intentionally preserved. Also refreshes the users-guide status note (the contribute flow has now been exercised end-to-end). Lint green; all contracts parse. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
egress-lint.py and evaluate-report.schema.json (landed on main via #6) are toolkit artifacts too — stamp them and add them to the lint's versioned set, so 'the entire toolkit is versioned as a unit' actually holds after the merge with main. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
richbodo
force-pushed
the
spec/toolkit-versioning
branch
from
567820f to
ec01074
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Versions the toolkit as a unit, anchored to the spec version — so "which toolkit am I building against?" resolves to a name, not just a git SHA. Per the discussion, the version is called
Toolkit-Version(notSpec-Version): it covers the whole toolkit — spec, contracts, skill, lint, templates — and every contribution shape is a PR against that versioned unit.Stacked on #9 (base
docs/toolkit-dx-improvements); merge order #8 → #9 → this.Changes
/VERSION=0.1.0-draft— single source of truth (precise/pre-release version).Toolkit-Version: 0.1stamp (the minor series, so it doesn't churn during draft) on every versioned artifact, in its native format:spec/*.md,SKILL.md,CONTRIBUTING.md,README.md, both templates;tools/lint-spec-ids.py(#), SQL (--), OpenAPI (#), TypeScript (//);$comment— the 8 schema contracts (kept valid JSON; all re-parsed).lint-spec-ids.pynow reads/VERSIONand fails any versioned artifact missing the stamp or whose minor mismatches. This is the check we re-run to validate against the named version.CONTRIBUTING.md§ Versioning — the version is the toolkit unit; the three contribution shapes (reference design / new AC-exception-solution / spec-doc change) are all PRs against it; releases git-tagged; designs declare theToolkit-Versionthey built against.ARCHITECTURE_TEMPLATE.md— design version field relabeledToolkit-Version.The chicken-and-egg, resolved
#8/#9 validated against the un-named spec (lint green). This PR introduces the named
0.1+ the version-stamp check, and the lint is green across the whole chain — i.e.fellows_local_dband the contribution now validate against the namedToolkit-Version 0.1:One point for the maintainer
spec/PNA_Spec.mdnow carries both the newToolkit-Versionstamp and its pre-existingSpec-Version: 0.1 (draft)block (with explanatory prose). They're the same number. Keep both (spec doc's own version + the unit stamp), or reconcile to a singleToolkit-Version? I left the existingSpec-Versionblock intact rather than churn the preamble — easy follow-up either way.🤖 Generated with Claude Code