Skip to content

docs: sync metrics and monitor-architecture specs with main - #39952

Merged
bolichen97 merged 3 commits into
mainfrom
docs/sweep-r1b-modules-b-2
Nov 20, 2026
Merged

bolichen97 merged 3 commits into
mainfrom
docs/sweep-r1b-modules-b-2

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: metrics.md and monitor-architecture.md state 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.
  • Any spec other than these two.

What changed (motivation → approach → change)

Follow-up to #39914, which merged before these two full reads finished. Both files were read from the first line to the last against the code on main.

  • metrics.md: retention caps default to 30 days / 100 MB (not 0); env_pin() order is DO_NOT_TRACK, KIROCREW_TELEMETRY, then the disabled hold; the notice counts an ack at or above the current version; the inventory gains kirocrew.session.runtime_reconcile, the voice STT/TTS signals, kirocrew.security.redaction.fail_closed, kirocrew.inventory.voice.provider, the handoff session-control op and six fold names; the inventory gauges export through PRODUCT_METRICS by default; host.*_peak are declared, never emitted; bucket table gains loop.lag_ms and turn.completed.duration; history prose rewritten.
  • monitor-architecture.md: section 5 names the two stored records (the irq watch file and MonitorState) and their real fields instead of a table no document matches; the default patrol interval is 300 s; all-accepted / all-closed are wake keys, not terminal keys; the tool-policy table cites mcp_shared_policy and agent_materialization/worker_agent.

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.

…obe keys to code

Section 5 names the irq watch file and MonitorState fields as stored; patrol interval is 300 s; all-accepted/all-closed are wake keys; current module paths for the tool-policy table.
Retention caps default on, consent pin order, missing signals and gauges in the inventory, product-metrics export, bucket table, history prose.
@bolichen97
bolichen97 enabled auto-merge (squash) November 20, 2026 11:48
@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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 5698549795db152cb11bf2cf78fd8792816e7e66 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Docs-only sync of two specs to the code on main. Every item corrects prose to match existing behaviour. None changes a default, a key or any code.

Not checked: the 11 code and RFC files in the supplied patch match 18f143d2..HEAD absence (base drift from main, not this PR's change).

What this change ships

Inventory (8 items) — 8 justified

Intent: contributors reading metrics.md and monitor-architecture.md get what the code does today. This is a FIX (to docs).

  1. Retention caps are documented as 30 days / 100 MB by default, not opt-in 0 — justified
  2. The env_pin() order now names DO_NOT_TRACK, KIROCREW_TELEMETRY, then the disabled hold — justified
  3. The metric inventory adds the runtime_reconcile, voice STT/TTS, redaction fail-closed and voice-provider gauge signals, plus the handoff op — justified
  4. The inventory gauges are described as exported through PRODUCT_METRICS, and the old "operator-only" claim is dropped — justified
  5. host.*_peak is marked as declared but never emitted. The bucket table adds loop.lag_ms and turn.completed.duration — justified
  6. History narration ("shipped", "used to") is rewritten as present-tense rationale — justified
  7. Monitor section 5 names the two real state records and their fields — justified
  8. The default patrol interval is 300 s. all-accepted/all-closed are documented as wake keys, and the tool-policy table paths are corrected — justified

[FIRST-PRINCIPLES-REVIEWED] 5698549

Description read

[DESCRIPTION-READ] db36798cd954ca6fe73602b979594eafc16af5f811e22534ab11c41f1d062fa6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 5698549795db152cb11bf2cf78fd8792816e7e66 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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the diff touches only two spec files, renders nothing and removes no code, key or path.

[DESIGN-REVIEWED] 5698549

Description read

[DESCRIPTION-READ] a51105e5ee691607b0bf7278fc7586fb8350faf4fd1904313659515c0e9924c2

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 5698549795db152cb11bf2cf78fd8792816e7e66 — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • docs/system-specs/modules/metrics.md:21-24 — the claim that it "decides the effective state regardless of the config flag" is only true of DO_NOT_TRACK and KIROCREW_TELEMETRY. A telemetry.enabled value written to config overrides KIROCREW_TELEMETRY_DISABLED (consent_pins.py:64-78). Consider saying so.

[OPUS-REVIEWED] 5698549

Verdict parsed from the review's SHA-scoped output markers for commit 5698549795db152cb11bf2cf78fd8792816e7e66.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5698549795db152cb11bf2cf78fd8792816e7e66 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 5698549795db152cb11bf2cf78fd8792816e7e66 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5698549

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

@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

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 5% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: design-doc-gate: A.

The PR changes only metrics.md and monitor-architecture.md, and every claim I spot-checked matches the code at head. Retention defaults are 30 days / 100 MB (sections_telemetry.py), env_pin() checks DO_NOT_TRACK, then KIROCREW_TELEMETRY, then the KIROCREW_TELEMETRY_DISABLED hold, and the notice counts an ack at or above the current version. handoff is in the op list, there are 25 _counted routes and the six unlisted ones count as other, so the 640-series ceiling holds. The fold catalogue matches FOLD_NAMES, and the voice, redaction, runtime_reconcile and inventory.voice.provider instruments exist, with the inventory and voice gauges in PRODUCT_METRICS. In the monitor spec, PATROL_INTERVAL_SECS is 300, _TERMINAL_SUCCESS_KEYS holds only merged, decision.py imports metrics.monitor_loops, and the irq watch-file path, digest and mode match the code, as do the MonitorState fields and the quarantine and unsupported-version handling. No behaviour, key or trust boundary changes; the text about egress and recording-on-by-default now matches the code.

Tier: 2, held for a person: design-doc-gate: A.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 5698549795 · 277 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@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 5698549. The diff changes only the metrics and monitor architecture specs; no code, test or configuration is touched. I compared the changed claims with the source at this head: the patrol interval, which keys count as terminal versus wake, how a privacy notice acknowledgement is compared, and the order in which consent env pins are resolved. Each one matches. One optional wording point: the paragraph on consent resolution could say that the legacy disabled variable gives way to a written telemetry.enabled value, although the module table already says so. Nothing here blocks merge.

@bolichen97
bolichen97 merged commit d9a8652 into main Nov 20, 2026
100 checks passed
@bolichen97
bolichen97 deleted the docs/sweep-r1b-modules-b-2 branch November 20, 2026 13:18
@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