plan repository-wide behavior ownership catalogue

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/CHUNK_MAP.md

@@ -0,0 +1,17 @@
+# Chunk Map: WS-QUAL-002 Behavior Ownership Catalogue
+
+| Chunk | Purpose | Dependency | Risk | State |
+|---|---|---|---|---|
+| `WS-QUAL-002-01` | Catalogue schema, inventory, generator, validation foundation | none | L1 | proposed |
+| `WS-QUAL-002-02` | Coverage-context candidate evidence and runtime calibration | 01 | L1 | pending |
+| `WS-QUAL-002-03A` | AUTH, actors, API controls, audit ownership | 01, 02 | L1 | pending |
+| `WS-QUAL-002-03B` | Artifacts, storage, extraction, external adapters ownership | 01, 02 | L1 | pending |
+| `WS-QUAL-002-03C` | Projects, tasks, checkers, reviews, contribution ownership | 01, 02 | L1 | pending |
+| `WS-QUAL-002-03D` | Core, DB, async execution, scripts, remaining shared ownership | 01, 02 | L1 | pending |
+| `WS-QUAL-002-04` | Completeness/staleness gate and contributor preparation command | 03A-D | L1 | pending |
+| `WS-QUAL-002-05` | Changed-line-aware mutation reactivation and AUTH workflow proof | 04 | L1 | pending |
+
+Population chunks `03A` through `03D` may run concurrently in separate
+branches after `01` and `02` merge. Their scopes come exclusively from the
+machine-readable target partition committed by `01`; each target belongs to
+exactly one population chunk.

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/DECISIONS.md

@@ -0,0 +1,18 @@
+# Decisions: WS-QUAL-002 Behavior Ownership Catalogue
+
+## Accepted human direction
+
+Pre-create behavior ownership for the whole codebase so AUTH and other
+contributors do not pause during implementation to rediscover mutation claims.
+
+## Planning decisions
+
+- Durable catalogue and transient PR selection are separate concepts.
+- Ordinary PR mutation remains changed-scope.
+- Candidate automatic mappings are not blocking authority until reviewed.
+- AUTH is the first subsystem proof, but catalogue scope is repository-wide.
+- The 05M workflow remains retired; only a fresh, explicitly approved,
+  changed-line-aware workflow may reactivate mutation enforcement.
+- Callable groups enumerate exact AST members and never widen exact-callable selection.
+- Foundation assigns every eligible target to one population group before concurrent work.
+- Coverage-context calibration is local/manual and cannot add a workflow or required check.

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/DISCOVERY.md

@@ -0,0 +1,68 @@
+# Discovery: WS-QUAL-002 Behavior Ownership Catalogue
+
+## Repository facts
+
+- Eligibility is defined by `ELIGIBLE_PREFIXES` in
+  `backend/scripts/mutation_policy.py`.
+- Exact changed callables are derived by `changed_callables()` using Git
+  merge-base hunks and AST spans.
+- `build_selection()` currently requires changed targets and claimed callables
+  to match exactly.
+- Claim schema v1 is in `scripts/behavior-claim.schema.json`; it permits at most
+  eight targets, 24 callables per target, and 12 exact pytest nodes per target.
+- Backend semantic ownership is process-level, not production ownership:
+  `backend/scripts/run_test_lanes.py` assigns all 66 test modules to five lanes.
+- The current hosted Backend run proves all lane nodes and combines coverage,
+  but it does not emit callable-to-test context ownership.
+
+## Scope inventory
+
+- 168 eligible implementation/script modules excluding `__init__.py`.
+- 66 top-level backend test modules.
+- High-risk groups include authorization/actors/auth, artifacts/storage,
+  projects/tasks/checkers/reviews, audit/outbox, async job runtimes, and CI scripts.
+- Existing behavior claims cover mutation-policy calibration only; they are not
+  a repository ownership catalogue.
+
+## Existing evidence that can be reused
+
+- Exact AST callable mapping in `mutation_policy.py`.
+- Exact test collection and lane custody in `run_test_lanes.py`.
+- Combined coverage and protected subsystem floors in `coverage_policy.py` and
+  the Backend workflow.
+- Current schema vocabulary for outcomes and real boundaries.
+- `pytest-cov`/coverage support test contexts, which can provide candidate
+  callable-to-test evidence without inventing ownership from imports.
+
+## Gaps
+
+- No canonical target/callable ownership registry.
+- No deterministic command to prepare ownership before implementation.
+- No context-coverage artifact mapping executed lines to exact pytest nodes.
+- No completeness check covering every eligible module.
+- No stale-node check proving catalogue tests still collect.
+- No bounded rule for modules whose owning test would exceed mutation runtime.
+
+## Dependencies and integrations
+
+The solution touches mutation policy, test collection/coverage evidence,
+repository schemas, contributor documentation, and the mutation workflow. It
+must use protected-base authority and cannot trust PR-head catalogue changes
+without validation.
+
+## Risks
+
+- Static import inference can overclaim behavior ownership.
+- Coverage contexts show execution, not assertion strength; mutation remains
+  the assertion-sensitivity proof.
+- A single test module can be too broad for bounded mutation.
+- Catalogue population is data-heavy and must be split by subsystem.
+- Renames/deletions require explicit fail-closed catalogue reconciliation.
+
+## Unknowns to resolve during the prototype
+
+- Hosted size/runtime cost of per-test coverage contexts.
+- Whether exact test functions or stable test groups are the best stored unit.
+- How many eligible modules contain no executable callable and should be typed
+  `structural_only` rather than mutation-owned.
+- Which existing broad integration tests need smaller owning behavior tests.

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/INTENT.md

@@ -0,0 +1,83 @@
+# Intent: WS-QUAL-002 Behavior Ownership Catalogue
+
+## Problem being solved
+
+The retired 05M mutation gate required exact changed-callable ownership, but
+contributors had to discover and author that ownership during each PR. AUTH
+paused implementation to build mutation metadata, while callable-wide mutation
+also evaluated unchanged executable lines. PR #289 retired that blocking
+workflow. Durable ownership and changed-line selection are both required before
+mutation enforcement can safely return.
+
+## Why this work matters
+
+Humans and agents should begin implementation with known owning tests and
+boundaries. Mutation should verify changed behavior, not force every contributor
+to rediscover the repository's test architecture.
+
+## Current behavior
+
+- 168 non-`__init__` Python modules are eligible under `backend/app/` and
+  `backend/scripts/`.
+- 66 backend test modules exist.
+- Only the historical `04M` and `05M` behavior claims exist.
+- The hosted mutation workflow is retired; Backend lanes, coverage, lint,
+  review, and human merge remain active.
+
+## Target behavior
+
+Main contains reviewed behavior ownership for every eligible module. A local
+command derives exact changed executable lines and their containing callables
+from Git and generates bounded PR selection automatically. Contributors update
+ownership only for new or materially remapped behavior.
+
+## Design chosen
+
+Create a canonical ownership catalogue separate from transient PR selection.
+Catalogue records bind targets and callable ownership to exact tests, observable
+outcomes, and required real boundaries. Generation and validation are
+deterministic. Any future mutation engine is changed-line-aware, never mutates
+unchanged executable lines, and never runs the whole repository on an ordinary
+PR.
+
+## Alternatives considered
+
+- One permanent giant claim: rejected; it violates exact changed-scope custody
+  and would create excessive mutation runtime.
+- One generated claim based only on filenames/imports: rejected; imports do not
+  prove behavior ownership.
+- Full-repository mutation on every PR: rejected for cost and review noise.
+- Disable mutation for AUTH: rejected; subsystem pressure must improve the
+  workflow, not weaken evidence.
+
+## Boundaries preserved
+
+- Global 78-percent and protected 90-percent coverage floors remain unchanged.
+- Existing Backend semantic lanes and full-suite custody remain authoritative.
+- GitHub permissions and human merge remain contribution authority.
+- No product, authorization, payment, reputation, migration, or API behavior
+  changes.
+
+## Expected risks
+
+False ownership is worse than missing ownership. Automatically inferred
+mappings must remain candidates until deterministic coverage evidence and human
+engineering review confirm them. Large test modules may exceed mutation runtime if mapped
+too broadly.
+
+## What must not change
+
+No arbitrary skips, survivor allowlists, score thresholds, PR-controlled gate
+authority, or whole-repository mutation.
+
+## How this will be proven
+
+Schema and generator tests, exact Git-delta tests, catalogue completeness and
+staleness checks, coverage-context evidence, subsystem review, an AUTH pilot,
+and final hosted changed-line mutation evidence before reactivation.
+
+## Human decisions required
+
+Approve the staged plan and first contract. Later mutation reactivation requires
+a separate human checkpoint after AUTH proves that normal work no longer pauses
+for manual claim construction and unchanged lines cannot enter selection.

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/PLAN.md

@@ -0,0 +1,87 @@
+# Plan: WS-QUAL-002 Behavior Ownership Catalogue
+
+## Approach
+
+1. Define a versioned catalogue schema and read-only inventory/generation CLI.
+2. Produce coverage-context candidates and validate them against collected
+   pytest nodes and current AST callables.
+3. Pilot reviewed ownership for AUTH/actors first because it is active and
+   security-sensitive.
+4. Populate remaining catalogue groups in independent data PRs.
+5. Require catalogue completeness and staleness checks without reactivating
+   hosted mutation.
+6. Add a fresh changed-line-aware mutation workflow using protected-base
+   catalogue ownership, requiring changed catalogue data only for new/remapped
+   behavior.
+7. Prove normal AUTH work can generate selection without pausing and that
+   unchanged executable lines never enter mutation selection.
+
+## Catalogue model
+
+One record per eligible target. Records distinguish mutation-owned callables
+from typed structural-only modules. Each owned callable binds exact collected
+pytest nodes, observable outcomes, and real boundaries. A callable group is
+only a storage and review convenience: it must enumerate every exact AST
+callable member, and Git-delta selection still resolves and validates each
+changed executable line and containing callable independently. Wildcards,
+module-wide ownership, and implicit
+group membership are forbidden. Candidate evidence and reviewed test ownership
+are separate states; candidate inference can never satisfy the blocking gate.
+
+The catalogue is engineering QA and mutation evidence only. It does not create
+or modify Workstream product authority, review decisions, ContributionRecords,
+payment, reputation, or lifecycle truth.
+
+## Protected authority
+
+For existing behavior, ordinary PRs use the catalogue read from protected base.
+New or remapped callables require an additive changed record validated from PR
+head. PR-head data cannot delete, narrow, downgrade, or replace protected-base
+reviewed ownership. Exact Git delta remains the source of changed callables.
+
+Each reviewed behavior has an immutable `behavior_id`; its current location is
+the exact `(target_path, AST-qualified callable name)` binding. A remap record
+names `supersedes_behavior_id`, is admitted only when the exact Git delta proves
+the protected location is absent or renamed and the PR-head location exists,
+and carries forward every protected owning test, outcome, and real boundary
+unless a separately reviewed ownership change adds stronger evidence. Effective
+selection resolves the superseded binding before mutation input and must yield
+exactly one reviewed owner for every changed executable line; zero or multiple
+effective owners fail closed.
+
+## Verification strategy
+
+- JSON Schema and path/custody validation.
+- Exact eligible-module completeness and no-orphan checks.
+- A deterministic target-to-population-group manifest that assigns every
+  eligible target to exactly one of `auth`, `artifacts`, `lifecycle`, or
+  `shared` before concurrent population begins.
+- Exact collected-node existence and no skip/deselect weakening.
+- Context-coverage candidate reconciliation.
+- Negative tests for missing, narrowed, stale, renamed, deleted, duplicated,
+  unsafe, and overly broad ownership.
+- Focused 90-percent coverage for new catalogue tooling.
+- AUTH pilot and final hosted mutation evidence within the existing job cap.
+
+## Rejected architecture
+
+No monolithic claim, import-only mapping, mutable runtime registry, generic
+plugin discovery, global mutation score, or full-repository ordinary-PR run.
+
+## Rollout boundary
+
+The 05M workflow remains retired. Mutation enforcement may return only through
+the final human-approved changed-line-aware reactivation chunk after hosted
+evidence proves the catalogue path and excludes unchanged lines. Population work
+may proceed concurrently only after both the schema/generator foundation with
+its target partition (`01`) and observational context evidence (`02`) merge.
+The observational context prototype is local/manual and adds no workflow;
+chunk `05` is the first chunk allowed to add a new workflow or reactivate
+mutation enforcement.
+
+Before reactivation, a blocking repository scan covers active workflows,
+scripts, and configuration and rejects references to the retired workflow,
+callable-wide selectors, or historical claim authority. Historical planning and
+review evidence may name the retirement; executable or active configuration may
+not. The retired state remains authoritative until this scan and all hosted
+evidence pass on the exact proposed head.

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/RISKS.md

@@ -0,0 +1,13 @@
+# Risks: WS-QUAL-002 Behavior Ownership Catalogue
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Inferred execution is mistaken for assertion ownership | Vacuous catalogue | Keep candidates non-authoritative; engineering review and future mutation evidence confirm ownership |
+| Retired callable-wide behavior returns under a new name | Contributor blocking and false survivors | Require exact changed-line selection and negative proof that unchanged executable lines never enter mutation |
+| Broad test nodes make mutation slow | Contributor latency | Calibrate contexts and require bounded owning nodes/groups |
+| Protected ownership is narrowed by PR data | Gate bypass | Protected-base merge semantics and explicit additive remap validation |
+| Catalogue becomes stale after renames | False failures or escapes | Exact AST, target, collected-node, rename, and deletion checks |
+| 168-module population is unreviewable | Review failure | Four subsystem data chunks with focused reviewers |
+| Context coverage is too slow or produces oversized artifacts | Contributor latency | Keep it local/manual; accept only at no more than two minutes and 10 MiB per artifact |
+| Structural modules hide executable behavior | Gate bypass | Machine-checkable AST criteria, a required reviewer rationale, and negative tests |
+| Concurrent population overlaps or omits targets | Stale review and merge conflicts | Commit one exact target-to-group partition before population; make population PRs data-only |

.agent-loop/initiatives/WS-QUAL-002-behavior-ownership-catalogue/STATUS.md

@@ -0,0 +1,22 @@
+# Status: WS-QUAL-002 Behavior Ownership Catalogue
+
+Planning is complete and internally reviewed. PR #289 retired the 05M hosted
+mutation workflow; Backend lanes and coverage remain authoritative. No
+catalogue implementation or mutation reactivation has started.
+
+The first proposed chunk is `WS-QUAL-002-01`. Stop after planning review and
+human approval; do not start implementation automatically.
+
+## Plan review
+
+- Architecture: PASS
+- CI integrity: PASS WITH LOW RISKS
+- Security: PASS
+- QA: PASS WITH LOW RISKS
+- Senior engineering: PASS WITH LOW RISKS
+- Product/operations: PASS WITH LOW RISKS
+- Documentation: PASS
+- Reuse/deduplication: PASS WITH LOW RISKS
+
+All blocking findings were resolved in the planning artifacts. Remaining low
+risks are implementation review focuses, not approval blockers.