From 8a0318bd2d082d15b342282118f2ec641797d160 Mon Sep 17 00:00:00 2001 From: fedorovvvv Date: Sat, 9 May 2026 15:11:36 +0400 Subject: [PATCH] chore(forgeplan): activate cluster A + deprecate stale PRD-001 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Process-debt cleanup. Cluster A — 7 RFCs/SPEC whose parent PRDs already shipped active via #109/#118 — were left in draft, distorting `forgeplan health`. Flipped to active to match parent state: - RFC-020 (citty arch) ← PRD-024 active - RFC-021 (scope resolver) ← PRD-025 active - RFC-022 (start scaffold) ← multi-instance wave - RFC-023 (port allocator) ← PRD-027 active - RFC-024 (Combobox primitive) ← PRD-029 active - RFC-025 (HealthBar switcher) ← PRD-029 active - SPEC-003 (instances schema) ← PRD-027 + ADR-004 active PRD-001 deprecated: title/body mismatch (title 'show versions in footer', body 'bootstrap CLAUDE.md baseline') — both shipped out-of-band. Markdown was Lance-only; surfaced into git as part of deprecation. EVID-004/EVID-005 retain dependency on deprecated parent; they're frozen evidence and don't need rework. Health: 79 → 86 active, 16 → 8 draft, 2 → 3 deprecated. Refs: PRD-024, PRD-025, PRD-027, PRD-029, ADR-004 Co-Authored-By: Claude Opus 4.7 (1M context) --- ...lan-forgeplan-web-versions-in-ui-footer.md | 117 ++++++++++++++++++ ...ation-architecture-bin-subcommand-split.md | 3 +- ...nd-user-scope-path-conventions-for-init.md | 3 +- ...ffold-resolution-algorithm-and-error-ux.md | 3 +- ...d-liveness-probe-atomic-registry-writes.md | 3 +- ...ui-wrapper-variants-playground-showcase.md | 3 +- ...her-and-api-instances-readonly-endpoint.md | 3 +- ...son-schema-forgeplan-web-instances-json.md | 3 +- 8 files changed, 131 insertions(+), 7 deletions(-) create mode 100644 .forgeplan/prds/PRD-001-show-forgeplan-forgeplan-web-versions-in-ui-footer.md diff --git a/.forgeplan/prds/PRD-001-show-forgeplan-forgeplan-web-versions-in-ui-footer.md b/.forgeplan/prds/PRD-001-show-forgeplan-forgeplan-web-versions-in-ui-footer.md new file mode 100644 index 0000000..8b8ac3a --- /dev/null +++ b/.forgeplan/prds/PRD-001-show-forgeplan-forgeplan-web-versions-in-ui-footer.md @@ -0,0 +1,117 @@ +--- +depth: standard +id: PRD-001 +kind: prd +status: deprecated +title: Show forgeplan + forgeplan-web versions in UI footer +--- + +# PRD-001: Bootstrap CLAUDE.md baseline and add methodological guides + +## Problem + +`ForgePlanWeb` ships with a working `CLAUDE.md` (208 lines) and 6 enforced +rules in `.claude/rules/`, **but the entry-point file lacks the structural +elements the reference repo (`/Users/explosovebit/Work/ForgePlan/CLAUDE.md`) +established as agent-safety baseline**: + +- No top-level **Red lines** block listing irreversible actions. Agent has + to discover deny-list rules from `.claude/settings.json#permissions.deny` + and from grepping hooks — both are not in the U-shaped attention zone + (start of file). +- No **Routing table** — depth selection (Tactical/Standard/Deep/Critical) + is buried in one prose paragraph (lines 92–94 of the original file). +- No **Forge Mode permission zones** table — agent does not know that + `.claude/hooks/forge-safety-hook.sh` blocks `npm publish`, `git push --force`, + `rm -rf /...`. This is dangerous because agent may attempt these without + knowing they are blocked, then re-attempt with workarounds. +- No reference to **methodological guides** (how to write CLAUDE.md, git flow + best practices). The reference repo bundles authored guides; this repo has + no equivalent. +- The **EvidencePack structured-fields trap** (silent CL0 → R_eff = 0.1) is + mentioned in one sentence with no example — agents miss the trap. + +**Impact**: Standard+ tasks executed by agents in this repo are at higher +risk of (a) destructive actions blocked by the hook (wasted context), +(b) skipped methodology (creating EvidencePack without structured fields, +silently scoring 0.1), (c) inconsistent depth routing. + +## Target Users + +| Persona | Description | Pain | +| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- | +| Claude Code agent | LLM operating on this repo via `claude-code` harness | Has to grep hooks/rules to know what's blocked; misses cry-wolf U-curve start of file | +| Repo contributor | Human reading CLAUDE.md before opening a PR | No quick "what not to do" reference; depth routing buried in prose | + +## Goals + +| ID | Criterion | Metric | Target | How to measure | +| ---- | ------------------------------------------------------------ | ---------------------------------------------- | -------------------------- | -------------- | +| SC-1 | CLAUDE.md has Red lines block in the first 30% of the file | `grep -n "🔴 Red lines" CLAUDE.md` line number | line number ≤ 30% of total | shell command | +| SC-2 | CLAUDE.md references methodological guides | `grep "guides/INDEX.md" CLAUDE.md` | ≥ 1 occurrence | shell command | +| SC-3 | `forgeplan health` reports 0 blind_spots after reindex | `forgeplan health --json` | `blind_spots: []` | jq query | +| SC-4 | `guides/` exists with 3 files (INDEX + 2 guides) | `ls guides/` | 3 files | shell command | +| SC-5 | `node scripts/smoke.mjs` passes (no regression in build/bin) | exit code | 0 | CI smoke | + +## Non-Goals + +- Do **not** modify `bin/forgeplan-web.mjs`, `template/`, `scripts/`, + `package.json`. This is a documentation-only change. +- Do **not** add new `.claude/rules/*.md` files. Existing 6 rules are correct. +- Do **not** change `.claude/hooks/`. Existing 4 hooks stay as-is. +- Do **not** configure an LLM provider in `.forgeplan/config.yaml`. Reset + to default (gemini block commented out) is intentional — provider config + is per-developer and lives outside the repo. +- Do **not** delete or rewrite existing artifacts (RFC-001, ADR-001, + EVID-001/002/003) — only add new ones. + +## Functional Requirements + +| ID | Category | Priority | Requirement | Acceptance | +| ------ | ------------- | -------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| FR-001 | Agent safety | Must | Agent can find red-line rules within the first 60 lines of CLAUDE.md | Block titled `🔴 Red lines (never do)` exists, lists ≥5 rules, before line 60 | +| FR-002 | Methodology | Must | Agent can pick depth via a 4-row routing table | Table with rows Tactical/Standard/Deep/Critical, columns Complexity/Depth/Artifacts/ADI | +| FR-003 | Methodology | Must | Agent has a concrete `## Structured Fields` example for EvidencePacks | Code block with `verdict`/`congruence_level`/`evidence_type` literal values + CL penalty table | +| FR-004 | Agent safety | Must | Agent knows what each `.claude/hooks/*.sh` blocks | Table listing all 4 hooks with Blocks + When columns | +| FR-005 | Documentation | Must | Repo has `guides/` directory with index + ≥2 methodological guides | `guides/INDEX.md` + `CLAUDE-MD-GUIDE.ru.md` + `GIT-FLOW-GUIDE.ru.md` exist | +| FR-006 | Documentation | Must | CLAUDE.md links to `guides/INDEX.md` | `Reference (guides)` section present, mentions all 3 files | +| FR-007 | Recovery | Should | RED LINES warns about destructive `forgeplan` commands | Pending — see future RFC; not in scope of PRD-001 | + +## Non-Functional Requirements + +| ID | Category | Requirement | Metric | +| ------- | ------------- | ---------------------------------------------------------------------------------------------- | -------------------------------- | +| NFR-001 | Length | CLAUDE.md stays under 350 lines | `wc -l < CLAUDE.md` ≤ 350 | +| NFR-002 | Idempotency | Re-running the bootstrap skill against `guides/` does not duplicate files | `ls guides/ \| wc -l` stays at 3 | +| NFR-003 | Compatibility | All existing `.claude/rules/*.md` remain valid (no contradictions with new CLAUDE.md sections) | Manual review by reviewer | + +## Affected Files + +- `CLAUDE.md` — modified (~+85 lines) +- `guides/CLAUDE-MD-GUIDE.ru.md` — new (copy from `~/.claude/skills/bootstrap-claude-project/resources/guides/`) +- `guides/GIT-FLOW-GUIDE.ru.md` — new (same source) +- `guides/INDEX.md` — new (from skill template) +- `.forgeplan/config.yaml` — reset to default (per user request after `init --force`) + +## Related Artifacts + +| Artifact | Relation | Status | +| -------- | --------------------------------------------------------------------------------- | ------- | +| RFC-001 | Existing — describes the published-package pre-build pipeline | active | +| ADR-001 | Existing — describes `init` writing to host `.gitignore` | active | +| EVID-\* | Smoke evidence for the build pipeline | active | +| RFC-002 | Will be created — adoption plan + future RED LINE additions | planned | +| EVID-004 | Will be created — proves CLAUDE.md baseline and `forgeplan health` post-bootstrap | planned | + +## Risks & Mitigations + +| ID | Risk | Probability | Impact | Mitigation | +| --- | -------------------------------------------------------------------------- | ----------- | ------ | ---------------------------------------------------- | +| R-1 | Cry-wolf: too many RED LINES dilute attention | Low | Medium | Capped at 7; each tied to a real hook or rule | +| R-2 | CLAUDE.md grows past attention limit | Low | Low | NFR-001 caps at 350 lines | +| R-3 | Drift between CLAUDE.md and `.claude/rules/` | Medium | Medium | Always cross-reference rule numbers; reviewer checks | +| R-4 | `forgeplan init --force` recurrence (it deleted artifacts in this session) | Low | High | Add to a future RED LINE in a follow-up RFC (FR-007) | + + + + diff --git a/.forgeplan/rfcs/RFC-020-citty-integration-architecture-bin-subcommand-split.md b/.forgeplan/rfcs/RFC-020-citty-integration-architecture-bin-subcommand-split.md index 2ce4be2..94e508d 100644 --- a/.forgeplan/rfcs/RFC-020-citty-integration-architecture-bin-subcommand-split.md +++ b/.forgeplan/rfcs/RFC-020-citty-integration-architecture-bin-subcommand-split.md @@ -5,7 +5,7 @@ kind: rfc links: - target: PRD-024 relation: based_on -status: draft +status: active title: citty integration architecture — bin/ subcommand split --- @@ -264,3 +264,4 @@ citty supports both. Help is auto-generated; we delete the bespoke > **Next step**: Land alongside PRD-024 + ADR-003. Phase order is strict; do not skip Phase 1's helper extraction. + diff --git a/.forgeplan/rfcs/RFC-021-scope-resolver-and-user-scope-path-conventions-for-init.md b/.forgeplan/rfcs/RFC-021-scope-resolver-and-user-scope-path-conventions-for-init.md index 3a95e94..62e3060 100644 --- a/.forgeplan/rfcs/RFC-021-scope-resolver-and-user-scope-path-conventions-for-init.md +++ b/.forgeplan/rfcs/RFC-021-scope-resolver-and-user-scope-path-conventions-for-init.md @@ -5,7 +5,7 @@ kind: rfc links: - target: PRD-025 relation: based_on -status: draft +status: active title: Scope resolver and user-scope path conventions for init --- @@ -250,3 +250,4 @@ Reader code (in `bin/lib/config.mjs`) treats absent `scope` as > **Next step**: Land alongside PRD-025. PRD-026 (RFC-022) consumes `resolveScopeRoot`. + diff --git a/.forgeplan/rfcs/RFC-022-start-scaffold-resolution-algorithm-and-error-ux.md b/.forgeplan/rfcs/RFC-022-start-scaffold-resolution-algorithm-and-error-ux.md index 4f7c304..86a4303 100644 --- a/.forgeplan/rfcs/RFC-022-start-scaffold-resolution-algorithm-and-error-ux.md +++ b/.forgeplan/rfcs/RFC-022-start-scaffold-resolution-algorithm-and-error-ux.md @@ -5,7 +5,7 @@ kind: rfc links: - target: PRD-026 relation: based_on -status: draft +status: active title: start scaffold-resolution algorithm and error UX --- @@ -272,3 +272,4 @@ async function handleEmpty({ isTTY, yesFlag }) { > **Next step**: Land alongside PRD-026. PRD-027's registry hook fires inside `start` after resolution. + diff --git a/.forgeplan/rfcs/RFC-023-port-allocator-pid-liveness-probe-atomic-registry-writes.md b/.forgeplan/rfcs/RFC-023-port-allocator-pid-liveness-probe-atomic-registry-writes.md index 2bf1e9a..9b09119 100644 --- a/.forgeplan/rfcs/RFC-023-port-allocator-pid-liveness-probe-atomic-registry-writes.md +++ b/.forgeplan/rfcs/RFC-023-port-allocator-pid-liveness-probe-atomic-registry-writes.md @@ -5,7 +5,7 @@ kind: rfc links: - target: PRD-027 relation: based_on -status: draft +status: active title: Port allocator, pid-liveness probe, atomic registry writes --- @@ -407,3 +407,4 @@ process.on('beforeExit', cleanup); > **Next step**: Land alongside PRD-027 + SPEC-003. + diff --git a/.forgeplan/rfcs/RFC-024-combobox-primitive-bits-ui-wrapper-variants-playground-showcase.md b/.forgeplan/rfcs/RFC-024-combobox-primitive-bits-ui-wrapper-variants-playground-showcase.md index 8f53747..d84e7b7 100644 --- a/.forgeplan/rfcs/RFC-024-combobox-primitive-bits-ui-wrapper-variants-playground-showcase.md +++ b/.forgeplan/rfcs/RFC-024-combobox-primitive-bits-ui-wrapper-variants-playground-showcase.md @@ -5,7 +5,7 @@ kind: rfc links: - target: PRD-028 relation: based_on -status: draft +status: active title: Combobox primitive — bits-ui wrapper, variants, /playground showcase --- @@ -305,3 +305,4 @@ toolbar. > **Next step**: Land alongside PRD-028. PRD-029 imports Combobox after this lands. + diff --git a/.forgeplan/rfcs/RFC-025-healthbar-instance-switcher-and-api-instances-readonly-endpoint.md b/.forgeplan/rfcs/RFC-025-healthbar-instance-switcher-and-api-instances-readonly-endpoint.md index c4b97a1..59078a2 100644 --- a/.forgeplan/rfcs/RFC-025-healthbar-instance-switcher-and-api-instances-readonly-endpoint.md +++ b/.forgeplan/rfcs/RFC-025-healthbar-instance-switcher-and-api-instances-readonly-endpoint.md @@ -5,7 +5,7 @@ kind: rfc links: - target: PRD-029 relation: based_on -status: draft +status: active title: HealthBar instance switcher and /api/instances readonly endpoint --- @@ -360,3 +360,4 @@ copy-paste into `.claude/rules/22-readonly-proxy.md`. > **Next step**: Land alongside PRD-029. Last RFC of the #109 chain. + diff --git a/.forgeplan/specs/SPEC-003-instance-registry-json-schema-forgeplan-web-instances-json.md b/.forgeplan/specs/SPEC-003-instance-registry-json-schema-forgeplan-web-instances-json.md index d7f2772..44887f6 100644 --- a/.forgeplan/specs/SPEC-003-instance-registry-json-schema-forgeplan-web-instances-json.md +++ b/.forgeplan/specs/SPEC-003-instance-registry-json-schema-forgeplan-web-instances-json.md @@ -5,7 +5,7 @@ kind: spec links: - target: PRD-027 relation: based_on -status: draft +status: active title: Instance registry JSON schema (~/.forgeplan-web/instances.json) --- @@ -252,3 +252,4 @@ On error: `{ "ok": false, "error": "...", "data": { "instances": [] } }`. > **Next step**: Land alongside RFC-023. PRD-029 consumes the API surface defined here. +