Skip to content

docs(architecture): revise CS-RG execution ownership and reuse policy - #8

Merged
novelKR merged 4 commits into
mainfrom
codex/cs-rg-plan-review
Sep 26, 2026
Merged

novelKR merged 4 commits into
mainfrom
codex/cs-rg-plan-review

Conversation

@novelKR

@novelKR novelKR commented Sep 26, 2026 •

Copy link
Copy Markdown
Owner

Summary

This PR revises the CS-RG execution layer at the user's explicit instruction to re-examine the design after DG-1 completed. Besides consistency with the DG-1 implementation, it addresses CodeSpace's duplicate lifecycles, spawn protection, output contract and backend maintenance cost. It keeps the authority and resource-correctness goals of the existing design and re-evaluates the boundaries and work order that implement them.

The file changes are limited to documentation and the documentation checker, but the PR changes design decisions that bind later implementation. Base 395315d, head cb3001e. It carries two documentation units and a handoff:

  • DGP-D05 (92a3472, unchanged): the CS-RG plan aligned with the implemented DG-1 consumer interface.
  • DGP-D06: design revision 1, a new English/Korean baseline (b17eb4c), and its application to the design reference and the plan (760f479).
  • Handoff (cb3001e): a session handoff so that a reviewer, another agent or a later session can continue the work. It is English only, a dated snapshot rather than an authoritative document, and leaves out personal information.

Design revision 1

  • Goals kept. One reaper per process; observation before reaping for managed executions; no private descriptor reaching unrelated children or payloads; no conclusion from a lost reply, timeout, EOF or root reap alone; one-time preparation with no automatic re-execution; control independent of new grants; distinct termination, output, workspace and lease lifetimes; separate implementation, functional, platform and SLO evidence (INV-01–INV-08).
  • F1 split. F1a reap ownership, F1b descriptor passing, F1c concurrent spawn, F1d output and handle contract, F1e maintenance branch. The conclusion is limited to "the examined high-level Codex spawn cannot carry a managed execution unchanged", not "Codex is impossible".
  • Target architecture. CodeSpace coordinates execution identity, approval linkage, state, timeout, termination, output and release in one layer; backends keep child creation, I/O, terminal setup, exit observation and the reap. BackendReaped (legacy off) and OwnerControlledReap (required) are distinct ownership models.
Decision Result
D1 required execution A CodeSpace-owned Unix transport at the current pin by default; reuse options and contract differences recorded before new code
D2 legacy off backends CSRG-C09 decides, before final qualification, between integration with removal and a limited compatibility backend on recorded grounds
D3 DevGuard and Codex No Codex dependency now; the core and shared client stay Codex-free, and adapter reuse follows a conditional policy with revisit triggers
A4 adaptation Permitted only for separated execution mechanisms, with provenance, divergence and removal conditions recorded
Codex pin Kept by this revision; a later change is a separate decision based on verification
ProcessDriver Only if it meets the output-loss, backpressure and Drop criteria
  • Work units. CSRG-C00 (execution-boundary fitness) forms CSRG-P0; CSRG-C09 (backend convergence decision) joins C07 in CSRG-P4; C08 moves to CSRG-P5 and qualifies only the head C09 leaves. CS-RG has 10 units in 6 groups; the plan has 48 units in 25 groups.
  • Failure mapping. Evidence of non-execution is separated from evidence of resource cleanup. Calling AbandonLaunch is not itself evidence; the authority's NoHelperCreated release is.

Changes by document

Document Change
docs/design-revision-1.md, docs/ko/design-revision-1.md New baseline: the revision specification in English and the supplied Korean text; review citations replaced with neutral wording; an evidence appendix
docs/design.md and Korean Conditional reuse instead of a permanent Codex ban; current registration rule without service-exec; an execution ownership section; pin statement scoped to this revision; the three distinct 250 ms / 5 s / 250 ms limits
docs/planning/decisions.md ADR-006 with alternatives, current rules, adaptation policy and triggers; ADR-001's current rule separated from superseded wording; new baselines
docs/planning/codespace-integration.md Confirmation baseline b6e7ed2; execution ownership (F1a–F1e, single reaper, pre-reap Observe, signals, spawn protection, PTY composition); one-time preparation; revised failure table; output contract and ProcessDriver criteria; D1–D3; new adoption order
docs/planning/milestones/CS-RG.md CSRG-C00 and CSRG-C09 with all fields; P0–P5; C01–C08 revised
docs/planning/consumer-readiness.md R3 requires the common lifecycle, mixed-mode safety and the C09 decision
docs/planning/verification.md 48/25 counts; CS-RG execution matrix, evidence levels, maintenance and dependency measurement, platform recording
docs/planning/pr-delivery.md DGP-D06 and CSP-D04; documentation PRs versus code PRs; final-head order C07 → C09 → C08
docs/planning/README.md, README.md, docs/milestones.md, AGENTS.md Reading order, revision summary, 48/25, baseline relationship and the reuse rule
DG-0.md, Korean P1-RECOVERY.md and DG-LINUX.md Count 48; predecessor group CSRG-P5
scripts/check_docs.py, scripts/test_check_docs.py Explicit unit and group numbering so CSRG starts at 0; a regression test
docs/handoff/2026-09-27-cs-rg-revision-and-codespace-ci.md Session handoff: state, refs, decisions, constraints, next steps and pitfalls

Changed from this PR's earlier description

Earlier statement Now
"The structure is unchanged: 8 CSRG units, 4 groups, 46/23" The execution layer and verification order are revised; CS-RG has 10 units in 6 groups, 48/25 overall
"The Codex adapter stays for off" An initial compatibility measure; CSRG-C09 decides integration or a limited backend before CSRG-C08
"The pin is unchanged" Design revision 1 keeps the pin; this is not a ban on a later change
"The approved design, milestones.json and all implementation and qualification status stay as they are" The historical approval, the ledger and all status stay; the editorial design is revised at the user's instruction of 2026-09-27, recorded as the basis of the re-examination
"This PR changes documentation only" The file changes are documentation and its checker, but the decisions bind later implementation

Preserved

  • docs/design.ko.md keeps SHA-256 97b67a1f…, and docs/design-source.json and milestones.json are unchanged.
  • CS-RG stays not-started/not-run. docs/contracts.md keeps only DGP-D05's removal of the stale C12 item; it describes implemented behavior only.
  • DG-1 qualification is not invalidated; no runtime artifact changed.

Evidence

Code review at fixed revisions, listed in the revision's appendix: Codex 6b9826e (pty.rs:244-253, :378-387, pipe.rs:280-299, process.rs:273-277, :427), CodeSpace b6e7ed2 (process.rs:366, :684, :714) and DevGuard 395315d (launch.rs, exec.rs, main.rs, root.rs). No runtime test was run for this revision.

Verification

  • python3 scripts/check_docs.py: passed, 17 reviewed pairs, 48 work units, 25 logical groups.
  • python3 -B -m unittest discover -s scripts -p test_check_docs.py: 9 tests OK, including the new numbering test.
  • python3 -B -m unittest discover -s scripts -p test_measure.py: 62 tests OK.
  • The validator's source_contract() stage: passed (approval checksum and critical path).
  • git diff --check: clean. b17eb4c alone also passes check_docs.py (46/23 at that commit), and the checks pass again at cb3001e.
  • The Korean counterparts of all 12 changed pairs were reviewed and their hashes recorded with check_docs.py record.
  • The Rust suites run in CI; this PR changes no Rust code.

Limitations and rollback

  • The 1 s pre-reap Observe budget is a proposal for CSRG-C00 to validate, not a qualified value.
  • The CodeSpace counterpart documentation (CSP-D04) follows after this PR merges and links the actual merge SHA.
  • Rollback is a new documentation revision with updated pairs and hashes; no runtime state depends on these documents.

The user reviews this PR before it is merged. It does not start CSRG-P0.

novelKR and others added 3 commits September 26, 2026 13:45
…-D05)

The CS-RG plan and the CodeSpace integration specification predate
DG-1's consumer interface. A review against the implemented contracts
and the current CodeSpace source found that following them literally
would break managed launches:

- the pinned Codex spawn reaps its child internally and drops
  close-on-exec descriptors, so launches must use HelperCommand with
  Runner-owned pipes or PTY and observe before reaping;
- DG-1 has no service-exec path and re-registers the same instance in
  every bounded session, with CredentialHandoff for the UDS worker;
- consumers are host.toml configuration read at start, and the default
  control reservation leaves a hosted macOS runner no work capacity;
- the per-exec resource request, the outcome table and the error
  mapping needed DG-1's actual requests, transcript phases and codes.

Record these in CS-RG, the integration specification and an ADR-001
note without changing the eight units or four groups. Remove the stale
C12 item from the contracts, update the planning index and readiness
status, and record DGP-D05 and CSP-D03 in the documentation history.
The Korean counterparts are reviewed and their hashes recorded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…DGP-D06)

At the user's explicit instruction after a mid-course review, record the
revision specification for CS-RG execution ownership and reuse as a new
design baseline, in English with its reviewed Korean counterpart. It keeps
the correctness goals, splits F1 into reap ownership, descriptor passing,
concurrent spawn, output contract and maintenance branch, and records the
D1-D3 decisions, the bounded adaptation policy and the CSRG-C00/C09 units.
Citations of individual review responses are replaced with neutral wording,
and an appendix lists the code-review evidence for its factual statements.
The historical approval docs/design.ko.md and its checksum are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Design reference: conditional reuse instead of a permanent Codex ban,
  the current registration rule without service-exec, an execution
  ownership section and a pin statement scoped to this revision.
- ADR-006 records the execution ownership and reuse decision; ADR-001
  separates its current rule from superseded wording; the baselines add
  CodeSpace b6e7ed2, DevGuard 395315d, the revised PR #8 head and the
  Codex comparison snapshot.
- CS-RG adds CSRG-C00 (P0) and CSRG-C09 (P4), moves C08 to P5 and
  revises C01-C08; the plan becomes 48 units in 25 groups.
- The integration specification, readiness, verification, delivery and
  indexes follow, and the Korean counterparts are reviewed and recorded.
- check_docs.py numbers units and groups explicitly so that CSRG starts
  at 0, with a regression test.

No runtime code, ledger status or approval checksum changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@novelKR novelKR changed the title docs(planning): align CS-RG with the implemented DG-1 interfaces (DGP-D05) docs(architecture): revise CS-RG execution ownership and reuse policy Sep 26, 2026
…(DGP-D06)

Add an English handoff so that a reviewer, another agent or a later
session can continue the work. It covers the state of PR #8 and of the
CodeSpace CI changes, the refs and checkouts involved, the decisions and
judgement calls behind design revision 1, the standing constraints, the
next steps with their commands, and the pitfalls met. It is a dated
snapshot rather than an authoritative document, and it leaves out
personal information.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@novelKR
novelKR merged commit d4981b4 into main Sep 26, 2026
5 of 6 checks passed
@novelKR
novelKR deleted the codex/cs-rg-plan-review branch September 26, 2026 18:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant