docs(arch): decompose open-questions.md into per-OQ files under questions/
The monolithic open-questions.md (1310 lines, 47 OQs) was large enough to be unmanageable, with high size variance (OQ-42 at 220 lines next to OQ-06 at 8). Decomposed into one file per OQ under docs/architecture/questions/ (NNN-slug.md, mirroring the ADR convention), with open-questions.md retained as the index: theme-grouped tables plus a cross-theme Deferred/Blocked section that surfaces the 6 deferred OQs with their Blocked-on conditions inline (the safe-exit visibility surface). Per-OQ content moved verbatim; all 62 inbound links stay valid (none used anchors). README's curated OQ summary dropped (now redundant with the index tables). Also seeds tasks/architecture/ with this task plus two follow-ups found during the decompose: OQ-09/10 missing structured Blocked-on fields, and the tasks/architecture/ blocker-task half of the Safe Exit protocol being unenforced.
This commit is contained in:
glm-5.2 committed
1 parent
e4e6ccfb14
commit
1baa619ce9
52 files changed
+1504
-1306
No files matched your search
@@ -0,0 +1,54 @@
|
||||
---
|
||||
id: architecture/open-questions-decompose
|
||||
name: Decompose open-questions.md into per-OQ files under questions/
|
||||
status: completed
|
||||
depends_on: []
|
||||
scope: moderate
|
||||
risk: low
|
||||
impact: project
|
||||
level: architecture
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
The single `docs/architecture/open-questions.md` file had grown to 1310 lines
|
||||
across 47 OQs — large enough to be unmanageable, with high size variance
|
||||
(OQ-42 at 220 lines next to OQ-06 at 8 lines). Decomposed into one file per
|
||||
OQ under `docs/architecture/questions/` (`NNN-slug.md`, mirroring the ADR
|
||||
convention), with `open-questions.md` retained as the index (theme-grouped
|
||||
tables + a cross-theme "Deferred / Blocked" section for safe-exit visibility).
|
||||
|
||||
## What changed
|
||||
|
||||
- Created `docs/architecture/questions/` with 47 files (`001-...md` through
|
||||
`047-...md`), content moved verbatim from the old monolithic file (heading
|
||||
rewritten from `### OQ-NN` to `# OQ-NN` for standalone files).
|
||||
- Rewrote `docs/architecture/open-questions.md` as the index:
|
||||
- Status-values / door-type definitions preserved
|
||||
- 15 theme sections, each with a table: `| OQ | Title | Status | Door | Pri |`
|
||||
- A "Deferred / Blocked" cross-theme section surfacing the 6 deferred OQs
|
||||
with their `Blocked on:` conditions inline (the safe-exit visibility
|
||||
surface)
|
||||
- Updated `docs/architecture/README.md`: dropped the 65-line curated OQ summary
|
||||
section (replaced by the index tables), kept the doc-table row pointing at
|
||||
`open-questions.md`.
|
||||
- Original monolithic file preserved at `/tmp/opencode/open-questions.old.md`
|
||||
for verification.
|
||||
|
||||
## Verification
|
||||
|
||||
- `python3 /tmp/opencode/verify_oqs.py` confirms all 47 per-OQ files match the
|
||||
original content byte-for-byte (modulo the `### OQ` → `# OQ` heading rewrite).
|
||||
- All 62 inbound links to `open-questions.md` across ~30 files remain valid
|
||||
(none used `#oq-NN` anchors — they all point at the bare filename, which is
|
||||
unchanged).
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Re-resolving or editing any OQ content — verbatim move only.
|
||||
- Fixing OQ-09/OQ-10's missing `Blocked on:` field — tracked as
|
||||
`architecture/oq-09-10-blocking-conditions`.
|
||||
- Establishing the `tasks/architecture/` blocker-task convention — tracked as
|
||||
`architecture/safe-exit-blocker-task-mechanism`.
|
||||
- Touching reviews/research docs that cite `open-questions.md` by line number
|
||||
(those citations are already stale; reviews are historical artifacts).
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
id: architecture/oq-09-10-blocking-conditions
|
||||
name: Add explicit Blocked on conditions to OQ-09 (WASM) and OQ-10 (Git Adapter)
|
||||
status: pending
|
||||
depends_on: []
|
||||
scope: small
|
||||
risk: low
|
||||
impact: local
|
||||
level: architecture
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
During the open-questions.md decompose (July 2026), I found that OQ-09 (WASM
|
||||
Target Boundaries) and OQ-10 (Git Adapter Scope) use the legacy `deferred`
|
||||
status without a structured `Blocked on:` field. They predate the formalized
|
||||
`deferred(scope)` + blocking-condition pattern established by ADR-009's Safe
|
||||
Exit protocol.
|
||||
|
||||
The four newer deferred OQs (OQ-32, OQ-41, OQ-44, OQ-46) all carry an explicit
|
||||
`Blocked on:` condition. OQ-09 and OQ-10 do not — their deferral reason lives
|
||||
in the Resolution prose, not in a structured field.
|
||||
|
||||
This matters because the new `open-questions.md` index has a "Deferred / Blocked"
|
||||
section that surfaces `Blocked on:` inline as the safe-exit visibility surface.
|
||||
OQ-09 and OQ-10 currently render as "_(no explicit blocking condition recorded
|
||||
— see full file)_" in that section, which weakens the visibility guarantee.
|
||||
|
||||
## Work
|
||||
|
||||
Either:
|
||||
- Add a `Blocked on:` field to each (e.g., OQ-09: "blocked on: a concrete
|
||||
server-side WASM use case — currently a design constraint, not a
|
||||
deliverable"; OQ-10: "blocked on: speccing alknet-git — resolve when that
|
||||
crate is specified, not deferred past it"), or
|
||||
- Reframe them as `deferred(scope)` if the original `deferred` status was
|
||||
imprecise, and confirm the blocking condition from the Resolution text.
|
||||
|
||||
The decision content stays unchanged — this is a metadata-structure fix, not a
|
||||
re-resolution.
|
||||
|
||||
## Verification
|
||||
|
||||
The "Deferred / Blocked" section of `docs/architecture/open-questions.md` should
|
||||
show a concrete blocking condition for OQ-09 and OQ-10 instead of the "no
|
||||
explicit blocking condition recorded" placeholder.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
id: architecture/safe-exit-blocker-task-mechanism
|
||||
name: Establish the tasks/architecture/ blocker-task half of the Safe Exit protocol
|
||||
status: pending
|
||||
depends_on: []
|
||||
scope: moderate
|
||||
risk: low
|
||||
impact: project
|
||||
level: architecture
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
During the open-questions.md decompose (July 2026), I found that the role
|
||||
spec's Safe Exit protocol says "create a blocker task in `tasks/architecture/`
|
||||
that names the dependency" when deferring a decision — but that directory has
|
||||
never existed. The four `deferred(scope)` OQs in the current file (OQ-32,
|
||||
OQ-41, OQ-44, OQ-46) carry a `Blocked on:` field but no corresponding blocker
|
||||
task files anywhere in the repo.
|
||||
|
||||
So the deferral *field* exists (the visibility half), but the *task* half of the
|
||||
safe-exit mechanism is unenforced/unused. This task is about establishing the
|
||||
convention so future deferrals create the corresponding blocker task, and
|
||||
backfilling the existing deferred OQs.
|
||||
|
||||
## Context
|
||||
|
||||
The project's broader pattern (per the July 2026 discussion): questions often
|
||||
lead to decisions which lead to tasks — a graph not unlike how implementation
|
||||
tasks are modeled as a DAG. The `tasks/architecture/` directory is where the
|
||||
"this decision is blocked on X" blocker tasks live, so that:
|
||||
|
||||
1. A deferred OQ has a visible `Blocked on:` condition in the index (the
|
||||
open-questions.md "Deferred / Blocked" section — already in place after the
|
||||
decompose).
|
||||
2. A deferred OQ has a corresponding blocker task that names the dependency and
|
||||
can itself be depended on by downstream work that needs the decision
|
||||
resolved.
|
||||
|
||||
The two halves serve different audiences: the index section is for the
|
||||
architect ("what's currently parked and why"), the blocker task is for the
|
||||
implementation agent / planner ("what unblocks this, and what's waiting on
|
||||
it").
|
||||
|
||||
## Work
|
||||
|
||||
1. Confirm the task file format (YAML frontmatter: `id`, `name`, `status`,
|
||||
`depends_on`, `scope`, `risk`, `impact`, `level`) is the right shape for
|
||||
architecture blocker tasks, or adjust if the architecture workflow needs
|
||||
different fields (e.g., a `blocks:` field pointing back at the OQ).
|
||||
2. Backfill blocker tasks for the four existing `deferred(scope)` OQs:
|
||||
- OQ-32 (Multi-Hop Federation) — blocked on a concrete multi-hop use case
|
||||
- OQ-41 (Stream Operators Library) — blocked on a handler needing operators
|
||||
beyond existing combinators
|
||||
- OQ-44 (Terminal Modes) — blocked on a concrete mode-control use case
|
||||
- OQ-46 (Runner API Surface) — blocked on a concrete runner-policy use case
|
||||
3. Document the convention (one line in `docs/sdd_process.md` or the architect
|
||||
role spec) so future deferrals create the blocker task as part of the Safe
|
||||
Exit step.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- The DB-backed backend (no manual links, vector/text search) — that's a future
|
||||
evolution that this file-based pattern informs, not something to build now.
|
||||
- Re-resolving any of the deferred OQs — this is about the tracking mechanism,
|
||||
not the decisions themselves.
|
||||
|
||||
## Verification
|
||||
|
||||
- `tasks/architecture/` contains one blocker task per `deferred(scope)` OQ
|
||||
- Each blocker task's `depends_on` names the concrete unblocking condition (or
|
||||
a task that represents it)
|
||||
- `docs/sdd_process.md` (or equivalent) references the convention
|
||||
Reference in new issue
Block a user