docs(surface): describe createSurfaceApp's CLI-backed mutation boundary - #266
Merged
Merged
Conversation
The createSurfaceApp doc comment still claimed "No route mutates the queue in this slice", which stopped being true once the surface grew its operator mutation routes (approve, reject, defer, requeue, cancel, note, prioritize, re-verify, and the board actions) — all attributed `operator:web`. Restate the boundary the way accepted ADR-0060 and docs/design/operator-surface.md do: the surface is read-first, its mutation routes are exactly the operator commands the CLI already has invoked through the same store methods, and it introduces no new state transition, no worker-facing route, and no rendered lease token. Also attach the comment to createSurfaceApp itself rather than to the SurfaceEnv type alias that had drifted between them. Comment-only; no runtime behavior changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UigLsmd17TVDuaaSN4yfdU
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
createSurfaceApp's doc comment still said "No route mutates the queue in thisslice". That stopped being true once the operator surface grew its mutation
routes — approve, reject, defer, requeue, cancel, note, prioritize, re-verify,
and the board's import-issues / seed-dogfood / verify-artifacts / hold actions,
all attributed
operator:web— so the only architectural statement a readerfinds next to the surface's entry point contradicts the code beneath it.
This restates the boundary the way accepted
ADR-0060
("Same store, same commands … The surface introduces no new state transition,
no batch 'approve all', no worker tool, and never renders or transmits a lease
token") and
docs/design/operator-surface.md
("Exactly the operator commands the CLI has … There is no batch action and no
worker-facing endpoint") already do: the surface is read-first, its mutation
routes reuse the existing CLI-backed store transitions, and it introduces no
new transition.
The comment is also moved below the
SurfaceEnvtype alias that had driftedbetween it and
createSurfaceApp, so the JSDoc actually attaches to thefunction it describes.
Comment-only: 8 insertions, 5 deletions in one file, no statement changed.
Checks
npm run checkgreen — with one environment caveat:check:deploycannot run on this host (
check:deploy: shellcheck is required but not installed), so it was skipped; this diff touches nodeploy/file orshell script. Every other stage was run and passed:
check:audit—found 0 vulnerabilitiescheck:docs—Documentation valid: 115 docs, 76 ADRs, 389 requirements, 151 domain termstypecheck—tsc --noEmit, cleantest:coverage—all files | 53.37 | 74.25 | 47.27(392 tests, 0 fail)check:coverage-floors—Node 24 per-file floor(s) metcheck:coverage-denominator—all 73 src module(s) are in the coverage denominatorbuild—✓ built in 176ms;check-dist: 9 bundled schema file(s) shipped byte-identical;check-boot: dist/app.mjs imported, startFlueNodeServer listened on 127.0.0.1 … and stopped in 218 msmake verifygreen —ℹ tests 392 / ℹ pass 392 / ℹ fail 0plusDocumentation valid: 115 docs, 76 ADRs, 389 requirements, 151 domain terms. This is the gate the originating queue item names.node scripts/check-pr-title.mjs "$TITLE"printedPR title lint passedsrc/queue/**orsrc/mcp/**changed: not applicable — this PR touchesonly
src/surface/app.ts, so no work-queue spec rule is added orrenumbered.
Risk classification
Select the highest applicable tier from
docs/risk-tiers.md.
Rationale:
content alone), but
src/surface/app.tsis inside theauthenticationprotected boundary in
policies/agent-governance.json, whoseminimum_risk_tierishigh;highest_applicable_riskmeans the boundary'sfloor governs, so this is classified Tier 3.
Docs housekeeping
docs/design/*anddocs/specs/*updated alongside the code theydescribe — not applicable in the usual direction: the design doc and ADR
are already correct and are what the comment is being corrected to, so
no doc file changes.