Skip to content

docs(surface): describe createSurfaceApp's CLI-backed mutation boundary - #266

Merged
bketelsen merged 1 commit into
mainfrom
docs/surface-app-jsdoc-mutation-boundary
Aug 28, 2026
Merged

docs(surface): describe createSurfaceApp's CLI-backed mutation boundary#266
bketelsen merged 1 commit into
mainfrom
docs/surface-app-jsdoc-mutation-boundary

Conversation

@bketelsen

Copy link
Copy Markdown
Collaborator

Summary

createSurfaceApp's doc comment still said "No route mutates the queue in this
slice". 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 reader
finds 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 SurfaceEnv type alias that had drifted
between it and createSurfaceApp, so the JSDoc actually attaches to the
function it describes.

Comment-only: 8 insertions, 5 deletions in one file, no statement changed.

Checks

  • npm run check green — with one environment caveat: check:deploy
    cannot run on this host (check:deploy: shellcheck is required but not installed), so it was skipped; this diff touches no deploy/ file or
    shell script. Every other stage was run and passed:
    • check:auditfound 0 vulnerabilities
    • check:docsDocumentation valid: 115 docs, 76 ADRs, 389 requirements, 151 domain terms
    • typechecktsc --noEmit, clean
    • test:coverageall files | 53.37 | 74.25 | 47.27 (392 tests, 0 fail)
    • check:coverage-floorsNode 24 per-file floor(s) met
    • check:coverage-denominatorall 73 src module(s) are in the coverage denominator
    • build✓ 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 ms
  • make verify green — ℹ tests 392 / ℹ pass 392 / ℹ fail 0 plus
    Documentation valid: 115 docs, 76 ADRs, 389 requirements, 151 domain terms. This is the gate the originating queue item names.
  • This PR's title matches Conventional Commits —
    node scripts/check-pr-title.mjs "$TITLE" printed
    PR title lint passed
  • src/queue/** or src/mcp/** changed: not applicable — this PR touches
    only src/surface/app.ts, so no work-queue spec rule is added or
    renumbered.

Risk classification

Select the highest applicable tier from
docs/risk-tiers.md.

  • Tier 1: Low
  • Tier 2: Moderate
  • Tier 3: High
  • Tier 4: Critical

Rationale:

  • The change itself is comment-only and alters no runtime behavior (Tier 1 on
    content alone), but src/surface/app.ts is inside the authentication
    protected boundary in policies/agent-governance.json, whose
    minimum_risk_tier is high; highest_applicable_risk means the boundary's
    floor governs, so this is classified Tier 3.

Docs housekeeping

  • docs/design/* and docs/specs/* updated alongside the code they
    describe — 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.
  • Conformance aliases (ADR-0002) untouched — no instruction surface edited.

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
@bketelsen
bketelsen marked this pull request as ready for review August 28, 2026 10:21
@bketelsen
bketelsen added this pull request to the merge queue Aug 28, 2026
Merged via the queue into main with commit 23ca3f0 Aug 28, 2026
2 checks passed
@bketelsen
bketelsen deleted the docs/surface-app-jsdoc-mutation-boundary branch August 28, 2026 10:24
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