gabogg/hikcentral
Watch
1
0
Fork
You've already forked hikcentral
 0
Code Issues 113 Pull requests 8 Projects Releases Packages Wiki Activity Actions

docs: align calibration glossary and record triage decisions #63

Merged
gabogg merged 2 commits from docs/triage-guardrails-and-validation into master 2026-09-23 18:02:37 +00:00
Conversation 2 Commits 2 Files changed 4 +156 -5
gabogg commented 2026-09-23 16:29:51 +00:00
Owner
Copy link

Summary

The glossary incorrectly used the cycle-ratio trust bounds as the operational exit-multiplier guardrail, and ADR 0002 still described the delivered Tailwind compilation path as deferred. Align the glossary with the canonical [0.90, 1.35] operational guardrail and distinguish the [0.80, 1.30] trust bounds, define door state transitions and sustained calibration clamping, and clarify runtime asset independence versus development tooling.

Archive the maintainer-approved triage decisions for #50 and #55–#60 under docs/audit/ and link them from the documentation index. The record includes the three-cycle clamp escalation policy, live transition delivery scope, explicit checksum-verified Tailwind setup, trust-rule compatibility, evidence required to reopen #56, and human Windows validation before merging PATH changes. #58 remains blocked on PR #54.

Architectural impact

Documentation only. The archive defines acceptance criteria for follow-up implementation; it does not implement new diagnostics, telemetry, build provisioning or Windows behavior. ADR 0002 records the standalone compiler as delivered while marking reproducible provisioning as pending in #57.

Verification

  • pytest -q -o faulthandler_timeout=30: 214 passed in 70.65s outside the sandbox; earlier sandbox attempts stalled on the first analytics test.
  • git diff --check: passed.
  • Ruff 0.16.6 (the repository-pinned version), ruff check .: passed.
  • Installed pre-commit hooks passed during commit, including whitespace, file-format checks and pytest.

Checklist

  • Maintainer confirmed all triage decisions and publication.
  • Canonical glossary and ADR clarification updated.
  • Durable decision record added to the documentation index.
  • Application test suite passed.
  • All seven approved Forgejo issue amendments and dispositions published and verified.
## Summary The glossary incorrectly used the cycle-ratio trust bounds as the operational exit-multiplier guardrail, and ADR 0002 still described the delivered Tailwind compilation path as deferred. Align the glossary with the canonical [0.90, 1.35] operational guardrail and distinguish the [0.80, 1.30] trust bounds, define door state transitions and sustained calibration clamping, and clarify runtime asset independence versus development tooling. Archive the maintainer-approved triage decisions for #50 and #55–#60 under `docs/audit/` and link them from the documentation index. The record includes the three-cycle clamp escalation policy, live transition delivery scope, explicit checksum-verified Tailwind setup, trust-rule compatibility, evidence required to reopen #56, and human Windows validation before merging PATH changes. #58 remains blocked on PR #54. ## Architectural impact Documentation only. The archive defines acceptance criteria for follow-up implementation; it does not implement new diagnostics, telemetry, build provisioning or Windows behavior. ADR 0002 records the standalone compiler as delivered while marking reproducible provisioning as pending in #57. ## Verification - `pytest -q -o faulthandler_timeout=30`: 214 passed in 70.65s outside the sandbox; earlier sandbox attempts stalled on the first analytics test. - `git diff --check`: passed. - Ruff 0.16.6 (the repository-pinned version), `ruff check .`: passed. - Installed pre-commit hooks passed during commit, including whitespace, file-format checks and pytest. ## Checklist - [x] Maintainer confirmed all triage decisions and publication. - [x] Canonical glossary and ADR clarification updated. - [x] Durable decision record added to the documentation index. - [x] Application test suite passed. - [x] All seven approved Forgejo issue amendments and dispositions published and verified.
docs: align calibration glossary and record triage decisions
All checks were successful
CI / lint-and-test (pull_request) Successful in 1m21s
Details
711a0b1740
docs: address PR #63 review — policy-free glossary, current #58 dependency
All checks were successful
CI / lint-and-test (pull_request) Successful in 1m9s
Details
0bfba7a902 
- CONTEXT.md: Calibration Clamp Hit and Sustained Calibration Clamping are
  now definitions only; the escalation threshold and streak rules live in
  the #50 triage record. Add _Avoid_ lines to the three new terms, and let
  the Exit Multiplier bullet reference the Operational Calibration
  Guardrail instead of restating [0.90, 1.35].
- Triage record: #58 now waits on PR #54's narrowed scope (same join and
  filter for get_hourly_flow_distribution_async); the camera-group
  exclusion test waits on #62, where the join cutover moved. Add the #50
  and #55 test criteria the record omitted, and restore "pre-clamp EWMA
  value".
- ADR 0002: replace the date-stamped provisioning status with a pointer
  to #57.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gabogg commented 2026-09-23 18:01:23 +00:00
Author
Owner
Copy link

Code review — pre-merge

Reviewed 711a0b1 against master (including #53's merge 1ed0f45) with two independent passes: Standards (domain-modeling CONTEXT-FORMAT.md / ADR-FORMAT.md, docs/agents/domain.md, AGENTS.md §4, a code-smell baseline, and fact-checks against the code) and Spec (this PR's description and issues #50, #55–#60 with their comments).

Pre-flight: CI green on 711a0b1; git merge-tree merges cleanly into master after #53.

Question asked: merge now, or hold for / fold into the related issues? → Merge after small fixes. The glossary correction fixes a real error with no owning issue (master conflated the guardrail with the trust bounds). The triage record matches the issues except for one dependency #54's rescope has made stale. The ADR edit delivers one of #57's own criteria.

Standards

The new terms sit before "Transit Bleed" and #53's after it: no duplicates, no contradictions. Facts check out against the code: guardrail [0.90, 1.35] (occupancy_service.py:855,1043), trust bounds [0.80, 1.30] (:959-960), door state transitions (database.py:349).

  • P2, rule breach (CONTEXT-FORMAT: "define what it IS, not what it does"; implementation-free): CONTEXT.md:123-133. The two clamping entries carry escalation policy (streak thresholds and reset rules, "warrant investigation"). That policy belongs in #50.
  • P3: _Avoid_ lines missing on Cycle Ratio Trust Bounds, Clamp Hit and Sustained Clamping; the trust-bounds entry repeats the guardrail's _Avoid_.
  • P3, possible Duplicated Code: [0.90, 1.35] written out at CONTEXT.md:103 and :115.
  • P3, possible Duplicated Code: the audit record restates the clamp rules almost word for word from CONTEXT.md, so the two can drift.
  • P3, possible Divergent Change: ADR 0002 line 44 mixes delivery status, #57 criteria and a status dated 2026-09-23 into the decision record.

Spec

  • P2, pre-empts #57: the ADR 0002 edit delivers #57's criterion "ADR 0002 records the standalone compiler as delivered…", while #57's resolution says to "integrate it with the implementation rather than duplicating it". The content is accurate; only its placement conflicts.
  • P2, stale: the record says #58 is "blocked on the camera-group join cutover in PR #54" (:16, :90) and asks for a camera-group exclusion test (:98). After #54's rescope, #54 only aligns get_hourly_flow_distribution_async's join and filter, and the cutover moved to #62. #58's own resolution has the same stale wording.
  • P3: the #50 section omits its deterministic-tests criterion and shortens "pre-clamp EWMA value"; the #55 section omits the failed-persistence and offline/commanded/excluded-door test cases.
  • P3: the clamp glossary entries hard-code #50's "three cycles" threshold, so the policy would live in two places.

Standards: 5 findings, worst P2 (policy inside definitions). Spec: 4 findings, worst P2 (the ADR edit pre-empts #57; the #58 dependency is stale).

## Code review — pre-merge Reviewed `711a0b1` against `master` (including #53's merge `1ed0f45`) with two independent passes: **Standards** (domain-modeling `CONTEXT-FORMAT.md` / `ADR-FORMAT.md`, `docs/agents/domain.md`, `AGENTS.md` §4, a code-smell baseline, and fact-checks against the code) and **Spec** (this PR's description and issues #50, #55–#60 with their comments). **Pre-flight:** CI green on `711a0b1`; `git merge-tree` merges cleanly into `master` after #53. **Question asked: merge now, or hold for / fold into the related issues?** → **Merge after small fixes.** The glossary correction fixes a real error with no owning issue (`master` conflated the guardrail with the trust bounds). The triage record matches the issues except for one dependency #54's rescope has made stale. The ADR edit delivers one of #57's own criteria. ## Standards The new terms sit before "Transit Bleed" and #53's after it: no duplicates, no contradictions. Facts check out against the code: guardrail `[0.90, 1.35]` (`occupancy_service.py:855,1043`), trust bounds `[0.80, 1.30]` (`:959-960`), door state transitions (`database.py:349`). - **P2, rule breach (CONTEXT-FORMAT: "define what it IS, not what it does"; implementation-free):** `CONTEXT.md:123-133`. The two clamping entries carry escalation policy (streak thresholds and reset rules, "warrant investigation"). That policy belongs in #50. - **P3:** `_Avoid_` lines missing on Cycle Ratio Trust Bounds, Clamp Hit and Sustained Clamping; the trust-bounds entry repeats the guardrail's `_Avoid_`. - **P3, possible Duplicated Code:** `[0.90, 1.35]` written out at `CONTEXT.md:103` and `:115`. - **P3, possible Duplicated Code:** the audit record restates the clamp rules almost word for word from `CONTEXT.md`, so the two can drift. - **P3, possible Divergent Change:** ADR 0002 line 44 mixes delivery status, #57 criteria and a status dated 2026-09-23 into the decision record. ## Spec - **P2, pre-empts #57:** the ADR 0002 edit delivers #57's criterion "ADR 0002 records the standalone compiler as delivered…", while #57's resolution says to "integrate it with the implementation rather than duplicating it". The content is accurate; only its placement conflicts. - **P2, stale:** the record says #58 is "blocked on the camera-group join cutover in PR #54" (`:16`, `:90`) and asks for a camera-group exclusion test (`:98`). After #54's rescope, #54 only aligns `get_hourly_flow_distribution_async`'s join and filter, and the cutover moved to #62. #58's own resolution has the same stale wording. - **P3:** the #50 section omits its deterministic-tests criterion and shortens "pre-clamp EWMA value"; the #55 section omits the failed-persistence and offline/commanded/excluded-door test cases. - **P3:** the clamp glossary entries hard-code #50's "three cycles" threshold, so the policy would live in two places. --- **Standards: 5 findings, worst P2** (policy inside definitions). **Spec: 4 findings, worst P2** (the ADR edit pre-empts #57; the #58 dependency is stale).
gabogg commented 2026-09-23 18:01:26 +00:00
Author
Owner
Copy link

Review addressed — 0bfba7a

  • Glossary (Standards P2, P3s; Spec P3): Calibration Clamp Hit and Sustained Calibration Clamping are now definitions only. The threshold and streak rules live in one place, the #50 section of the triage record. All three new terms have _Avoid_ lines, and the Exit Multiplier bullet references the Operational Calibration Guardrail instead of restating [0.90, 1.35].
  • #58 dependency (Spec P2): the record now says #58 waits on PR #54 (same join and filter for get_hourly_flow_distribution_async), and the camera-group exclusion test waits on #62. #58's body was amended to match, with a comment explaining the change.
  • ADR 0002 vs #57 (Spec P2): kept in this PR. The text is accurate and already written. #57's two ADR checkboxes are ticked, with a comment saying the ADR criterion was met here, so it isn't done twice. The date-stamped provisioning status in the ADR is replaced by a pointer to #57 (Standards P3).
  • Triage record (Spec P3s): added the #50 deterministic-tests criterion, restored "pre-clamp EWMA value", and added the #55 test cases (offline, commanded and excluded-door transitions, failed persistence, duplicate-emission prevention, reconnect snapshots).

Verification: tests/test_docs.py 7/7, git diff --check clean, pre-commit hooks passed (including pytest).

## Review addressed — `0bfba7a` - **Glossary (Standards P2, P3s; Spec P3):** Calibration Clamp Hit and Sustained Calibration Clamping are now definitions only. The threshold and streak rules live in one place, the #50 section of the triage record. All three new terms have `_Avoid_` lines, and the Exit Multiplier bullet references the Operational Calibration Guardrail instead of restating `[0.90, 1.35]`. - **#58 dependency (Spec P2):** the record now says #58 waits on PR #54 (same join and filter for `get_hourly_flow_distribution_async`), and the camera-group exclusion test waits on #62. **#58's body was amended to match**, with a comment explaining the change. - **ADR 0002 vs #57 (Spec P2):** kept in this PR. The text is accurate and already written. **#57's two ADR checkboxes are ticked**, with a comment saying the ADR criterion was met here, so it isn't done twice. The date-stamped provisioning status in the ADR is replaced by a pointer to #57 (Standards P3). - **Triage record (Spec P3s):** added the #50 deterministic-tests criterion, restored "pre-clamp EWMA value", and added the #55 test cases (offline, commanded and excluded-door transitions, failed persistence, duplicate-emission prevention, reconnect snapshots). **Verification:** `tests/test_docs.py` 7/7, `git diff --check` clean, pre-commit hooks passed (including pytest).
gabogg changed title from WIP: docs: align calibration glossary and record triage decisions to docs: align calibration glossary and record triage decisions 2026-09-23 18:01:28 +00:00
gabogg merged commit 4115881eed into master 2026-09-23 18:02:37 +00:00
gabogg deleted branch docs/triage-guardrails-and-validation 2026-09-23 18:02:37 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
blocked
Waits on the issues listed in its "Blocked by:" line before implementation

  
bug
Category: something is broken; behaviour differs from the spec or docs

  
enhancement
Category: new feature or improvement, including refactors, chores and docs

  
high-priority
Address before ordinary-priority work; independent of triage readiness and blockers

  
low-priority
Address after ordinary-priority work; independent of triage readiness and blockers

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
ready-for-agent
Fully specified, ready for an AFK agent

  
ready-for-human
Requires human implementation

  
referenced
Previously closed issue reopened or referenced by an open issue; visible history marker

  
research
Needs investigation (internet or local resources) before it can be triaged down; used alongside a category and a triage role

  
wontfix
Will not be actioned

No labels
blocked
bug
enhancement
high-priority
low-priority
needs-info
needs-triage
ready-for-agent
ready-for-human
referenced
research
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
gabogg/hikcentral!63
No description provided.