docs(adr): RFC-761 ADR-0001 §4 history fix + §5 phase readiness criteria#769
Merged
docs(adr): RFC-761 ADR-0001 §4 history fix + §5 phase readiness criteria#769
Conversation
ADR-0001 §4 was authored when Settings Hooks was the only web UI sync surface. Phases A (Skills), B (Commands), C (Agents) have since shipped to _PROD_ROUTERS while Settings remains in _DEV_ONLY_ROUTERS — so the "web UI currently supports Settings Hooks sync only" prose is now historically inverted. Update §4 to reflect that A–C shipped and Settings (Phase D) is the remaining dev-only surface awaiting promotion. Add new §5 "Phase readiness criteria" — the four-point contract that gates any phase's promotion from _DEV_ONLY_ROUTERS to _PROD_ROUTERS (and removal of its STATE.uiMode === 'dev' UI gate): 1. No P0/P1 issues open ≥2 weeks 2. Round-trip integration test (write → diff → import-back) 3. i18n key parity (en + ko, via test_i18n.py auto-discovery) 4. Conflict path test fixture (HTTP 409 OR documented soft-abort) §5 applies prospectively. Phases A–C ship as-is; gaps in their tests (e.g., missing 409 fixtures in B/C) are tracked as hygiene follow-ups, not regressions blocking re-merge. Procedure mirrors ADR-0007 (Namespace CRUD prod exposure): no env kill-switch; rollback via 'git revert' of the gate-removal commit. This is the decision-artifact PR for RFC #761; the Settings test backfill (round-trip + conflict-aborts + ctx_settings i18n nav keys) and the actual flip (router move + JS gate removal) ship as separate PRs against this contract. Refs: #761 Co-Authored-By: Claude <[email protected]>
Two refinements based on review feedback: **Criterion 2** — phase-shape aware. The previous wording required import-back via extract_*_to_canonical() for every phase, but Phase D Settings is unidirectional by design: canonical → runtime additive merge has no reverse-import API because merged entries cannot be distinguished from user-authored entries in ~/.claude/settings.json. Forcing reverse-import would self-block the very PR-3 §5 is meant to enable. Split into bidirectional (Skills/Commands/Agents — extract-back) and unidirectional (Settings — sync route + diff re-read with merge invariant assertion). **Criterion 1** — drop the specific gh command. The original 'gh issue list --label context-gateway,P0,P1' had two flaws: 1. --label A,B,C filters AND, not OR; a P0-only or P1-only issue could be missed. 2. The labels (context-gateway, P0, P1) are not a fixed convention in this repo today. Replace with a label-agnostic phase-scope description so the criterion remains accurate as labeling conventions evolve. Refs: #761 Co-Authored-By: Claude <[email protected]>
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
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
shipped to
_PROD_ROUTERS, but the doc still claimed "web UIcurrently supports Settings Hooks sync only" (historically inverted).
contract gating any future phase's promotion from
_DEV_ONLY_ROUTERSto
_PROD_ROUTERSand the removal of itsSTATE.uiMode === 'dev'UI gate.
Why
This is the decision-artifact PR for RFC #761 (Settings Hooks dev-only
gate → prod transition). The RFC's primary deliverable is the
stability criteria — without them, the same RFC repeats for each
future phase. The actual gate flip and Settings test backfill ship as
follow-up PRs against this contract.
The §5 criteria are:
import-back via
extract_*_to_canonical().tests/test_i18n.pyauto-discovers,so adding the phase's keys is sufficient.
(Skills'
mtime_nsdesign) or documented soft-abort (Settings'200 + {"status": "aborted"}). Both shapes qualify; therequirement pins conflict semantics, not a specific status code.
Decisions resolved (RFC open questions)
is the right place; cross-phase contract didn't justify a new ADR.
set the precedent for trigger-criteria-then-flip with
git revertrollback. A
MEMTOMEM_WEB__CONTEXT_GATEWAY__SETTINGS_DEV_ONLYknobwould be the first feature-level disable, breaking convention.
as-is; their gaps (missing 409 fixtures in B/C) are tracked as
hygiene follow-ups, not regressions.
earlier "409 conflict" wording would have flagged Settings itself
(which uses
200 + status:"aborted"by design) and Phases B/Cretroactively. Both 409 and documented soft-abort qualify now.
Out of scope (follow-up PRs)
This PR is docs-only — no code changes. Two follow-up PRs land the
behavior:
test_settings_round_trip_*andtest_settings_conflict_aborts_with_statustotests/test_context_settings.py, plus thectx_settings.*navigation i18n keys to
en.json+ko.json.settings_syncfrom_DEV_ONLY_ROUTERSto
_PROD_ROUTERSinweb/app.py, drop the twoSTATE.uiMode === 'dev'gates inweb/static/context-gateway.js,CHANGELOG entry.
Phases B/C 409 backfill is filed as a separate hygiene issue (not
blocking).
Test plan
coherent and the §4 prose is no longer historically inverted.
that drift).
modifications).
Refs: #761
🤖 Generated with Claude Code