Changelog

All notable changes to Context Forge will be documented in this file. This file should contain concise entries from user point of view and should answer the following questions:

• What can I do now that I couldn't do before?
• What specific bugs, if any, are fixed?
• Were any features removed?

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.17.0] - 20260922

Fixed

• cf validate frontmatter now validates the worktree you are standing in, not the project root. From a registered worktree every explicit path fell outside the document root and was silently dropped, so the command reported a clean pass having examined nothing — filesChecked: 0, exit 0. Anything gating on it passed everything (#88).
• Skipped paths are reported instead of vanishing. cf validate frontmatter told you how many files it checked but never which of your paths it ignored or why. A path that is out of scope, not markdown, missing, or has no frontmatter now says so, in both --json and human output. "I checked nothing because everything you gave me was out of scope" is now distinguishable from "I checked nothing" (#92, #96).
• Human output no longer prints No inconsistencies found (0 files checked) when nothing was examined. It lists the skipped paths with reasons and says No files were checked.
• cf check findings name the worktree they came from in a multi-worktree project. Each finding carries a structured worktree field in --json and is prefixed with [worktree-name] in human output, so you can tell whose checkout a finding belongs to instead of hunting for it locally. Single-checkout projects — including a migrated project with one default worktree — see no change at all (#87).
• cf list arch lists every initiative from a worktree. It was filtering initiative indices through the worktree's slice index range, so a worktree owning 920-929 hid every initiative outside that band — usually all of them, reporting No initiatives found in initiative plan. against a fully populated plan. An initiative plan is a project-level artifact and is no longer range-filtered; cf list arch and cf list arch --all now agree (#97).
• The empty-initiative messages name the plan file or the directory that was scanned, so "none" is a statement you can go verify.

Added

• cf validate frontmatter --json gains three fields, all additive — the existing filesChecked, totalFindings, errors, warnings, and findings keep their exact name, type, and meaning, so external consumers parsing this output keep working unchanged:
  • documentRoot — the document root actually scanned, so a caller can tell which checkout it was.
  • filesSkipped — how many supplied paths were not validated.
  • pathResults — per-path outcome (checked, skipped-out-of-scope, skipped-not-markdown, skipped-not-found, skipped-no-frontmatter) for explicit-path calls. A full walk emits no path list.
• rules.exclude config key — comma-separated filename globs for scoped rule files to skip when installing rules (e.g. dart.md,swift*.md). Matching is basename-only and skip-only; an already-installed file is never deleted. cf stores and validates the value; the guide's setup-ide script is what acts on it (ai-project-guide#23). Validation rejects surrounding whitespace and empty entries from doubled or trailing commas, because the consuming script matches patterns literally and a malformed one would silently never match.
• cf recognizes both managed-marker forms, the legacy [//]: # (context-forge:managed) and the newer <!-- BEGIN:context-forge -->, anywhere in a file rather than only in its first 20 lines. This must ship before ai-project-guide#22, which makes the guide preserve your existing instructions file and append its managed block below — that pushes the marker past any fixed window, and without this change cf would stop recognizing managed installs and start prompting and writing .bak files on files it already manages (#98).

[0.16.0] - 20260921

Changed

• tarball is now the default guide install strategy for cf init and cf guides install (previously submodule). The guide lands as plain files with no git wiring. Pass --strategy submodule to get the old behavior. Existing installs are unaffected: cf reads the installed strategy from disk, and a project whose config already names a strategy keeps it.
• Tarball installs and updates are committed for you, the same way submodule installs already were. The commit touches only the guide directory, leaves anything else you have staged alone, and never pushes. Skipped, and reported, when the project is not a git repository or gitignores the guide.
• A strategy passed with --strategy is saved to guide.git_strategy in the shared project config when it differs from what config resolves to, so a later bare install, or a teammate's, uses the same one. Previously the choice lived only in the flag and the next install silently went back to the default.
• README documents switching an existing submodule install to tarball: cf guides uninstall, then cf guides install --strategy tarball.

Fixed

• cf guides uninstall no longer leaves empty directories behind under .git/modules/. Module data belonging to other submodules is left alone.

[0.15.0] - 20260919

Changed

• Node.js 20.18.1 or newer is required (previously 18). Node 18 reached end of life in April 2025 and Node 20 in April 2026; the tarball download now uses undici 7, which needs 20.18.1. Nothing else changes on a supported Node.
• README documents what the tarball strategy actually needs: one person reaches github.com and api.github.com once, the guide lands as plain files, and cf guides update shows up as an ordinary reviewable diff.

Fixed

• Tarball guide installs work behind a corporate proxy. cf guides install and cf guides update with the tarball strategy now honor HTTPS_PROXY, HTTP_PROXY, and NO_PROXY for the archive download. Previously only the tag lookup did, so the install failed halfway with a bare connection error. Failures now name the URL, which call failed, and which proxy variable applied; an exhausted GitHub API rate limit is reported as such instead of a generic status (#86).
• cf guides update with the tarball strategy honors a configured guide.source. It previously always updated from the public default, silently replacing a fork's content (#85).
• Tarball installs drop the guide repository's own git wiring (.gitmodules, .gitignore, and a self-referential project-documents/ entry present in guide tags before v0.17.8) at extract time, so the guide lands as plain files in every case.
• The review gate no longer picks a same-prefix sibling (for example a *.response.md file) over the actual review artifact, which produced a spurious UNKNOWN verdict and a misleading "review failed" reason. The failure rationale now names the file it read (#90).
• cf set plan|arch|slice|tasks <index> matches zero-padded filenames (003-slices.foo.md for index 3), so cf next and cf check --slice no longer report an existing slice plan as missing (#91).
• The git.integration_branch config description no longer implies the integration branch prefixes slice branch names; only the fork and merge target change.

[0.14.0] - 20260910

Added

• Fresh clones no longer start with an empty guide directory. Cloning a project without --recurse-submodules used to leave project-documents/ai-project-guide empty, and the failure surfaced later as a confusing missing-file error. cf build, cf prompt, cf setup-ide, and the MCP context_build, prompt_list, and prompt_get tools now check out the guide automatically the first time they read it, reporting what they did on stderr (CLI) or in a notices array (MCP). Closes #80.
• cf init --strategy <method> selects the install strategy at project creation, with the same help text and trade-offs as cf guides install --strategy.
• cf guides info shows the submodule checkout state (in sync, out of sync, not initialized). It remains read-only and never modifies the checkout, so you can inspect before acting.
• The guide directory now says it is managed content. cf guides info, the MCP guide_status tool, and the README all state that project-documents/ai-project-guide is overwritten on cf guides update and that customizations belong under project-documents/user/. Closes #82.
• README gained a "Choosing a guide install strategy" section covering all three strategies and why submodule remains the default.

Changed

• The manual install strategy is now called tarball. manual still works as a deprecated alias and prints a notice, and existing config files with guide.git_strategy = "manual" keep validating. Closes #81.
• Output change: cf guides info --json, the MCP guide_install and guide_status results, and InstallResult.method now report "tarball" where they previously reported "manual". Existing tarball installs are detected correctly and need no migration. If you parse this field, update the comparison.
• A checkout sitting at a commit other than the one your project pins is reported but deliberately left alone, since that is usually intentional. The message names cf guides update as the remedy.

Fixed

• cf guides update works in a project that has no commits yet. Straight after cf init, the branch guard failed with git rev-parse --abbrev-ref HEAD failed ... unknown revision because the branch exists but has nothing on it. The guard now reads the branch name and, when it is not the trunk, asks for confirmation as it does for a branch with no shared history.
• A malformed config file no longer silently falls back to the default install strategy and source. Config read errors now fail the command with the actual parse error.
• The automatic checkout is bounded by a timeout, so an unresponsive proxy fails with offline guidance instead of blocking a read command for the operating system's connection timeout. User-initiated cf guides install and cf guides update remain unbounded.

[0.13.2] - 20260909

Changed

• Bare cf install-commands installs machine-level again (~/.claude/commands/cf/, ~/.codex/skills/), and the scope flag is now --local for a project-local install. This reverts the 0.13.0 change that made project-local the default: in practice the commands are wanted machine-wide essentially always, and defaulting to project-local cluttered every project with an identical copy of the same nine commands. --global is gone — machine-level is the default, so it has nothing left to select. --target <dir> still overrides both scopes, and uninstall-commands follows the same resolution.
• If you relied on 0.13.0/0.13.1's project-local default, add --local. If you passed --global explicitly, drop the flag. Commands already installed project-local by an earlier version are not migrated or removed — clean them up with cf uninstall-commands --local.

Fixed

• cf setup-ide now points at the offline install path when guides are missing, instead of only saying "Guides are not installed. Run 'cf guides install' first." — a user behind a corporate DNS/proxy was told to run a command that would fail again for the same reason, with no hint why. The offline guidance (cf config set guide.source <path>) is now one shared constant used by both cf guides install and setup-ide, so the two cannot drift apart (#78)

[0.13.1] - 20260909

Fixed

• cf guides install and cf guides update now explain network and DNS failures and suggest a VPN/proxy check or a local guide.source instead of printing a bare git error (contributed, #77)
• Guide install no longer hangs forever when git blocks on an interactive credential prompt; git runs non-interactively and fails with a message instead (#77)
• Embedded credentials in a guide.source URL are redacted from error output (#77)
• The tarball strategy no longer reports "Could not determine latest version" for network failures; the real cause is shown (#77)

[0.13.0] - 20260810

Added

• The nine /cf:* commands are now available in OpenAI Codex as agent skills. cf install-commands --ide codex installs cf-build, cf-check, cf-get, cf-next, cf-onboard, cf-project, cf-prompt, cf-set, and cf-status as SKILL.md skill directories — invoked in Codex as $cf-build, $cf-status, etc. Project-local installs go to .agents/skills/ (shareable via git, alongside the guide's workflow skills); --global installs to ~/.codex/skills/. The thin passthrough skills (status, get, check, next, project, set) instruct the model to run the CLI and print its output verbatim — Codex skills have no output-injection directive like Claude commands' !`cf …`, so these are model-mediated by platform limitation (#74).
• cf setup-ide claude and cf setup-ide codex now install the commands/skills too (machine-level), so one command fully configures an IDE. cf init --ide codex installs Codex skills instead of Claude commands; cf init --no-ide no longer installs any commands.
• README: Codex MCP-server registration snippet for ~/.codex/config.toml.

Changed

• Bare cf install-commands now installs project-local (.claude/commands/cf/) instead of machine-level. The previous destination (~/.claude/commands/cf/) is available with --global. An explicit directory via --target <dir> still overrides both. uninstall-commands follows the same resolution (#74).

[0.12.0] - 20260809

Changed

• BREAKING: derived-status wire values are now underscored — in-progress → in_progress and not-started → not_started in all machine-readable output: cf list slices --json, cf list arch --json, cf status --json, cf next --json, and the MCP introspection_* / project_get tools. There is no deprecated alias or dual-emission — the old hyphenated spellings are no longer emitted anywhere. Consumers comparing against 'in-progress' / 'not-started' must update; complete, deferred, deprecated are unchanged. One vocabulary now exists everywhere: on disk, in memory, and on the wire (#72).
• cf check now rejects non-canonical status spellings in frontmatter — and migrates them. validateFrontmatter is strict: only the five canonical values (not_started, in_progress, complete, deferred, deprecated) pass. Historical aliases (in-progress, done, completed, ready, pending, planned, …) and close typos (e.g. in-progres) are flagged with an auto-fix that cf check --fix applies, rewriting the document to the canonical spelling; genuinely unknown values are flagged with no auto-fix. Reading remains lenient everywhere (cf list, cf status still understand every historical spelling); invalid-value messages now report the status exactly as typed.
• Every frontmatter write via cf check --fix (and the new cf validate frontmatter --fix) now stamps dateUpdated with the write date, in the same file write as the field it's fixing. Previously a fixed document kept whatever dateUpdated it had before the fix, silently going stale. The one exception: when a fix's own target field is dateUpdated itself (the missing-dateUpdated-backfilled-from-dateCreated case), the stamp is skipped so the backfill isn't immediately overwritten with today's date (#71).
• BREAKING (internal API): updateFrontmatterField, exported from @context-forge/core/node, gains a required fourth parameter (dateUpdated: string). Any external consumer calling it directly must pass a date stamp; there is no default. Acceptable in this unpublished 0.12.0 window (#71).

Added

• cf validate frontmatter [paths...] — a new, narrow, scriptable command that validates YAML frontmatter against the per-docType schema, suitable as a pre-commit gate. With no paths, it walks all methodology documents (the same set cf check scans); with paths, it validates only the in-root .md files among them and silently skips everything else (out-of-root paths, non-.md files, nonexistent paths — no errors). Exit codes: 0 clean (or --fix resolved everything), 1 findings remain, 2 invocation error (unresolvable project). --json emits { filesChecked, totalFindings, errors, warnings, findings[] }, plus fixed/fixLog/fixErrors in fix mode. Unlike cf check --fix, --fix here applies without a confirmation prompt — findings are per-document and deterministic, and the command's primary caller is a script (documented in --help) (#73).
• Three new frontmatter docTypes are now recognized: review-resolution, gate-evidence, and devlog (squadron machine-artifacts). Each requires only docType and dateCreated — no status (these are append-only records with no lifecycle) and, deliberately, no dateUpdated (a single-file validator can't know whether such a document was edited after creation, so requiring the field would force a false backfill) (#73).
• cf setup-ide and cf init --ide now support two new targets: cursor and agents (aliases openai, codex). The guide-side compiler already supported all four; CF's own target validation had simply never been updated to match. cf setup-ide codex writes AGENTS.md plus .agents/skills/<name>/SKILL.md for each skill; cf setup-ide cursor writes always-on rules to AGENTS.md and scoped rules to .cursor/rules/*.mdc (existing paths: → globs: conversion, unchanged).
• Re-running cf setup-ide cursor against a project set up by an older version migrates it automatically: .mdc files superseded by the always-on/scoped split are removed and the removal is printed, so an upgraded project doesn't end up with the same always-on rule loaded from two places.

Fixed

• cf check's consistency rules now read frontmatter status leniently through the shared alias map. Previously seven rule sites compared the raw string, so a document whose frontmatter said in_progress or not_started — the canonical spellings — was silently ignored by rules like "frontmatter says complete but tasks are incomplete", while only the hyphenated spellings happened to match. All historical spellings now work everywhere status is read.
• cf check --fix output now attributes each fix to the correct file. When several findings shared a rule (e.g. multiple frontmatter status fixes in one run), every "Fixed:" line displayed the first file's path and before-value.
• cf build --embed now works for projects whose conventions live in AGENTS.md or .github/copilot-instructions.md, not only CLAUDE.md. Previously it silently embedded nothing for any non-Claude project — a defect reachable today, since Squadron automatically appends --embed for every non-Claude-Code model. A visible warning is now emitted when no conventions file is found at all, instead of silent omission.
• Nested skill directories (.claude/skills/<name>/SKILL.md and similar) now actually reach registered git worktrees when propagating IDE setup files. Previously the propagation logic only copied top-level files in each directory, so any skill — which is always a subdirectory — silently never made it to a worktree.
• Propagating IDE files to worktrees no longer silently does nothing for an unrecognized target; it now fails loudly instead.
• Copilot's AGENTS.md no longer duplicates the scoped-rules index that .github/instructions/*.instructions.md already covers via applyTo — the index only appears for a target (like agents) with no scoped-rule surface of its own.

[0.10.7] - 20260802

Fixed

• cf check (and the workflow_check MCP tool) no longer silently accept draft as a status value. Frontmatter validation previously special-cased draft as a hidden alias for not_started, so a slice/task/design document with an invented draft status passed validation with zero findings. It's now flagged the same as any other unrecognized status (Invalid value 'draft' for field 'status'...).

[0.10.6] - 20260801

Fixed

• On macOS, cf now stores its data at ~/.config/context-forge — and, critically, the published package now agrees with local builds about where that is. Previously the published core resolved storage to a legacy location (~/Library/Preferences via env-paths, with older builds using Electron's ~/Library/Application Support/context-forge/context-forge), so installing from the registry silently pointed cf at a stale or empty store: projects seemed to vanish (cf status reported "no registered project found"), while the real data sat untouched in ~/.config/context-forge. Any existing ~/Library/Preferences/context-forge directory is migrated to the new location automatically (one-time atomic rename, only when the new location doesn't already exist); CONTEXT_FORGE_DATA_DIR still overrides everything. Linux and Windows are unaffected. (#53)
• cf next's index-band warning no longer misfires in worktree-configured projects. Previously it compared the active slice's hundred-block against the architecture's, assuming one architecture owns exactly one hundred-block — so every slice at 200/300/…/700 tripped a false warning in the common case of a default worktree declaring indexRange: [100, 799]. It now checks against the active worktree's declared range instead (falling back to the union of all configured worktrees, then to the original hundred-block check for projects with no worktrees), bringing it into agreement with cf set slice's existing worktree-scoped warning. (#48)
• A slice-plan line marked [~] (the descoped/deprecated convention) is no longer silently dropped by the parser. Previously such a line matched neither checkbox format, so the entry vanished entirely — not shown, not counted, not flagged. It now parses as a deprecated entry: cf list slices renders it ⊘ deprecated, cf next skips past it, and cf check no longer false-flags a plan as inconsistent just because it contains one.

[0.10.3] - 20260718

Fixed

• parseFrontmatter() no longer lets a nested field (e.g. a review's findings[].verdict) silently overwrite a same-named top-level field (e.g. verdict). Previously the parser tracked no indentation, so any colon-bearing line anywhere in the frontmatter block — however deeply nested inside an object, a list of objects, or a folded/literal block scalar — was read as a new top-level key. This could mask a real review verdict with the last nested value seen, producing a false cf check review-gate failure.
• cf next now flags a stale phase field when a review gate is blocking progress, the same way it already does for every other lifecycle stage. Previously, if phase had drifted while a slice/tasks/code review was pending or failing, cf next named the review that was owed but gave no hint that phase itself also needed to move — the guidance loop went silent at exactly the moment a confused user most needed it. No change to whether a review gate blocks; this only adds the missing suggestion.

[0.10.2] - 20260714

Fixed

• cf check now flags an architecture document whose frontmatter status isn't a recognized value — previously cf list arch would show it as "⚠ unreadable" but cf check stayed silent, because its frontmatter-schema validation used a different, narrower alias list than the one driving cf list arch. Both now agree on what counts as a valid status.
• cf check's "Architecture status is..." findings now name which architecture document they're about (e.g. Architecture (100) status is "complete" but plan has unchecked entries) instead of a generic, unattributed message — needed in projects with multiple architecture initiatives, where the old message couldn't be traced to a specific one.

[0.10.1] - 20260714

Fixed

• deferred is now a fully recognized slice status. It was already accepted by cf check's frontmatter validation, but cf status, cf next, and cf list slices didn't know what to do with it and surfaced a spurious "not a recognized status" warning. A slice marked deferred is now treated the same way a deprecated one already is — it's skipped when picking the next slice to work on, instead of being reported as an error or offered as "next".

[0.10.0] - 20260714

Added

• cf guides update (and the guide_update MCP tool) now guard against committing a guide update on the wrong branch. If a git.integration_branch is configured and you're on main, the update is blocked outright with guidance on how to proceed. If you're on any branch other than the configured trunk (or main, when no integration branch is set), you're asked to confirm before it commits — pass -y/--yes to cf guides update to skip the prompt, or confirm: true to the MCP tool. Being on the trunk branch itself behaves exactly as before, with no new prompt.
• cf config unset <key> — removes a configuration value. Defaults to the current project's config (same as cf config set); pass --global to remove a machine-wide value instead. Removing a key that isn't set is a harmless no-op, not an error.
• Project-scoped config keys are now classified as shared (team-wide policy, e.g. guide.source, workflow.review_enabled) or personal (per-developer, currently only git.integration_branch). Personal keys are written to a new .context-forge.local.toml file instead of the committed .context-forge.toml — cf config set/get/unset --project route to the right file automatically, no flag changes needed. cf init now gitignores .context-forge.local.toml by default.
• cf check now warns if a personal-scope key (e.g. git.integration_branch, set before this change or by an older version) is present in the committed .context-forge.toml. cf config migrate-personal [--project <id>] moves any such keys into the personal file — if a different value is already set in your personal file, it's left untouched and reported as skipped rather than overwritten.

Fixed

• cf config set <key> <value> (with no --project/--global flag) now writes to the current project's config file, as it always should have — previously it silently wrote to a machine-wide file shared by every project on your machine, so a value set while working in one project could quietly leak into every other project. Writing to the machine-wide file is now an explicit opt-in via a new --global flag. cf config get/set --project (with no value) also now consistently resolves "the current project" from your working directory.

[0.9.2] - 20260712

Fixed

• cf status/cf next no longer abort when a slice-design has an unrecognized frontmatter status value — that slice is now reported with a distinct, clearly-labeled warning instead of erroring out the whole command. cf list slices already handled this correctly; cf status/cf next now match.

[0.9.1] - 20260711

Changed

• The git.branch_root config key is renamed to git.integration_branch, to match its intended meaning as a long-lived integration branch that work branches fork from and merge into (rather than a plain name prefix on branches that still fork from/merge to main). This is a clean rename with no deprecated alias — git.branch_root no longer resolves.
• A slice design's docs-only declaration is renamed from codeReview: none to review: none, and now exempts the slice from the slice, tasks, and code review gates uniformly (previously it only exempted the code gate, so a minimal-documentation slice with no task file yet could still be blocked at the slice review boundary with no way to declare itself exempt). It does not affect the arch (architecture) review gate, which applies to a different document. cf check --set-review-none <index> now writes review: none.

[0.9.0] - 20260711

Changed

• Internal: NormalizedStatus values (complete/in-progress/not-started/deprecated) are now referenced via the STATUS constant everywhere in packages/core, replacing ~65 scattered bare-string literals. No behavior change — purely a maintainability/type-safety refactor (a typo like STATUS.Compelte is now a compile error instead of a silent runtime mismatch).

Added

• Foundation for review-aware workflow gating (initiative 240): workflow.review_enabled, workflow.review_threshold, and workflow.review_unknown_as config keys, plus per-gate override keys (workflow.review_gates.{code,arch,slice,tasks}.threshold). All keys default to off/empty and have no effect yet — no command reads them. Introduced to unblock upcoming gate-logic slices.
• The review gate is now active behind workflow.review_enabled (default off — no behavior change unless explicitly turned on). When enabled, cf next/cf status (and their MCP equivalents workflow_next/workflow_status) automatically look for the review owed at the slice's current lifecycle position — arch before a slice plan, slice before task breakdown, tasks before implementation, code before advancing — and report pending-review or review-failed instead of the usual recommendation when that review is missing or its verdict doesn't clear the configured threshold. Per-gate threshold overrides are honored; the review type is always derived from position, never configured (an earlier per-gate review_type config key was removed before release, since position-derivation made it redundant).
• cf check/workflow_check (and their --fix/fix variants) now surface the same review gate as a consistency finding, at all four lifecycle boundaries (arch/slice/tasks/code): an artifact whose owed review is absent reports a warning, and one whose review is present but failing (or UNKNOWN under the default policy) reports an error. Both are advisory only — never auto-fixable. Silent behind workflow.review_enabled (default off, byte-identical to prior output).
• A slice design can now declare codeReview: none in its frontmatter to mark itself docs-only (e.g. documentation, analysis) — cf next/workflow_next will not block it on a missing code review at the pre-advance gate. Absent (the default) is unchanged: code review is still required before advancing.
• cf check/workflow_check gained two new consistency checks: a task file that has started (any task checked) while its slice plan entry is still unchecked, and a task file that has started while its slice-design frontmatter still says not_started — both previously produced no finding at all. The frontmatter case is auto-fixable with --fix.
• workflow.review_gate_effective_date config key (format YYYYMMDD, default empty = no cutoff): grandfathers any slice or architecture designed before this date out of every review gate boundary. Turning on workflow.review_enabled on a project with existing history no longer retroactively demands reviews for work completed before the gate existed.
• cf check --set-review-none <index> declares a single slice docs-only by writing codeReview: none to its slice-design frontmatter — a quicker path than hand-editing the file for slices that can't produce a code review.
• cf list slices [archIndex] and cf list tasks [archIndex] accept an optional index argument to inspect a different initiative's slice plan or task files directly (e.g. cf list slices 140) without first switching the active architecture pointer via cf set arch and switching it back afterward. Neither command mutates project state when given an explicit index. [archIndex] and --all cannot be combined on cf list tasks.

Fixed

• cf check/workflow_check no longer reports a "requires a code review" finding for a checked slice-plan entry that has no slice-design or task file at all — there is no code to review, so the finding was a false positive. Slices with real design/task artifacts and no review are still flagged correctly.
• cf check/workflow_check now correctly resolve zero-padded artifact filenames (e.g. 050-arch.foo.md) when matching by numeric index. Previously the exact-prefix filename match failed for any zero-padded index, which silently skipped the workflow.review_gate_effective_date cutoff check for that artifact and produced a false "no review artifact found" finding even when the artifact predated the cutoff.
• cf check/workflow_check no longer reports review-gate (or any other consistency) findings against slice indices that don't correspond to any real slice in the active plan. A legacy slice plan using the older, unindexed list format (predating the (NNN) index convention) could produce synthetic sequential indices that numerically collided with real project indices once merged across plans, generating phantom findings.
• cf config get/set --project <name> now resolves the project name to its actual projectPath before reading/writing config, instead of treating the raw name as a literal directory. A bare registered project name previously caused .context-forge.toml to be silently written to the wrong (nonexistent) path.
• cf next, cf list slices, cf list arch, and workflow_status no longer report a slice as "not started" when its tasks are actually complete (or in progress) but its slice-plan checkbox hasn't been ticked yet — a slice with 100% of its tasks done, awaiting checkbox sign-off, now reads as complete (shown as "tasks done" until checked) everywhere instead of contradicting cf status. cf next also now says "Continue slice N" rather than "Advance to slice N" when the next slice in the plan is already partway done.
• cf next no longer suggests cf set arch <index> when the architecture pointer is already set but the file doesn't exist yet — a no-op that stranded users mid-transition between initiatives. It now suggests advancing to Phase 2 (Architecture) instead; the field-unset fallback is unchanged.
• The pending architecture (arch) review gate in cf next no longer silently stops being checked once a slice plan exists. Previously, an unreviewed architecture would only be flagged before the slice plan was created; afterward the requirement vanished for good.
• cf check/workflow_check now reports pending or failing reviews for all four lifecycle boundaries (arch, slice, tasks, code), not just code — each only once its corresponding artifact (architecture file, slice design, task file) exists. Finding text now correctly names the review type owed (e.g. "Run the slice review for slice 100") instead of always saying "code review". A malformed review artifact now degrades to a single error finding for that slice/architecture instead of aborting the whole check.
• cf config set no longer misinterprets an all-digit value (e.g. a YYYYMMDD date) as a number for string-typed config keys — the value is now coerced toward the key's declared type instead of guessed from its shape.

[0.8.1] - 20260514

Fixed

• cf set now normalizes artifact field values to bare stems before storage. Full paths (e.g. project-documents/user/architecture/100-arch.foo.md) and stems with .md suffix were stored as-is, causing resolveArtifactPath to construct an invalid doubled path — making cf next, cf check, and cf build silently fail to detect files on disk.
• cf check now warns when an initiative plan entry is checked but its associated slice plan still has incomplete slices, rather than only comparing the initiative checkbox against the architecture document status.

[0.8.0] - 20260514

Added

• cf build --embed — inlines all referenced artifact files (fileArch, fileSlicePlan, fileSlice, fileTasks, fileHLD, fileSpec, fileConcept) and CLAUDE.md as labeled fenced markdown blocks appended to the context output. Produces a fully self-contained prompt for models without file-read access. Missing files emit a warning rather than failing silently. Composes with all existing flags (--phase, --slice, --json, etc.).

[0.7.1] - 20260512

Fixed

• @context-forge/context-forge (umbrella package) now exposes the cf command after a global install. Previously, installing the umbrella package installed @context-forge/cli as a dependency but did not link its binary — leaving users with no cf command until they manually installed @context-forge/cli. Fixed by adding a bin/cf.js forwarding script to the umbrella package.
• cf list slices, cf list tasks, and cf next now correctly order slices by index regardless of the order entries appear in the slice plan file. Previously, entries added out of order during planning could cause the wrong slice to be flagged as "next".

[0.7.0] - 20260412

Added

• cf setup-ide copilot and cf init --ide copilot — VS Code Copilot users can now use Context Forge. Compiles project rules and skills into the VS Code Copilot file layout: always-on rules → .github/copilot-instructions.md + AGENTS.md; scoped rules → .github/instructions/*.instructions.md with applyTo frontmatter; skills → .github/prompts/*.prompt.md. Existing unmanaged files are backed up before overwriting; managed files (from a previous run) are updated silently.

Fixed

• cf next now recommends cf set phase 'Phase 3: Slice Planning' instead of cf build when a new slice plan file is configured but doesn't exist yet and the project is not already in Phase 3 — previously, running cf build from Phase 6 would have generated an implementation prompt rather than a slice planning prompt

[0.6.42] - 20260406

Fixed

• cf check no longer flags status: draft — now treated as alias for not_started (work hasn't begun)
• cf check auto-fixes missing dateUpdated by defaulting to dateCreated when present
• cf check no longer floods output with "plan entry but no task file" notices for backlog entries — only flagged when a slice design exists (the only state where missing tasks is actually inconsistent)

[0.6.41] - 20260404

Fixed

• Context profile filtering was silently disabled — ContextProfileParser only handled the expanded multi-line YAML format but the actual prompt file uses compact one-liners; all artifact fields (including fileTasks) were included in every phase regardless of profile configuration
• Affects cf build, MCP context_build, and /cf:build slash command

Changed

• ProfileMap type simplified from Record<string, { variables: string[] }> to Record<string, string[]>
• parseProfilesYaml rewritten as format-agnostic state machine — no indent-depth logic

[0.6.40] - 20260404

Added

• cf list arch / cf list initiatives now drives from the initiative plan (001-initiative-plan.*.md) when present, showing all entries with index, name, status, and arch file per entry — mirrors cf list slices behavior
• Entries without an arch file show not_started; entries with an arch file but unchecked show in_progress; checked entries show complete
• cf list arch --json emits structured array with index, name, status, archFile, isActive fields
• resolveInitiativePlanPath(projectPath) exported from @context-forge/core/node — shared utility for locating initiative plan files

Changed

• cf list arch falls back to buildModel()-based output on projects without a formal initiative plan (no behavior change for those projects)

[0.6.39] - 20260404

Added

• cf check Rule 13 (initiative-entry-vs-arch): flags mismatch between initiative plan entry checkbox and corresponding arch doc status — warns and auto-fixes in both directions
• cf check Rule 14 (initiative-plan-status-vs-entries): flags initiative plan frontmatter status vs. all-entries-checked state (mirrors Rule 7 for slice plans)

Fixed

• cf check aggregate rules (stale-worktree-path, frontmatter-schema, initiative plan rules) were silently skipped when no slice plans existed; removed early-return guard that blocked them

[0.6.38] - 20260403

Fixed

• cf setup-ide claude now propagates generated files (CLAUDE.md, .claude/rules/, .claude/agents/, .claude/skills/) to all registered worktrees after updating the project root. Worktrees do not maintain independent IDE config — they receive a copy from root. .claude/settings.local.json and .claude/worktrees/ are intentionally excluded (worktree-specific).

[0.6.37] - 20260402

Added

• Short-form flags for common CLI options: -j (--json), -p (--project), -y (--yes), -f (--fix), -a (--all), -r (--raw)
• New packages/cli/src/options.ts module with 7 composable helper functions (withJsonOption, withProjectOption, withYesOption, withFixOption, withAllOption, withRawOption, withProjectLevelOption)

Changed

• Migrated all 14 CLI command files to use shared option helpers from options.ts (removed ~70 inline option registrations)
• Normalized --project option description to "Project ID or name (overrides default)" across all commands

Fixed

• cf check --fix now reports "No fixable findings — nothing to apply." when no findings are auto-fixable, instead of silently showing check-only output
• Version flag changed from -V to -v (--version)

[0.6.36] - 20260402

Added

• cf next suggests cf set phase when current phase doesn't match the recommended phase
• cf next warns when active slice is outside the architecture's index band (e.g., slice 904 under arch 100)
• cf next recommends creating the architecture document when arch is set but the file is missing, even with an active slice
• warnings field on NextAction type for non-blocking configuration warnings

[0.6.35] - 20260401

Added

• cf update command — check npm for newer versions and prompt to install (slice 906)
  • --yes flag for non-interactive auto-install
  • --json flag for machine-readable version info
  • Detects npm vs pnpm global installs; skips local dev installs

[0.6.34] - 20260331

Added

• cf worktree rm shows git worktree removal hint when the directory still exists on disk

Fixed

• cf guides uninstall from a worktree now only deinits the submodule in that worktree — no longer breaks the main repo's guide installation (fixes #46)
• Guide directory physically removed from worktree after submodule deinit

[0.6.31–0.6.33] - 20260331

Added

• SlicePlanEntry.description — overview text from slice plan entries (after bold name)
• FutureWorkItem.description — description text from future work entries (after title separator)
• DocSummary.description — overview paragraph extracted from ## Overview section of arch docs

[0.6.30] - 20260330

Fixed

• cf guides update now fetches before --remote and uses --init for resilience after worktree removal

[0.6.29] - 20260330

Added

• Frontmatter schema registry (FRONTMATTER_SCHEMAS) — maps 8 docTypes to required fields with value constraints (slice 905)
• validateFrontmatter() pure function exported from @context-forge/core
• ConsistencyChecker Rule 12: validates all project documents against per-docType frontmatter schemas
• Status alias normalization: accepts in-progress, not started, active, completed as valid
• Auto-fix inference for missing docType, slice, component, archIndex, project from filename/context

Fixed

• Slices and tasks outside worktree range now shown when plan is cross-initiative

Changed

• Removed Rules 9 (missing-plan-status) and 11 (missing-arch-status) — subsumed by generic schema validation

[0.6.27] - 20260327

Added

• Derive fileArch and fileSlicePlan from initiative plan when file is missing

Fixed

• cf install-commands now removes stale slash commands from previous versions

[0.6.26] - 20260327

Fixed

• MCP tools resolve project from CWD when projectId is omitted

Changed

• Extracted compound workflow commands into dedicated CLI modules

[0.6.25] - 20260325

Added

• 900-band maintenance initiative support: maintenanceInitiatives field in project model (same Initiative type, separate display bucket for visualization)
• getFieldNamesByGroup() schema utility for deriving field lists from PROJECT_FIELDS
• agent_quickstart MCP tool — structured JSON capability schema for machine consumers (slice 209)
• cf help --json — machine-readable command catalog
• cf version --json — structured version output
• Structured JSON error format for --json mode (code, message, suggestion fields)
• docs/AGENT-INTEGRATION.md — agent consumption guide
• 7 new slash commands for compound workflows (/cf:concept, /cf:initiatives, /cf:arch, /cf:plan, /cf:slice, /cf:tasks, /cf:implement)

Fixed

• cf list tasks and cf list plans no longer error on empty directories — returns empty result instead of UserError (blocked Squadron review commands on new projects)
• Compound commands (cf slice, cf tasks, etc.) now validate numeric index — previously cf slice banana silently set invalid values
• cf set warns on non-numeric artifact values that don't match expected patterns

Changed

• Removed agent_guide MCP tool (superseded by agent_quickstart)
• Replaced hard-coded field arrays (ARTIFACT_FIELDS, WORKFLOW_FIELDS, fieldKeys, MANAGED_FILES) with schema-derived or filesystem-derived sources
• Initiative detection expanded from 100-799 to 100+ (900+ partitioned into maintenanceInitiatives)
• Bare cf build (no flags) now shows help message instead of raw prompt output

[0.6.8] - 20260318

Added

• Worktree-aware guide operations (slice 190):
  • cf guides info and cf guides update detect worktree context via resolveProjectWorktree() and operate on the correct worktree path
  • SubmoduleStrategy.sync() reads target commit from main worktree, fetches objects, and checks out in worktree guide directory — handles worktrees on different branches
  • GuideManager.syncWorktrees() syncs multiple worktrees in one call with per-path error handling
  • GuideDetector.checkSyncStatus() reports per-worktree sync state via git submodule status
  • MCP guide_update auto-syncs all registered worktrees after primary update
  • MCP guide_status includes worktreeSync array for submodule-based projects with worktrees
  • New SyncResult type exported from @context-forge/core

Fixed

• Guide submodule updates now work in non-default worktrees — previously cf guides update from a worktree only updated the main worktree's checkout, leaving stale guide files in other worktrees (#44 cosmetic display issue noted)

[0.5.2] - 20260314

Added

• cf check Rule 11: missing-arch-status — flags architecture files with no status frontmatter field; fixable (infers from paired slice plan if present, else not_started)
• Renamed 200-arch.event-driven-pipeline.md → 220-arch.event-driven-pipeline.md (index reserved for new initiative)

[0.5.1] - 20260312

Added

• Default worktree improvements (slice 188):
  • Default worktree renamed from "Default" to "default" (lowercase)
  • Default range changed from [0, 99] to [100, 799] (working range instead of system range)
  • Dynamic range chopping: default worktree automatically shrinks when new worktrees claim overlapping sub-ranges
  • Artifact collision detection blocks range shrinking when default holds references outside the new range
  • CLI and MCP surface chopWarning on worktree add/update

[0.5.0] - 20260312

Added

• Worktree initiative (8 slices, 180–188): full git worktree support for parallel multi-initiative development
  • WorktreeService core service — CRUD for WorktreeContext records on ProjectData
  • applyWorktreeOverlay moved to @context-forge/core (CLI re-exports); shared by CLI and MCP
  • cf worktree init/list/get/update/rm CLI command group
  • cf status shows dedicated Worktree: line; --worktree and --worktrees flags for cross-directory access
  • cf set routes worktree-scoped fields (phase, slice, tasks, arch, plan) to WorktreeContext
  • cf check runs across all worktree overlays — worktree-scoped fields are visible in all checks
  • stale-worktree-path consistency rule detects registered worktrees whose paths no longer exist
  • cf status shows first-run hint when CWD is an unregistered git worktree of a known project
  • CWD resolution step 2b: auto-resolves project from git worktree even before cf worktree init
  • MCP tools: worktree_list, worktree_get, worktree_init, worktree_update, worktree_rm (5 new)
  • MCP extended: workflow_status, workflow_next, context_build, project_update accept worktreeId
  • MCP worktree_update overlap detection — rejects duplicate slice ranges across worktrees
• cf tasks command (renamed from cf task) with list and items subcommands

Fixed

• cf check was blind to worktree-scoped fields after worktree migration; now checks all views
• cf worktree init required --project flag from unregistered git worktree directories; resolved automatically

[0.4.2] - 20260311

Added

• cf backup CLI command — creates versioned timestamped backup of project data (keeps last 10, auto-prunes)
• storage_backup MCP tool — same backup functionality accessible to AI agents

[0.4.1] - 20260310

Added

• cf check --slice <index> — narrow consistency checks to a single slice
• cf check --yes — skip confirmation prompt in fix mode
• cf check default scope is now all-slices (previously single-slice)
• workflow_check MCP tool: sliceIndex param to target specific slices
• ConsistencyChecker rules 6–9: architecture-plan linkage, missing-plan-status, all-arch-plan pairs, filesystem discovery
• updateFrontmatterField supports inserting new keys (not just updating existing ones)

[0.4.0] - 20260309

Added

• cf setup-ide claude command — configures Claude Code integration with CLAUDE.md backup safety and y/N confirmation
• Context-profile-aware assembly — ContextProfileParser filters artifacts per instruction phase, reducing context bloat
• cf build --instruction-type / --it flag for profile override without persisting
• instructionType param on context_build MCP tool
• fileConcept field on project schema for concept document tracking
• Rule: avoid overly restrictive regex when creating parsers

Fixed

• /cf:prompt works with or without get subcommand (no double-dispatch)
• cf set architecture also sets slice plan (like slice → tasks)
• cf next suggests creating architecture when arch is specified but nonexistent
• fileConcept added to schema; project fields listed in general→specific order

[0.3.6] - 20260307

Added

• Guide install (cf guides install) now creates user artifact directories (user/, architecture/, slices/, tasks/, project-guides/)

Fixed

• cf next recommends creating architecture before slice plan when neither exists
• Electron date picker displays correctly for dates set via CLI as YYYYMMDD (normalized to YYYY-MM-DD)
• Slice plan parser supports unindexed entries (**Name** without (NNN) prefix)
• Slice plan heading exclusion no longer falsely skips sections like "Feature Slices (in implementation order)"

Changed

• Removed obsolete test infrastructure task file (all 891 tests now pass)
• Cleaned up maintenance file: removed completed items, condensed descriptions

[0.3.5] - 20260307

Added

• ConsistencyChecker core service with 5 detection rules: task-vs-plan, frontmatter-vs-computed, missing artifacts, plan-vs-frontmatter, task-file-status
• MarkdownWriter utility for non-destructive write-back (checkbox toggling + frontmatter field updates)
• Fix mode with FixLogEntry before/after tracing for each applied correction
• workflow.auto_fix config key for automatic corrections during consistency checks
• workflow_check MCP tool (25 total MCP tools)
• cf check CLI command replaces stub with full implementation (--fix, --json, --project)

Fixed

• /cf:prompt get P5 slash command no longer doubles the get subcommand
• --project help text across all CLI commands clarifies name or ID accepted

Changed

• Integration testing slice (168) demoted to maintenance — most deliverables completed incrementally
• Future work item (169) added: all-slices consistency checking mode, duplicate index detection

[0.3.4] - 20260307

Added

• WorkflowNavigator core service: getStatus() derives slice status from filesystem, getNext() priority-ordered state machine
• MCP tools: workflow_status, workflow_next
• CLI discovery commands: cf arch list, cf plan list, cf slice list, cf task list, cf task items
• Smart index resolution: cf set slice 166 derives filename from slice plan
• Auto-set fileTasks from slice name
• workflow.auto_advance config key

Fixed

• Artifact path resolution: resolveArtifactPath() correctly resolves stems to full paths
• slicePlan null handling in WorkflowNavigator, ArtifactIntrospector, cf slice list

Changed

• Slash command prompts optimized for token efficiency (~800 tokens saved)

[0.3.3] - 20260307

Added

• Auto-commit after cf guides install and cf guides update (submodule and clone strategies)

[0.3.2] - 20260306

Fixed

• Phase resolution in cf build --phase: accepts P1-P7 shorthands, numbers (1-7), and short names (task-breakdown); warns on unrecognized values
• Instruction matcher (getPromptForInstruction) handles full phase strings like Phase 5: Task Breakdown — extracts name portion for fuzzy matching
• Template conditionals support {{#if var}}content{{/if}} without requiring {{else}} clause
• Conditional evaluator uses enhanced data (artifact aliases like fileArch) instead of raw ContextData only

[0.3.1] - 20260306

Added

• README screenshots and assets (context-visualizer, cf-project-list, cf-status)
• CLI README: slash commands section, git-like CWD model explanation, cf init workflow

Changed

• Root README rewritten with screenshots, structured sections, and updated architecture description
• CLI README restructured: npm-focused install, slash commands table, commands reference
• Core and MCP READMEs updated for slice 175 changes

[0.3.0] - 20260306

Added

• Artifact fields (fileArch, fileSlicePlan, fileHLD, fileSpec) in ContextData, mapped through full pipeline
• Template variable aliases: {arch}, {plan}, {hld}, {spec} with index extraction ({archIndex}, {planIndex}, {hldIndex})
• Phase→instruction auto-set: setting developmentPhase via CLI or MCP automatically updates instruction to match
• Top-level shortcuts: cf set and cf get as shortcuts for cf project set/get
• Claude Code slash commands: /cf:status, /cf:build, /cf:next, /cf:prompt, /cf:get, /cf:set, /cf:project
• cf install-commands / cf uninstall-commands for Claude Code integration
• Smart field setting: cf set slice 171 resolves by scanning project files; customData sub-fields settable with merge semantics
• Schema-driven field metadata: cf project --schema with aliases, groups, enum values
• cf guides command: install, update, and status for ai-project-guide templates
• cf check command: consistency checks with --fix option
• cf future command: consolidated future work across all slice plans

Changed

• Consolidated ### Project Context section with clean key-value format (replaces bracket-wrapped ### Current Work Context)
• Unified opening statement (project-statement) regardless of workType (replaces start/continue branching)
• Template field removed from context output
• CWD-based project detection: cf auto-detects project from current directory
• Name-based project resolution: --project orchestration with project names instead of IDs
• Compact cf project list with * active indicator and ~ path shortening

[0.2.0] - 20260228

Added

• CWD-based project detection
• Name-based resolution with --project flag
• Resolution indicators in cf status output
• Compact cf project list format

Changed

• Tighter output formatting: consistent label alignment, suppressed empty fields

[0.1.0] - 20260225

Added

• Initial release with 8 commands: status, next, build, config, project, future, check, prompt
• Integration with @context-forge/core for context assembly
• Phase shorthands for prompt templates (P1-P7)
• JSON output mode on all applicable commands
• MCP server with project management, context generation, artifact introspection, and workflow tools
• Core context engine: template processing, statement management, prompt parsing, project storage