# Roadmap

Current release: v8.1.2

- **v8.1.2:** Fixes duplicate `Checks` labels in human-readable doctor output and expands black-box
  coverage for read-only, offline, non-interactive, and failure paths in the CLI update flow.
  Preserves selective skill reconciliation and zero runtime dependencies.

- **v8.1.1:** Makes CLI upgrades pin the verified package version and reconcile only affected managed
  files. Preserves locally modified skills when package sources are unchanged, updates skills when
  the published bundle changes, and clarifies upgrade status, provenance, and read-only planning.

- **v8.1.0:** Adds compact v8 evidence references and canonical-artifact reconciliation for resumed
  task work, required continuity corpus coverage, and the published-source TypeScript boundary in
  the normal typecheck. Preserves local-first behavior, zero runtime dependencies, legacy report
  visibility, and human release authority; no new CLI command, runtime loop, telemetry, automatic
  migration, or remote mutation is added.

- **v8.0.0:** Adds declared-scope evidence provenance, deterministic v1 report resolution, and
  explicit-baseline maintainer audit behavior. Legacy reports remain historical context; no runtime
  dependency, provider behavior, telemetry, implicit network access, or automatic remote mutation
  is added.

- **v7.17.0:** Adds independent maintainer evidence records, deterministic tree/input manifests,
  bounded sanitization, fail-closed freshness, explicit closure-versus-review finding boundaries,
  and contract provenance for direct, inherited, and undeclared fields. Preserves the 12-Skill
  roster, local-first behavior, zero runtime dependencies, and human release authority. No runtime
  registry, public evidence schema, new CLI command, telemetry, implicit network behavior, or
  mandatory host certification is added.

- **v7.16.0:** Refines Skill discovery and conditional context, observable obligations and
  enumerated evidence coverage, and local review convergence through stable findings and
  resolution tables. Expands the existing corpus and structural validators instead of adding
  a context auditor, runtime, public schema, or host certification. Preserves the 12-Skill roster,
  existing local outcome vocabularies, and all remote authorization boundaries.

- **v7.15.1:** Fixes interactive Team/project setup target selection, makes the configured specs
  root visible during review, and preserves shared specs visibility through workspace initialization.
  No runtime, public CLI command, telemetry, or automatic remote mutation is added.

- **v7.15.0:** Adds deterministic consumer-closure verification across source, dist, packed,
  project, and supported user-target installations; keeps maintenance-only audit/diff evidence
  local; aligns discovery/specification routing for ordinary technical uncertainty; and reports
  actionable diagnostics when an external symbolic link blocks installation. No runtime, public CLI
  command, telemetry, external host certification, or automatic remote mutation is added.

- **v7.14.1:** Adds safe clean-reinstall recovery for invalid or interrupted SAF-owned setup
  state, preserves foreign paths and collisions, and keeps healthy user-only setup navigable
  outside Git by returning to its menu after **Back**.

- **v7.14.0:** Aligns conditional Skill artifacts and verifier authority, validates the canonical
  human override against the selected loop-state section, bounds resume mutations while preserving
  history and line endings, and rejects invalid effective configuration. Keeps external host
  certification, expanded campaigns, monetary cost measurement, and dependency maintenance out of
  scope.

- **v7.13.0:** Clarifies state-first discovery/specification routing, preserves package/task
  identity and human authority gates, adds fixture-aware routing cases and deterministic corpus
  validation, and keeps external host certification and monetary cost measurement deferred.

- **v7.12.0:** Corrects evidence-sensor adequacy guidance, makes configuration reads and writes
  section-aware without changing the public CLI contract, and aligns version-stamp documentation
  with the generator. Host certification and monetary cost measurement remain explicit future
  backlog work; local-first, provider-neutral and zero-runtime-dependency boundaries are preserved.

- **v7.11.0:** Adds SVG-derived responsive terminal branding with wide, medium, and compact
  variants, centralized truecolor detection for trustworthy Windows Terminal markers, rich
  subcell rendering, outlined ASCII fallback, width/height welcome selection, and truthful
  wide-only motion backpressure handling. Preserves CLI, machine output, state, Skills, safety,
  local-first, zero-runtime-dependency, and human release authority contracts.

- **v7.10.2:** Hardens uninstall ownership, provenance and filesystem preflight; requires
  structurally complete evidence; preserves unrelated installation intent; improves packaging
  sensors and certification cleanup; and adds dist/packed platform CI matrices.

- **v7.10.1:** Enforces release-state coherence with a deterministic roadmap-entry guard and
  records the corrected v7.10.0 history. Refreshes dev-only @types/node and Biome tooling while
  preserving all CLI, machine, state, Skill, safety, local-first, and zero-runtime-dependency
  contracts.

- **v7.10.0:** Replaces timing-driven release audits with output-driven PTY journeys,
  deterministic cleanup, canonical 80×34 terminal branding, deadline-driven SAF brand motion,
  responsive fallbacks, and packed-artifact certification. Preserves all CLI, machine, state,
  Skill, safety, local-first, and zero-runtime-dependency contracts.

- **v7.9.1:** Makes Language the first interactive setup decision, keeps its locale
  session-local until Apply, persists synchronized workspace language fields only for Git setup,
  and unifies guided-init ordering across terminal presentations. It also refines the SAF welcome
  composition with a centered display title, localized italic tagline, and the canonical 110×46
  terminal brand mask from `public/ascii`, while preserving theme-owned colors and deterministic
  narrow-terminal fallbacks.
- **v7.9.0:** Completes the SAF terminal design system across every human-facing
  CLI journey. Unifies terminal context, semantic tokens, glyph fallbacks, cell-aware geometry,
  copyable output, selector rendering, gallery/catalog evidence, and presentation-boundary checks.
  Interactive `NO_COLOR` preserves rich structure without ANSI. Machine output, command semantics,
  selector state transitions, local-first behavior, and zero external runtime dependencies remain
  unchanged. No TUI framework, new command or flag, telemetry, implicit network behavior,
  automatic Git mutation, or release publication authority.

- **v7.8.0:** SAF Terminal Design System and Human CLI UX.
  Replace log-oriented rich output with a coherent guided terminal journey, bundled
  Clack/Picocolors primitives, cell-aware layout, inert terminal-text sanitization,
  responsive notes and summaries, transient rich-TTY progress, and representative
  packed/cross-platform evidence. Preserve selector semantics, machine schema 2,
  safety boundaries, local-first behavior, and zero external runtime npm dependencies.
  No new command semantics, workflow authority, telemetry, implicit network behavior,
  automatic Git mutation, or release publication authority.

- **v7.7.1:** Removes the local-only `release-saf` skill from the
  published package and republishes the corrected package contents.

- **v7.7.0:** Hardens canonical CLI grammar, fail-fast dispatch,
  zero-delta rejection, Team authorization, atomic machine JSON, and dist/packed
  certification for contract and mutation regressions.

- **v7.3.0 (2026-08-27):** CLI behavioral certification with independent
  sandbox observation, bidirectional mutation evidence, output-driven PTY
  journeys, fail-closed recovery coverage, packed-artifact verification, and a
  release gate that accepts only a complete `PASS`. No new dependency,
  telemetry, runtime network behavior, or automatic Git/release mutation.

- **v7.2.0 (2026-08-26):** Completes the guided CLI contract with derived setup
  state, local host evidence, five-field intent, declarative plan/review/apply,
  surgical policy mutation, staged recovery, and truthful purge behavior. Adds
  focused and black-box certification without provider invocation, telemetry,
  network behavior, or automatic Git/release mutation.

- **v7.1.0 (2026-08-26):** Guided CLI setup recovery. Restores bare TTY setup
  as the human path while retaining deterministic non-TTY behavior, derives
  setup state from durable artifacts, and strengthens zero-config readiness and
  purge truthfulness. No runtime dependency, telemetry, provider invocation,
  persisted onboarding marker, remote mutation, or automatic publication.

- **v7.0.0 (2026-08-26):** Simplified workspace-first SAF lifecycle. Consolidates one
  official 12-Skill bundle, Git-aware per-workspace initialization, optional configuration with
  `apply + supervised` defaults, v3 state, portable sidecars, bounded pre-v7 reset, stable
  worktree adoption identity, schema-2 diagnostics, deterministic project context, and aligned
  docs. Final RC hardening covers nested monorepo excludes, Team-local workspace markers,
  zero-config autonomy reporting, and retired-v6 documentation vocabulary. No AI runtime,
  external Skill registry, telemetry, or automatic remote mutation.

- **v6.5.0 (2026-08-25):** Local-first adoption and explicit sharing. Adds
  personal, specs-shared, and team presets, optional installation-intent
  adoption state, scoped SAF-owned Git exclude blocks, foreign-skill
  preservation, and doctor/purge reconciliation. No new intent schema,
  automatic Git history mutation, `.gitignore` changes, telemetry, or remote
  automation.

- **v6.4.3 (2026-08-23):** Documentation and CLI guidance consistency. Corrects stale
  onboarding and recovery suggestions, removes unnecessary historical version labels from
  user-facing CLI messages, and aligns the documentation set with the current command surface.
  No new command, flag, dependency, workflow authority, telemetry, or automatic remote mutation.

- **v6.4.1 (2026-08-23):** Corrective CLI release after real-user certification findings.
  Adds target/scope-aware uninstall filtering, canonical read-only help parity, preservation and
  validation regression coverage, and current v6 uninstall documentation. No new workflow
  authority, runtime dependency, telemetry, or automatic remote mutation.

- **v6.4.2 (2026-08-23):** Corrective CLI contract release after real-NPX certification.
  Aligns installation automation guidance with the accepted command grammar and rejects unknown
  `list` arguments with structured recovery guidance. No new command, flag, dependency, workflow
  authority, telemetry, or automatic remote mutation.

- **v6.4.0 (2026-08-23):** CLI audit reliability and release certification. Adds normalized
  black-box evidence, persistent-state snapshots, disposable source materialization,
  registry-derived read-only command coverage, and bounded documentation corrections. Keeps
  the runner local-first and network-independent; no new runtime authority, dependency,
  telemetry, or automatic remote mutation.

- **v6.3.1 (2026-08-22):** Autonomous contract hardening. Clarifies repair
  transition admissibility, evidence authority, invocation guidance, and
  fail-closed loop-state diagnostics without adding runtime orchestration or
  changing the public Skill roster.

- **v6.3.0 (2026-08-22):** Autonomous end-to-end completion for bounded local
  delegations. Recoverable failures, review findings, validation findings,
  re-planning, and intent-preserving reconciliation now use authorized repair
  transitions before exceptional escalation. No scheduler, provider, new
  public Skill, remote mutation, or automatic release authority.

- **v6.2.0 (2026-08-22):** Harness contract integrity,
  consequential contract-change admission, context-selection discipline,
  independent verification freshness, and repository-level readiness guidance.
  No runtime, scheduler, new public Skill, machine-schema change, provider,
  telemetry, or automatic remote mutation.

- **v6.1.0 (2026-08-22):** Information representation architecture. Adds the
  contract-kind registry and audited representation model, clarifies durable
  artifact and skill closeout ownership, documents Markdown/YAML/hybrid and
  projection profiles, and adds focused conformance sensors. Additive; no
  format migration, public skill roster change, runtime dependency, telemetry,
  or automatic remote mutation.

- **v6.0.1 (2026-08-22):** Documentation coherence and release hardening. Added deterministic
  documentation contract checks, grounded documentation/change-impact guidance, and finalized
  post-v6 clean-slate installation and pack validation. No new skill, runtime dependency, or
  remote automation was added.

- **v6.0.0 (2026-08-22):** Provider-neutral skills and packs, local change-review contracts,
  durable pre-spec discovery, minimum-sufficient prompts, generic multi-task isolation, and
  deterministic skill-contract lint. Breaking clean boundary; no provider adapter, runtime,
  scheduler, telemetry, or automatic remote mutation.

- **v5.0.0 (2026-08-19):** Clean-slate CLI grammar, strict state schemas, transactional
  ownership/provenance, terminal capability separation, and deterministic shell completions.

- **v4.4.0 (2026-08-19):** Agentic Workflow Harness identity and developer lifecycle. Audited A1–A4: root lock metadata is stamped and checked, architecture documents the npm wrapper chain, optional companion tooling is scoped, and active documentation distinguishes skills/capabilities from host runtime execution. Added a practical lifecycle guide and narrow positioning sensor; no runtime, scheduler, dependency, or remote automation was added.
- **v4.3.0 (2026-08-19):** Engineering control-plane coherence. Qualified public model and host-capability matrix; `doctor --harness` projects canonical readiness checks; Evidence Graph gains a safe deterministic HTML projection that writes only with explicit `--output`. No runtime, scheduler, new skill, telemetry, or implicit file write.
- **v4.2.0 (2026-08-17):** Init and local artifact polish. Enriched `usage.md` generation
  (workflow mermaid, localized stub, bundled guide copy), `inferInitDefaults()` for contextual
  `config.yml`, automatic `.git/info/exclude` for user-scope installs, canonical docs renamed to
  `saf-skills-usage-guide*`, and `saf-explain` outputs moved to
  `.sdd-agentic-flow/explanations/<feature>.md`.
- **v4.1.0 (2026-08-16):** Operating policy & autonomy UX. Guided `init` includes
  Supervised/Manual/Autonomous/Advanced policy selection; Current setup and Review show the full
  policy pair; returning menu separates policy changes from installation changes. No CLI
  orchestration engine or new persisted policy axis.
- **v4.0.0 (2026-08-16):** Harness integrity. v4 artifact contract (`REQ-*`, requirement
  anchors, feature-scoped evidence tables), shared bounded-execution contracts, read-only
  `doctor --evidence-graph`, cross-scope `uninstall --purge`, and SPEC-Q spec gate. Breaking;
  no migration layer.
- **v3.6.0 (2026-08-16):** Maintainer architecture consolidation. Post-TypeScript CLI
  entrypoint decomposed into flat command modules (`doctor.ts`, `setup.ts`, `install.ts`,
  etc.); docs/tooling aligned to `src/` / `dist/` layout; TypeScript unused-code flags enabled.
  No public CLI, skill, or preset contract change.
- **v3.5.0 (2026-08-15):** TypeScript strict migration. Maintainer code moved from `bin/*.js`
  to `src/*.ts`, compiled output in `dist/`, tests/scripts converted to `.ts`, and CI gates
  updated to validate the new layout.
- **v3.4.0 (2026-08-15):** Guided CLI setup UX. Interactive onboarding now offers a safe
  recommended path or bounded customization, one review-before-write, semantic progress, derived
  resume/maintenance state, localized recovery, and canonical setup summary. It remains an inline
  CLI: no TUI framework, screen takeover, onboarding marker, telemetry, new dependency, or new
  automation authority.

- **v3.3.0 (2026-08-15):** Adaptive validation and workflow consolidation. Public workflow
  ends at feature validation with 13 skills. Verification selects the minimum adequate sensors
  from requirements, changed seams, repository contracts, and risk; no CLI validation engine,
  new config axis, or new Status enum. Canonical terminology documents harness boundaries.

- **v3.3.1 (2026-08-15):** Corrective CLI release after real-user packaged-flow validation.
  Fixed TTY cursor/menu behavior, project-scope legacy detection, saved-intent resumption,
  full-pack reporting, Portuguese navigation, and the post-install usage guidance. No new
  workflow capability, dependency, skill, or automation authority was added.

- **v3.2.0 (2026-08-15):** Continuous guided onboarding: `init` is a TTY-first
  0 → Ready path with review-before-write, default `full` installation, context,
  and doctor verification. Automation remains explicit through `--non-interactive`;
  no onboarding state, dependency, or automatic registry access was added.

- **v3.1.0 (2026-08-15):** CLI UX coherence: truthful guided flows, EN/pt-BR human-facing
  messages, human-plain output for pipes/CI, explicit JSON diagnostics, progressive doctor
  summaries, target-stable diagnostic IDs, state-aware navigation, and grouped uninstall plans.
  No new skills, workflow layer, telemetry, or automation authority; default install targets and
  safety gates remain unchanged.

- **v3.0.0 (2026-08-15):** Public skill identity changes to `saf-*`; intent-aware install
  profiles, safe reconciliation, and multi-task wave execution contracts.

- **v2.1.0 (2026-08-14):** DX / CLI UX / onboarding minor. Control-plane commands:
  `config show|policy`, install preflight + `install --interactive`, welcome/menu policy
  blocks, `learn-sdd`, redesigned `init --interactive`. Collision-safe install; inspect-before-
  mutate for policy. `baseline_version` stays `0.7.0`. No third config axis; no CLI skill
  runner; project install still single path (`.agents/skills/`).
- **v2.0.0 (2026-08-13):** Public-readiness / consolidation major. One
  methodology, one canonical workflow path, three operating presets
  (`init --preset`), one router. `migrate` removed; leftover `.sdd/` is a
  `doctor` WARN and a manual rename. Breaking notes in
  the active v5+ compatibility contract. Autonomous does not mean unattended; no
  config value overrides safety. 13 skills; no public `auto-sdd` / `sdd-run`;
  no third stored axis. `baseline_version` stays `0.7.0`.
- **v1.19.0 (2026-08-13):** Spec package lifecycle and scoped context. Path
  `.specs/features/<slug>/` unchanged. Skills resolve one package, then load
  only artifacts the active operation already requires. Optional advisory
  `Lifecycle:` (`implemented`, not `completed`) and `Extends:` / `Supersedes:`.
  TLC on-demand load invariant; `baseline_version` stays `0.7.0`. No CLI, no
  auto-archive, no `STATE.md`, no `validation.md` under `.specs`, no 15th skill.
- **v1.18.0 (2026-08-13):** Shared engineering-principles contract for how
  agents change code. Language- and architecture-agnostic; not a skill and not
  a TLC/TDD baseline. Consumed by implement / prompts / specs / check /
  pr-review / pr-fix. `baseline_version` stays `0.7.0`. No 15th skill, no web
  or security pack, no CLI flag, no registry baseline. KISS/YAGNI/DRY findings
  do not flip check/validation `PASS` by themselves.
- **v1.17.0 (2026-08-13):** Positioning and curated foundations. Documentation
  minor; `baseline_version` stays `0.7.0`. Public definition: local-first
  agentic software-engineering harness; skills are the **execution layer**, not
  the whole product. `docs/inspirations.md` has epistemic roles and the caveat
  that sources are not specifications. No CLI flag, no skill rename, no
  `docs/references/` folder, no token multipliers, no survey-driven backlog.
- **v1.16.0 (2026-08-13):** Progressive rigor and work-type content contracts.
  Additive minor; `baseline_version` stays `0.7.0`. Inferred work intent
  (feature / bugfix / refactor / investigation / maintenance) plus existing
  `feature_profile`. Bugfix at any profile names unchanged behavior and
  regression sensors. Rigor follows uncertainty and risk, not only diff size.
  Spec analysis is a skippable step in `sdd-create-specs`. Living specs.
  DAG → waves documented (no orchestrator). Named feedback loop (not auto-run).
  Sensor taxonomy as methodology only. No CLI `--type`, no 15th skill, no PBT
  engine, not a Kiro runtime.
- **v1.15.0 (2026-08-13):** Completion integrity and false-positive resistance.
  Additive minor; `baseline_version` stays `0.7.0`. Named catalog of illegitimate
  completion (green-but-wrong, inherited author narrative, suite weakening,
  completion theater, …); fresh-eyes state-checking in check/validation; requirement
  coverage mapping; evidence strength ladder; observable expected outcomes in specs
  and prompts; reproduction sensor under existing `small_fix`. Self-report is not
  evidence. No Verifier, LLM-judge, PBT, CLI `--type`, or fifth profile.
- **v1.14.0 (2026-08-12):** Behavioral evidence and feedback sensors. Baseline minor:
  `tdd` / `tlc-spec-driven` `0.6.0` → `0.7.0`. Required loop is name-behavior →
  sensor at contractual seam → implement → record current evidence. Test-first
  recommended when useful; full TDD ritual optional and never harness proof. Passing
  sensor = evidence, not a correctness verdict. `quality.require_tdd` kept (evidence
  contract, not ritual). No mutation engine, Verifier, or `doctor --quality`.
- **v1.13.1 (2026-08-12):** Compact welcome brand (~8–10×≤52) + slower reveal + tiny-TTY
  one-line fallback. Presentation-only patch.
- **v1.13.0 (2026-08-12):** Confirm-gated `upgrade` command + welcome opt-in update ask.
  Additive minor; baseline unchanged. `--check` / `--plan` / `--skills-only`, skill
  diff-safety + provenance, three documented network entry points, menu entry, orthogonal
  did-you-mean on more commands. Evidence graph remains a separate future candidate.
- **v1.12.0 (2026-08-12):** CLI UX foundation. Additive minor, no breaking changes.
  `outputMode` / `FORCE_COLOR` / `symbol`, structured `fail` (Reason/Try), `nextStep` on
  mutating commands, TTY-only welcome brand mark, contextual menu (`menuActionsFor`),
  init/install rich connectors, help `Useful when:`, doctor Fix/Next footer, public
  `docs/cli-interaction.md`, opt-in `--ascii`. Evidence graph (`doctor --evidence-graph`)
  remains a future candidate (v1.9.3 audit / Slice B).
- **v1.11.0 (2026-08-12):** Discovery and positioning. Additive minor, no breaking changes.
  `init` writes `.sdd-agentic-flow/usage.md` (resolvable usage-guide pointer for `--scope user`
  consumers). `welcome` mentions `doctor --check-updates` with zero network. Opt-in
  `init --local-git-exclude` appends `.sdd-agentic-flow/` to `.git/info/exclude` only.
  `sdd-explain-me` requires source-artifact anchors. README audience paragraph for AI-first
  teams; Graph note on the mental-model doc.
- **v1.10.0 (2026-08-11):** Toolkit path rename + system coherence. **Breaking:** `.sdd/` →
  `.sdd-agentic-flow/` for all toolkit state; `migrate --plan|--apply`, `doctor` `legacy_sdd_root`
  WARN, `docs/upgrading.md` migration table, grep gate `scripts/check-sdd-paths.sh`. **Additive:**
  `docs/sdd-agentic-flow-model.md`, README storytelling, five Autonomy Golden Flows (AUTO-001–005)
  proving static autonomy CLI contracts, cross-agent parity docs. Evidence graph (`doctor
  --evidence-graph`) and per-agent guide parity remain future candidates (v1.9.3/v1.9.4 audits).
- **v1.9.2 (2026-08-10):** Flow-phase and completion-semantics cross-references. Docs-only patch,
  audited against `.local/gmm/sdd-agentic-flow/v1.9.2-flow-state-implementation-plan.md`'s 3-item
  candidate skeleton — 2 of 3 items closed a real, narrow gap; the third stayed out, its own
  precondition still unmet. `shared/references/autonomy-guardrails.md` and its public mirror
  `docs/autonomy-guardrails.md` now point a `loop-state.md` reader at `docs/sdd-methodology.md`'s
  existing `Phase | Typical skill` table to read a `Skill:` entry's SDD flow phase — the table
  already existed, only the cross-reference was missing, no schema change.
  `shared/references/evidence-standard.md`'s `Status:` field section now also states that the
  same field is what `handoff-standard.md`'s terminal-state rule keys off, closing a one-directional
  gap (`handoff-standard.md` already pointed to it, not the reverse) without adding a second
  completion taxonomy. The skeleton's third item, a no-progress/repeated-failure signal for
  `loop-state.md`, was re-evaluated and stays deferred: no real stuck-loop incident has been
  observed, the same conclusion v1.9.0 reached. A separately proposed heavier governance layer
  (a `docs/decisions/` ADR folder, decision templates, an "official methodology" doc, and a
  pre-committed `v1.10` schedule) was evaluated and rejected — it duplicated what this file's own
  dated entries already do, and pre-committing a future version's schedule contradicts this same
  section's "decided when that work actually starts, not now" rule. `CONTRIBUTING.md` gained one
  short paragraph pointing contributors at this audit-first pattern instead. Zero breaking
  changes.
- **v1.9.1 (2026-08-10):** Release Consistency Hardening. Closes 4 small, real gaps found by
  directly auditing the repository after v1.9.0 shipped — no new mechanism, same discipline.
  `bin/sdd-agentic-flow.js`'s own `const VERSION` and `OFFICIAL_SKILLS` array had drifted from
  `package.json`/`skills/` during v1.9.0 (`VERSION` stuck at `1.8.0`, `OFFICIAL_SKILLS` drifting)
  with `npm run check` still reporting green, because
  `scripts/check-version-consistency.js` only ever walked `skills/*/SKILL.md` and
  `presets/*.json`, never `bin/` — caught only by manual testing after the fact. Both scripts
  that consume it (`check-skills.sh`, `release-checklist.sh`) now also check `bin/`'s `VERSION`;
  a new `OFFICIAL_SKILLS`-vs-`skills/` parity check was added directly to `check-skills.sh`. Both
  fixes were proven against the actual v1.9.0 bug shape (temporarily reintroducing it locally)
  before being kept — see `.local/gmm/sdd-agentic-flow/v1.9.1-implementation-report.md`.
  Zero breaking changes.

- **v1.9.0 (2026-08-10):** Method & Reliability. Deepens v1.8.0's autonomy foundation instead of
  adding a new mechanism. This release closes individually audited gaps rather than the originally drafted
  candidate wholesale (see "Corrections vs. the v1.9 candidate draft" below). New
  `shared/references/handoff-standard.md` defines when a skill populates the
  previously-unused `shared/templates/handoff.template.md` and how it cross-references
  `.sdd-agentic-flow/autonomy/loop-state.md` without duplicating it; wired into the 7 skills whose work can
  span a session/agent boundary. `check-report`/`validation-report` gain a top-line `Status:`
  field, with `shared/references/evidence-standard.md` documenting the mapping from each
  skill's own local vocabulary to guardrail 1's generic pass/not-pass check. `sdd-brainstorm`
  gains an explicit Known/Assumed/Unknown/Needs research split before handing off to
  `sdd-create-specs`; `sdd-implement-multi` now explicitly links
  `worktree-orchestration.md`. Zero breaking changes, same as every release since v1.0.

  **Corrections vs. the v1.9 candidate draft below and its
  `.local/gmm/sdd-agentic-flow/v1.9.0-implementation-plan.md` skeleton:** progressive disclosure
  was audited and found not needed — all 13 pre-existing skills measured 55–70 lines at audit
  time (before this release's own content additions nudged `sdd-brainstorm` to 71), far under
  the ~500-line guidance even after v1.8.0's `## Autonomy` section addition; no refactor
  shipped. The skeleton's claim of 2 orphaned golden-flow fixtures (and an earlier re-check
  during this release that initially assumed 3) was also wrong on inspection:
  `project-context-lifecycle` and `version-migration` have no on-disk fixture files by design
  and are already proved by dedicated `test/cli.test.js` tests; `invoice-approval` is a
  deliberately smaller, non-golden-flow fixture per
  `.local/gmm/sdd-agentic-flow/ai-context-report.md`, not an untested golden flow — there was
  nothing to wire. A formal no-progress/repeated-failure signal for `loop-state.md` (raised in a
  separate pre-planning discussion, not in the original v1.9 candidate) was evaluated and
  explicitly deferred: no real stuck-loop incident has been observed, and building the
  taxonomy ahead of a validated need would contradict this release's own audit-first discipline
  — noted below as a v2.0/evidence-graph candidate. A Token Economics benchmark needs a live,
  human-run comparison and is left for the maintainer to run separately, outside this release.

- **v1.8.0 (2026-08-09):** Autonomy levels. `workflow.autonomy_level` (`manual`/`supervised`/
  `autonomous`, default `manual`) ships as a **new axis orthogonal to** the 5 existing
  `execution_modes` (`docs/execution-modes.md`) — it does not replace or duplicate them.
  7 deterministic guardrails (completion status, evidence validation, verification gates, scope
  boundary, transition validity, resource sufficiency, human override) gate every automatic
  transition; any failure returns control to a human, same as `manual`. An `autonomy_profile`
  frontmatter extension ships across all 13 skills (`supported_levels`, `auto_continue_condition`,
  `blocking_conditions`, `evidence_required`), validated by `scripts/check-skills.sh` the same way
  `extends`/`requires`/`produces`/`depends_on`/`conflicts` already are. `.sdd-agentic-flow/config.yml` gains
  `workflow.execution_mode`/`autonomy_level`/`autonomy_budget` (all additive; an existing config
  without them defaults to `guided`/`manual`, identical to pre-v1.8.0 behavior — `doctor
  --autonomy` reports `WARN`, not `FAIL`). New CLI surface: `init --execution-mode
  --autonomy-level`, `doctor --autonomy [--verbose]`, `context autonomy-state`, and
  `autonomous-resume [--force | --override-guard=<1-7> --reason="..."]`. There is no
  orchestration engine in this CLI — these commands validate the static contract and manage
  `.sdd-agentic-flow/autonomy/loop-state.md`, the execution-state file an agent maintains while running a
  workflow; they never invoke a skill themselves. Two new docs
  (`docs/autonomy-levels.md`, `docs/autonomy-guardrails.md`) plus a new shared reference
  (`shared/references/autonomy-guardrails.md`); `docs/execution-modes.md`,
  `docs/configuration.md`, `docs/compatibility-promise.md`, `docs/troubleshooting.md`, and
  `docs/inspirations.md` updated to cross-reference it. MCP stays **awareness, not a
  platform**: `autonomy_level` governs skill-to-skill transitions only, never tool use — a skill
  may call any available MCP integration at any autonomy level, exactly as before. Zero breaking
  changes: every field and command is additive, and no skill's documented behavior changed.
- **v1.7.0 (2026-08-09):** Local CLI testing without publishing. `npm run cli:dev` runs
  `bin/sdd-agentic-flow.js` straight from source against a persistent scratch project and an
  isolated `HOME`, for the fastest possible edit-and-look loop (`--fresh` resets it). `npm run
  cli:sandbox` goes further: a real `npm pack` — the exact tarball `npm publish` would ship —
  installed and run via `npx "file:<tarball>"` in a brand-new project directory with its own
  isolated `HOME`, exercising the same npm package resolution and `bin` shim a first-time
  consumer gets, on demand instead of only inside `test/cli.test.js`'s tarball e2e tests. Both
  scripts are plain Node with no new dependency, matching the existing `scripts/pack-dry.js`.
  Purely a contributor-workflow change — no CLI-facing behavior, skill, or capability-contract
  change, so it ships outside `compatibility-promise.md`'s scope.
- **v1.6.2 (2026-08-09):** Fixes v1.6.1's `npm publish` automation, which tagged and released on
  GitHub correctly but never actually reached npm — `publish-npm.yml` listened for `release:
  published`, an event GitHub does not fire for a release created by another workflow's own
  `GITHUB_TOKEN`. `npm publish` now runs in-process inside `.github/workflows/release.yml`
  itself; `publish-npm.yml` is removed (npmjs.com allows only one Trusted Publisher per package,
  and it's registered to `release.yml`). First version actually published through the fully
  automated pipeline end to end (push → CI → tag → release → npm publish, zero manual steps).
- **v1.6.1 (2026-08-09):** `npm publish` automation attempted via a second, event-triggered
  workflow (`publish-npm.yml`) — tag/GitHub release succeeded via v1.6.0's `release.yml`, but the
  `npm publish` step never ran (see v1.6.2). Reverses v1.6.0's "manual forever" decision on `npm
  publish` specifically, by explicit request; tag/GitHub-release automation from v1.6.0 itself is
  unaffected. `v1.6.2` is the version that actually completed the automated `npm publish`.
- **v1.6 (2026-08-09):** Project & Repository Engineering Quality. Applies the same rigor v1.5
  brought to skill content to the project's own engineering, driven by a direct repository audit
  rather than an assumed gap list. **Process change, the headline item:** tag creation and the
  GitHub release are now automatic — a `.github/workflows/release.yml` workflow, triggered only
  after `ci.yml` finishes successfully on `main`, tags and publishes a GitHub release once
  `package.json`'s version is ahead of the latest tag and `CHANGELOG.md` has a matching section
  (an accidental bump with no changelog entry is skipped, not released). The human decision point
  moves from "authorize the tag/release" to "authorize the push of the version-bump commit to
  `main`" — `npm publish` stays manual forever, with no exception, and is not part of this
  workflow. Also: closed the real security-scanning gap (CodeQL, `npm audit --audit-level=high`
  as a CI gate, Dependabot for `github-actions`+`npm`) — the `npm audit` fix required bumping
  `markdownlint-cli` to clear real high-severity transitive advisories, which introduced a new
  table-formatting lint rule (`MD060`) disabled in `.markdownlint.json` since it's unrelated
  noise, not a real defect, across many already-existing tables. Deduplicated the
  version-consistency check that `scripts/release-checklist.sh` and `scripts/check-skills.sh`
  each reimplemented independently into `scripts/check-version-consistency.js`. Added the
  open-source governance files a public repo was missing (`CODE_OF_CONDUCT.md`, issue/PR
  templates, `CODEOWNERS`, a `SECURITY.md` supported-versions table and disclosure SLA). Closed
  the `README.pt-BR.md` structural parity gap (8 missing section equivalents: Commands, Packs,
  Skill map, Agent workflows, Domain vocabulary, Examples, Safety boundaries, Publishing).
  Test coverage is now visible in CI via Node's native `--experimental-test-coverage`, no new
  dependency. `CONTRIBUTING.md` now also references `shared/references/evidence-standard.md`
  alongside `skill-authoring-standard.md`. No skill content changed — that stays v1.5's scope.
- **v1.5.1 (2026-08-09):** Docs-only patch — cites the open Agent Skills Standard
  (`agentskills/agentskills`) in `docs/inspirations.md` as an interoperability reference and
  points `docs/agent-compatibility.md`'s "Generic / other Markdown-first agent" row at it,
  since this toolkit's `SKILL.md` format already matches that shape by construction. No CLI,
  skill-content, or capability-contract change, so it ships as a patch, entirely outside
  `compatibility-promise.md`'s scope. Everything else proposed alongside that standard —
  `evals/`/`scripts`/`assets` skill subdirectories, `doctor --skills`, `skill validate`/`skill
  test`, quality-gate tooling — stays out of scope; a dedicated skill test framework was
  already deferred to v1.7+ in the v1.5.0 plan, and no "compliant"/"certified" claim is made
  without a formal validator run.
- **v1.5 (2026-08-09):** Skill System Consolidation. Prompted by a real audit of the 11 skills
  shipped in v1.4 rather than an assumed gap: the "evidence before claims" principle already
  existed, reworded slightly differently, in 6 of them, and `sdd-route` duplicated the routing
  table `shared/references/workflow-routing.md` already owned — both real maintenance drift,
  not missing content. Extracted both into new shared references
  (`skill-authoring-standard.md`, `evidence-standard.md`) that the affected skills now reference
  instead of re-deriving. Closed the one real flow gap the audit found — no stage before
  `sdd-create-specs` for an idea that isn't spec-ready yet — with `sdd-brainstorm`, and added
  `sdd-explain-me` for on-demand, never-required plain-language explanations of an already
  specified feature; both only ever hand off to existing skills rather than duplicating their
  output. 13 skills total, up from 11 — the result of closing two real gaps, not a "more skills"
  goal. Also normalized frontmatter key order across all 13 skills once the audit found the
  inconsistency was wider than assumed (7 of 11, not only `sdd-create-pr`), and added a
  dependency-independence analysis step to `sdd-implement-multi` before any parallelization
  recommendation. One new golden flow (`idea-to-spec`), bringing the total to 5.
- **v1.4 (2026-08-09):** CLI UX & Guided Onboarding. Colored, TTY-aware status output;
  "did you mean" suggestions on unknown commands/packs/agents and a clearer `uninstall`
  neither-flag message; a new public `--quiet` flag on `init`/`install`/`uninstall`/`discover`;
  partial core-skill install detection in `doctor` and the bare-invocation screen; `doctor` fix
  hints; a new opt-in `doctor --check-updates` (the sole, explicit exception to "no network
  access by default"); a numbered interactive menu on bare invocation, offered only when the
  process is genuinely interactive (real TTY on both streams, no `CI` env var) and never
  affecting piped/scripted/CI/agent invocations; and two exit-code bug fixes. Stays
  zero-runtime-dependency throughout — every addition is hand-rolled, informed by patterns
  studied in `anomalyco/opencode` and `vercel-labs/skills`.
- **v1.3 (2026-08-08):** Uninstall completeness and post-command guidance. Added
  `uninstall --apply --full` for a genuine clean-reinstall reset — it removes
  `.sdd-agentic-flow/context/project-context.md`, `.sdd-agentic-flow/snapshots`, and `.sdd-agentic-flow/reports` on top of what
  `--include-config` already covered, while `.specs/features` stays permanently protected, same
  as source code, under every flag combination. `init` and `install` now print a short
  "Suggested next step" line on success (pointing at `install core`, then `doctor` and
  `sdd-route`), suppressed during `doctor --smoke`'s internal calls so its own output stays
  clean. Also fixed a `docs/upgrading.md` line that overstated `.sdd-agentic-flow/config.yml` as never
  touched by `uninstall`, when `--include-config`/`--full` always removed it on request. All
  changes are additive under the v1.0 stability commitment — no documented command or flag was
  removed or had its default meaning changed.
- **v1.2 (2026-08-08):** CLI UX audit and upgrade. Fixed a real bug where `doctor` (and
  `doctor --contracts`, and the language-profile check) reported false `WARN`s after the
  documented Quick Start flow (`init` → `install core`, default `--scope user`), because those
  checks were hardcoded to project scope and never looked at the resolved user-scope install
  location. Added `--br`/`--en` as shorthand aliases for `init --language pt-BR`/`en-US`; real
  per-command help (`help <command>` / `<command> --help`, previously only `init --help`
  existed and the other five commands `FAIL`ed on `--help`); and a contextual, read-only status
  screen for bare `npx sdd-agentic-flow` (no command) instead of silently aliasing to the full
  `help` reference. All changes are additive under the v1.0 stability commitment — no
  documented command or flag was removed or had its default meaning changed.
- **v1.1 (2026-08-08):** dropped Node.js 18/20 as supported versions — CI-required minimum is
  now Node 22 (Maintenance LTS), with 24 (Active LTS) and 26 (Current) also required; a
  compatibility-reducing change under the v1.0 stability commitment, so it ships as a minor
  release with a matching `CHANGELOG.md` entry rather than silently. Also fixed four
  independent CI bugs (macOS `bash` 3.2 vs `mapfile`, Windows CRLF vs Biome, Windows `.cmd`
  spawn without a shell, Puppeteer sandbox on `ubuntu-latest`) and switched CI from
  `npm install` to `npm ci` for reproducible installs.
- **v1.0 (2026-08-08):** public go-live — first public stability commitment. The CLI's
  documented argument surface and the environment support matrix now follow the same
  minor/major-only change rule already established for skill capability contracts (see the
  "v1.0 stability commitment" section in [compatibility promise](docs/compatibility-promise.md)).
  No new product features; this release audits and freezes what v0.6–v0.9 already built.
- **v1.x (open):** future work adopted from validated need, not assumed in advance — candidates
  include adapters beyond `local-files`/`github` (Jira, Linear, Azure DevOps, Notion, Slack) and
  maturity-model documentation. Nothing in this line is committed or scheduled.

## Future direction (post-1.9.1, v2.0 undefined)

**v2.0 is deliberately undefined.** It is not the next release, has no scope, no acceptance
criteria, and no schedule. By explicit maintainer decision (2026-08-10), the project evolves
through several more incremental, audit-first minor/patch versions first — each one scoped the
same way v1.5 through v1.9.1 already were: a real gap found by reading the code, not a
pre-assigned roadmap slot. There is no fixed number or sequence of versions between here and
v2.0; the next one is whatever the next real audit finds, decided when that work actually
starts, not now.

At this point, the strongest lever is not adding another mechanism — skills, contracts,
evidence, handoff, routing, autonomy, guardrails, and `loop-state.md` already exist. It's making
the mechanisms that already exist work together as one coherent system rather than growing the
list further; a watched direction below only earns a real version when an audit finds a gap none
of the existing pieces already cover.

This replaces the earlier "v2.0 — Agentic SDD Platform (candidate)" outline that used to live in
this section. That fuller sketch is preserved, unchanged, in
`.local/gmm/sdd-agentic-flow/v2.0.0-implementation-plan.md` for whenever v2.0 is eventually
picked up — it is historical/reference material now, not a committed plan, and should be
re-audited against the codebase at that time rather than trusted as still accurate.

**Directions being watched, not committed to any version:** a longer-range pre-planning
discussion surfaced several themes that may eventually justify real work — none of them do
today, and none is scheduled. Recorded here so they have a home without inflating any specific
version's scope:

- A no-progress/repeated-failure signal for `loop-state.md` (an `Attempt:`/`Progress:` field,
  self-evaluated by the invoking agent the same way guardrails 1–6 already are) — raised and
  explicitly deferred during v1.9.0's planning; becomes real scope only if a genuine stuck-loop
  incident is actually observed, not before.
- An evidence graph linking requirement → spec → task → code → test → validation → PR, exposed
  via `doctor --evidence-graph` rather than a new top-level command — extending the existing
  optional `REQ-{id}` traceability convention in `artifact-contracts.md`, not inventing a new ID
  scheme.
- `.sdd-agentic-flow/` as portable, cross-agent context — evolving what already exists (`config.yml`,
  `context/`, `reports/`, `snapshots/`, `autonomy/loop-state.md`) rather than a parallel
  structure.
- Cross-agent portability as a documented extension of the existing adapter pattern
  (`local-files`/`github`, `docs/adapters.md`), which stays at the edge, carrying no
  methodological logic of its own.

**Out of scope, holds regardless of how many versions come before v2.0:** an agent
runtime/scheduler, a hosted MCP platform, a model-provider abstraction/router, a heavy
workflow-DAG engine, a proprietary skill format, a skill marketplace ahead of validated need,
mandatory telemetry, any `while (...)`-shaped orchestration loop inside this CLI, unbounded or
unattended-forever autonomous execution (autonomous stays guarded, bounded, and interruptible —
see [autonomy guardrails](docs/autonomy-guardrails.md)), and quantitative token/speed/cost claims
without a reproducible benchmark backing them (see the token economics note in
[README.md](README.md)). Matches
`docs/design-principles.md`: concrete claims over broad compatibility, security, or autonomy
promises.

- **v0.1:** local-first core and full public skill pack.
- **v0.2:** Adoption & Trust Release: interactive setup, local validation, rollback, agent docs, and public examples.
- **v0.3:** Language Profiles & Brazilian Workflow Release.
- **v0.4:** TDD Implementation Baseline.
- **v0.5:** Workflow Navigation & Task Quality.
- **v0.6:** Foundation Architecture Release — capability contracts, a baseline registry,
  project discovery and context, feature profiles, and a baseline compliance gate.
- **v0.7:** Operational Excellence (start) — capability contracts v2 (`depends_on`/`conflicts`
  plus consumer-side `doctor --contracts`), light artifact contracts, Project Discovery 2.0
  (architecture/CI/platform signals), an agent-neutrality regression guard and action
  vocabulary, the first decision guides and a compatibility matrix, and the
  `sdd-reverse-engineer` skill.
- **v0.8:** Flow Consolidation & Dynamic Project Context Release — resolved
  `sdd-reverse-engineer`'s place in the Flow by merging it into `sdd-create-specs` as an
  existing-code mode, restoring a single entry point for the Specification step (12 skills →
  11). Also formalized Dynamic Project Context:
  `project-context.md` now carries provenance (generated-at, repository revision, branch), with
  new `context status`/`context refresh` commands to inspect and regenerate it explicitly,
  additive to the unchanged `discover [--force]`. Deliberately no Context Indexing, Context
  Query, knowledge graph, RAG, or vector database — those remain out of scope for the core
  product, to protect the toolkit's focused SDD-flow identity.
- **v0.9:** Installation, Portability & Public Readiness Release — `install` defaults to a
  zero-project-footprint `--scope user`, with an Agent Integration Layer for 4 officially
  supported agents (Codex CLI, Cursor, Claude Code, VS Code + GitHub Copilot); a cross-platform
  CI matrix (Node 18–24 on Linux, full pipeline on macOS/Windows) and a centralized platform
  layer in the CLI; a vendored `requires_cli` version-compatibility gate; the skill catalog
  (`docs/skills-catalog.md`); 5 golden flows proved as integration tests; and
  `docs/upgrading.md`/`docs/troubleshooting.md`/`docs/environment-compatibility.md` closing the
  documentation gaps the beta had accumulated. See `CHANGELOG.md` for the full list. Skill
  cards ✅ delivered (`docs/skills-catalog.md`).

With v1.0.0, the project leaves beta: the CLI argument surface and environment support matrix
now carry the stability commitment described at the top of this file. Future v1.x scope
remains open and will be defined from validated needs rather than assumed in advance.