CHANGELOG.md

Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog and follows Semantic Versioning.

[0.12.0] - 2026-04-18

Synchronized version bump for all @stackbilt/* packages to 0.12.0.

Added

• analyze() + Zod schemas for @stackbilt/surface — new high-level analyze(input: SurfaceInput): SurfaceOutput entry point, plus SurfaceInputSchema, SurfaceOutputSchema, RouteSchema, SchemaTableSchema, SchemaColumnSchema, DEFAULT_SURFACE_EXTENSIONS, and DEFAULT_SURFACE_IGNORE_DIRS exports. The Zod schemas are the authoritative input/output contract shared by the CLI and MCP tool adapters. Existing extractSurface / extractRoutes / extractSchema / formatSurfaceMarkdown exports preserved. Route, SchemaTable, and SchemaColumn are now z.infer<> aliases of their schemas — structurally identical to the prior interfaces, so consumer code is unaffected.
• charter_surface MCP tool — charter serve now registers a callable tool for API surface extraction. Supports a format: "json" | "markdown" input for agents that want a compact human-readable summary instead of the structured payload. The tool description leads with "use this instead of grepping for route handlers" to nudge cold-boot usage.

Changed

• @stackbilt/surface gains zod (^3.24.1) as a runtime dependency. The "zero runtime dependencies" README claim is updated — Zod is the authoritative contract at the package boundary.
• charter surface CLI routes argv through SurfaceInputSchema — invalid arguments surface as a structured Zod validation error instead of silently defaulting.
• extractSurface now references the exported DEFAULT_SURFACE_EXTENSIONS / DEFAULT_SURFACE_IGNORE_DIRS constants so schema defaults and in-function fallbacks cannot drift (same pattern as DEFAULT_MAX_DEPTH in blast).

Security

• All @stackbilt/* packages published from v0.12.0 onward carry npm provenance attestations via GitHub Actions trusted-publisher OIDC auth. Each tarball cryptographically links back to the GHA workflow run that built it; consumers can verify via npm audit signatures or the "Provenance" badge on each package's npmjs.com page. Long-lived NPM_TOKEN usage is retired.

[0.11.0] - 2026-04-16

Synchronized version bump for all @stackbilt/* packages to 0.11.0.

Added

• STACKBILT_API_KEY environment variable — charter run and charter architect now resolve the API key from STACKBILT_API_KEY first, falling back to stored credentials only if the env var is absent or blank. This lets users authenticate the commercial commands without writing a token to ~/.charter/credentials.json.
• STACKBILT_API_BASE_URL environment variable — companion to STACKBILT_API_KEY; sets a custom engine base URL for env-var-authenticated callers. Preserves parity with the stored-credentials path (charter login --url …).
• resolveApiKey() helper exported from @stackbilt/cli's credentials module (env-var precedence, trimmed, returns { apiKey, source: 'env' | 'credentials', baseUrl? }).
• analyze() + Zod schemas for @stackbilt/blast — new high-level analyze(input: BlastInput): BlastOutput entry point, plus BlastInputSchema, BlastOutputSchema, and DEFAULT_MAX_DEPTH exports. The Zod schemas are the authoritative input/output contract shared by the CLI and MCP tool adapters. Existing buildGraph / blastRadius / topHotFiles / extractImports exports preserved.
• charter_blast MCP tool — charter serve now registers a callable tool for blast-radius analysis, in addition to the existing resource-style governance tools. Agents can query the reverse dependency graph via MCP; tsconfig path aliases are auto-detected at the scan root.

Deprecated

• charter login — emits a deprecation notice on every invocation. Functionality unchanged; scheduled for removal in 1.0 when gateway-bound commands (login, run, architect, scaffold) move out of @stackbilt/cli into a separate @stackbilt/build package.

Changed

• Scaffold auth-error message now points users at STACKBILT_API_KEY as the primary path, with charter login marked deprecated.
• CLI README gains a short "Authentication (optional)" section documenting the env-var path.
• @stackbilt/blast gains zod (^3.24.1) as a runtime dependency. The "zero runtime dependencies" README claim is updated — Zod is the authoritative contract at the package boundary.
• topHotFiles ties now break deterministically by filename ascending, so output is stable across Node majors and filesystem scan order.
• charter blast CLI routes argv through BlastInputSchema — invalid --depth values surface as a structured Zod validation error instead of a hand-rolled check.

[0.10.0] - 2026-04-09

Synchronized version bump for all @stackbilt/* packages to 0.10.0.

Added

• charter blast <files> — Compute blast radius for a set of seed files. Builds a reverse dependency graph by walking TS/JS imports and BFS-traverses up to a configurable depth. Reports affected files, hot files (most imported), and warns on ≥20-file blast radius as a CROSS_CUTTING signal.

  Import resolution handles: ES modules, CommonJS require, dynamic import(), re-exports, ESM .js → .ts rewrite, tsconfig path aliases (including extends chains), src/index.* monorepo fallback, package.json source/types/main fields, index files, cycles, and comment stripping. Zero runtime dependencies.

• charter surface — Extract the API surface of a project. Detects HTTP routes from Hono, Express, and itty-router (regex-based, requires / prefix to reduce false positives) and parses D1/SQLite CREATE TABLE statements with column flags (pk, unique, nullable, default). Strips block and line comments before scanning. Ignores __tests__/, *.test.*, *.spec.* files. Supports --markdown output for injection into .ai/ modules or AI mission briefs. Zero runtime dependencies.

• @stackbilt/blast — New standalone package exporting buildGraph, blastRadius, extractImports, resolveSpecifier, topHotFiles. 19 tests.

• @stackbilt/surface — New standalone package exporting extractSurface, extractRoutes, extractSchema, formatSurfaceMarkdown. 14 tests.

• .ai/analysis.adf — New on-demand ADF module documenting the analysis subsystem (blast + surface). Triggers on blast, surface, dependency graph, blast radius, route extraction, schema extraction.

Rationale

Originally inspired by analysis of the CodeSight project's blast-radius and route-detection patterns. Extracted the two highest-value algorithms into Charter as deterministic (no LLM) commands that feed into governance workflows: blast radius for CROSS_CUTTING classification, surface extraction for auto-generated .ai/surface.adf modules and cc-taskrunner mission-brief fingerprinting.

Validated on

Real-world dogfooding caught six bugs that made it into the first commit and were fixed before release:

1. Global CLI flags (--format, --config) being swept into positional seed list
2. JSDoc example strings matching as real routes
3. Test fixture routes matching as real routes
4. tsconfig extends chain not being followed, breaking monorepo alias resolution
5. Package alias resolving to compiled .d.ts instead of source .ts
6. ESM .js → .ts extension rewrite missing for TypeScript ESM projects

Validation runs:

• AEGIS web Worker (263 files): 95 routes + 50 D1 tables extracted in ~15s. dispatch.ts blast radius = 72, types.ts = 127, PWA fix files = 1.
• Charter monorepo (121 files): 0 routes (correctly identifies as CLI, not Worker). packages/types/src/index.ts blast radius = 27 files across cli/adf/git/validate/drift.

All 345 existing tests pass.

[0.9.3] - 2026-03-22

Fixed

• CI workflow — raised cli_entry_loc metric ceiling from 200 to 250 lines to accommodate actual 220 LOC entry point.
• Governance workflow — added pnpm run build step (missing, causing CLI binary not found). Made validate, doctor, and evidence steps non-blocking with continue-on-error until CI-specific doctor failure is root-caused.
• Release workflow — added job-level if: startsWith(github.ref, 'refs/tags/v') guard to prevent false-failure notifications on non-tag pushes. Fixed shell block indentation in tag resolution step.
• All three workflows now pass cleanly on main. No more 3 failure emails per push.

[0.9.0] - 2026-03-21

Added

• run command — stackbilt run "description" combines architect + scaffold in one step with animated 6-mode terminal output (PRODUCT, UX, RISK, ARCHITECT, TDD, SPRINT). Supports --dry-run, --format json, --output, --file, and all constraint flags.
• stackbilt binary alias — the CLI is now accessible as both charter and stackbilt. npx @stackbilt/cli run "..." works without global install.

Changed

• All packages bumped from 0.8.0 to 0.9.0.

[0.8.0] - 2026-03-15

Added

• architect command — generate a tech stack from a project description via the Stackbilt engine.
• scaffold command — write scaffold files from last architect build to disk.
• login command — store Stackbilt API key for engine access.
• Engine HTTP client — EngineClient for calling the Stackbilt engine API.

[0.7.0] - 2026-03-04

Added

• charter serve — MCP server (#28): New command exposes ADF-curated project context as an MCP server over stdio, enabling Claude Code and other MCP clients to query project constraints, architectural decisions, and recent changes. Tools: getProjectContext (ADF bundle filtered by task keywords), getArchitecturalDecisions (load-bearing CONSTRAINTS from core.adf), getProjectState (constraint validation status), getRecentChanges (git log). Resources: adf://manifest, adf://modules/{name}. Add to Claude Code via mcpServers: { charter: { command: "charter", args: ["serve"] } } in .claude/settings.json.
• Static site detection (#30): charter setup --detect-only now distinguishes static sites that deploy via Wrangler from actual Workers applications. Repos with wrangler.toml containing [assets] config and no worker entrypoint (src/index.ts, worker.ts, etc.) are suggested docs preset instead of worker, with an explanatory warning in detection output.
• content.adf for docs preset (#31): charter bootstrap --preset docs now scaffolds content.adf (triggers: Markdown, MDX, frontmatter, Astro, navigation, docs, authoring) alongside decisions.adf and planning.adf. MANIFEST_DOCS_SCAFFOLD trigger keywords updated to match documentation workflows.
• 7 new harness edge-case scenarios (#36): edge-dedup-rephrased, edge-dedup-partial-overlap, edge-heading-dominates-cross-module, edge-auth-implementation-vs-policy, edge-trigger-prefix-collision, edge-large-injection (22-item multi-module stress test), edge-empty-heading. Harness: 21/21 passing.

Fixed

• Trigger prefix collision in content classifier (#36): contentToModule() regex changed from bare prefix match (\bauth) to suffix-aware word-boundary match (\bauth(?:s|ed|ing|ment|tion|ity|ication)?\b). Triggers auth and api previously matched "author", "authentic", "authority", "apiary" — now blocked.

Changed

• adf init and charter setup next-steps (#32): Both commands now include charter adf bundle --task "<your task>" in next-steps output with a note that verify:adf runs this in CI.
• All packages bumped from 0.6.0 to 0.7.0.

[0.6.0] - 2026-03-03

Added

• Content-based module routing for migrate (#6, #15): adf migrate now routes rules to on-demand modules by matching content against manifest trigger keywords, not just markdown headings. Rules mentioning "React" under a generic "Conventions" heading now correctly route to frontend.adf instead of falling through to core.adf. New TriggerMap type (Record<string, string[]>) exported from @stackbilt/adf.
• docs stack preset (#3, #16): New --preset docs for documentation-only and planning-heavy workspaces. setup auto-detects docs workspaces via directory signals (docs/, ADR/, adrs/, decisions/, papers/, rfcs/) or when root files are predominantly markdown (>=50%). Bootstrap scaffolds decisions.adf and planning.adf modules with governance-focused patterns instead of irrelevant frontend/backend scaffolds.
• Bootstrap auto-migration (#7, #17): charter bootstrap --yes now auto-migrates existing agent config files (CLAUDE.md, .cursorrules, agents.md, GEMINI.md, copilot-instructions.md) into ADF modules as part of the bootstrap flow, eliminating the separate charter adf migrate step. Without --yes, shows a dry-run summary with instructions. Bootstrap flow expanded from 5 to 6 steps with migrate phase inserted between ADF init and dependency install.
• Unified evidence pipeline (#9, #19): New evaluateEvidence() API in @stackbilt/adf combines constraint validation, token budget analysis, module budget overruns, advisory-only module warnings, and stale baseline detection into a single typed EvidenceReport. Stale baseline detection (detectStaleBaselines) moved from CLI to @stackbilt/adf as a pure function. New EvidenceReport and StaleBaselineWarning types exported for typed consumption.
• manifest.ts module (#8, #18): Manifest parsing, trigger resolution, keyword matching, and trigger reporting extracted from bundler.ts into a focused manifest.ts module (~175 LOC). Functions parseManifest, resolveModules, isKeywordMatch, and buildTriggerReport are individually importable.
• merger.ts module (#8, #18): Pure document merge logic and token estimation extracted from bundler.ts into merger.ts (~85 LOC). Functions mergeDocuments and estimateTokens are individually importable.
• Configurable classifier/parser rulesets (#11, #21): New ClassifierConfig interface allows overriding STAY patterns and heading-to-module routing in classifyElement() and buildMigrationPlan(). New StrengthConfig interface allows overriding imperative/advisory patterns in parseMarkdownSections(). All parameters are optional with backward-compatible defaults.
• Domain-owned type modules (#10, #22): Monolithic types.ts (258 LOC) split into 6 focused domain files under types/: ast.ts, decorations.ts, patch.ts, manifest.ts, bundle.ts, validation.ts. Barrel re-export preserves all existing imports.
• 36 new focused unit tests across manifest.test.ts (9), merger.test.ts (9), evidence.test.ts (10), classifier-config.test.ts (5), strength-config.test.ts (3). Total: 251 tests across 22 test files (up from 215 in v0.5.0).

Fixed

• Bootstrap on-demand modules missing after init (#4, #14): adf init phase during bootstrap now scaffolds on-demand module stubs (frontend.adf, backend.adf), preventing fatal missing-module errors on first adf bundle after bootstrap completes.
• adf init --module overwrites existing .ai/ directory (#5, #13): Running adf init --module <name> when .ai/ already exists now creates only the new module file without overwriting existing manifest, core, or state files.

Changed

• Bundler architecture refactored (#8, #18): Monolithic bundler.ts (413 LOC) split into three focused modules: manifest.ts (~175 LOC) for manifest parsing and trigger resolution, merger.ts (~85 LOC) for pure merge logic and token estimation, and bundler.ts (~125 LOC) as a thin orchestration shell. All existing public exports preserved via re-exports — no breaking changes for @stackbilt/adf consumers.
• CLI evidence command simplified (#9, #19): adf-evidence.ts delegates evaluation to evaluateEvidence() instead of manually assembling evidence from validateConstraints(), BundleResult, and inline stale-baseline detection. Reduced from 312 to 272 LOC. Output format unchanged.
• buildMigrationPlan() signature extended (#6): Accepts optional triggerMap parameter for content-based module routing. Existing callers without triggerMap are unaffected.
• classifyElement() content fallback (#6): When heading-based routing returns core.adf and a triggerMap is provided, classifier falls back to content-based keyword matching before defaulting to core.
• Patcher handler map (#12, #20): patcher.ts switch statement replaced with keyed handler map. Extracted checkBounds() and parseColonEntry() helpers to eliminate duplicated bounds checks and colon-parsing logic.
• types.ts split into domain modules (#10, #22): 258-LOC monolith split into 6 focused files under types/. No consumer-side import changes needed — barrel re-export preserves backward compatibility.

0.5.0 - 2026-03-02

Added

• charter adf metrics recalibrate: New subcommand to re-measure LOC from manifest metric sources, propose new ceilings with configurable headroom, and update metric baselines/ceilings with required rationale (--reason or --auto-rationale).
• Budget rationale trail: Recalibration writes BUDGET_RATIONALES map entries so metric-cap changes carry explicit context for later review.
• Cross-platform git helpers: Unified git-helpers.ts module with shell: true for WSL/CMD/PowerShell PATH resolution, replacing ~6 duplicated runGit implementations across commands.
• EPERM/EACCES retry hint: Bootstrap install step now suggests --force or elevated permissions when write failures occur (ADX-005 F5).
• No-HEAD guard in audit: hasCommits() check prevents hard errors when auditing repos with no commits (ADX-005 F6).
• ADX-005 feedback paper: papers/AGENT_DX_FEEDBACK_005.md documenting 8 findings from end-to-end charter CLI UX walkthrough.
• Papers directory restructure: UX feedback buckets (papers/ux-feedback/), release planning templates (papers/releases/), and feedback paper template (papers/templates/).
• Papers lint script: scripts/papers-lint.mjs for validating paper frontmatter and cross-references.
• Custom /commit skill: Claude Code slash command for intelligent, organized multi-group committing (.claude/skills/commit/SKILL.md).

Fixed

• Cross-platform git invocation (ADX-005 F2): Hook install no longer reports "not inside git repo" on WSL/PowerShell due to PATH resolution failures.
• adf migrate prose sections (ADX-005 F3): Patcher ADD_BULLET on text sections now converts to list; migrate detects text sections and uses REPLACE_SECTION instead.
• Doctor thin pointer false positive (ADX-005 F4): .cursorrules thin pointers now recognized via shared POINTER_MARKERS constant.

Changed

• Stale baseline detection in evidence: charter adf evidence now detects stale metric baselines (current vs baseline drift), emits structured staleBaselines warnings (baseline/current/delta/recommendedCeiling/rationaleRequired), and suggests recalibration actions.
• README updated: Cross-platform support section, bootstrap command in Getting Started, refreshed dogfood evidence snapshot.
• All packages bumped from 0.4.2 to 0.5.0.

0.4.2 - 2026-02-27

Added

• charter doctor --adf-only mode: New mode runs strict ADF wiring validation only (manifest, required default-load wiring, module parseability, thin pointer integrity, sync lock status) for clean CI/pre-commit gating in repos that may not use .charter/ policy artifacts.
• ADF governance workflow hardening: setup --ci github workflow template now includes ADF Wiring & Pointer Integrity (doctor --adf-only --ci) and ADF Evidence (adf evidence --auto-measure --ci) steps when .ai/manifest.adf is present.
• Setup script sync expanded: setup now also syncs verify:adf, charter:doctor, and charter:adf:bundle scripts (in addition to detect/setup), so post-setup agent loops have first-class commands for ongoing governance.
• Repository adoption guardrails: setup docs/templates now include PR validation guidance (verify:adf) and .ai/* CODEOWNERS review ownership for explicit policy-change review.

Changed

• Pre-commit gate upgraded: charter hook install --pre-commit now prefers pnpm run verify:adf when available and otherwise enforces doctor --adf-only --ci + adf evidence --auto-measure --ci. This shifts enforcement from ceiling-only to full ADF routing + ceiling integrity.
• adf init scaffolding upgraded: now creates starter frontend.adf and backend.adf module stubs to avoid fatal missing-module experiences on first bundle.
• adf bundle missing on-demand behavior: missing ON_DEMAND module files are now reported as warnings (missingModules in JSON) instead of hard failures; missing DEFAULT_LOAD modules remain hard errors.
• adf sync --write empty-sync behavior clarified: when manifest has no SYNC entries, --write now writes an empty .adf.lock and reports tracked source semantics explicitly.

0.4.1 - 2026-02-27

Added

• charter doctor agent config pointer check: When .ai/manifest.adf exists, doctor now scans for agent config files (CLAUDE.md, .cursorrules, agents.md, AGENTS.md, GEMINI.md, copilot-instructions.md) that contain stack rules instead of thin pointers. Flags them with [warn] and suggests charter adf migrate --dry-run. Recognizes both pointer marker phrasings.

0.4.0 - 2026-02-26

Added

• charter hook install --pre-commit: New flag installs a git pre-commit hook that runs charter adf evidence --auto-measure --ci before each commit. Only gates when .ai/manifest.adf exists -- no-op otherwise. Uses npx charter for consuming repos. Both --commit-msg and --pre-commit can be passed together. Same skip/overwrite pattern with independent markers per hook type.
• Evidence pre-commit gate (this repo): .githooks/pre-commit now runs ADF evidence checks after typecheck, preventing LOC ceiling breaches from being committed. This is the self-regulating mechanism for unattended agent builds.

Changed

• adf.ts split into 4 files: adf.ts (966 LOC) refactored into adf.ts (412), adf-bundle.ts (153), adf-sync.ts (203), and adf-evidence.ts (262). Each file is independently tracked by its own METRICS ceiling. No behavioral changes -- purely structural.
• METRICS expanded from 4 to 8 entries: manifest.adf and core.adf now track adf_commands_loc, adf_bundle_loc, adf_sync_loc, adf_evidence_loc, adf_migrate_loc, bundler_loc, parser_loc, cli_entry_loc with appropriately sized ceilings.
• hook install error message updated: Now accepts --commit-msg and/or --pre-commit (previously required --commit-msg only).
• 178 tests across 12 test files (unchanged).

0.3.4 - 2026-02-26

Added

• charter adf migrate command: Scans existing agent config files (CLAUDE.md, .cursorrules, agents.md, GEMINI.md, copilot-instructions.md), classifies content using the ADX-002 decision tree, and migrates structured blocks into ADF modules. Replaces originals with thin pointers retaining environment-specific rules. Supports --dry-run, --source, --no-backup, and --merge-strategy append|dedupe|replace.
• Markdown section parser (parseMarkdownSections): Pure parser that splits markdown on H2 headings and classifies sub-elements as rules (with imperative/advisory/neutral strength detection), code blocks, table rows, or prose. Exported from @stackbilt/adf.
• Content classifier (classifyElement, buildMigrationPlan, isDuplicateItem): Deterministic rule-routing decision tree that classifies markdown elements into STAY (env/runtime) or MIGRATE (to ADF CONSTRAINTS/CONTEXT/ADVISORY). Jaccard similarity (0.8 threshold) for deduplication. Exported from @stackbilt/adf.
• GUIDE section type: New GUIDE decoration (📖) added to ADF standard decorations and canonical key order. The rule-routing decision tree in core.adf scaffold is now a first-class GUIDE section that survives adf fmt --write round-trips.

Changed

• Trigger keyword stemming: resolveModules() now uses prefix matching with a 66% length ratio threshold so ingest matches ingestion/ingesting without false-positives like React matching Reactive.
• Bootstrap overwrite protection (ADX-004 P0): charter bootstrap now detects existing custom ADF content in .ai/core.adf and skips scaffold overwrite, suggesting charter adf migrate instead. Pointer generation also skips files with custom content.
• CORE_SCAFFOLD updated: Rule-routing decision tree converted from # comments (which adf fmt --write strips) to a GUIDE [advisory] section that persists through parse/format cycles (ADX-004 P4).

0.3.3 - 2026-02-26

Added

• charter bootstrap command: One-command repo onboarding that orchestrates detect → setup → ADF init → install → doctor in a single frictionless flow. Supports --ci github, --preset, --skip-install, --skip-doctor, and --format json for full machine-readable output including next-step plans.
• Thin pointer generation: charter adf init --emit-pointers (and bootstrap) generates thin CLAUDE.md, .cursorrules, and agents.md files that redirect to .ai/ — preventing rule duplication across agent config files.
• Rule-routing decision tree: adf init scaffold now includes a commented decision tree in core.adf guiding agents on where rules belong (CLAUDE.md vs core.adf vs domain modules), derived from ADX-002 agent DX feedback.
• Section taxonomy documentation: Generated core.adf template documents the open section taxonomy (CONTEXT, CONSTRAINTS, ADVISORY, METRICS), weight tags ([load-bearing], [advisory]), and custom section rules.
• charter adf sync --explain: New flag outputs the .adf.lock schema documentation (format, hash algorithm, commands, purpose) in both text and JSON, eliminating lockfile archaeology friction reported in ADX-001.
• Agent DX feedback papers: ADX-002 (rule routing friction), ADX-003 (install automation friction), and RM-001 (vNext roadmap draft) added to papers/.
• GitHub Actions governance workflow: Bootstrap and setup now generate .github/workflows/charter-governance.yml for PR governance checks.

Changed

• Scaffold templates shared: ADF scaffold constants (MANIFEST_SCAFFOLD, CORE_SCAFFOLD, STATE_SCAFFOLD) and pointer templates are now exported from the adf command module and shared with bootstrap, eliminating template drift.
• Setup functions exported: detectStack(), loadPackageContexts(), detectPackageManager(), and other setup utilities are now exported for reuse by the bootstrap command.

0.3.2 - 2026-02-26

Added

• Lockfile types exported: AdfLockfile and AdfSyncStatus interfaces now exported from @stackbilt/adf public API, giving agents .d.ts visibility into the .adf.lock schema without reverse-engineering compiled output.
• Lockfile schema documented: .adf.lock format (flat JSON map of filename → sha256-prefix-16) documented in the @stackbilt/adf README.
• pnpm run dev watch script: New tsc --build --watch dev script for incremental rebuilds during local development via tsconfig.build.json.
• Research papers directory: papers/ with versioned white papers (CSA-001: Context-as-Code v1.1, CSA-002: Greenfield measurement rubric draft) and Architect v2 integration brief.

Changed

• Build uses tsconfig.build.json: Root build script replaced hardcoded 9-path tsc --build invocation with a tsconfig.build.json reference file. TypeScript resolves build order from project references automatically.
• Publish workflow simplified: PUBLISHING.md no longer instructs manual workspace:^ replacement — PNPM handles this at publish time. Publish commands no longer need --access public flag.
• publishConfig.access: "public" declared in all 9 packages (previously only cli and adf).
• sideEffects: false declared in all 9 packages for bundler tree-shaking.

0.3.1 - 2026-02-25

Added

• CI evidence gating: Governance workflow template (governance.yml) now runs charter adf evidence --auto-measure --ci on PRs when .ai/manifest.adf is present, automatically validating metric ceilings before merge.
• Scorecard evidence: Charter's own governance-scorecard.yml now includes ADF evidence output alongside validate and drift results.

0.3.0 - 2026-02-25

Added

• Metric content type: ADF parser now supports key: value / ceiling [unit] syntax for numeric metrics with hard ceilings. Metric entries are auto-detected by lowercase key and value/ceiling/unit structure.
• Weight annotations: ADF sections can carry [load-bearing] or [advisory] weight annotations (e.g., CONSTRAINTS [load-bearing]:). Weight is preserved through parse/format/patch/merge cycles.
• UPDATE_METRIC patch op: New patch operation updates a metric entry's value by key while keeping ceiling and unit immutable.
• Token budgets: Manifest BUDGET section with MAX_TOKENS sets a global token budget. bundleModules() reports tokenBudget, tokenUtilization, and perModuleTokens.
• Per-module budgets: ON_DEMAND entries support [budget: N] suffix for module-level token limits. Budget overruns reported in moduleBudgetOverruns.
• charter adf sync: New subcommand with --check (verify source .adf hashes against .adf.lock, exit 1 on drift) and --write (update lock file).
• Cadence scheduling: Manifest CADENCE section declares check frequency expectations (e.g., LINT_PASS: every commit). Cadence entries reported in bundle output.
• Constraint validation: New validateConstraints() API checks all metric entries against their ceilings. Status semantics: value < ceiling = pass, value === ceiling = warn, value > ceiling = fail.
• charter adf evidence: New subcommand produces structured evidence reports with constraint results, weight summary, sync status, and verdict. Supports --task, --context, --context-file, and --auto-measure flags. In --ci mode, exits 1 on constraint failures.
• computeWeightSummary(): Standalone API to count sections by weight category (load-bearing, advisory, unweighted).
• Scaffold LOC guardrail: charter adf init now scaffolds core.adf with a [load-bearing] CONSTRAINTS section and a METRICS [load-bearing] section containing entry_loc: 0 / 500 [lines].
• Auto-measurement: charter adf evidence --auto-measure counts lines in files referenced by the manifest METRICS section and injects them as context overrides.
• Manifest METRICS section: parseManifest() now reads a METRICS map section mapping metric keys to source file paths for auto-measurement.
• Advisory-only warnings: bundleModules() flags on-demand modules loaded without any [load-bearing] sections. Reported in both bundle and evidence output.
• --ops-file flag: charter adf patch accepts --ops-file <path> as an alternative to inline --ops <json>.
• --context-file flag: charter adf evidence accepts --context-file <path> as an alternative to inline --context <json>.
• Doctor ADF checks: charter doctor now validates ADF readiness: manifest existence, manifest parse, default-load module presence/parseability, and sync lock status.
• Trigger observability: triggerMatches now includes matchedKeywords (which task keywords matched each trigger) and loadReason ('default' or 'trigger'). New unmatchedModules field lists on-demand modules not resolved for the current task.
• nextActions in JSON output: adf init, adf evidence, and adf sync --check now include a nextActions array in JSON output suggesting logical follow-up commands based on results.
• 178 tests across 12 test files (up from 48 in v0.2.0).

Changed

• bundleModules() now accepts an optional taskKeywords parameter for richer trigger reporting.
• ADF format example in root README updated to show metric sections and weight annotations.
• Root, CLI, and ADF package README documentation comprehensively updated for all Phase 1-7 features.
• Help text for charter adf updated to list all six subcommands (init, fmt, patch, bundle, sync, evidence).
• Charter's own .ai/ directory now uses ADF metric ceilings to enforce LOC limits on its own source files (adf_commands_loc: 835/900, bundler_loc: 389/500, parser_loc: 214/300, cli_entry_loc: 142/200), validating the full evidence pipeline end-to-end.

0.2.0 - 2026-02-24

Added

• New @stackbilt/adf package: AST-backed parser, formatter, patcher, and bundler for the ADF (Attention-Directed Format) standard. Zero runtime dependencies.
• New charter adf command namespace with four subcommands:
  • charter adf init scaffolds .ai/ directory with manifest.adf, core.adf, and state.adf modules.
  • charter adf fmt <file> parses and reformats ADF files to canonical form (--check for CI gating, --write for in-place reformat).
  • charter adf patch <file> --ops <json> applies typed delta operations (ADD_BULLET, REPLACE_BULLET, REMOVE_BULLET, ADD_SECTION, REPLACE_SECTION, REMOVE_SECTION) for safe agent memory updates.
  • charter adf bundle --task "<prompt>" resolves manifest modules via keyword trigger matching and outputs merged context with token estimate.
• ADF parser supports three content types: text (inline values), list (dash-prefixed items), and map (KEY: value pairs for STATE sub-keys).
• ADF formatter auto-injects standard emoji decorations and sorts sections by canonical key order (TASK, ROLE, CONTEXT, OUTPUT, CONSTRAINTS, RULES, DEFAULT_LOAD, ON_DEMAND, FILES, TOOLS, RISKS, STATE).
• ADF patcher is immutable -- original documents are never mutated. Throws AdfPatchError with context on invalid operations.
• ADF bundler merges duplicate sections across modules (lists concatenated, texts joined, maps concatenated) and reports trigger match details.
• 48 new tests covering parser, formatter, patcher, and bundler.

Changed

• All internal @stackbilt/* dependency specifiers now use workspace:^ protocol for consistent monorepo resolution.
• Workspace layout documentation updated across README, CLAUDE.md, AGENTS.md, CONTRIBUTING.md, PUBLISHING.md, and SECURITY.md.
• Package dependency flow now includes: adf (NEW -- zero deps, self-contained AST) <- cli.

0.1.20 - 2026-02-17

Added

• New charter hook install --commit-msg command to install a commit-msg hook that normalizes Governed-By and Resolves-Request trailers using git interpret-trailers.
• setup --detect-only output now includes agentStandards and detects repository-level agent governance files (AGENTS.md, CLAUDE.md, GEMINI.md).
• drift and audit output now include pattern customization signal (patternsCustomized) when metadata is present in pattern files.

Changed

• Setup-generated GitHub workflow is now pnpm-aware and emits pnpm/action-setup + pnpm install --frozen-lockfile when pnpm is detected.
• Stack detection now scans monorepo manifests more broadly (packages/* and pnpm-workspace.yaml paths) and reports monorepo/hasPnpm.
• charter classify is now surfaced earlier in onboarding/setup guidance for LM-agent-first workflows.
• Pattern scaffold output now stores metadata envelope (customized, preset, generatedAt, patterns) while remaining backward-compatible in loaders.

Fixed

• Trailer parsing now follows terminal contiguous git trailer block semantics, matching git interpret-trailers behavior.
• validate now emits explicit trailer parsing warnings when governance-like lines are present but not parsed as valid trailers.
• Commit parsing in validate, audit, and quickstart snapshot flow now uses full commit body (%B) so trailer/body analysis is accurate.

0.1.19 - 2026-02-17

Added

• validate now emits effectiveRangeSource and defaultCommitRange for explicit default-range traceability.
• policyOffenders entries now include policyReason while keeping riskReason for backward compatibility.

Changed

• Root and CLI docs now recommend npx --no-install charter --version for deterministic post-upgrade version checks.
• Agent docs now clarify strict branching: use strictTrailerMode.mode and offender classification fields.

Fixed

• Reduced semantic ambiguity by making policy-offender reasoning explicitly policy-scoped.

0.1.18 - 2026-02-17

Added

• Setup baseline mutation metadata now includes configHashBefore, configHashAfter, and writesPerformed in mutationPlan/appliedMutations.
• validate.strictTrailerMode now includes explicit mode (STRICT_ONLY, RISK_ONLY, STRICT_AND_RISK, NONE).

Changed

• validate policy offender payload is now policy-context focused and no longer carries risk-rule metadata by default.
• Setup no longer rewrites .charter/config.json on reruns unless an explicit force path is used and content differs.

Fixed

• Eliminated baseline idempotency false-positive updates caused by unconditional writes during repeated setup runs.

0.1.17 - 2026-02-17

Added

• validate JSON now includes strictTrailerMode and split evidence arrays: evidence.policyOffenders (strict-policy failures) and evidence.riskOffenders (threshold-driven risk failures).
• setup JSON now includes explicit mutationPlan and appliedMutations blocks for baseline/workflow/scripts/dependencies.

Changed

• setup now supports --no-dependency-sync to skip rewriting devDependencies["@stackbilt/cli"].
• validate text output now prints separate policy-vs-risk offender sections to reduce explainability ambiguity.

Fixed

• Clarified offender semantics so strict no-trailer failures no longer overload threshold-risk offender reporting.

0.1.16 - 2026-02-17

Added

• validate now emits commit-level evidence even for zero-trailer failures, including riskRuleId, matchedSignals, and thresholdSource.
• drift --format json now includes explicit decision metadata (status, minScore, thresholdPercent, configPath).

Changed

• setup now treats multi-runtime detection as mixed stack (mixedStack: true) with consistent fullstack recommendation semantics.
• Generated GitHub workflow now runs Charter via repo-local npx after dependency install instead of global CLI install.
• setup now pins local @stackbilt/cli devDependency to the active CLI version for local/CI parity.
• Setup workflow telemetry now distinguishes created vs updated for truthful idempotency reporting.

Fixed

• Script synchronization no longer depends on setup path differences when preset inference converges on fullstack.

0.1.15 - 2026-02-17

Added

• validate JSON output now includes an evidence block with offending commit details (sha, riskLevel, riskReason, missingTrailers).
• setup --detect-only now surfaces runtime ambiguity warnings when multiple runtime families are detected without a clear stack split.

Changed

• setup now synchronizes package.json onboarding scripts to the selected preset (charter:setup) instead of only adding missing entries.

Fixed

• audit --range now fails with a runtime error on invalid git revspecs (matching validate semantics) instead of silently returning zero commits.
• validate text output now includes offending short SHAs for faster remediation loops.

0.1.14 - 2026-02-17

Added

• Documentation runbook updates for mixed-stack setup decision flow and LM-agent decision rules.
• setup now adds optional onboarding scripts to root package.json when missing: charter:detect and charter:setup.
• validate and audit now include explicit commit range in output for easier score interpretation.

Changed

• Root and CLI README now lead with detect-first setup (setup --detect-only) and explicit CI gating commands (validate/drift --ci).
• Publishing guide now verifies detected.sources in setup detection output and includes drift/audit checks in post-publish validation.
• Generated GitHub workflow from setup --ci github now installs a pinned CLI version for reproducible CI behavior.
• Default baseline config now enforces stricter trailer policy (validation.citationStrictness: "FAIL").

0.1.13 - 2026-02-17

Added

• setup --detect-only --format json now includes detected.sources listing which package.json files were used for detection.

Changed

• Stack detection now merges dependencies from root and nested manifests (client/, frontend/, web/, apps/*/), improving React/Vite signal detection in mixed repos.

0.1.12 - 2026-02-17

Added

• Mixed-stack setup guidance now appears directly in setup --detect-only and setup completion output.
• Framework-aware baseline specialization for detected Cloudflare, Hono, and React/Vite signals.

Changed

• Auto-detection now prioritizes fullstack for mixed frontend + backend/worker repositories.
• Setup now uses repo path signals (for example client/, apps/web) to improve mixed-stack inference.
• Docs now recommend detect-first + explicit fullstack preset for mixed repos.

0.1.11 - 2026-02-17

Added

• setup stack auto-detection with preset selection (worker|frontend|backend|fullstack) and --detect-only preview mode.
• Configurable policy coverage checklist in .charter/config.json under audit.policyCoverage.requiredSections.

Changed

• setup now scaffolds richer preset-based baseline patterns and infers project name from local package.json (fallback: directory name).
• audit policy score now uses required section coverage instead of markdown file count.
• Root and CLI docs updated with preset and detection guidance.

Fixed

• Policy scoring now rewards governance coverage quality over policy-file quantity.

0.1.10 - 2026-02-17

Changed

• Root and CLI README install guidance now leads with local repo install (npm i -D @stackbilt/cli + npx charter) and keeps global install as optional.
• Audit output now includes explicit scoring formulas and actionable remediation steps for trailer coverage, pattern definitions, and policy docs.

Fixed

• charter validate now returns runtime error (exit 2) when git commit loading fails (for example invalid revision/range), instead of incorrectly returning PASS.
• Validation output now distinguishes true "no commits" from internal git failures.

0.1.9 - 2026-02-17

Changed

• Synchronized all published @stackbilt/* packages to version 0.1.9 with aligned internal dependency ranges.

0.1.8 - 2026-02-17

Added

• New first-run UX: charter now prints a governance value/risk snapshot with a single recommended next action.
• New charter why command to explain adoption rationale and expected operational payoff.

Changed

• setup command output rewritten to focus on concrete outcomes (guardrails active, CI policy gate, immediate follow-up commands).
• CLI and root docs updated for human and agent onboarding paths.

0.1.6 - 2026-02-17

Fixed

• Cross-platform git invocation in validate and audit (removed shell-specific quoting/redirection issues on Windows).
• charter validate and charter audit no longer emit %an/shell noise on Windows.

0.1.5 - 2026-02-17

Fixed

• charter --version now reports package version dynamically instead of a hardcoded value.

0.1.4 - 2026-02-17

Fixed

• Replaced published internal dependency references from workspace:* to semver ranges so npm consumers can install successfully.
• Published patched internal package dependency chain used by CLI.

0.1.0 - 2026-02-16

Added

• Initial Charter Kit workspace with modular @stackbilt/* packages.
• CLI command surface: init, validate, drift, audit, classify.
• Governance workflow template in .github/workflows/governance.yml.

Changed

• Introduced seamless CLI setup with setup and diagnostics via doctor.
• Standardized command exit-code contract for human and LM-agent workflows.
• Improved cross-platform build scripts and docs for public contribution.

Security

• Added repository security policy and reporting process.