Skip to content

docs: sync module specs (list B) with main - #39914

Merged
KiroCrewCaptain merged 28 commits into
mainfrom
docs/sweep-r1b-modules-b
Nov 20, 2026
Merged

KiroCrewCaptain merged 28 commits into
mainfrom
docs/sweep-r1b-modules-b

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Every module spec in list B of the round-1b sweep (49 files under docs/system-specs/modules/) states what the code on main does today.

Many of these specs name merged PRs and closed issues as provenance, carry history prose ("used to", "this PR", "the fix"), and in places describe behaviour, middleware order or opt-outs that the code no longer matches.

Why it matters

These specs are what agents and contributors read before they change the code. A wrong layer order, a stale opt-out list or a closed issue named as an open gap sends a reader to the wrong place or makes them re-solve a solved problem.

Not a goal

  • No file deletes or renames; candidates go to the sweep's candidates list.
  • No change to modules/README.md, the list-A specs, docs/decisions/, or code.
  • examples/workflows/01_review_changes.py is left to docs: sync module specs (list A) with main #39898, which carries the same change to all four example files.

What changed (motivation → approach → change)

Approach: per file, mechanical checks (backticked identifiers against the code tree, module.attr against the module, cited test names against the test files, config defaults against config-baseline.json, every #NNN reference classified by GitHub type and state), then a read of the prose against the code it describes. Merged PRs and closed issues named as provenance are dropped; an open issue that tracks a real gap stays; a closed issue named as an open gap is checked in code and the sentence states the current behaviour.

Files changed, by area (one line on what was wrong):

Every file below also loses merged-PR / closed-issue provenance tags and history prose ("used to", "this PR", "the fix", "as before this change"); open issues that track a real gap stay.

Security and governance

CLI, sessions and Crew

  • cli.md: POST /api/update only arms an update; its error codes are not_git_checkout, arm_check_failed, update_check_pending, no_update (dirty_tree / checkout_diverged are gone); no caller builds the frontend on update.
  • session.md: opener inject kinds, steer states with retracted, deliver_note in chat_api/slot_note.py, build_dm_session_key(..., chat_type), crew_filing._frame_parents; closed tracking issues restated as open gaps checked in code.
  • session-control.md: every session-control route sits behind _require_internal.
  • crew-mode.md: no local_persistence: pending field exists; a failed history write answers 503 history_unavailable.
  • agent-host-contract.md: a server is withheld with a logged warning (acp/client_mcp_array.py), not a narrowed_control_plane token.
  • metrics.md: telemetry config table lists all 16 fields (adds the traces, beacon and plan_alert_pcts keys); _persist_abnormal_turn_usage lives in chat_turn/turn_stats.py.
  • monitor-architecture.md: names the work-ledger probe's host wakes (posture change, same-level fall, worker growth); wake board history rewritten.

Messaging and channels

  • messaging.md: get_signing_key_from_jwt; recipient helpers live in chat_turn/recipient; ReceiptQueue still keys on session_key (stated as a known gap).
  • channel-history.md: per-message 300-character cap.

Dashboard, auth and connections

  • dashboard-token-auth.md: middleware chain adds app_web_origin, relay_origin, redaction_audience, team_config and _change_card_hook.
  • connections.md: l0_probe and l1_smoke honour the proxy http_proxy.resolve_proxy picks.
  • onboarding-import.md: first run has two chapters (Import setup, Customize tour); no Privacy chapter.
  • prompt-optimizer.md: the relay Crew chat window and the Bot composer also turn the optimizer off.
  • kas-auth.md, command-bar.md, computer-use.md, cloud.md, aws-control.md: provenance and history only; closed tracking issues checked in code (no Fargate sweep caller, no producer-held archive body).
  • adaptive-concurrency.md, connector-capability-manifest.md, harness-plugin-mapping.md, mcp-apps.md, mcp-gateway-daemon-lifecycle.md, stt-streaming.md: history prose only.

Checked and left unchanged (mechanical checks, and a full read where noted in the sweep report): the remaining list-B specs.

Backwards compatibility

Compatible: docs only.

Removes nothing: only doc prose changes; no code, key or path is removed.

Tests

Proof: not provable -- docs or config only

./scripts/docs-lint.sh exits 0 on the head.

Manual verification

N/A — docs only; each changed claim was checked against the cited source on main.

Real-machine verification

N/A -- docs only, the diff runs nothing.

Related Issues

Round-1b docs sweep, module specs list B.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6e35a00fd92e4ed457e0d764c005c39cd3852124 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 6e35a00fd92e4ed457e0d764c005c39cd3852124 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 6e35a00fd92e4ed457e0d764c005c39cd3852124 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs-only sync of the module specs to the code on main. It removes nothing and adds no UI, so no design-level check applies.

Notes

  • I spot-checked the claims in this PR against the code: the update error codes are in updates_apply.py, and the gate tiers spec-builtin-grant, batch-guard-grant and app-own-tools are in hooks.py:1568-1572. Both match.
  • ## Backwards compatibility has both a Compatible: line and a Removes nothing: line. The template expects one of the two, so drop the redundant one.

[DESIGN-REVIEWED] 6e35a00

Description read

[DESCRIPTION-READ] d02e163e775a64efc720d39e5d85c32321d4924e8c96103e960b0f2c7e181565

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 6e35a00fd92e4ed457e0d764c005c39cd3852124 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6e35a00

Verdict parsed from the review's SHA-scoped output markers for commit 6e35a00fd92e4ed457e0d764c005c39cd3852124.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6e35a00fd92e4ed457e0d764c005c39cd3852124 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 6e35a00fd92e4ed457e0d764c005c39cd3852124 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6e35a00

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6e35a00fd92e4ed457e0d764c005c39cd3852124 false-positive: <reason, 20 to 500 characters>

Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
…st spec with main

Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
… spec with main

Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
Drop PR/issue provenance and history prose, fix names and claims that drifted from code.
@bolichen97
bolichen97 force-pushed the docs/sweep-r1b-modules-b branch from 1eb3b95 to 6e35a00 Compare November 20, 2026 10:04
@bolichen97
bolichen97 marked this pull request as ready for review November 20, 2026 10:06
@bolichen97
bolichen97 enabled auto-merge (squash) November 20, 2026 10:06
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 20, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed head 6e35a00, which only changes prose in module specs. I checked the claims it adds or rewrites against the code at the same commit: the sandbox tightening recycle path, the IMDS expansion helper, the moved chat_turn segment and recipient helpers, the write-tier leaves, the shell wrapper rows, the grant-row order in the gate tiers, the dashboard middleware chain order, the update error codes and the SEL forward warning. All of them match the code, and the identifiers it removes no longer exist in the source tree. The docs lint passes on this head, and with no code, test or config change there is no behavioural risk that blocks merging.

@KiroCrewCaptain
KiroCrewCaptain merged commit 5a072e3 into main Nov 20, 2026
103 of 112 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the docs/sweep-r1b-modules-b branch November 20, 2026 11:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 20, 2026
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.

2 participants