docs: preserve proven operational properties across refactors #125

Merged

kilo merged 1 commit from docs/operational-property-preservation into develop

2026-09-24 22:25:38 +00:00

kilo commented

2026-09-24 22:19:11 +00:00

Member

Summary

Owner-directed small governance change (no issue per owner instruction): capture the durable discipline that prevents a class of regressions where an internally correct, well-tested refactor silently loses an operational property of a path that actually works today.

Rule added across three documents: generalization must preserve the relevant behavior of a proven working path unless changing that behavior is an explicit decision — and transient environment observations stay task/PR evidence, never become durable repository policy.

AGENTS.md — new "Preserve proven operational properties" section: establish the real working path before abstracting it; property classes (local/remote, interactive/headless, auth boundary, network, filesystem, lifecycle, deployment ordering, tool/runtime, manual steps) are classes, not facts about any installation; compatibility is the default; anti-staleness rule for transient observations.
.kilo/rules/30-implementation-discipline.md — before a material refactor/generalization, establish (1) the existing working/operator path, (2) its operational properties, (3) the intended compatibility delta; evidence lives in issue/PR/task reasoning, no new artifact or template; plus rules on new recurring manual steps, losing a supported operating mode, and not inferring environment facts from abstractions.
docs/llm-operating-policy.md — new "Operational UX and compatibility review" section: the reviewer question (operator journey before/after and which operational properties changed), the five verification points, the synthetic-evidence rule (synthetic tests prove only the synthetic boundary; environment-dependent acceptance needs bounded real-environment evidence or stays explicitly OPEN), the rule that review observations become durable assumptions only via explicit decision, and CHANGES_REQUESTED for a material unapproved operator-path regression.

Constraints honored

Governance/documentation only; no code, no catalog, no serialized contract changes.
Based on the exact current origin/develop (98dd25a); independent of PR #124 and does not touch it.
No new review phase, no mandatory templates, no environment inventory, no host/auth/deployment facts, no docs/reference-environments.md; docs/decisions.md untouched (no document conflict exists).
Not security-critical; no Daybreak gate applicable.

Validation

uv sync --only-dev, make check (1957 tests OK + typecheck), uv run basedpyright (0 errors), git diff --check clean.
Diff is exactly the three target files, 69 insertions, 0 deletions.

Review

UX impact: none — documentation-only; no user-facing surface, workflow or operator path of the product changes.

Review scope: one independent review of this single-commit docs change; check the three documents for duplication, contradiction with existing policy, and constraint compliance.

## Summary Owner-directed small governance change (no issue per owner instruction): capture the durable discipline that prevents a class of regressions where an internally correct, well-tested refactor silently loses an operational property of a path that actually works today. Rule added across three documents: **generalization must preserve the relevant behavior of a proven working path unless changing that behavior is an explicit decision** — and transient environment observations stay task/PR evidence, never become durable repository policy. - `AGENTS.md` — new "Preserve proven operational properties" section: establish the real working path before abstracting it; property classes (local/remote, interactive/headless, auth boundary, network, filesystem, lifecycle, deployment ordering, tool/runtime, manual steps) are classes, not facts about any installation; compatibility is the default; anti-staleness rule for transient observations. - `.kilo/rules/30-implementation-discipline.md` — before a material refactor/generalization, establish (1) the existing working/operator path, (2) its operational properties, (3) the intended compatibility delta; evidence lives in issue/PR/task reasoning, no new artifact or template; plus rules on new recurring manual steps, losing a supported operating mode, and not inferring environment facts from abstractions. - `docs/llm-operating-policy.md` — new "Operational UX and compatibility review" section: the reviewer question (operator journey before/after and which operational properties changed), the five verification points, the synthetic-evidence rule (synthetic tests prove only the synthetic boundary; environment-dependent acceptance needs bounded real-environment evidence or stays explicitly OPEN), the rule that review observations become durable assumptions only via explicit decision, and `CHANGES_REQUESTED` for a material unapproved operator-path regression. ## Constraints honored - Governance/documentation only; no code, no catalog, no serialized contract changes. - Based on the exact current `origin/develop` (`98dd25a`); independent of PR #124 and does not touch it. - No new review phase, no mandatory templates, no environment inventory, no host/auth/deployment facts, no `docs/reference-environments.md`; `docs/decisions.md` untouched (no document conflict exists). - Not security-critical; no Daybreak gate applicable. ## Validation - `uv sync --only-dev`, `make check` (1957 tests OK + typecheck), `uv run basedpyright` (0 errors), `git diff --check` clean. - Diff is exactly the three target files, 69 insertions, 0 deletions. ## Review `UX impact: none` — documentation-only; no user-facing surface, workflow or operator path of the product changes. Review scope: one independent review of this single-commit docs change; check the three documents for duplication, contradiction with existing policy, and constraint compliance.

kilo added 1 commit

2026-09-24 22:19:11 +00:00

docs: preserve proven operational properties across refactors

ci / check (pull_request) Failing after 6m32s

Details

5d12513e7c

Add the durable discipline that a refactor, redesign or generalization
of an existing working path must first establish how that path works in
the relevant real environment and preserve its operational constraints
unless the selected issue or the owner explicitly authorizes a change.

- AGENTS.md: preserve-proven-operational-properties principle with the
  property classes, the compatibility requirement, and the anti-staleness
  rule separating transient environment observations from durable policy.
- .kilo/rules/30-implementation-discipline.md: pre-implementation
  establishment of the working path, its operational properties and the
  intended compatibility delta, plus rules against inferring environment
  facts from abstractions or generalizing one observed environment.
- docs/llm-operating-policy.md: operational UX and compatibility review
  expectations, the synthetic-evidence rule, and the explicitly OPEN
  acceptance gate for environment-dependent acceptance.

Owner-directed small governance change; no issue per owner instruction.

kilo commented

2026-09-24 22:25:31 +00:00

Author

Member

Independent review of the frozen reviewed head 5d12513 (single-commit docs change, not security-critical; no Daybreak gate applicable):

Verdict: APPROVED
UX impact: none — documentation-only; no product surface, workflow or operator path changes.

Constraint compliance (all pass):

Governance/docs only — exactly the three target files, +69/−0, no code/catalog/contract changes.
Based on origin/develop 98dd25a; independent of PR #124; no postmortem content.
Core rule verbatim at AGENTS.md:125-126; anti-staleness rule at AGENTS.md:130-133.
Property classes framed as example classes, not installation facts (AGENTS.md:118-123).
All forbidden items absent (no environment inventory/host facts/templates/new review phase/docs/reference-environments.md; docs/decisions.md untouched).
Three documents consistent, layered by audience (principle / implementation discipline / review discipline), no contradiction with existing policy.

Findings: 0 MERGE_BLOCKER, 4 DEFER:

DEFER: new section headers use sentence case; casing conventions vary across the corpus (cosmetic).
DEFER: CHANGES_REQUESTED appears without prior corpus definition at this base (standard forge verdict vocabulary; not a contradiction of the MERGE_BLOCKER/DEFER finding taxonomy).
DEFER: "explicitly OPEN" acceptance-gate state is prose, not a formally enumerated token (consistent with existing open external gates).
DEFER: whichever of this PR or PR #124 merges second needs small conflict resolution in AGENTS.md/docs/llm-operating-policy.md (insertion-point adjacency, non-overlapping content).

No remediation round required (no blockers). Human merge gate: owner has explicitly authorized merging this small governance change to develop after review and validation pass.

Independent review of the frozen reviewed head `5d12513` (single-commit docs change, not security-critical; no Daybreak gate applicable): **Verdict: APPROVED** `UX impact: none` — documentation-only; no product surface, workflow or operator path changes. Constraint compliance (all pass): 1. Governance/docs only — exactly the three target files, +69/−0, no code/catalog/contract changes. 2. Based on `origin/develop` `98dd25a`; independent of PR #124; no postmortem content. 3. Core rule verbatim at `AGENTS.md:125-126`; anti-staleness rule at `AGENTS.md:130-133`. 4. Property classes framed as example classes, not installation facts (`AGENTS.md:118-123`). 5. All forbidden items absent (no environment inventory/host facts/templates/new review phase/`docs/reference-environments.md`; `docs/decisions.md` untouched). 6. Three documents consistent, layered by audience (principle / implementation discipline / review discipline), no contradiction with existing policy. Findings: 0 MERGE_BLOCKER, 4 DEFER: - DEFER: new section headers use sentence case; casing conventions vary across the corpus (cosmetic). - DEFER: `CHANGES_REQUESTED` appears without prior corpus definition at this base (standard forge verdict vocabulary; not a contradiction of the MERGE_BLOCKER/DEFER finding taxonomy). - DEFER: "explicitly OPEN" acceptance-gate state is prose, not a formally enumerated token (consistent with existing open external gates). - DEFER: whichever of this PR or PR #124 merges second needs small conflict resolution in `AGENTS.md`/`docs/llm-operating-policy.md` (insertion-point adjacency, non-overlapping content). No remediation round required (no blockers). Human merge gate: owner has explicitly authorized merging this small governance change to `develop` after review and validation pass.

kilo merged commit cebd1d6472 into develop

2026-09-24 22:25:38 +00:00

kilo referenced this pull request from a commit

2026-09-24 22:25:40 +00:00

Merge pull request 'docs: preserve proven operational properties across refactors' (#125) from docs/operational-property-preservation into develop

adrian.tkacz referenced this pull request from a commit

2026-09-24 23:25:59 +00:00

merge: canonical develop (PR #125 operational-property governance) into the sources program

kilo referenced this pull request

2026-09-24 23:26:31 +00:00

Dynamic Execution Sources, Model Discovery, Multi-Account & Security (D-053, #116) #124

kilo referenced this pull request