feat: feature-flag + image system; promote bundle to stable (#121)#122
Merged
Conversation
#121) Replaces the single --experimental boolean with a config-driven multi-image pipeline. Two images for v1: stable (default) and nightly, both shipping with empty feature lists — framework only. The legacy SvelteKit-with- node_modules/ shape is removed; the esbuild bundle (PRD-014 / RFC-013) is now the universal artifact form for every image. - config/images.json + config/features.json: source of truth for image → flags mapping and per-flag lifecycle metadata (addedIn / expiresIn / rollout). - scripts/build.mjs: bundles once via esbuild, copies to dist/ (stable) and dist-<name>/ (others), each with its own forgeplan-web-build.json carrying { image, features }. Build-time validator fails fast when any flag is past expiresIn or has lifetime > 3 minor versions. - bin/lib/images.mjs: image-name → directory mapping, allow-list-safe (node:* + relative siblings only — rule 23 unchanged). - bin/commands/init.mjs + update.mjs: --image <name> flag (default stable). Persisted in forgeplan-web.json. --experimental kept as deprecated alias for --image nightly with stderr warning; removed in 0.3.0. - scripts/smoke.mjs: extended to exercise both images end-to-end; asserts no node_modules/ in scaffold, image fields match, idempotent gitignore. - README + CHANGELOG + rules 21/23 + CLAUDE.md updated. Forgeplan: PRD-030 / RFC-026 / ADR-005 / EVID-035 (active, R_eff > 0). Refs: PRD-030, RFC-026, ADR-005 Closes: #121 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 9, 2026
fedorovvvv
added a commit
that referenced
this pull request
May 9, 2026
Tactical follow-up to #121 (PR #122) — agent context files and the Russian README still described the legacy `dist/` + `dist-experimental/` shape. Bring them in line with what `develop` actually ships: - README.ru.md: new "Образы (images)" section mirroring README.md; package summary in "Что получаешь" notes the per-image bundle. - docs/agents/domain.md: replace "legacy dist/" + "opt-in dist-experimental/" entries with image / feature-flag definitions; document `--experimental` as deprecated alias. - docs/agents/paths.md: top-level table swaps `dist-experimental/` for `dist-nightly/` + `config/`; tarball inventory now reads from `config/images.json`. No code changes — `bin/`, `scripts/`, `template/` untouched, smoke unchanged. Tactical depth per rule 11 (doc copy-edit, no public behaviour change), so no new Forgeplan artifact required; references the existing PRD-030 / RFC-026 / ADR-005 chain. Refs: PRD-030, RFC-026, ADR-005, #121 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
fedorovvvv
added a commit
that referenced
this pull request
May 9, 2026
…up) (#124) ## Summary Tactical follow-up to #121 (PR #122). Three doc files still described the legacy `dist/` + `dist-experimental/` shape — bring them in line with what `develop` actually ships post-PR-#122. - `README.ru.md` — new "Образы (images): `stable` (по умолчанию) и `nightly`" section mirroring `README.md`; updated "Что получаешь" line to mention the per-image bundle. - `docs/agents/domain.md` — replace **legacy `dist/`** + **opt-in `dist-experimental/`** entries with **Image** + **Feature flag** definitions, and document `--experimental` as a deprecated alias. - `docs/agents/paths.md` — top-level table swaps `dist-experimental/` for `dist-nightly/` + `config/`; tarball inventory now references `config/images.json` for the canonical image list. ## Why `docs/agents/*.md` are auto-loaded by the `fpl-skills` skill set. Stale terms there mean every future agent invocation starts with an inaccurate mental model of the package shape — exactly the kind of drift rule 11 (Forgeplan as single source of truth) is meant to prevent. PRD-030 already activated; this PR closes the doc gap without re-opening the artifact discipline. ## Scope No code changes — `bin/`, `scripts/`, `template/` untouched. Smoke status from PR #122 still applies. Tactical depth per rule 11 (docs without behaviour change), so no new Forgeplan artifact required. ## Test plan - [x] `grep -rn 'dist-experimental\|--experimental' docs/` shows only the `--experimental` *deprecated alias* mention in `domain.md`. - [x] `git diff --stat` is bounded to the three doc files. - [x] No code paths touched → smoke unaffected. - [ ] CI: docs-only PRs still trigger the smoke matrix; expected green since no source changed. Refs: PRD-030, RFC-026, ADR-005, #121 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
node_modules/shape is removed from the published tarball; the esbuild bundle (≈1.8 MB, capped at 3 MB) is now the universal artifact form for every image.config/images.json+config/features.jsondescribe what images ship and what flags each one carries. v1 shipsstable(default) andnightly, both with zero flags — framework only. Lifecycle policy: a flag'sexpiresIn≤addedIn + 3 minor; build fails fast when a flag is past expiry.--image <name>CLI oninitandupdate. Defaultstable. Sticky inforgeplan-web.json.--experimentalkept as deprecated alias for--image nightlyfor one minor release; removed in 0.3.0.Why
Two pressures merged: PRD-014 / RFC-013's
dist-experimental/bundle has been opt-in long enough to graduate, and a single--experimentalboolean can't scale to three or four parallel tracks. PRD-030 asks for a registry, not more booleans, with a forcing function so experimental flags can't accrete indefinitely.Forgeplan
evidence_type: test, CL3, supports)Test plan
npm run build— emitsdist/(image=stable, 1.79M) anddist-nightly/(image=nightly, 1.79M), both ≤3 MB, both with per-imageforgeplan-web-build.json.npm run smoke— exercises both images end-to-end (init + start +/api/health+/api/list+GET /returning 200), asserts nonode_modules/in scaffold, image fields match, gitignore idempotent.--experimentaldeprecation alias prints stderr warning and writesimage: "nightly"to both config files.expiresIn ≤ currentVersionexits non-zero with descriptive error; same forlifetime > 3 minor.Breaking changes (npm tarball internals only)
dist-experimental/is renamed todist-nightly/inpackage.json#files. Users runningnpx @forgeplan/web initsee no difference; only consumers that pinned the directory name in scripts must switch.installRuntimeDeps,emitDistPackageJson,copyToDist) removed fromscripts/build.mjs.Out of scope
lts).Refs: PRD-030, RFC-026, ADR-005
Closes: #121
🤖 Generated with Claude Code