Skip to content

Commit 9e61949

Browse files
committed
chore(gates): declare commands below cli-schema via R2 commands-floor (#2543)
Add the from:commands to:cli-schema policy so the declared direction (cli-schema reads the command facets; commands never imports cli-schema) cannot regress. R6 4 -> 3 (command-explain moved above daemon-server). Update the R2 hint, the check spine comment, and the surviving-inversion notes in the findings doc.
1 parent b8abe22 commit 9e61949

4 files changed

Lines changed: 41 additions & 6 deletions

File tree

‎docs/dependency-graph-findings.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ with `command`/`positionals` `Pick`ed from the wire so they cannot drift from it
111111
resolver already read only those three, in two spellings (the full type and a `Pick` of it); one
112112
narrow name replaced both.
113113

114-
**The remaining 5 are positions, not debt** — each for a mechanical reason, not an appeal to an ADR:
114+
**The remaining 4 are positions, not debt** — each for a mechanical reason, not an appeal to an ADR:
115115

116116
- **4 × `AgentDeviceClient`** (`commands/command-contract.ts`, `commands/command-surface.ts`,
117117
`commands/family/types.ts`, `mcp/command-tools.ts`). The zone-level type cycle this bullet used to
@@ -120,11 +120,13 @@ narrow name replaced both.
120120
facade above `commands/` is the remaining argument: a narrower port does not exist — 4 files
121121
*name* the facade, but 26 call sites use methods across 13 of its namespaces, so any port would
122122
re-declare it.
123-
- **1 × `DaemonCommandRoute`** (`commands/command-explain.ts`). The union lives in core so
124-
descriptors can name a route without importing the daemon, and the handler table covers it with
125-
`satisfies Record<DaemonCommandRoute, …>`. `command-explain.ts` still type-imports the re-export
126-
from `daemon-command-registry.ts` to key an exhaustive owner-file map; that remaining inversion
127-
is the commands-zone consumer, not a second source of truth for the union.
123+
124+
Retired by #2543: the **1 × `DaemonCommandRoute`** inversion whose only commands-zone consumer was
125+
`command-explain.ts`. The union lives in core so descriptors can name a route without importing the
126+
daemon; the explainer only type-imported the `daemon-command-registry.ts` re-export to key an
127+
exhaustive owner-file map. #2543 relocated `command-explain.ts` to the `cli/` zone — above
128+
`daemon-server` — so that consumer's type import no longer outranks its target, and the
129+
`commands -> daemon-server` R6 pair fell to zero.
128130

129131
All remaining inversions are argued here. R6 (`scripts/layering/type-inversion-ratchet.ts`) records
130132
no numbers of its own: its reference is the same count taken at the merge-base with `origin/main`,

‎scripts/layering/check.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
// ◄ { client, daemon-server } ◄ daemon-client ◄ cli
88
// (authoritative ranks: `TARGET_DAG_RANK` in model.ts. The former rank-0 kernel
99
// zone lives in packages/kernel since #1490 W0; R11 owns its boundary.)
10+
// `commands` and `cli-schema` share a rank, so the spine cannot order them; R2 declares the
11+
// direction instead — cli-schema renders the command facets and reads them, commands never
12+
// imports cli-schema (#2543).
1013
//
1114
// This gate enforces five things, across four scopes:
1215
// - GLOBALLY, across every production source file: the remaining R2 move rule and

‎scripts/layering/zone-policy.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,22 @@ test('R2 commands-floor closes the remaining zones below the command surface, wh
4444
assert.deepEqual(firing(edge('src/mcp/tools.ts', 'mcp', 'commands')), []);
4545
});
4646

47+
test('R2 commands-floor places commands below the cli-schema layer, whatever the kind', () => {
48+
// #2543: cli-schema renders the facets commands authors, so it reads commands and commands never
49+
// reads it back. The direction holds for value, type-only, and dynamic forms alike.
50+
for (const kind of [{}, { typeOnly: true }, { dynamic: true }]) {
51+
assert.ok(
52+
firing(edge('src/commands/thing.ts', 'commands', 'cli-schema', kind)).includes(
53+
'R2 commands-floor',
54+
),
55+
`commands -> cli-schema ${JSON.stringify(kind)} must violate R2`,
56+
);
57+
}
58+
59+
// The declared direction — cli-schema reading the facets — must stay silent.
60+
assert.deepEqual(firing(edge('src/cli-schema/command-schema.ts', 'cli-schema', 'commands')), []);
61+
});
62+
4763
test('the retired R3 platforms seam has no zone-policy declaration', () => {
4864
assert.equal(
4965
ZONE_POLICIES.some(({ rule }) => rule === 'R3 platforms-seam'),

‎scripts/layering/zone-policy.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ export type ZonePolicy = {
4343
* R1 kernel-sink retired 2026-07-30 (#1490 W0): the kernel moved to
4444
* packages/kernel, where package resolution and R11 package-boundaries enforce
4545
* the sink property physically — a package cannot import root src at all.
46+
*
47+
* The two rows share `R2 commands-floor`: both state that commands sits at a floor and is read
48+
* from above. The first keeps `core`/`daemon` below it; the second places `cli-schema` above it,
49+
* so commands may not import the schema layer that renders its facets (#2543 declared the
50+
* direction after the shared schema grammar moved down to the command registry).
4651
*/
4752
export const ZONE_POLICIES: readonly ZonePolicy[] = [
4853
{
@@ -53,6 +58,15 @@ export const ZONE_POLICIES: readonly ZonePolicy[] = [
5358
'commands/ is the command surface, above these zones. Depend on shared kernel/contracts ' +
5459
'instead; if two zones need the same rule, put the rule below both of them.',
5560
},
61+
{
62+
rule: 'R2 commands-floor',
63+
from: ['commands'],
64+
to: ['cli-schema'],
65+
hint:
66+
'cli-schema is the CLI/MCP schema layer that renders the command facets, so it sits above ' +
67+
'commands and reads them; commands must not import it back. The shared CommandSchema type and ' +
68+
'flag grammar live in @agent-device/command-registry, below both zones.',
69+
},
5670
];
5771

5872
function kindOf(imp: ImportEdge): 'type-only' | 'dynamic' | 'value' {

0 commit comments

Comments
 (0)