v1.0.0

[1.0.0] - 2026-05-23

Breaking: run, architect, scaffold, and login commands removed from @stackbilt/cli. The stackbilt binary alias is also removed. These commands have moved to @stackbilt/build — install it with npm install -g @stackbilt/build. Migration tracked in RFC #112.

Removed

• charter run, charter architect, charter scaffold, charter login — removed after four minor release cycles of deprecation warnings (0.13–0.17). All four commands live in @stackbilt/build@0.1.0+.
• stackbilt bin alias — @stackbilt/cli now ships only the charter binary. Run npm install -g @stackbilt/build to get the stackbilt bin.
• credentials.ts, http-client.ts, types/scaffold-contract-types.ts — removed with the commands. @stackbilt/cli now has zero network calls, no bearer-token handling, and no references to stackbilt.dev.

Changed

• Package description updated: "Charter CLI — repo-level governance toolkit" (drops scaffolding claim).

What's Changed

• feat(drift): scan template literal bodies for anti-patterns by @stackbilt-admin in #181
• feat(context-refresh): add repo-intel source for GitHub history snapshots by @stackbilt-admin in #182
• feat(bootstrap): add --mode lean for fast, install-safe onboarding by @stackbilt-admin in #180
• feat(cli)!: Charter 1.0 — remove commercial surface from @stackbilt/cli (#127) by @stackbilt-admin in #183

Full Changelog: v0.17.0...v1.0.0

v0.17.0

[0.17.0] - 2026-05-23

Minor release closing issue #155 — session continuity is now first-class in the charter toolchain.

Added

• charter hook print --claude (hook.ts): New subcommand on the existing hook command. Prints a copy-pasteable UserPromptSubmit hook config JSON to stdout. Pasting into .claude/settings.json makes Claude Code auto-run charter context-refresh --once at every session open, so charter_context returns live project state before the agent acts. The command is a deliberate generator (not a writer) — .claude/settings.json is user-controlled.

• Session-start next step in charter bootstrap (bootstrap.ts): After setup, bootstrap now surfaces charter hook print --claude as a next step with an explicit reason: agents that skip this start cold, re-inferring constraints already declared in .ai/.

• ## Session Start section in generated CLAUDE.md (adf.ts): Both POINTER_CLAUDE_MD (thin) and POINTER_CLAUDE_MD_HYBRID (with module index) now include a ## Session Start section telling the agent to call charter_context before any other action. Includes fallback instructions for sessions where charter serve is not running.

• charter context-refresh Phase 1 + 2 (context-refresh.ts, index.ts, docs/tests): new live-context refresh command that writes both .ai/context.adf and .ai/context.snapshot.json.

  • Phase 1 (c5e90fd): git-source snapshot generation, optional markdown mirror via --output, initial command wiring and tests.
  • Phase 2 (5fb4a44): source expansion (git, github), config contract support via .charter/context-sources.json, TTL controls (--once, --ttl-minutes, --force), and machine-readable refresh status.

• Snapshot contract for warm starts: normalized root aggregates (openWork, recentActivity, pendingDecisions) are generated at refresh time from source payloads to prevent semantic drift while preserving raw source diagnostics under sources.*.

Changed

• charter context-refresh GitHub failure mode is fail-closed: missing GITHUB_TOKEN or unavailable GitHub source no longer crashes refresh. Snapshot records sources.github.available = false plus warning context, and refresh continues with remaining sources.
• CLI + docs command surface: top-level help and CLI reference now include charter context-refresh usage, flags, output artifacts, and config-file behavior.

What's Changed

• docs(context-refresh): phase-3 kickoff skeleton + release verification gates by @stackbilt-admin in #178
• feat(serve): session-start hook wiring + CLAUDE.md warm-start section by @stackbilt-admin in #179

Full Changelog: v0.16.0...v0.17.0

v0.16.0

[0.16.0] - 2026-05-22

Minor release adding ADF write-back tooling — the first step in closing the LM→ADF automation loop.

Added

• updateEvidence MCP tool (serve.ts): charter serve now registers updateEvidence, which measures actual file line counts for every metric declared in manifest.adf, diffs them against stored ADF values, and writes UPDATE_METRIC patches back to the owning ADF modules in place. Returns { measured, changes, skipped, written, constraints } so agents get full before/after visibility and live constraint pass/fail after the write. Supports dryRun: true (preview without writing) and metrics: [...] (update specific keys only). Deliberately does not touch .adf.lock — callers should run charter adf sync --write if lock hygiene is needed (preserves drift-detection signal).
• adf patch changes[] output (adf.ts): charter adf patch --format json now includes a changes array alongside opsApplied. Each entry records { op, section/key, before, after } — UPDATE_METRIC shows numeric before/after values, REPLACE_BULLET/REMOVE_BULLET show the original item text, ADD_BULLET shows before: null. Human-readable output also prints inline per-op diffs for metrics and bullet ops.

Fixed

• charter serve exits cleanly on startup errors (serve.ts, #157): Both @modelcontextprotocol/sdk/server/mcp.js and @modelcontextprotocol/sdk/server/stdio.js bind process.stdin at module load time, keeping Node's event loop alive past process.exit(). Both imports are now lazy (dynamic import() inside serveCommand(), after path guards). A bad --ai-dir now exits in under 100 ms with a JSON-RPC error and non-zero exit code instead of hanging indefinitely.
• charter stamp-policies structured error + env fallback (stamp-policies.ts): CHARTER_POLICY_REPO_REF env var is now accepted as a fallback when --policy-repo-ref is not passed. When SHA resolution fails, the command emits a structured JSON error object with code: POLICY_REPO_REF_UNRESOLVED and a recoveryCommand hint rather than a plain string message.

What's Changed

• chore(oss): ship CodeQL, CoC, CODEOWNERS coverage, and policy-block fallback by @stackbilt-admin in #173
• fix(score): filter URLs, env-vars, Windows paths, and HTTP routes from grounding checker by @stackbilt-admin in #168
• fix(context): use CLI package version when repo is a private workspace root by @stackbilt-admin in #169
• feat(setup): detect npm/yarn workspace monorepos + brief stack fallback by @stackbilt-admin in #170
• feat(ux): risk-first posture view for installed repos, adoption pitch for new ones by @stackbilt-admin in #176
• chore: add keywords, author, and provenance to all 12 packages by @stackbilt-admin in #171
• test: export boundary tests for @stackbilt/ci, classify, and validate by @stackbilt-admin in #174
• feat(dogfood): bootstrap .charter governance to score 80/100 on own audit by @stackbilt-admin in #175
• docs(ci): add VERSIONING.md documenting unified workspace versioning invariant by @stackbilt-admin in #177

Full Changelog: v0.15.1...v0.16.0

v0.15.1

What changed

Patch release fixing three charter serve MCP startup issues discovered during real-world Claude Code wiring (#156).

Fixed

• Path anchoring — --ai-dir is now resolved to an absolute path at startup. Relative paths were previously re-resolved against process.cwd() at each tool invocation, causing getProjectContext and all ADF tools to fail in multi-repo / WSL2 setups where the MCP host's cwd differed from the project root.
• getProjectContext double-prefix bug — the bundleModules reader callback was prepending aiDir to a path that already included it, producing paths like .ai/.ai/core.adf and making every getProjectContext call throw "Module not found".
• Structured startup errors — startup validation failures now emit a JSON-RPC -32000 envelope to stdout so Claude Code shows a human-readable message instead of a dead error code. Error messages distinguish missing .ai/ directory (→ charter init) from missing manifest.adf (→ charter adf init).
• adf init scaffolding guard — charter adf init no longer silently overwrites existing core.adf, state.adf, or preset module files. Files are skipped if present (with a notice and --force hint); only the missing manifest.adf is written.

Documentation

• Added dedicated charter serve section to `docs/cli-reference.md` covering `--ai-dir` behavior, `.mcp.json` wiring, startup error table, and all registered MCP tools.
• Updated `charter adf init` flag docs to clarify the new skip-if-exists behavior.

Full diff: v0.15.0...v0.15.1

v0.15.0

v0.15.0

See CHANGELOG.md for release details.

What's Changed

• [codex] Consolidate pre-repo work by @stackbilt-admin in #141
• chore(ci): bump actions/setup-node from 6.3.0 to 6.4.0 by @dependabot[bot] in #128
• chore(deps): bump vitest from 4.1.4 to 4.1.5 by @dependabot[bot] in #133
• chore(ci): bump pnpm/action-setup from 5.0.0 to 6.0.5 by @dependabot[bot] in #136
• chore(deps): bump vitest from 4.1.5 to 4.1.6 by @dependabot[bot] in #145
• chore(ci): bump pnpm/action-setup from 6.0.5 to 6.0.8 by @dependabot[bot] in #147
• feat: security-sensitive bootstrap mode (0.13.0) by @stackbilt-admin in #151
• fix: bootstrap manifest DEFAULT_LOAD corruption + UX gaps (closes #150, #146) by @stackbilt-admin in #152
• feat: charter context command + charter_brief MCP tool (closes #113) by @stackbilt-admin in #153

Full Changelog: v0.12.1...v0.15.0

v0.12.1

v0.12.1

Hotfix release for npm consumer install breakage in 0.12.0.

What happened

0.12.0 published with workspace: protocol dependencies in package manifests for some @stackbilt/* packages.
This broke pnpm installs for consumers outside the Charter monorepo.

Fix in this release

• Republished all publishable @stackbilt/* packages at 0.12.1.
• Replaced published internal runtime dependency specifiers with concrete semver ranges (for example, ^0.12.1).
• Updated release runbook to require concrete dependency verification and removed stale pnpm pack --dry-run guidance.

Consumer impact

• pnpm add @stackbilt/cli@0.12.1 now succeeds in external repos.
• If you are pinned to 0.12.0, upgrade immediately to 0.12.1 or later.

Deprecated versions

The following broken 0.12.0 package versions are deprecated with an upgrade message to 0.12.1:

• @stackbilt/cli@0.12.0
• @stackbilt/ci@0.12.0
• @stackbilt/classify@0.12.0
• @stackbilt/drift@0.12.0
• @stackbilt/git@0.12.0
• @stackbilt/validate@0.12.0

Verification

• npm dist-tag latest now points to @stackbilt/cli@0.12.1.
• Published @stackbilt/cli@0.12.1 dependencies resolve to concrete semver ranges (no workspace: specifiers).

v0.12.0

[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.

What's Changed

• ci(release): publish to npm on tag push by @stackbilt-admin in #118
• refactor(surface,cli,serve): Zod-Core-Out vertical slice for surface (#114) by @stackbilt-admin in #117

Full Changelog: v0.11.0...v0.12.0

v0.11.0

[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.

What's Changed

• docs: post-0.10.0 state refresh + http-client comment fix by @stackbilt-admin in #95
• feat(adf): typed-data-access policy module + named-scaffold registry (#69 Session 1) by @stackbilt-admin in #96
• feat(validate): ontology policy check (#69 Session 2) by @stackbilt-admin in #97
• fix(cli,blast): accept ea_ key prefix + exclude .claude/ from graph scan by @stackbilt-admin in #99
• chore(ci): bump actions/upload-artifact from 7.0.0 to 7.0.1 by @dependabot[bot] in #105
• chore(deps): bump vitest from 4.0.18 to 4.1.4 by @dependabot[bot] in #107
• chore(ci): bump softprops/action-gh-release from 2.6.1 to 3.0.0 by @dependabot[bot] in #106
• chore(deps): bump @types/node from 25.5.0 to 25.6.0 by @dependabot[bot] in #108
• feat(cli): STACKBILT_API_KEY env var auth; deprecate charter login by @stackbilt-admin in #111
• refactor(blast,cli,serve): Zod-Core-Out vertical slice (#109) by @stackbilt-admin in #110

Full Changelog: v0.10.0...v0.11.0

v0.10.0

[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.

What's Changed

• [auto] [Issue #59] Suppress release.yml false-failure notifications by @stackbilt-admin in #62
• [auto] [Issue #61] Guided onboarding for charter init by @stackbilt-admin in #63
• [auto] fix: bootstrap --yes vs --force separation + backup + orphan detection by @stackbilt-admin in #67
• fix: sentinel awareness, fmt normalization, lifecycle-scaled scoring by @stackbilt-admin in #76
• chore(deps): bump @types/node from 25.2.3 to 25.5.0 by @dependabot[bot] in #84
• chore(ci): bump pnpm/action-setup from a15d269cd4658e1107c09f1fabf4cbd7bd1f308a to fc06bc1257f339d1d5d8b3a19a8cae5388b55320 by @dependabot[bot] in #78
• chore(ci): bump actions/upload-artifact from 4.6.2 to 7.0.0 by @dependabot[bot] in #77
• chore(deps): bump @modelcontextprotocol/sdk from 1.27.1 to 1.29.0 by @dependabot[bot] in #83
• docs: add WSL2 + Windows filesystem install guidance by @stackbilt-admin in #91
• fix(cli): vendor scaffold-response types, unblock 0.10.0 publish by @stackbilt-admin in #93

New Contributors

• @dependabot[bot] made their first contribution in #84

Full Changelog: v0.9.2...v0.10.0

v0.9.0 — stackbilt run

What's New

stackbilt run command

One command to architect and scaffold a Cloudflare Worker project:

npx @stackbilt/cli run "Multi-tenant SaaS API with auth and billing"

Animated 6-mode output (PRODUCT, UX, RISK, ARCHITECT, TDD, SPRINT) with real-time progress. Files written to disk immediately.

stackbilt binary alias

The CLI is now accessible as both charter and stackbilt:

# These are equivalent:
stackbilt run "My API"
charter run "My API"
npx @stackbilt/cli run "My API"

Full Changelog

See CHANGELOG.md for details.