docs: create client host orchestration intent baseline for issue #135 - #141
Conversation
Create the docs-first Slice A baseline for issue #135 around client host orchestration. Key changes: - add issue-specific gap analysis and master TODO with a Slice A claim ledger - define the planned host orchestration contract in client/DESIGN.md - clarify in client/README.md that current --output json is a legacy automation schema, not the future host protocol - sync canonical design backlog in docs/design/modules/event/README.md and docs/design/TODO_INDEX.md - add OpenSpec change artifacts and a feature aggregation doc for client-host-orchestration-doc-baseline Rationale: Issue #135 is not a request to rebuild the examples CLI. The real entrypoint is /client, which already has run/script, JSON output, skills, and dynamic MCP support. The missing piece is a canonical host-orchestration contract that separates legacy automation JSON from future headless event and control protocols. This commit creates the docs-only intent baseline required before any implementation slice can start. Validation: - openspec list - openspec validate client-host-orchestration-doc-baseline --type change --strict --json --no-interactive
…n baseline Update the active feature aggregation doc for client-host-orchestration-doc-baseline after opening the docs-only intent PR. Key changes: - add the governance evidence truth command to the feature evidence block - record that the governance evidence gate passed - replace the placeholder review section with the real PR link (#141) Rationale: The repository governance gate requires active feature docs to include concrete review and merge-gate links. Once the docs-only intent PR existed, the feature doc needed a follow-up evidence update so the governance script could pass. Validation: - ./scripts/ci/check_governance_evidence_truth.sh
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1974edc509
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Update the Slice A claim ledger and completed TODO owner fields to use the requester's GitHub identity instead of the agent label. Key changes: - change Claim Ledger owner for CLM-20260302-CCLI-A from codex to bouillipx - change completed TODO owner fields for CCLI-001 and CCLI-002 from codex to bouillipx Rationale: These governance records should identify the human owner of the claimed scope rather than the coding agent label. Validation: - rg -n "CLM-20260302-CCLI-A|\| bouillipx \||\| codex \|" docs/todos/2026-03-02_client_cli_host_orchestration_master_todo.md
…ctions Address PR review feedback about action identifier drift in the client host orchestration baseline. Key changes: - replace dotted action examples like actions.list and approvals.list with canonical resource:action identifiers - align MCP examples to use mcp:list/reload/show-tool/unload - rename the planned status action to status:get to keep the same identifier shape - sync the README, gap analysis, master TODO, and OpenSpec design/spec delta with the canonical naming Rationale: The runtime already defines stable deterministic action ids in dare_framework/transport/interaction/resource_action.py using resource:action form. Leaving the docs on dotted names would create a false protocol contract and either force an unnecessary translation layer or break future slices against ResourceAction.value_of. Validation: - openspec validate client-host-orchestration-doc-baseline --type change --strict --json --no-interactive - ./scripts/ci/check_governance_evidence_truth.sh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 10c52e9293
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Address the latest PR review feedback on issue #135 docs. Key changes: - remove `mcp:unload` from the documented v1 host control action baseline in `client/DESIGN.md` because the current canonical deterministic action set only includes `mcp:list`, `mcp:reload`, and `mcp:show-tool` - update the gap analysis and master TODO so future control-plane work is scoped to the current canonical MCP action set, while keeping CLI `unload` explicitly documented as a separate command capability pending a future canonical action - normalize the Slice A/B/C/D coverage table so each slice matches the TODO-to-change mapping and the active claim scope Rationale: The previous docs mixed existing CLI command surface with the current canonical `resource:action` identifiers, which overstated what the v1 host control plane can promise today. The Slice planning table also drifted from the claimed TODO scope. This commit tightens both boundaries so the docs-only intent PR stays aligned with the runtime contract and governance ledger.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ea7c589f5a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 2. `approvals:list/poll/grant/deny/revoke` | ||
| 3. `mcp:list/reload/show-tool` | ||
| 4. `skills:list` | ||
| 5. `status:get` |
There was a problem hiding this comment.
status:get from v1 control baseline
The new control-plane baseline lists status:get as a first-batch action, but the deterministic action registry in dare_framework/transport/interaction/resource_action.py has no status:get, and ResourceAction.value_of(...) returns None for unknown IDs. If a host follows this design and sends status:get over the structured control plane, it will be rejected as an unknown action, so the documented contract is internally inconsistent unless this action is added canonically (or explicitly mapped) first.
Useful? React with 👍 / 👎.
| - `interaction-dispatch`: 补充宿主能力发现与结构化 control plane 的规划约束。 | ||
| - `transport-channel`: 补充宿主事件 envelope 的版本化与关联字段要求。 |
There was a problem hiding this comment.
This proposal says the change modifies interaction-dispatch and transport-channel, but the change set only includes a single spec delta under specs/client-host-orchestration/spec.md. As written, those two modified capabilities are not represented by any normative OpenSpec requirements, so downstream work can pass validation without enforcing the constraints this proposal claims to have established; either add matching spec deltas or remove these modified-capability claims.
Useful? React with 👍 / 👎.
Scope:\n- create the main openspec/specs/client-host-orchestration/spec.md by folding in the merged Slice A and Slice B deltas\n- archive the completed client-host-orchestration-doc-baseline and client-headless-event-envelope-v1 changes plus their feature aggregation docs\n- update the issue #135 master TODO ledger to mark Slice A/B done and claim Slice C\n- create the Slice C feature aggregation doc and OpenSpec artifacts for client-external-control-plane-v1\n\nRationale:\nPR #141 and PR #145 are already merged, so the repository should no longer keep Slice A and Slice B as active OpenSpec changes. Before starting external control-plane work, the host-orchestration capability needs a canonical main spec and a clean active-change set. This commit closes the previous slices, preserves their audit trail under archive paths, and establishes the docs-first kickoff baseline for Slice C around --control-stdin, canonical action bridging, and structured control responses.
1 participant
Summary
This is a docs-only intent PR for issue #135.
It establishes Slice A of the client host orchestration work:
/clientrather thanexamples/06CCLI-001~CCLI-002underclient-host-orchestration-doc-baselineWhy
Issue #135 is not about adding basic CLI capability from scratch.
/clientalready has:run/script--output jsonskills listmcp reload/unloadWhat is still missing is a stable host-orchestration contract:
headlessmode semanticsThis PR creates the docs-first baseline required by the repo SOP before implementation begins.
Scope
Included in this PR:
client/DESIGN.mdandclient/README.mddocs/design/modules/event/README.mdanddocs/design/TODO_INDEX.mdclient-host-orchestration-doc-baselinedocs/features/client-host-orchestration-doc-baseline.mdNot included in this PR:
--headlessimplementation--control-stdinimplementationTODO / Change Mapping
CCLI-001CCLI-002CLM-20260302-CCLI-Aclient-host-orchestration-doc-baselineValidation
Executed:
openspec listopenspec show client-host-orchestration-doc-baseline --type change --json --no-interactiveopenspec validate client-host-orchestration-doc-baseline --type change --strict --json --no-interactiveResults:
client-host-orchestrationMerge Gate Intent
This PR is intended to satisfy the docs-only intent gate for Slice A.
After this PR is merged to
main, the next step is to start implementation slices in order:client-headless-event-envelope-v1client-external-control-plane-v1client-capability-discovery-and-host-tests