Skip to content

Evaluate a generic governance-observation command #64

Description

@iperev

Status

Blocked candidate. This issue preserves a proposal; it is not implementation authority or a release commitment.

Problem

A consumer exhibited requirement/contract inflation, weak product-value linkage, repeated witness signatures, and high governance-to-source volume. One observation proves existence in one consumer, not recurrence or Proofkit causation.

Promotion Predicate

Promote only when all are true:

  • a sanitized reproducible consumer fixture names an atomic failure predicate;
  • the proposed metric detects that predicate;
  • a false-positive fixture is not classified;
  • existing adoption-doctor or consumer-local mechanics are proven insufficient;
  • a second independent consumer reproduces the predicate, or the owner admits recurring first-consumer cost.

Candidate Boundary

If promoted, add governance-observation as explicit_filesystem_scan. Require caller-selected --repo-root, an explicit bounded repository-relative file inventory, and caller-owned file classes: source, governance, test, generated, or excluded. Read only listed regular files under the canonical root; reject symlinks, races, escapes, duplicate paths, unreadable files, and byte/path/top-K limit violations.

Report contentCountAuthority: scanned_explicit_inventory separately from inventoryCompletenessAuthority: caller_declared. Never claim inventory completeness.

Candidate Metrics

  • requirement density = requirement count / scanned source KLOC;
  • blocking share = blocking requirement count / requirement count;
  • governance/source ratio = scanned governance LOC / scanned source LOC;
  • witness signature clusters over exact (witnessKind, sorted commandIds, sorted environmentClasses) binding signatures;
  • risk-signal divergence only from explicit typed caller signals plus a complete versioned caller mapping.

Every ratio must name numerator, denominator, unit, scope, and zero-denominator behavior. Missing typed risk inputs yields not_applicable. Threshold classification exists only when the caller supplies a complete versioned threshold profile. Observation outcomes remain exit 0; invalid input or unsafe execution exits 1.

Required Falsifiers

  • independent numerator/denominator/zero-state fixtures;
  • binding count cannot affect requirement-density contribution order;
  • no threshold profile cannot emit threshold classification;
  • omitted semantic counts cannot collapse to omitted presentation row counts;
  • prose keywords cannot invent risk signals;
  • symlink, race, non-regular, oversized, duplicate, and secret-content cases fail without disclosure;
  • operation-count/property oracle over at least three sizes rejects pairwise clustering.

Non-Claims

No requirement meaning, product quality, inventory completeness, threshold policy, benchmark execution, gating, merge approval, release, rollout, or production readiness.

Rollback

Remove the command package, app scanner, descriptor/CLI row, family-catalog row, requirement/binding/witness owners, and tests. Existing commands and schemas remain unchanged.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions