docs(VSY-167): merge 9 architecture files into the 8 kept topics

[Brad (bmethod)]

Closes VSY-167

Lane status

Branch: vsy-167. Head 144a8c0.

• Required CI: green on this head (CI, Bun (lint, types, tests, build), Arch package warden status, Bot instructions, CodeQL).
• Copilot: one finding, fixed at this head. The capability sentence in layers.md now names the capabilities re-read every sample. The thread is answered and resolved.
• Second opinion: passed at this head with no findings.
• Rule map: the master approved the ## AGENTS.md rule map below (note 1791309456).

ready: VSY-167 head 144a8c0

Design note

• What changes: each of the 9 source files merges into its destination by subject, not pasted under it, and the source is deleted.
  • agent-tools.md → lanes.md: the agent-tool rules join the rules list, and the name-plus-install-location idea joins the approach.
  • events.md → history.md: EventLog joins the approach, and the hold and alert rules join the store rules.
  • reporters.md → storage-integrity.md: the privilege boundary is stated in the approach and the why ("The dashboard reads what a privileged reporter wrote and is never privileged itself"), with a matching never-rule.
  • warden-install.md → warden.md.
  • builds.md, collection-threads.md, scratch.md, settings.md and unknown-readings.md → layers.md. Each kept rule is written at principle level: one predicate per count, a duty cycle for background work, one worker lifecycle, unknown stays null, and only collection settings rebuild the collector.
• What is dropped: sentences the code already shows (eligibility measured from completion, a failed scan keeping its last reading, row origin, the per-file canonical examples) and duplicates (the stored-field migration rule already in history.md, the skipped-scratch null level already in verdict.md).
• The scratch bound: the measurement behind it ("an unrested traversal of a populated scratch tree holds more than a processor core") moves to the restMs() comment in src/collect/scratch-scan.ts, the code that enforces the bound. The doc keeps only the rule and the bench:scratch instrument.
• Referrers: DEVELOPMENT.md, ui.md, verdict.md, src/collect/scrub.ts, scripts/scrub-reporter/vsys-scrub-report and AGENTS.md § Read when. All 10 decision records are kept.
• Why this route: it is the smallest change that leaves one owner per subject. No new file, no other AGENTS.md change, and the only code change is a comment.

Known limits

• A literal search for events.md outside .agents/ still matches oversee-events.md and overseer-session-events.md in kendex-rendered files (.claude/, .codex/, .github/, .pi/ hooks and .kendex-generated.json). Those name orch skill references, not this repo's architecture doc, and those paths are out of scope. None of the other 8 removed filenames matches anything outside .agents/.
• The commit header carries [no-changelog]. The commit-msg lane asked for a fragment because of the comment line in vsys-scrub-report, but changelog.d/ is out of scope and no consumer sees a comment change.

Validation

• The commit-guards md-format and md-refs lanes report 0 violations at 144a8c0. The full pre-commit chain is clean.
• I ran python3 scripts/ci.py as root at e22b151; the later commit changes only one sentence of markdown. The script stops at the first failing stage, so I then ran every later stage by hand:
  • The warden suites, package_file_list_check.py, lint, typecheck, build, smoke, bench:scratch and bench:writes pass.
  • Four permission-denial tests fail. Each fails the same way on the untouched base tree (git stash), because root ignores the directory modes they depend on:
    • scripts/scrub_reporter_test.py: test_a_migration_mkdir_failure_is_reported_as_a_carry_over_problem_not_an_install_failure
    • warden/agent_confine_test.py: test_agent_confine_scratch_mkdir_failure_keeps_inherited_tmpdir, in 2 subtests
    • warden/agent_warden_scratch_test.py: test_reap_scratch_dirs_read_only_directory_rows
    • bun test src/: "only a root on a list other than the shipped one fails for not existing"
• The pull request CI, which runs the whole contract as a non-root user, is green at 144a8c0.
• shellcheck and gitleaks are not installed here, so preflight and the secrets lane skipped those checks and said so.
• No new test, so no must-fail control: this is a docs merge plus one comment.

AGENTS.md rule map

Old Read-when line	New line	Reason
Before moving work between src/collect/, src/model/, src/store/ and src/ui/, or adding a read the collector makes: layers.md	Before moving work between src/collect/, src/model/, src/store/ and src/ui/, or adding a read the collector makes, a reading, a counter, a capability probe, a stored field or a screen that shows a number: layers.md	Merged with the next line: both now name layers.md, and adding a reading is the same task as adding a read the collector makes.
Before adding a reading, a counter, a capability probe, a stored field or a screen that shows a number: unknown-readings.md	(merged into the line above)	unknown-readings.md merged into layers.md.
Before changing which processes count as agent tools, the shared agent-tool data, or how the dashboard and the warden read it: agent-tools.md	Same trigger: lanes.md	agent-tools.md merged into lanes.md. It is a different task from finding or naming a lane, so the line stays separate.
Before changing how compile and link work, the build cache or the make token pools are counted: builds.md	Same trigger: layers.md	builds.md merged into layers.md. It is a distinct task, so the line stays separate.
Before changing how processes or scratch directories are read, adding a worker thread, or changing how a build ships one: collection-threads.md	Before changing how processes or scratch directories are read, which directories Storage measures as scratch, how often, or how much processor time the traversal may hold, adding a worker thread, or changing how a build ships one: layers.md	Merged with the scratch line: both now name layers.md, and both cover how scratch directories are read.
Before changing which directories Storage measures as scratch, how often, or how much processor time the traversal may hold: scratch.md	(merged into the line above)	scratch.md merged into layers.md.
Before changing what the timeline records, when an alert opens or closes, or what a stored event holds: events.md	Same trigger: history.md	events.md merged into history.md. Events are a different task from replay and retention, so the line stays separate.
Before changing the scrub reporter, the drive reporter, the check report format, their installers, or the udisks2 fallback: reporters.md	Same trigger: storage-integrity.md	reporters.md merged into storage-integrity.md. Reporters are a different task from integrity states, so the line stays separate.
Before adding a setting, changing what a settings save writes, or changing what a settings change rebuilds: settings.md	Same trigger: layers.md	settings.md merged into layers.md. It is a distinct task, so the line stays separate.
Before changing vsys warden install, warden/install, the unit templates, or what a package ships beside the binary: warden-install.md	Same trigger: warden.md	warden-install.md merged into warden.md. Installation is a different task from what the warden moves, so the line stays separate.

No other AGENTS.md line changes. § Read when goes from 18 lines to 16.

🤖 Generated with Claude Code

https://claude.ai/code/session_013qZ4P3H2Z1o3dncyAcTb7f

[linear-code]

VSY-167

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[Brad (bmethod)]

Waiting on the master: the ## AGENTS.md rule map in the PR body needs the master's answer before this lane writes its ready: line. The work is pushed at e22b151, and the only failures are four permission tests that also fail on the base when run as root (listed under Validation).

---

Generated by Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

layers.md incorrectly describes dynamic capabilities as startup-only probes.

Review effort: Balanced
Findings: 1

Open (1)

• Refresh dynamic capability checks on every sample · New

What changed in this PR

Consolidates nine architecture documents into the eight retained topic documents and updates their references.

Changes:

• Merges related architecture principles into their canonical topics.
• Removes the superseded documents and redirects references.
• Moves the scratch traversal rationale beside restMs().

File	Description
AGENTS.md	Redirects architecture reading guidance.
DEVELOPMENT.md	Redirects worker guidance.
docs/​architecture/​agent-tools.md	Removes superseded agent-tool document.
docs/​architecture/​builds.md	Removes superseded build document.
docs/​architecture/​collection-threads.md	Removes superseded worker document.
docs/​architecture/​events.md	Removes superseded event document.
docs/​architecture/​history.md	Incorporates event principles.
docs/​architecture/​lanes.md	Incorporates agent-tool principles.
docs/​architecture/​layers.md	Incorporates collection, settings, build, scratch, and unknown-reading principles.
docs/​architecture/​reporters.md	Removes superseded reporter document.
docs/​architecture/​scratch.md	Removes superseded scratch document.
docs/​architecture/​settings.md	Removes superseded settings document.
docs/​architecture/​storage-integrity.md	Incorporates reporter principles.
docs/​architecture/​ui.md	Redirects unknown-reading guidance.
docs/​architecture/​unknown-readings.md	Removes superseded unknown-reading document.
docs/​architecture/​verdict.md	Redirects event guidance.
docs/​architecture/​warden-install.md	Removes superseded installer document.
docs/​architecture/​warden.md	Incorporates installer principles.
scripts/​scrub-reporter/​vsys-scrub-report	Redirects the report-format reference.
src/​collect/​scratch-scan.ts	Adds traversal-cost rationale.
src/​collect/​scrub.ts	Redirects the report-format reference.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vanillagreen-overseer]

Overseer approval at 144a8c0 under the docs program terms (no review rounds, overseer app approval, required CI only). Copilot's one finding was fixed at this head; check-review-replies passes. Second opinion (1codex gpt-6.1-sol medium, read-only) passed at this head. The master approved the AGENTS.md rule map (note 1791309456). Required CI is green.

[Copilot]

Copilot review overview

🔵 Needs a closer look

layers.md incorrectly claims every kernel-blocking read uses a worker thread while several collector reads remain synchronous.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Refresh dynamic capability checks on every sample

Previously missed (1)

In code that hasn't changed since last review

Narrow worker isolation claim to covered blocking reads

docs/​architecture/​layers.md:11

Blocking: this overstates worker isolation. Only process reads and scratch traversal use WorkerHost; Collector.sample() still runs mount, system, cgroup, and device reads synchronously (src/collect/collector.ts:218-240,286), through Reader's synchronous filesystem calls (src/collect/io.ts:20-46). As written, the canonical architecture falsely promises that any kernel-blocking read cannot stall the dashboard; narrow the claim to the two reads covered by D007/D008.