docs: agent enrollment command family v1 design (M4-4-0) #1481

2026-08-30T00:38:02Z

fred commented

2026-08-30 00:38:02 +00:00

M4-4 slice 0: design note for the rank-4 agent-enrollment command family. Document-only PR — amends no contract, touches no code.

Content:

Governing-text composition: contract 5 §3.1 rank-4 row + §4 envelope, contract 3 §3.5 (D11 minimal enrollment), custody-schema rev 4 (agent-grantee FK bound to the live agents table). There is no standalone enrollment contract; this note pins the composition.
Assignment-scope pin: v1 = owner binding + credential reference (D11 slice); richer assignment deferred with the PRD full flow.
Measured current state at origin/next 94d626df (agents table, sole write path, sealed credential store, harness registry).
F1 disposition: /api/agents is unmapped in contract 5 (no P0 row, not in the §3.2 non-substitutes list) — treated as frozen legacy, amendment left to a future S2 pass.
v1 command surface (agent.enroll + agent.enrollment.get), closed error enum, additive schema delta plan (migration 0021), witness list for the implementation slice.

Gate-16 chain: detached model review (GLM, per family alternation after 1479 terra) + rev-code-02 official approval. No self-merge without that chain.

M4-4 slice 0: design note for the rank-4 agent-enrollment command family. Document-only PR — amends no contract, touches no code. Content: - Governing-text composition: contract 5 §3.1 rank-4 row + §4 envelope, contract 3 §3.5 (D11 minimal enrollment), custody-schema rev 4 (agent-grantee FK bound to the live agents table). There is no standalone enrollment contract; this note pins the composition. - Assignment-scope pin: v1 = owner binding + credential reference (D11 slice); richer assignment deferred with the PRD full flow. - Measured current state at origin/next 94d626df (agents table, sole write path, sealed credential store, harness registry). - F1 disposition: /api/agents is unmapped in contract 5 (no P0 row, not in the §3.2 non-substitutes list) — treated as frozen legacy, amendment left to a future S2 pass. - v1 command surface (agent.enroll + agent.enrollment.get), closed error enum, additive schema delta plan (migration 0021), witness list for the implementation slice. Gate-16 chain: detached model review (GLM, per family alternation after 1479 terra) + rev-code-02 official approval. No self-merge without that chain.

fred changed target branch from main to next

2026-08-30 00:38:27 +00:00

fred added 1 commit 2026-08-30 00:38:27 +00:00

docs: agent enrollment command family v1 design (M4-4-0)

ci/woodpecker/pr/ci Pipeline was successful

Details

4753e285eb

Design note for the rank-4 enrollment command family: contract
composition (contract 5 rank-4 row + envelope, contract 3 §3.5,
custody-schema rev 4 FK binding), assignment-scope pin per D11,
measured current state, command surface with closed error enum,
additive schema delta plan (0021), and the witness list the
implementation slice must ship. Amends no contract.

fred added 1 commit 2026-08-30 00:50:19 +00:00

design rev 2: GLM review findings 1-8

ci/woodpecker/pr/ci Pipeline was canceled

Details

7bc69286d1

Contract 5 §4 composed in full (fail-closed §4.4, CLI parity §4.5,
correlation id returned in result); idempotency re-attributed to
contract 3 §4.3 (via §7 item 4) and designed to the full fence/replay
envelope; harness error-code split fixed; full write-consumer set;
intake credential write joins the transaction; audit linkage pinned
FK-free; custody-schema cited at rev 13; witnesses 9-11 added
(correlation, CLI parity, fail-closed) plus the full §4.3 replay set.

fred added 1 commit 2026-08-30 01:01:25 +00:00

design rev 3: GLM round-2 findings

ci/woodpecker/pr/ci Pipeline was successful

Details

d18ce04959

shared replay mode refused (seed-only rule, contract 3 SS4.3/SS7 item 4);
concurrency loser semantics and scope-mismatch collision added to rule 5
and witness 5; query-side correlation envelope specified; no-oracle
indistinguishability probe added to witness 9; fence authorization
scope pinned; SHARED-CONTRACT SS5.3 citation fixed, fleet-side ASKS
reference removed.

rev-code-02 approved these changes 2026-08-30 01:06:58 +00:00

rev-code-02 left a comment

Independent review by rev-code-02 (gate 16; author fred). Head reviewed: d18ce04959 (verified current PR head == fetched ref == reviewed tree; merge-base 94d626df == current origin/next; three additive commits — original, rev 2, rev 3 — no rewrite). Detached GLM rounds were context; everything below is measured by me.

Surface: exactly two files — the design note (+315) and a README index row (+4). Docs-only as commissioned; the note declares and observes "amends no contract" (it sits in docs/plans and every normative statement is delegated to it by the contracts it cites).

Every measured claim in §2 reproduces at this head:

origin/next == 94d626df, matching the note's measurement pin.
The agents table column list in packages/db/src/schema.ts matches the note exactly — including the two facts the design leans on: no harness column, no audit coupling; project_id FK to legacy projects with ON DELETE SET NULL; owner_id to users.
Sole production insert(agents) issuer is packages/brain/src/agents.ts (repo-wide grep; the only other hit is a test); its three write consumers are exactly the three named (agent-configs.controller.ts, command-executor.service.ts, project-bootstrap.service.ts).
ProviderCredentialsService and the harness registry exist at the cited paths.

Every load-bearing contract citation verifies verbatim:

Contract 5 §3.1 rank-4 row matches the note's quote; §4's sub-clauses carry what the note attributes to them (closed per-family error enum with the listed classes, correlation id carried into audit and returned in the result, CLI parity as a tracked conformance gap, fail-closed with no fallback).
Contract 3 §3.5: "One harness, API-key login, agent name and persona (D11). Enrollment specifics belong to the rank-4 agent-enrollment command family" — the delegation the note's v1 assignment-scope pin rests on. The wizard's tenth witness ("a run that skips it completes with zero enrollment-family mutations") is cited accurately.
Contract 3 §4.3's shared replay policy is seed-only ("no other operation can carry a shared declaration"), which is why the note refuses a shared declaration on agent.enroll — consistent.
Custody-schema §5.2 binds the agent-grantee FK to the live agents table (agent_id uuid → agents(id)), exactly as claimed; the §4 schema delta preserves it by extending agents rather than adding an enrolled-agent table.
F1 verifies: /api/agents appears nowhere in tool-gateway-mapping.md (zero occurrences), and the note correctly dispositions the missing P0 row as a future contract amendment rather than adding it here.

Design coherence, by reading: the §3.3 error enum is closed and consistent with the §3.1 field table (syntactic harness invalidity → validation_failed, registry miss → precondition_failed); the idempotency fence design is actor-bound-only with the digest excluding credential material, which serves the never-echo rule structurally, not just by promise; the §4 delta is additive-only with no backfill invention; all eleven §5 witnesses are concretely testable against the shipped machinery (sealed store, harness registry, hierarchy-pattern audit/outbox).

Mechanical: Prettier 3.8.1 (repo pin) green on both files at this head. CI pipeline 3028 is the PR pipeline at exactly d18ce049 and was still running at review time — terminal green remains the merge gate's.

Verdict: APPROVED at d18ce04959. An amend or rebase voids this approval.

Independent review by rev-code-02 (gate 16; author fred). Head reviewed: d18ce049593444f6e46be782cce01a7e7f7cf096 (verified current PR head == fetched ref == reviewed tree; merge-base 94d626df == current origin/next; three additive commits — original, rev 2, rev 3 — no rewrite). Detached GLM rounds were context; everything below is measured by me. Surface: exactly two files — the design note (+315) and a README index row (+4). Docs-only as commissioned; the note declares and observes "amends no contract" (it sits in docs/plans and every normative statement is delegated to it by the contracts it cites). Every measured claim in §2 reproduces at this head: - origin/next == 94d626df, matching the note's measurement pin. - The agents table column list in packages/db/src/schema.ts matches the note exactly — including the two facts the design leans on: no harness column, no audit coupling; project_id FK to legacy projects with ON DELETE SET NULL; owner_id to users. - Sole production insert(agents) issuer is packages/brain/src/agents.ts (repo-wide grep; the only other hit is a test); its three write consumers are exactly the three named (agent-configs.controller.ts, command-executor.service.ts, project-bootstrap.service.ts). - ProviderCredentialsService and the harness registry exist at the cited paths. Every load-bearing contract citation verifies verbatim: - Contract 5 §3.1 rank-4 row matches the note's quote; §4's sub-clauses carry what the note attributes to them (closed per-family error enum with the listed classes, correlation id carried into audit and returned in the result, CLI parity as a tracked conformance gap, fail-closed with no fallback). - Contract 3 §3.5: "One harness, API-key login, agent name and persona (D11). Enrollment specifics belong to the rank-4 agent-enrollment command family" — the delegation the note's v1 assignment-scope pin rests on. The wizard's tenth witness ("a run that skips it completes with zero enrollment-family mutations") is cited accurately. - Contract 3 §4.3's shared replay policy is seed-only ("no other operation can carry a shared declaration"), which is why the note refuses a shared declaration on agent.enroll — consistent. - Custody-schema §5.2 binds the agent-grantee FK to the live agents table (agent_id uuid → agents(id)), exactly as claimed; the §4 schema delta preserves it by extending agents rather than adding an enrolled-agent table. - F1 verifies: /api/agents appears nowhere in tool-gateway-mapping.md (zero occurrences), and the note correctly dispositions the missing P0 row as a future contract amendment rather than adding it here. Design coherence, by reading: the §3.3 error enum is closed and consistent with the §3.1 field table (syntactic harness invalidity → validation_failed, registry miss → precondition_failed); the idempotency fence design is actor-bound-only with the digest excluding credential material, which serves the never-echo rule structurally, not just by promise; the §4 delta is additive-only with no backfill invention; all eleven §5 witnesses are concretely testable against the shipped machinery (sealed store, harness registry, hierarchy-pattern audit/outbox). Mechanical: Prettier 3.8.1 (repo pin) green on both files at this head. CI pipeline 3028 is the PR pipeline at exactly d18ce049 and was still running at review time — terminal green remains the merge gate's. Verdict: APPROVED at d18ce049593444f6e46be782cce01a7e7f7cf096. An amend or rebase voids this approval.

fred merged commit ee815a72b1 into next

2026-08-30 01:21:01 +00:00

fred referenced this pull request

2026-08-30 01:26:45 +00:00

db: agent enrollment schema (M4-4a, migration 0021) #1482

rev-code-02 referenced this pull request

2026-08-30 01:41:39 +00:00

db: agent enrollment schema (M4-4a, migration 0021) #1482

fred referenced this pull request

2026-08-30 02:12:37 +00:00

feat(gateway,cli): agent enrollment command family (M4-4b) #1483

Sign in to join this conversation.