Skip to content

CHANGELOG.md

Latest commit

 

History

History
883 lines (742 loc) · 51.5 KB

CHANGELOG.md

File metadata and controls

883 lines (742 loc) · 51.5 KB
Raw

Changelog

All notable changes to Product Forge are documented here. Format follows Keep a Changelog. Versioning follows Semantic Versioning.

[Unreleased]

Nothing yet.

1.7.0 — "Ivysaur" — 2026-06-13

Feature wave (v1.7, 2026-06) — roadmap items P1-B/P1-C/P2-A/P2-C/P3-A/P3-B/P3-C from docs/improvements/2026-06-feature-roadmap.md, triangulated from the SpecKit-community gallery × Hermes runtime leverage × internal gaps. Every addition is executable + gated by a lint-docs/doctor check and keeps the human gate. Followed by a two-reviewer independent code review whose findings are folded into the Fixed section below.

Added — feature wave (v1.7)

  • Cross-model code review (P1-B) — code-review --cross-model: exports the consolidated gate-review.md + git diff as a portable review-package.md, has a different model review it out-of-band, and ingests its findings as F-NNN (source: cross-model). reviewed_by_model stamped on the gate (CARRIER-enforced). Config review.cross_model.
  • Constitution↔code standing drift layer (P1-C) — sync-verify Layer 10 and verify-full Layer 11 re-assert the project architecture constitution against the code (resilience / EDA / layering / security), deterministic probe where possible. New lint-docs LAYER-COUNT rule keeps the "N-layer" prose honest. All "9-layer" prose → 10.
  • Lessons → Hermes skills (P2-A) — retrospective Step 5B promotes a lesson that recurs across ≥learning.min_recurrence features into a reusable SKILL.md via skill_manage (skills_promoted[] carrier). Cross-project, cross-session. No-op outside Hermes. Config learning.*.
  • Parallel implementation (P2-C) — implement --parallel runs path-disjoint task groups via delegate_task, proven independent by the portfolio conflict matrix; reconciled serially under the state-lock, single gate. policy §1.1 carve-out (intra-phase only).
  • --dry-run is now normative (P3-A) — runtime §7 rewritten from a "planned" stub into an enforceable contract: write redirection to .forge-dry-run/, no status mutation, no external side-effects, a DRY-RUN-REPORT.md per phase. Composes with --ci/--parallel/--cross-model.
  • Phase-map single source (P3-B) — docs/schema/phase-map.yml is the canonical phase set + per-mode applicability; the two forge.md tables now render it and lint-docs PHASEMAP asserts they agree (kills the phase-map drift class, mirroring the enum single-source). Completes step 3 of the schema-as-source design note.
  • status --cost + scripts/cost-report.js (P3-C) — rolls up the per-phase tokens_in/out / tool_calls telemetry (recorded by the orchestrator at phase completion when the host exposes usage accounting; see runtime §8.1a) per feature and --portfolio. Dollar cost only when the caller supplies a rate; reports "no telemetry recorded" rather than zeros when the host provides none.
  • lint-docs self-test 9→23; doctor 12→15 checks; 12 helper scripts.

Fixed — independent code review (post-wave)

A two-reviewer pass (Node-scripts + doc-contract integrity) on the feature wave. All findings reproduced and fixed; each lint-rule fix carries a regression test.

  • Phase-status scope (HIGH). validate-traceability.js readCompletedPhases matched name: completed lines anywhere, so a sibling block keyed by phase name (e.g. gate_summary:) falsely marked phases complete → spurious must_have.code/tests errors and a false --strict FAIL. Now scoped to the phases: block.
  • Layer-count report templates (HIGH). sync-verify's report still emitted {1-9} / {N}/9 after Layer 10 (P1-C) was added, so constitution↔code drift had no report slot. Fixed to {1-10} / {N}/{applicable}.
  • Gate carrier schema (P1-B). reviewed_by_model + cross_model_findings were stamped on gates[] but missing from the canonical schema and the runtime §6 audit trail — added to both.
  • skills_promoted read-back (P2-A). retrospective Step 5B wrote the carrier but never read it; it now drives the create-vs-patch decision (idempotent across features). skills_promoted + cross_model_findings added to the lint CARRIER registry.
  • Token-telemetry producer (P3-C). status --cost consumed per-phase tokens_*/tool_calls that no step produced; added the producer hook in runtime §8.1a (host-dependent) and corrected the overstated "already captures" wording.
  • --dry-run implementation gap (P3-A). The §7 mandate was callout-deep; added explicit honor-notes to all 10 spine writing phases and a coverage clause (§7.3).
  • Lint-rule precision. LAYER-COUNT no longer false-positives on a line naming both sync-verify and verify-full; SCRIPT-PATH is now per-occurrence (a bare node scripts/… is flagged even in a file that uses ${PLUGIN_ROOT} elsewhere); PHASEMAP flags empty/word-form per-mode cells instead of skipping them.
  • Script hygiene. cost-report.js num() uses Number() (decimals + thousands separators no longer truncate); require.main guards + module.exports added to cost-report/check-links/validate-traceability/doctor; a non-list steps: block now warns instead of being silently ignored.
  • Docs. .forge-dry-run/ described as "add to your project .gitignore" (it lives in the consumer project); PRODUCT_FORGE_COST_RATE_IN/OUT documented in config.md; the --dry-run "composes with --parallel/--cross-model" note scoped to standalone sub-skill invocation.
  • lint-docs self-test 18→23; validate-traceability 20→23.

Repo-hardening + tooling pass on top of v1.6.0 — addresses the 2026-06 deep review (docs/improvements/2026-06-deep-review.md). No behavioural change to the lifecycle; closes a runtime-portability bug, a dead config switch, and residual doc drift, and adds a deterministic consistency gate so the whole class can't silently return.

Fixed

  • Bundled-script path resolution (P1). forge.md, verify-full.md, and test-run.md invoked node scripts/… / require('./scripts/…') by bare relative path, which does not resolve once the plugin is installed to ~/.claude/plugins/cache (cwd = user's project). All call sites now route through ${PLUGIN_ROOT} with a WARN-and-fall-back-to-LLM rule. New normative section docs/runtime.md §1A "Locating bundled scripts".
  • a11y_gate dead switch. The key was documented as axe | none but no command read it (the axe floor was unconditional). test-plan.md §4 now gates generation and test-run.md §4.7 gates execution on a11y_gate.
  • how-it-works-v2.md §1 still said "v1.5 adds…" → updated to the v1.6 narrative; removed the phantom docs/adr/ + docs/reviews/ tree lines (those dirs were intentionally removed) and refreshed the doc/script tree to reality.
  • QA test plan quick-smoke said "18 phase rows" (actual 20), pinned version: "1.5.0", and carried an express-omitting abort message → corrected and made executable (delegates to doctor.js / lint-docs.js; dynamic counts replace hard-coded ones).
  • Task-ID drift. Canonicalized on T0NN (with TASK-NNN as an accepted alias) across schema.md §8, file-structure.md, traceability-matrix.md, and verify-full.md; added missing SEC- / F- rows to the ID registry.
  • docs/claude-plugin.md relative-ref typo (./config-template.yml).

Added

  • scripts/lint-docs.js — deterministic doc-corpus consistency linter (zero-dep, --selftest, --json). Rules: XREF (dangling refs + plugin-root escapes + anchors), CMD-COUNT, VERSION (extension.yml == plugin.json + stale narrative), ENUM, PHASEMAP, CONFIG-READER (dead-switch detection), SCRIPT-PATH (${PLUGIN_ROOT} enforcement), ID-FORMAT.
  • scripts/doctor.js — aggregate self-check (every --selftest + lint-docs
    • a live fixture smoke + release-blocking invariants). One command to gate a change; node scripts/doctor.js.
  • .github/workflows/ci.yml — runs doctor on every push/PR (+ best-effort claude plugin validate). The repo's first automated consistency gate.
  • fixtures/features/demo/ — a known-good feature state (.forge-status.yml
    • traceability.yml + journeys.yml) that passes validate-traceability.js --strict; real-file test input for doctor and CI.
  • docs/concept.md — 10-minute mental model + the producer→consumer wiring map for new contributors.
  • docs/improvements/2026-06-schema-as-source-design-note.md — staged design for single-sourcing enum/count invariants from the schema (preventive fix for the drift class).
  • forge.md command-syntax note (extension /speckit.product-forge.X vs plugin /speckit-product-forge:X).
  • .gitignore: ignore .serena/ and .remember/ agent-runtime dirs.

Added — deeper enforcement (2026-06 follow-up)

  • docs/schema/enums.yml — the single canonical source for the feature_mode / gate-decision / phase-status / gate-policy-action enums. lint-docs.js ENUM now reads it and asserts the curated enumeration sites (schema.yml, schema.md, runtime.md, forge.md) list the full canonical set — true single-source enforcement, not a spot-check (step 2 of the schema-as- source design note).
  • lint-docs.js CARRIER rule — every cross-phase carrier field (red_gate, reviewed_sha, commit_sha, the doc↔code drift carrier, produced_by) must have BOTH a producer and a consumer that name it. Direct antidote to the "callout-deep" class (a field written but read by nobody).
  • lint-docs.js GATE-POLICY rule — validates docs/templates/gate-policy.yml: every phase key is a real phase and every routing value is a canonical action, so forge --ci can't be driven by a malformed policy.
  • validate-traceability.js STEP coverage — object-shaped journey steps ({id, tests}) are now checked individually (≥1 test once test_run completes), fulfilling the template's "each step should map to ≥1 test"; bare steps still fall under journey-level coverage. Demo fixture upgraded to object-shaped steps.
  • scripts/check-links.js — best-effort external-link liveness checker (zero-dep, built-in fetch, --selftest, ignores illustrative/placeholder/ own-repo URLs). Wired as a continue-on-error CI job; never blocks a merge.
  • CONTRIBUTING.md — contributor workflow anchored on doctor + concept.md and the linter rules.
  • doctor now also runs the check-links self-test + STEP-aware fixture smoke (13 checks); lint-docs self-test 14/14, validate-traceability 20/20.

1.6.0 — "Bulbasaur" — 2026-05-29

First codenamed release 🌱 (Bulbasaur). A minor, fully additive release in three strands: (1) the SDD-flow wave — a spec-anchored living spec with a full traceability matrix, structured journeys → Playwright E2E, FE↔BE contract-first APIs, telemetry MCP wiring, a risk-scored two-layer gate review, and a first-class express track; (2) configurable documentation storage strategies, a single path-resolution contract, and a layered global config; (3) a repo-wide consistency/audit pass (56 findings). No breaking changes — with no new config keys set, behavior is byte-for-byte identical to v1.5.1. Schema v3 stays additive; the flat layout remains the zero-config default.

Added — Configurable storage strategies + global config

  • storage_strategy config key — selectable feature-root placement, all four values active: flat (default, today's features/<slug>/), domain-nested (features/<domain>/<slug>/), ddd (features/<context>/<slug>/, backed by a features/domains.yml registry), and workspace (features/<workspace>/<slug>/, monorepo scope.primary). The internal artifact tree is invariant across every strategy. See docs/file-structure.md §"Storage strategies", config-template.yml, and the registry template docs/templates/domains.yml.
  • Path-Resolution Contract — a single normative rule (docs/runtime.md §12) for resolving a feature root from a slug (resolve) and enumerating all features (enumerate), parameterized by storage_strategy, so every command/script shares one path rule instead of scattered globs.
  • scripts/lib-paths.js — the executable form of the contract (resolveFeatureDir() + enumerateFeatures(), depth-tolerant and strategy-agnostic), with its own --selftest. gate-risk.js, validate-traceability.js, and migrate-status-v2-to-v3.js now resolve/ enumerate through it, and the cross-feature commands (portfolio, status, sync-verify, feature-flag-cleanup, bridge) + single-feature resolvers (research, monitoring-setup, backfill) point at the contract. lib-paths reads the ddd domains.yml registry (O(1), read-only; orchestrator heals it). All four strategies work end-to-end (scripts find nested features across domain-nested/ddd/workspace; _archived/_portfolio/domains.yml excluded from enumeration; ambiguous bare slugs error with a qualified-ref hint).
  • Global (cross-project) config layer — ~/.product-forge/config.yml (canonical) with $XDG_CONFIG_HOME/product-forge/config.yml fallback, layered shipped defaults < global < project < per-feature < env with deep-merge of nested keys, plus a config-key → layer classification table. See docs/config.md §"Global Configuration".
  • Documented previously-undocumented config keys: supply_chain.license_allowlist, supported_locales, constitution_path.

Fixed — repo-wide consistency/audit pass (56 findings)

  • Repo-wide consistency pass (56 verified findings; see docs/improvements/2026-05-system-audit.md): command count 29 → 31; version coherence at 1.6.0 across README / CHANGELOG / extension.yml / QA plan; sync-verify consistently described as 9-layer; status-enum (completed_with_known_issues), gate-enum (rolled_back), and supporting-command phase keys reconciled into the canonical schema; the api_docs sibling collision renamed to api_docs_report.
  • Six command/template files whose inner triple-backtick code fences prematurely closed the outer block (bridge, code-review, product-spec, retrospective, tracking-plan, portfolio-report) now use 4-backtick wrappers; fixed a malformed GFM table in experiment-design.
  • Three real helper bugs: validate-traceability.js (substring task-ID matching → exact normalized equality; journey-coverage check no longer skipped when edges exist); gate-risk.js (countFindings now counts only open findings, so the CI no_open_critical gate clears once findings are resolved); acquire-lock.sh (rejects unsafe session_id to prevent JSON/grep injection).
  • release-readiness license-allowlist env override renamed to the documented PRODUCT_FORGE_SUPPLY_CHAIN_LICENSE_ALLOWLIST prefix.

Added — 2 new commands (catalog now 31)

  • speckit.product-forge.design-system-harvest (Phase 2H, opt; UI features) — Harvests a read-only manifest of the project's in-code design system (components with CMP- ids, props, variants, stable selectors, in-code token refs, Storybook) so mockups, component decomposition, and UI verification are grounded in real components rather than abstractions. The in-code design system stays the single source of truth.
  • speckit.product-forge.spec-merge (Phase 10 + cross-cutting; living spec) — Merges a feature's delta specs (ADDED / MODIFIED / REMOVED) into the canonical specs/<domain>/ and archives the change with audit history (spec-anchored source of truth, OpenSpec model).

Added — Express mode (first-class)

  • feature_mode: express is now a first-class lifecycle mode alongside lite, standard, and v-model. Express runs a minimal combined pass (product-spec minimal → plan inline → implement → verify) for trivial copy/config/one-liner changes, with everything else marked not_applicable. Escalation to lite/standard is append-only. Validated in forge.md Mode Resolution and the canonical schema.

Added — Living spec, delta specs, and traceability

  • Canonical specs/<domain>/ living spec with stable REQ-NNN requirement ids; bridge emits delta specs (ADDED/MODIFIED/REMOVED) against it, change-request propagates deltas, backfill seeds canonical specs for brown-field entry, and spec-merge folds approved deltas back in.
  • Live traceability.yml matrix (REQ→US→JRN→FR→CMP→API→TASK→code→TEST→EVT) — seeded by tasks, filled by implement as tasks complete, and consumed by verify-full instead of re-deriving the chain. New helper scripts/validate-traceability.js with a --selftest entry point.

Added — Structured journeys → Playwright E2E

  • Structured journeys are now first-class artifacts in product-spec/journeys/journeys.yml (JRN/STEP/EDGE, GIVEN/WHEN/THEN), the authoritative E2E source of truth (docs/journeys.md + journey-spec template). test-plan generates Playwright specs directly from journeys.yml (selectors via component-map.yml); test-run maps failures back to JRN/STEP/EDGE. playwright-cli is the committed default runner (e2e_runner config).

Added — FE↔BE contracts (contract-first)

  • bridge defines contract-first OpenAPI 3.1 + AsyncAPI (API-* ids) shared by front-end and back-end; api-docs becomes validation/regeneration against the contracts and the implementation. verify-full and sync-verify gain a contract-drift leg.

Added — Telemetry MCP wiring and quality gates

  • Real telemetry via connected MCPs — retrospective pulls funnels/errors from PostHog/Amplitude and Sentry (NewRelic optional); monitoring-setup creates real dashboards/alerts; experiment-design can create the real PostHog experiment.
  • Two-layer code review — code-review adds a machine-gate layer (lint/types/security/coverage) before the agent/human judgment dimensions, plus a doc↔code reconciliation dimension.
  • Risk-scored gate review — gate-review.md / gate-policy.yml templates and scripts/gate-risk.js (with --selftest) drive a unified F-NNN gate-finding model and the --ci auto-recommend pre-gate.
  • WCAG-AA accessibility gate — test-plan emits one @axe-core/playwright check per journey (JRN) and test-run executes it.

Changed

  • sync-verify expanded from 7 to 9 layers — adds Layer 8 (FE↔BE contract drift) and Layer 9 (doc↔code reconciliation) on top of the original seven artifact-pair layers.
  • verify-full adds Layers 7–10 — journey↔E2E coverage, UI↔design-system, FE↔BE contract drift, and doc↔code reconciliation.
  • Test-first Red gate — tasks orders test tasks before implementation and implement enforces a Red gate (unit/contract tests written and confirmed failing) before implementing Must-Have stories.
  • All consumers point at structured journeys/ — every command and doc that read the old free-form product-spec/user-journey*.md now reads product-spec/journeys/journeys.yml.
  • extension.yml — version 1.6.0; registers design-system-harvest and spec-merge (31 commands total); description and tags updated for the v1.6 wave.
  • config-template.yml / docs/config.md — documented v1.6 keys: flow_mode, e2e_runner, a11y_gate, telemetry, design_system, default_track_hint; v1.6 file-layout appendix (canonical specs/, contracts/, design-system/, journeys/, traceability.yml).

Phase accounting

  • Standard mode is 8 always-on core phases + 12 optional/conditional = 20 phase slots (Phase Map = 20 rows; 19 have a ## Phase section — 2H is a Phase-2 helper — plus a post-launch Retrospective); forge.md's Phase Map is the source of truth.

Migration notes

  • No action required. Existing features continue to work; nothing on disk moves. The flat feature layout remains the zero-config default. The first time a v1.6-aware skill writes to a feature's .forge-status.yml it keeps schema_version: 3 and may populate new optional fields as it runs.

1.5.1 — 2026-04-24

Docs-only patch. No behavioural change — closes a documentation gap on how users install the optional V-Model dependency.

Changed

  • README.md — new "V-Model mode (optional)" subsection under Requirements that names the external leocamello/spec-kit-v-model plugin (≥0.5.0), includes the install command, and spells out the "hard dependency only for v-model mode" rule with an explicit "no silent fallback" note for regulated/safety-critical work.
  • config-template.yml — feature_mode comment expanded: the v-model value now includes the install command for the external plugin and the abort-on-missing rule.
  • docs/config.md — rewrite the v-model bullet in feature_mode documentation to describe what Product Forge owns vs what the V-Model plugin owns, include the install command, and link to docs/v-model-integration.md.

No functional code change. The plugin already aborted with the install command when v-model mode was selected without the dependency; this release just makes the dependency visible to users before they try.

1.5.0 — 2026-04-19

Minor release (additive). Expansion of the lifecycle with portfolio view, brown-field entry, lite mode, full monorepo support, optional V-Model integration, unit + integration test phases, and operational readiness artifacts. Schema v3 for .forge-status.yml is additive over v2 — no breaking change to existing features; a lazy migration stamps schema_version: 3 on first write.

Added — 7 new commands

  • speckit.product-forge.portfolio — Cross-cutting portfolio view. Scans every features/*/.forge-status.yml, produces feature table, file-conflict matrix, dependency graph (Mermaid), and suggested merge order. Read-only.
  • speckit.product-forge.backfill — Brown-field entry. Reverse-engineers a feature folder from existing code: retro product-spec, plan, simplified tasks, .forge-status.yml with backfilled: true, and a gaps-report of missing artifacts.
  • speckit.product-forge.monitoring-setup (Phase 9.5, opt) — Produces real NewRelic-compatible dashboard JSON, alert rules, and SLI/SLO doc from plan NFRs and tracking-plan events. Wraps newrelic-dashboard-builder.
  • speckit.product-forge.migration-plan (Phase 5.5, opt, conditional) — Generates zero-downtime migration plan with forward.sql, rollback.sql, validation.sql, backfill plan, and risk matrix when plan.md introduces schema changes. Wraps db-migration-manager / mongodb-ops.
  • speckit.product-forge.i18n-harvest (post-bridge, opt) — Extracts user-facing strings from wireframes/spec, generates feature-namespaced locale keys, stubs TODO entries in every configured locale. Wraps i18n-workflow.
  • speckit.product-forge.experiment-design (Phase 9B, opt) — Forces a pre-registered A/B plan — hypothesis, MDE, sample size, exposure rules, guardrails, decision rule — before shipping a flag-gated feature. Wraps feature-flag-ab-testing.
  • speckit.product-forge.feature-flag-cleanup — Cross-cutting stale-flag audit. Scans every flags/registry.yml, cross-checks codebase, produces removal recipes for flags past cleanup_after. Read-only; wraps feature-flag-manager.

Added — Monorepo support (first-class)

  • codebase.paths block in project config, with workspace_type (pnpm | yarn | npm | turbo | nx | rush | lerna | none) driving test- runner resolution. Legacy codebase_path still supported.
  • scope.paths, scope.cross_workspace, scope.primary on .forge-status.yml — names which workspaces a feature touches.
  • Workspace-prefixed paths in tasks.md and task_log[].paths (e.g. backend:src/users.ts).
  • Per-workspace conflict matrix in /portfolio with grouped "By workspace" section.
  • Affected-only test execution in implement + test-run when running under nx / turbo / pnpm workspaces.
  • Cross-workspace change propagation — scope widens automatically when a change request touches code outside the original scope; recorded as gate condition.
  • Documented in runtime.md §9, config.md Paths.

Added — V-Model integration (optional extension)

  • optional_extensions block in extension.yml declaring leocamello/spec-kit-v-model (≥0.5.0) as an opt-in dependency.
  • feature_mode: v-model is now a real mode, not a stub. When selected, forge.md detects the V-Model extension and delegates the middle of the lifecycle (V1–V13) to its 14 commands: requirements, acceptance, system / architecture / module design paired with system / integration / unit test plans, trace, peer-review, test-results ingestion, audit report.
  • No silent fallback: if V-Model plugin is absent, v-model mode aborts with the install command. Regulated work must not degrade.
  • Domain selection via v-model-config.yml (iec_62304 | iso_26262 | do_178c | generic).
  • New docs/v-model-integration.md covers the full phase map, detection, fallback rules, status-file additions.

Added — Testing strategy (universal)

  • New docs/testing-strategy.md — universal (framework-agnostic) pyramid, when unit vs integration vs contract vs E2E, per-layer coverage criteria, anti-patterns, flaky-test handling, test-data management, monorepo-aware execution.
  • test-plan.md §5E Unit Tests (TC-UNIT-NNN) — derived from module boundaries + behavioural acceptance criteria. Framework-agnostic.
  • test-plan.md §5F Integration Tests (TC-INT-NNN) — beyond endpoint contracts: service↔DB, service↔cache, event emitter↔listener, middleware stacks, cross-workspace integration.
  • test-run.md §4E Unit and §4F Integration — non-browser execution with the same auto-fix loop; §4F handles testcontainers / docker-compose / in-memory / shared-DB isolation strategies.

Added — Structural capabilities

  • .forge-status.yml schema v3 — Additive over v2. New fields: feature_mode, backfilled, v2_native, phase started_at/completed_at/tokens_in /tokens_out/tool_calls/digest_path/skipped/skip_reason, task_log[] (renamed from early-draft tasks[] to avoid collision with phases.tasks) with size (XS/S/M/L/XL), paths, and commit_sha, gates[].approvals, gates[].skip_reason, dependencies.depends_on / depended_on_by, role_approvals.solo_mode / required_roles_per_phase. New status enum value not_applicable for out-of-mode and backfilled phases. Full spec in docs/schema/forge-status-v3.schema.yml. Migration rules in docs/schema/migration-v2-to-v3.md. Optional helper script scripts/migrate-status-v2-to-v3.ts.
  • State-lock protocol — .forge-status.yml.lock file-based lock with TTL-based takeover. Prevents concurrent-writer corruption between the orchestrator and sub-skills. Documented in docs/runtime.md §2.
  • Per-phase digests — Every major phase (research, product_spec, plan, tasks, implement, verify) now writes <phase>/digest.md. Runtime refuses to mark a phase completed without a digest. Downstream phases (verify-full, portfolio, retrospective) read digests first to keep context budgets small. Template: docs/templates/phase-digest.md.
  • Lite mode — New feature_mode field selects a 5-phase map (problem-discovery opt → product-spec → plan → implement → verify) for small features. Escalation to standard is append-only. Details in docs/policy.md §4.
  • Skip-reason policy — Skipping an optional phase now requires a free-text reason when require_skip_reason: true (default). Reason is persisted on both the phase and the gate entry. Enforced by all skippable commands. Details in docs/policy.md §3.
  • Learning loop — .product-forge/lessons.md append-only log. Written by retrospective at launch close, read by research as a new dimension ("Prior lessons that apply") scored by tag overlap. Format in docs/lessons-format.md.
  • Drift budget — sync-verify now categorizes drift as structural (always human-in-the-loop) or cosmetic (whitespace, ordering, stale dates). Opt-in sync_verify.auto_resolve.cosmetic auto-fixes whitelisted drift only; structural drift never auto-resolves. Budget warns when cosmetic count exceeds threshold.
  • Release-readiness becomes an artifact producer — Step 1D now invokes feature-flag-manager to produce flags/registry.yml; Step 3D invokes newrelic-dashboard-builder to produce monitoring/dashboard.json, alerts.yml, slo.md. Graceful fallback when provider skills are missing.

Changed

  • commands/forge.md refactored. Operating rules moved to docs/policy.md; runtime flow (config, state lock, detection, resume, pre-flight, sync, gate audit, digest enforcement, context budget) moved to docs/runtime.md; status schema narrative moved to docs/schema.md. The orchestrator file now focuses on phase delegation and the mode- resolution entry. No behavioral change; cross-references only.
  • config-template.yml — New keys: default_feature_mode, require_skip_reason, sync_verify.drift_budget.{cosmetic, structural}, sync_verify.auto_resolve.cosmetic.
  • research.md Step 2.5 — Consults .product-forge/lessons.md for matching prior lessons and surfaces them in research/README.md.
  • retrospective.md Step 5 — Drafts lesson blocks, confirms with user, appends to lessons.md, records count in phases.retrospective.lessons_added.

Release-prep hardening

Surfaced by the plugin test plan dry-run and closed before release:

  • Broken historical refs removed from CHANGELOG.md, README.md, and docs/how-it-works-v2.md — pointed to archive directories that are not in this tree.
  • Policy.md §3 tightened — empty skip reasons under require_skip_reason: true now explicitly reject the gate and re-prompt; no skipped gate entry is written until a non-empty reason is supplied.
  • Enum validation added to commands/forge.md Mode Resolution and docs/runtime.md §4 pre-flight — invalid feature_mode, phases.<name>.status, or gates[].decision values abort with a clear message instead of falling through silently.
  • tasks.md Step 4.1 — hard structural checks for task-ID uniqueness and monorepo workspace-prefix validation. Duplicates and unknown workspace names now abort the phase with a pointer to the offending line instead of propagating into task_log[].
  • Test-plan self-references — smoke and Layer B criteria updated to exclude docs/qa/plugin-test-plan.md (which legitimately names the patterns being searched for).

Migration notes

  • No action required. Existing features continue to work. First time a v1.5.0-aware skill writes to a feature's .forge-status.yml, it stamps schema_version: 3 and may populate new optional fields as it runs.
  • Optional: run scripts/migrate-status-v2-to-v3.ts once to stamp every feature at once.
  • Monorepo support (GitHub issue #1) remains unchanged in this release. Schema v3 fields reserve room for it (dependencies, backfilled) but the codebase-path configuration remains single-path. Tracked for a follow-up release.

1.4.0 — 2026-04-04

Minor release. Spec quality and lifecycle hardening across research, bridge, plan, and revalidation phases. No new commands — every improvement extends an existing phase with stricter validation, richer artifacts, or new self-checks.

Added

  • Codebase Constraint Analysis in research — the codebase-analysis dimension now captures concrete constraints (exact identifiers, payload interfaces, source paths) and Event / Message Patterns, so downstream phases see real integration shape instead of abstractions.
  • Dependency Discovery in bridge (Step 2.5) — bridge now walks sibling features' status files and surfaces upstream dependencies before writing spec.md, preventing silent coupling.
  • EDA Event Verification in bridge (Step 4.5) — when the plan touches an event bus, bridge verifies every produced event has a declared consumer contract and vice-versa; missing pairs are raised as CRITICAL before spec.md is approved.
  • Constitution Compliance auto-check in plan (Step 3.5) — reads the project's constitution (configurable path: config.yml → .specify/memory/constitution.md → skip) and auto-flags plan sections that violate declared principles. Results surfaced in the Approval Gate.
  • Feature-type detection in bridge (shared_infrastructure vs end_user) driving a conditional section table — infrastructure features don't need UX sections, end-user features don't need internal-API contracts. Removes boilerplate without removing information.
  • Unified review.md format in revalidate — every revision now writes four sub-sections: Open Questions Resolution (OQR), Decision Log, Change History, and the agent-notes block. Step 4B-post runs a drift-check between product-spec and spec.md after each approval round.

Changed

  • commands/bridge.md — spec.md template extended with Prerequisites, NFR Measurement Contract, Codebase Constraints, Consumer Contract, Testing Specification. Step 5 self-checks expanded from 6 to 10 with conditional guards based on feature type.
  • commands/plan.md — Approval Gate now shows constitution-compliance results alongside cross-validation status.
  • commands/revalidate.md — review.md init extended with OQR table and Decision Log; Step 3D writes all four sub-sections per revision; drift-check runs automatically after every approval.
  • config-template.yml — constitution_path key added (commented out by default) under the SpecKit Integration block.

Migration notes

  • No action required. All changes are additive. Existing features keep working; new features (or re-runs of a phase) pick up the richer templates automatically.

1.3.0 — 2026-04-01

Added — 5 new commands expanding the product lifecycle

  • speckit.product-forge.sync-verify — Cross-cutting 9-layer artifact consistency checker:

    • Detects forward drift (earlier artifacts not reflected in later) and backward drift (later decisions that should update earlier)
    • Checks 9 layers: research↔product-spec, product-spec↔spec.md, spec↔plan, plan↔tasks, tasks↔code, spec↔code, cross-links, FE↔BE contract drift, doc↔code
    • Each drift item: severity (CRITICAL/WARNING/INFO), direction, proposed resolution, human approval
    • --quick mode runs automatically between forge phase transitions (configurable via auto_sync_between_phases)
    • --fix mode applies approved resolutions after user confirmation
    • Outputs: sync-report.md, sync-report.json

  • speckit.product-forge.pre-impl-review (Phase 5C) — Combined design, architecture, and risk gate:

    • Design Review: state completeness (empty/loading/error/partial/offline), UX pattern compliance, accessibility pre-check, component reuse
    • Architecture Review: structural checks, integration point validation, NFR coverage
    • Risk Assessment: technical/scope/integration/rollback risks with likelihood×impact matrix
    • Rollout strategy recommendation based on risk profile
    • Optional for features with ≤5 tasks and no UI
    • Outputs: pre-impl-review.md

  • speckit.product-forge.code-review (Phase 6B) — Multi-agent code review:

    • 4 parallel review dimensions: Quality (SOLID, DRY), Security (OWASP surface scan), Patterns (vs codebase-analysis.md), Tests (coverage vs spec.md)
    • Enriched with Product Forge context — not a generic linter
    • Findings with CRITICAL/HIGH/MEDIUM/LOW severity and suggested code fixes
    • Outputs: code-review.md

  • speckit.product-forge.release-readiness (Phase 9) — Pre-ship checklist:

    • Feature flags & rollout: flag detection, rollout strategy, rollback plan
    • Documentation: user docs, API docs status, changelog, migration guide
    • Monitoring: metrics, alerts, dashboard panels, runbook
    • Analytics: tracking plan status, event instrumentation
    • Dependencies: environment readiness, infrastructure, security status
    • Consolidates api-docs, security-check, and tracking-plan status
    • Outputs: release-readiness.md with READY/CONDITIONAL/NOT READY verdict

  • speckit.product-forge.change-request — Formal scope change management:

    • Captures change description, rationale, priority
    • Impact analysis: which artifacts affected, effort delta, risk assessment
    • Decision gate: Accept/Defer/Reject/Modify
    • Propagates approved changes with <!-- CR-NNN --> markers across all artifacts
    • Runs sync-verify after application
    • Deferred changes logged in backlog.md
    • Outputs: change-log.md (append-only)

Changed — Lifecycle expansion and quality improvements

  • forge.md (major rewrite) — Now orchestrates 13 phases + 2 cross-cutting commands (was 9 phases):

    • Phase Map expanded with Phase 5C (Pre-Impl Review), Phase 6B (Code Review), Phase 9 (Release Readiness)
    • Automatic quick sync-verify between every phase transition
    • Gate audit trail: every gate decision recorded in .forge-status.yml gates: array
    • Schema migration: auto-detects v1 .forge-status.yml and migrates to v2
    • Cross-cutting commands (sync-verify, change-request) surfaced in operating rules

  • implement.md (enhanced) — Progressive verification during implementation:

    • Mini-verify checkpoint every N tasks (configurable via progressive_verify_interval)
    • Checks: task-code correspondence, spec AC alignment, unplanned changes, plan alignment
    • Results logged in implementation-log.md
    • CRITICAL drift pauses implementation with user options
    • Handoff now suggests code-review as next step

  • status.md (enhanced) — Displays new phases, gate audit trail, sync history, change requests

  • .forge-status.yml schema v2:

    • Added schema_version: 2 for migration detection
    • Split plan_tasks into separate plan and tasks fields
    • Added phase fields: pre_impl_review, code_review, release_readiness, retrospective
    • Added gates: array for audit trail
    • Added sync_runs: section for sync-verify history
    • Added change_requests: array for CR tracking

  • extension.yml — Version 1.3.0, 5 new command entries, 4 new tags

  • config-template.yml — 3 new config keys:

    • progressive_verify_interval (default: 3) — tasks between progressive verify checkpoints
    • auto_sync_between_phases (default: true) — automatic quick sync at phase transitions
    • release_readiness (default: "optional") — required/optional/skip

  • docs/file-structure.md — Updated directory layout, schema v2 documentation, new naming conventions (CR-NNN, DRIFT-NNN, D-NNN, A-NNN, R-NNN)

  • README.md — Updated lifecycle diagram, 20-command table, file structure, installation version

1.2.1 — 2026-03-30

Changed — Breaking: implement split into 3 independent commands

speckit.product-forge.implement previously covered Phase 5 (plan), Phase 5B (tasks), and Phase 6 (implementation) as a single monolithic command. It is now split into three standalone, independently runnable commands:

  • speckit.product-forge.plan (new, Phase 5) — generates plan.md from spec.md, cross-validates against product-spec, exits after approval. Extension point before tasks.
  • speckit.product-forge.tasks (new, Phase 5B) — generates tasks.md from plan.md, cross-validates all US-NNN and FR-NNN coverage, exits after approval. Extension point before implementation.
  • speckit.product-forge.implement (narrowed, Phase 6) — executes implementation from tasks.md only, exits when all tasks are [x]. Extension point before verification.

Why: Community members can now insert custom steps between any of the three phases — architecture review, cost estimation, sprint planning, PR approval gates, external review workflows — without forking or patching the core commands.

Forge orchestrator updated: forge.md now delegates to plan → tasks → implement as three separate calls, with explicit extension point prompts between each.

.forge-status.yml schema updated: plan_tasks field replaced by separate plan and tasks fields.

Migration: If you call speckit.product-forge.implement directly and expect it to also run plan/tasks — update your workflow to call plan → tasks → implement in sequence.

1.2.0 — 2026-03-30

Added

  • speckit.product-forge.problem-discovery (Phase 0) — validate the problem before any research begins:

    • JTBD analysis (functional / emotional / social job layers)
    • Competing Forces model (Push + Pull vs Inertia + Anxiety)
    • Problem Statement Canvas saved to problem-discovery/problem-statement.md
    • User interview script with scoring rubric saved to problem-discovery/interview-script.md
    • Go / Investigate further / No-go decision with confidence score
    • Hypotheses H1–HN passed forward to Phase 1 research agents

  • speckit.product-forge.api-docs — generate production-ready API documentation from plan.md contracts:

    • Auto-detects API framework (NestJS, Express, FastAPI, etc.) and existing OpenAPI setup
    • Generates OpenAPI 3.1 openapi.yml with full request/response schemas and examples
    • Generates postman-collection.json with auto-token-save login request
    • Consistency check: plan.md contracts vs actual implementation (reports drift)
    • Outputs: api-docs/openapi.yml, api-docs/postman-collection.json, api-docs/consistency-report.md

  • speckit.product-forge.security-check — feature-scoped OWASP security audit:

    • Builds a threat model from plan.md — only checks surfaces present in this feature
    • Covers: A01 Broken Access Control, A02 Crypto Failures, A03 Injection, A04 Insecure Design, A05 Misconfiguration, A07 Auth Failures, A08 Integrity Failures
    • Scans for hardcoded secrets, missing ownership checks, mass assignment, missing rate limiting
    • Outputs prioritized findings (Critical / High / Medium / Low) with code evidence and fix patterns
    • Ship-readiness decision: ✅ Ready / ⚠️ Fix critical first / 🔴 Not ready

  • speckit.product-forge.tracking-plan — analytics tracking plan from user journeys:

    • Auto-detects analytics SDK (Mixpanel, Amplitude, PostHog, Firebase, Segment)
    • Generates event taxonomy with property schemas, required/optional flags, and examples
    • Defines conversion funnels and abandonment funnels mapped to product-spec success metrics
    • Coverage matrix: each user story → key event → success metric
    • Generates ready-to-paste typed SDK snippets for the detected framework
    • Outputs: tracking/tracking-plan.md, tracking/snippets.md

  • speckit.product-forge.retrospective — post-launch retrospective (run ≥14 days after ship):

    • Loads predicted KPIs from research/metrics-roi.md as the baseline
    • Queries NewRelic (via MCP) for real performance data since launch date
    • Compares predicted vs actual: adoption, completion rate, latency, error rate, business metrics
    • Research accuracy audit: were Phase 1 predictions correct?
    • Lessons learned, open issues table, and next-step recommendations
    • Closes the full lifecycle loop: Idea → Ship → Measure → Learn

Changed

  • extension.yml: description updated to reflect full 15-command lifecycle
  • extension.yml: added tags analytics, security, api-docs, jtbd
  • README.md: commands table expanded to 15 commands
  • README.md: lifecycle diagram now includes Phase 0 (Problem Discovery) and post-implementation block (api-docs, security-check, tracking-plan, retrospective)
  • README.md: file structure updated with problem-discovery/, api-docs/, tracking/, security-check.md, retrospective.md
  • README.md: Why section updated to reflect the full 9-step value proposition

1.1.3 — 2026-03-28

Changed

  • README.md Installation section rewritten with proper specify extension add/update commands:
    • Install latest: specify extension add product-forge --from .../archive/refs/heads/main.zip
    • Install pinned version: specify extension add product-forge --from .../archive/refs/tags/v1.1.3.zip
    • Update: specify extension update product-forge --from ...
    • Added post-install config setup instructions with specify extension path product-forge

1.1.2 — 2026-03-28

Added

  • playwright-cli as execution engine for Phase 8B (speckit.product-forge.test-run): agent now drives the browser interactively using playwright-cli open, playwright-cli click/fill/snapshot/screenshot, playwright-cli tracing-start/stop, and playwright-cli -s=pf-auth state-save/load for auth session reuse
  • Dual execution model documented in commands/test-plan.md: test-cases.md (primary, agent-driven via playwright-cli) vs .spec.ts files (CI/CD companion, run with npx playwright test)
  • test-cases.md format specification: each test case now uses a playwright-cli action table (# | Action | playwright-cli equivalent) so Phase 8B can translate steps mechanically without ambiguity
  • playwright-cli dependency section in README.md Requirements with install instructions and link to github.com/microsoft/playwright-cli
  • "How to Run Tests" section in generated test-plan.md now documents both execution paths: agent-driven (/speckit.product-forge.test-run) and CI/CD (npx playwright test)

1.1.1 — 2026-03-28

Fixed

  • Command names updated to required speckit.{extension}.{command} pattern (was product-forge.*)
  • All 10 commands renamed: speckit.product-forge.forge, speckit.product-forge.research, etc.
  • All internal cross-references in command files updated accordingly

1.1.0 — 2026-03-28

Added

  • speckit.product-forge.test-plan — Phase 8A: Auto-detects test framework, ports, and env vars; generates smoke/E2E/API/regression test cases with TC-*-NNN IDs; writes runnable Playwright .spec.ts files with story traceability comments; initializes bugs/README.md dashboard
  • speckit.product-forge.test-run — Phase 8B: Executes tests in priority order (smoke → E2E → API → regression); creates bugs/BUG-NNN.md per failed test with evidence, gap analysis, and fix log; auto-fix loop for P0/P1 bugs with single-test retest and smoke regression check; generates test-report.md with full coverage matrix and traceability chain
  • Adaptive research depth in speckit.product-forge.research: input richness scoring (0–8 across 4 dimensions) selects FULL_INTERVIEW / PARTIAL_INTERVIEW / CONFIRM mode; avoids redundant questions when context is already rich

Changed

  • speckit.product-forge.forge orchestrator updated to 9-phase pipeline (8A and 8B added as optional after Phase 7)
  • forge.md Phase Map table updated; Phase 8A/8B offer shown after every successful Phase 7 completion
  • extension.yml version bumped to 1.1.0; tags updated to include testing
  • docs/phases.md updated with full Phase 8A and 8B documentation
  • docs/file-structure.md updated with testing/, bugs/, and test-report.md in directory layout; .forge-status.yml schema updated with test_plan, test_run, and testing: block; BUG-NNN.md and test-report.md schemas added; naming conventions updated with TC-* and BUG-NNN IDs
  • README.md updated with 9-phase lifecycle diagram, 10-command table, and expanded file structure

Bug Fixes

  • forge.md Phase 5 and 6 previously referenced SpecKit directly; corrected to delegate via speckit.product-forge.implement as intended

1.0.0 — 2026-03-28

Added

  • speckit.product-forge.forge — Full lifecycle orchestrator with 7-phase pipeline and human-in-the-loop gates
  • speckit.product-forge.research — Phase 1: Parallel research across competitors, UX/UI patterns, codebase analysis (mandatory), tech stack and metrics/ROI (optional)
  • speckit.product-forge.product-spec — Phase 2: Interactive product spec creation with configurable detail levels (concise/standard/exhaustive) and auto-decomposition for large features
  • speckit.product-forge.revalidate — Phase 3: Iterative review loop with structured change tracking in review.md; exits only on explicit user approval
  • speckit.product-forge.bridge — Phase 4: Converts approved product-spec into SpecKit spec.md; supports Classic and V-Model SpecKit modes
  • speckit.product-forge.implement — Phase 5-6: Wraps SpecKit plan + tasks + implement with product-spec cross-validation at each sub-phase
  • speckit.product-forge.verify-full — Phase 7: Full traceability verification across 6 layers (code ↔ tasks ↔ plan ↔ spec ↔ product-spec ↔ research)
  • speckit.product-forge.status — Status reporter showing all phases, artifact inventory, and next recommended action

Feature File Structure

Introduced the features/<name>/ directory convention with:

  • research/ — all research artifacts + README index
  • product-spec/ — all product spec artifacts + README index
  • .forge-status.yml — phase tracker
  • review.md — revalidation changelog
  • verify-report.md — verification report

Decomposition & Cross-linking

  • Auto-detects large features and suggests file decomposition for user journeys and wireframes
  • All documents cross-linked via feature root README.md and product-spec/README.md
  • Token budget awareness with max_tokens_per_doc config setting

Configuration

  • config-template.yml with full project configuration options
  • .product-forge/config.yml project-level config support
  • Per-feature config override support