Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,11 +1,24 @@
# 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.
mutation workflow; Backend lanes and coverage remain authoritative. PR #290
merged the catalogue plan.

The first proposed chunk is `WS-QUAL-002-01`. Stop after planning review and
human approval; do not start implementation automatically.
`WS-QUAL-002-01` is in implementation. The current branch adds the schema,
canonical exact target partition, deterministic inventory/candidate generator,
fail-closed validator, examples, focused tests, and contributor documentation.
It does not reactivate mutation or change any workflow, product behavior,
coverage floor, lane, skip, or deselection.

Current focused evidence:

- 49 focused tests pass.
- `scripts.behavior_ownership` coverage is 91.30 percent.
- 33 semantic-lane contract tests pass, including exact assignment of the new
focused test module to `shared_foundations` under the human-approved scope
correction.
- The initial catalogue is explicitly incomplete and candidate output remains
non-authoritative while subsystem population has not started.

## Plan review

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ P2.
.ci/behavior-ownership/examples/**
scripts/behavior-ownership.schema.json
backend/scripts/behavior_ownership.py
backend/scripts/run_test_lanes.py
backend/tests/test_behavior_ownership.py
CONTRIBUTING.md
docs/operations_backend_testing.md
Expand All @@ -56,6 +57,10 @@ coverage thresholds, lane membership, skips, deselection, survivor exemptions
authoritative inferred ownership without reviewed catalogue state
```

The only approved lane-membership change is assigning
`tests/test_behavior_ownership.py` to the existing `shared_foundations` lane.
No other lane membership or execution behavior may change.

## Acceptance criteria

- [ ] Schema distinguishes reviewed ownership, candidates, and strict structural-only records.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# PR Trust Bundle: WS-QUAL-002-01

## Chunk

`WS-QUAL-002-01` — Behavior Ownership Catalogue Foundation.

## Goal And Human-Approved Intent

Add one versioned catalogue contract, exact eligible-target partition, and
deterministic read-only generator/validator without activating mutation CI or
changing Workstream product behavior. The human separately approved the narrow
contract correction that assigns the new focused test module to the existing
`shared_foundations` lane.

## What Changed And Why

- Added the schema separating `candidate`, `reviewed`, and strict
`structural_only` records.
- Added the canonical digest-bound partition assigning every eligible target to
exactly one population group.
- Added deterministic inventory, non-authoritative candidate generation,
validation, exact pytest collection, and optional exact owned-test execution.
- Added fail-closed custody, symlink, path, schema, callable, test, remap,
carry-forward, structural-side-effect, identity, and effective-owner checks.
- Added contributor and backend-testing documentation plus a real reviewed
example.

## Design Chosen

The tooling delegates eligibility, safe paths, callable spans, changed-callable
derivation, outcomes, boundaries, and test-node syntax to
`backend/scripts/mutation_policy.py`. Candidate inference is structurally
non-authoritative. Protected records remain byte-identical or resolve through
exactly one reviewed, evidence-preserving remap. The initial empty catalogue is
reported as incomplete rather than promoted or blocked.

## Alternatives Rejected

No wildcard/group inference authority, branch-local partition replacement,
callable-wide mutation activation, inferred reviewed ownership, free-form
structural exemption, parallel AST implementation, or workflow change.

## Scope Control And Product Behavior

All files are within the approved contract plus the human-approved single lane
assignment. No `.github/workflows/**`, backend application module, migration,
coverage floor, timeout, skip, deselection, product review decision,
authorization rule, payment, reputation, or `ContributionRecord` behavior
changed.

## Acceptance Proof And Tests

- 49 focused tests pass.
- `scripts.behavior_ownership` focused coverage is 91.30 percent, above 90.
- 33 semantic-lane contract tests pass.
- Ruff passes for all touched backend Python files.
- Real validation reports 176 unresolved targets and `complete: false`.
- Candidate generation remains `authoritative: false`, emits no empty-callable
candidate, and separates structural-review targets.
- Markdown links pass; stale wording passed during product/operations review.

## Test Delta And CI Integrity

One focused test module was added and assigned to `shared_foundations`. No test
was removed, skipped, deselected, weakened, or moved between existing lanes. No
workflow, coverage threshold, package configuration, or required-check behavior
changed.

## Reviewer Results

- Architecture: PASS.
- Senior engineering: PASS after typed non-reviewed supersession and physical
group-directory enforcement.
- QA: PASS after current callable-owner uniqueness.
- Security: PASS after protected deletion and multiple-effective-owner repairs.
- Product/operations: PASS.
- CI integrity: PASS.
- Documentation: PASS after using a real example and documenting strict
structural exclusions.
- Reuse/deduplication: PASS.
- Test delta: PASS.

## External Review

CodeRabbit and exact-head GitHub checks are pending after PR creation. They
supplement, but do not replace, the internal reviews above.

## Remaining Risks And Follow-Up

The catalogue is intentionally incomplete until population chunks `03A` through
`03D` merge. Context evidence (`02`), completeness integration (`04`), and any
future changed-line mutation reactivation (`05`) remain separate approved
chunks. Mutation enforcement remains retired.

## Human Review Focus

Review candidate-versus-reviewed authority, protected partition bootstrap and
future trusted-base custody, remap carry-forward/effective-owner rules, strict
structural-only behavior, and the single lane assignment.

## Human Merge Ownership

- [x] Intent, scope, and non-goals are explicit.
- [x] Deterministic local evidence passes.
- [x] Required internal reviewers pass.
- [ ] External review findings are addressed.
- [ ] Exact-head GitHub checks pass.
- [ ] The user explicitly approves this PR for merge.
40 changes: 40 additions & 0 deletions .ci/behavior-ownership/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Behavior Ownership Catalogue

This directory holds reviewed engineering evidence about which exact tests own
which executable behavior. It does not grant Workstream product authority and
does not currently activate mutation testing.

`partition.v1.json` is the sole target-to-population-group partition. It lists
every eligible non-`__init__` Python target exactly once, binds the protected
base commit used to create it, and carries a digest over that authority data.
Population work must load this artifact from protected `main` or the approved
foundation commit. A branch-local replacement, relocation, duplicate, wildcard,
or digest mismatch fails validation.

Catalogue records belong under one group directory: `auth/`, `artifacts/`,
`lifecycle/`, or `shared/`. The JSON Schema is
[`scripts/behavior-ownership.schema.json`](../../scripts/behavior-ownership.schema.json).
Examples are illustrative only and never count as reviewed ownership.

Statuses are deliberately separate:

- `candidate` is deterministic discovery output awaiting human review.
- `reviewed` binds exact AST callables, collected pytest nodes, observable
outcomes, real boundaries, and reviewers.
- `structural_only` requires a reviewed reason and is valid only when the target
has no executable callable or module-level runtime behavior. Calls, branches,
loops, raises, awaits, mutation, I/O, SQL, validators, and other runtime side
effects fail validation. Structural records cannot contain callable or test
fields.

Run the tooling from `backend/`:

```bash
.venv/bin/python -m scripts.behavior_ownership inventory
.venv/bin/python -m scripts.behavior_ownership generate --group auth
.venv/bin/python -m scripts.behavior_ownership validate
```

Validation reports unresolved targets while the catalogue is being populated.
An empty catalogue is therefore explicit and non-authoritative, not silently
complete.
20 changes: 20 additions & 0 deletions .ci/behavior-ownership/examples/reviewed.example.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"behavior_id": "example.hashing.sha256",
"boundaries": [],
"callables": [
"app.core.hashing.canonical_json_hash"
],
"group": "shared",
"outcomes": [
"return"
],
"reviewed_by": [
"example-reviewer"
],
"schema": "workstream.behavior-ownership.v1",
"status": "reviewed",
"target": "backend/app/core/hashing.py",
"tests": [
"backend/tests/test_checkers.py::test_canonical_json_hash_rejects_non_finite_numbers"
]
}
Loading
Loading