Skip to content

program-governance.md

Latest commit

 

History

History
425 lines (320 loc) · 20.8 KB

program-governance.md

File metadata and controls

425 lines (320 loc) · 20.8 KB

Extension Platform Program Governance

This document defines ownership, decision authority, quality gates, and maintenance cadence for the Pi extension platform.

Ownership

Area Owner Backup
Runtime (PiJS, QuickJS, hostcalls) Primary maintainer AI agent review (Claude/Codex)
Extension API surface Primary maintainer AI agent review
Capability policy (safe/balanced/permissive) Primary maintainer Security review required
CI/CD pipelines Primary maintainer Self-healing via gate promotion
Conformance corpus (223 extensions) Automated via conformance harness Manual triage for new failures
Documentation Primary maintainer + agents Automated staleness checks
Sibling crates (asupersync, rich_rust, charmed, sqlmodel) Independently versioned Cross-repo coordination via bead dependencies

Decision Authority

  • Breaking changes to extension API: Primary maintainer approval required. Documented in CHANGELOG.md before release.
  • Capability policy changes (adding/removing capabilities): Requires security review and conformance regression check.
  • New official extensions: Must pass conformance at Tier 1-2 level with clean preflight report.
  • Dependency additions: Must pass cargo audit, no unsafe in new deps.

Quality Gates

CI Gates (Enforced on Every PR)

Gate Threshold Enforcement
cargo fmt Zero diff .github/workflows/ci.yml
cargo clippy -D warnings Zero warnings .github/workflows/ci.yml
Unit tests 100% pass .github/workflows/ci.yml
VCR/fixture tests 100% pass .github/workflows/ci.yml
No-mock dependency guard Zero violations .github/workflows/ci.yml
Suite classification guard All files classified .github/workflows/ci.yml
Traceability matrix guard All classified tests traced .github/workflows/ci.yml
VCR leak guard No cassettes in wrong suite .github/workflows/ci.yml
PR Definition-of-Done evidence guard Required for feature-surface PRs .github/workflows/ci.yml

Conformance Gates (Nightly + Release)

Gate Threshold Source
Extension corpus pass rate >= 80% (current: 91.9%) conformance_summary.json
Scenario conformance >= 90% (current: 96.0%) scenario_conformance.json
Node API matrix 100% critical pass (current: 13/13) runtime_api_matrix.json
Maximum failures <= 36 extensions conformance_summary.json
Maximum N/A <= 170 extensions conformance_summary.json
Policy negative tests 100% pass conformance_report.json

Performance Gates

Budget Threshold Source
Cold extension load < 200ms p95 budget_summary.json
Warm extension load < 50ms p95 budget_summary.json
Event dispatch latency < 10ms p95 budget_summary.json
Binary size < 50MB CI artifact check

See BENCHMARKS.md for full budget definitions.

Release Gates (1.0 Criteria)

Per releasing.md:

  • CI green on Linux/macOS/Windows
  • Core CLI modes stable (print + interactive + RPC)
  • Extension runtime surface and security policy stable
  • Conformance gates met at release thresholds

Definition of Done for Feature Changes

Feature-surface PRs (runtime/provider/tooling behavior changes) are not mergeable until:

  1. PR body includes checked evidence for unit, e2e, and extension validation.
  2. PR body links directly to structured artifacts/logs for those runs.
  3. PR body includes reproduction commands for both passing validation and the most recent failing path.
  4. PR body contains no unresolved checklist placeholders.

The canonical checklist source is .github/pull_request_template.md, and CI enforces it in the Linux PR lane.

Migration Guidance for Existing Feature Branches

  1. Rebase on latest main.
  2. Replace PR body with .github/pull_request_template.md.
  3. Backfill evidence links from latest CI/local runs.
  4. Include explicit failing-path artifact links plus exact rerun commands.
  5. Re-run CI and merge only after DoD guard passes.

Release Cadence

Channel Frequency Scope
Patch (0.x.Y) As needed Bug fixes, conformance improvements
Minor (0.X.0) Monthly New features, API additions
Major (X.0.0) When 1.0 criteria met Stability commitment
Pre-release (-rc.N) Before major/minor Validation window

Versioning Rules

  • SemVer with tag format vX.Y.Z (source of truth: Cargo.toml).
  • Pre-1.0: breaking changes allowed with changelog documentation.
  • Post-1.0: breaking changes require major version bump and deprecation window.
  • Sibling crates versioned independently.

See releasing.md for the full release process.

Maintenance Cadence

Weekly

Task Owner Verification
Dependency audit (cargo audit) Automated CI gate
Conformance regression review Agent triage Nightly CI reports
Bead backlog grooming Primary maintainer bv --robot-plan + br ready --json

Weekly QA Burndown (bd-1f42, as of 2026-02-10)

Snapshot:

  • Scope: bd-1f42* QA epic and sub-beads
  • Total: 51 beads (8 closed, 7 in_progress, 36 open)
  • Priority mix: open P0=19, open P1=17, in_progress P0=5, in_progress P1=2
  • Slip check: no bd-1f42* bead is past due as of 2026-02-10.
  • Near-term risk window: 2026-02-13 to 2026-02-16 (baseline-audit and core-unit milestones).

Top blocker graph pressure (open blockers):

  • bd-1f42.6.5 blocked by 8 prerequisites
  • bd-1f42.4 blocked by 7 prerequisites
  • bd-1f42.6 blocked by 7 prerequisites
  • bd-1f42.2 blocked by 6 prerequisites
  • bd-1f42.7.3 blocked by 6 prerequisites

Blocker RCA + Unblock Actions

Blocked target Root cause analysis Accountable owner Unblock action (next checkpoint)
bd-1f42.3 (E2E harness track) Critical-path concentration on runner core (bd-1f42.3.1) and versioned logging contract (bd-1f42.3.6) keeps scenario/replay beads from starting. TopazForest Close bd-1f42.3.1, then land bd-1f42.3.6 logging contract to unlock downstream scenario/replay work.
bd-1f42.4 (208-extension matrix track) Fixture corpus + executor + gate/reporting work is still serial (bd-1f42.4.2/.4.3/.4.4), so downstream compatibility and dossier beads remain blocked. OrangeBarn Prioritize bd-1f42.4.3 sharded executor completion, then wire bd-1f42.4.4 CI must-pass gate immediately after.
bd-1f42.6.5 (final full-suite gate) Final release-blocking gate depends on unfinished deliverables across CI, unit, e2e, extension, and reliability tracks. PearlRaven (coordination owner for bd-1f42.6.*) Keep prerequisite checklist explicit and sequence completion bd-1f42.6.1 -> bd-1f42.6.8 -> bd-1f42.6.5 with owner check-ins each burndown cycle.
bd-1f42.7.3 (final certification) Certification is evidence-gated: governance cadence (bd-1f42.7.2) plus runbook and CI evidence-bundle dependencies are still open. BrightValley Maintain weekly burndown updates, close bd-1f42.7.4 runbook, then assemble certification once bd-1f42.6.8 and bd-1f42.4.5 are complete.

Next burndown checkpoint: 2026-02-17 (UTC), with updated blocker counts and owner-level action status.

Weekly Provider Parity Rollup (bd-3uqg, as of 2026-02-12)

Snapshot:

  • Scope: bd-3uqg* provider-parity epic and sub-beads.
  • Ready front: only bd-3uqg is currently unblocked/open; most downstream tasks are intentionally dependency-gated.
  • Highest-impact current blocker: bd-3uqg.3.8.4 (native parity consolidation), which unlocks bd-3uqg.8, bd-3uqg.8.2, and bd-3uqg.9.1.2.

Execution lanes and ownership:

Lane Active beads Current owner/assignee Handoff target
Native implementation bd-3uqg.3 RusticPrairie bd-3uqg.3.8 verification
Native verification bd-3uqg.3.8 AmberHill bd-3uqg.3.8.4 consolidated report
Native parity consolidation bd-3uqg.3.8.4 IvoryPuma Test/docs expansion (bd-3uqg.8*, bd-3uqg.9.1.2)
Provider onboarding docs bd-3uqg.9 TealFox Docs matrix and playbook children
Provider support matrix bd-3uqg.9.1 QuietCove bd-3uqg.9.1.2 and bd-3uqg.9.1.3
Rollup orchestration bd-3uqg, bd-3uqg.10, bd-3uqg.10.1 CopperCreek bd-3uqg.10.2 gate execution

Sequencing gates (ordered):

  1. Gate A - Native parity evidence complete Criteria: bd-3uqg.3.8.4 includes provider-level pass/fail matrix with links to unit/e2e logs and explicit deviation notes.
  2. Gate B - Core provider test harnesses Criteria: bd-3uqg.8.2, bd-3uqg.8.3, and bd-3uqg.8.4 land with deterministic fixtures, event-parity assertions, and CI artifact hooks.
  3. Gate C - Provider docs evidence closure Criteria: bd-3uqg.9.1.2, bd-3uqg.9.1.3, bd-3uqg.9.2, bd-3uqg.9.3, bd-3uqg.9.4, and bd-3uqg.9.5 reference concrete test artifacts rather than narrative-only claims.
  4. Gate D - Rollup certification path Criteria: bd-3uqg.10.2 runs mandatory quality gates, then bd-3uqg.10.3 performs final parity audit, and bd-3uqg.10.4 publishes completion handoff + remaining-gap beads.

Anti-stall checkpoints:

  • Every active bd-3uqg* assignee posts a concise progress update in Agent Mail thread br-3uqg at least once per 24 hours while in_progress.
  • Any bead blocked for more than 12 hours must post a blocker note with exact blocking bead IDs, affected files, and required unblock action.
  • Rollup owner re-runs bv --robot-plan and bv --robot-priority at each checkpoint, then validates proposed bead IDs with br ready --json / br show <id> to skip tombstones before reassigning effort.
  • No new provider-family onboarding starts until Gate A evidence exists, to prevent parallel drift and report mismatch.

Next provider rollup checkpoint: 2026-02-13 (UTC), focused on bd-3uqg.3.8.4 completion and Gate A evidence audit.

Monthly

Task Owner Verification
Performance budget review Primary maintainer budget_summary.json trends
Extension corpus update Automated discovery extension-inclusion-list.json
Documentation staleness check Traceability tests traceability_staleness.rs
CI gate threshold review Primary maintainer Gate promotion workflow

Quarterly

Task Owner Verification
Full conformance campaign (223 extensions) Automated conformance.yml nightly
Security review of capability policies Primary maintainer Threat model doc
Dependency major version updates Primary maintainer cargo update + full test
Roadmap review and bead reprioritization Primary maintainer bv --robot-plan + bv --robot-priority

Extension Governance

Tiers and Vetting

Tier Count Vetting Conformance
Official 60 Full review, MIT license verified 100% pass required
Community 58 Automated conformance check 90%+ pass target
npm registry 66 License + provenance check Best-effort
Third-party 23 Provenance verification Best-effort
Agent ecosystem 1+ Same as community Same as community

Adding New Extensions

  1. Extension passes pi doctor with PASS verdict.
  2. License is permissive (MIT, Apache-2.0, BSD).
  3. Provenance is pinnable (git commit hash or npm version).
  4. No per-extension patches required (unmodified compatibility).
  5. Added to docs/extension-inclusion-list.json with tier assignment.

Removing Extensions

  • Extensions are removed from the corpus when:
    • License changes to incompatible terms.
    • Source becomes unavailable (unpinnable provenance).
    • Extension requires per-extension patches to function.
  • Removal is documented in CHANGELOG.md.

Deprecation Policy

Pre-1.0 (Current)

  • Breaking changes are allowed with CHANGELOG documentation.
  • Deprecated APIs emit runtime warnings for at least one minor release.
  • CLI flag changes are documented in --help output.

Post-1.0 (Future)

  • Deprecated APIs: warning for 2 minor releases, removal in next major.
  • CLI flag removal: 1 minor release deprecation window.
  • Extension API changes: 2 minor release deprecation window.
  • Capability policy changes: announced in release notes.

Incapacity Playbook

This playbook covers maintainer unavailability, account compromise, or a release-blocking emergency where the primary maintainer cannot operate the repository directly. It is intentionally procedural and does not store secrets, private contact details, recovery phrases, or personal account material in this repository.

Activation Criteria

Use this path only when at least one condition is true:

  1. The primary maintainer is unreachable for 72 hours and a Critical/High security fix, installer breakage, or release-blocking regression must ship.
  2. The primary maintainer explicitly delegates emergency control in writing.
  3. The GitHub or crates.io account appears compromised and normal release authority must be suspended while credentials are rotated.

Repo Ownership Escalation

Step Action Evidence
1 Open an emergency tracking bead with label operations and link the triggering incident. br show <id> --json
2 Confirm the activating condition with the out-of-band maintainer contact roster stored outside this repo. Emergency log entry, not committed
3 Have the designated emergency repo admin accept temporary operational ownership. GitHub organization or repo audit log
4 Freeze non-emergency merges until CI, release tags, and installer distribution are verified. Branch ruleset/audit-log snapshot
5 Record every action in the emergency bead and in release notes if a user-visible build ships. Bead comments, CHANGELOG entry

The private roster must identify at least two emergency contacts: one GitHub repository administrator and one release/secrets operator. If either role is vacant, the weekly governance review must file a P1 operations bead.

Secrets Recovery and Rotation

No secret value belongs in this repo. The emergency operator should recover or rotate credentials from the private secrets manager/escrow only after the activation criteria are met.

Secret or authority Recovery/rotation action Verification
GitHub repository/admin access Rotate compromised credentials, review SSH/GPG keys, revoke unknown tokens, and confirm branch rulesets still protect main. GitHub security log + ruleset snapshot
CARGO_REGISTRY_TOKEN Revoke the old crates.io token, issue a least-privilege replacement, and update the Actions secret. Publish workflow dry-run or pre-release tag
Release workflow authority Verify .github/workflows/release.yml permissions still use GitHub-scoped release rights only. Workflow run log
Installer artifact integrity Regenerate release assets, SHA256SUMS, and Sigstore/checksum evidence before advising users to install. GitHub Release artifact list + checksum proof
Local signing or recovery material Rotate outside Git, then document only the rotation event and operator identity. Private escrow audit log

After rotation, invalidate all emergency session tokens, remove temporary administrators, and capture a final audit-log snapshot before returning to normal governance.

Emergency Release Process

  1. Rebase on latest main and keep the patch scoped to the emergency.
  2. Run the mandatory local gates from AGENTS.md, including cargo check --all-targets, cargo clippy --all-targets -- -D warnings, cargo fmt --check, and ./scripts/reconcile_beads_ledger.sh.
  3. Cut a pre-release tag first when time allows: vX.Y.Z-rc.N.
  4. Verify the Publish and Release (GitHub binaries) workflows in releasing.md, including installer regression and checksum artifacts.
  5. Promote to the final SemVer tag only after the release artifact path and installer path both pass smoke tests.
  6. Document the reason for emergency authority in CHANGELOG.md and the emergency bead.

If a Critical/High vulnerability is actively exploitable, the emergency repo admin may bypass the normal monthly cadence, but may not bypass branch protection, code review evidence, or release artifact verification.

Branch-Protection Authority

Only the primary maintainer or the designated emergency repo admin may change branch protection, required checks, release workflow permissions, or tag protection. During an emergency, any such change requires:

  1. A linked emergency bead.
  2. A second human or agent review recorded in the bead.
  3. A before/after snapshot of the GitHub ruleset or workflow permission diff.
  4. Immediate restoration of the stricter rule after the emergency release.

Branch protection must never be relaxed to make unrelated work mergeable during an incapacity event.

Tabletop Dry Run

Run this review quarterly or after any release-process change:

  1. Pick a hypothetical Critical installer regression.
  2. Identify the emergency repo admin and release/secrets operator from the private roster without exposing their contact details in Git.
  3. Walk through credential rotation for CARGO_REGISTRY_TOKEN as a dry run: do not rotate unless there is a real incident, but verify the owner and storage location are known.
  4. Trigger or inspect a non-publishing release rehearsal, preferably a pre-release tag or workflow dry run.
  5. Confirm the installer path verifies SHA256SUMS and does not require --no-verify in published instructions.
  6. File beads for any missing role, stale secret owner, failing workflow, or ambiguous branch-protection authority.

The tabletop outcome is pass only when every role is named in private escrow, the release workflow can be rehearsed without publishing a final release, and no unresolved Critical/High operations gap remains untracked.

Incident Response

Conformance Regression on Main

  1. Triage within 24 hours via bv --robot-plan + br ready --json, and confirm candidate IDs with br show <id> before claiming.
  2. If regression is in runtime: fix and cut patch release.
  3. If regression is in test harness: fix harness, re-run campaign.
  4. If regression is in extension: update exception list with justification.

Security Vulnerability

  1. Assess severity (capability escape, sandbox bypass, data leak).
  2. Critical/High: fix within 48 hours, cut patch release.
  3. Medium/Low: fix in next scheduled release.
  4. Document in CHANGELOG.md and release notes.

Performance Regression

  1. Compare against baseline in budget_summary.json.
  2. If budget exceeded by >20%: investigate and fix before release.
  3. If budget exceeded by <20%: document and adjust threshold if justified.

Roadmap

Current Program (bd-k5q5)

Epic Status Goal
Conformance evidence (bd-k5q5.2) In progress 223 scenarios green or documented
Node/Bun compatibility (bd-k5q5.3) Closed 18+ Node modules shimmed
Capability policy (bd-k5q5.4) Closed Safe/balanced/permissive profiles
CI gates (bd-k5q5.5) In progress Regression prevention
Documentation (bd-k5q5.6) In progress Architecture + operator docs
Verification program (bd-k5q5.7) In progress Unit + E2E + diagnostics

1.0 Milestones

  1. All CI gates green on Linux/macOS/Windows.
  2. Extension conformance >= 90% with documented exceptions.
  3. Performance budgets met consistently over 30 days.
  4. Public documentation complete (compatibility matrix, playbook, governance).
  5. Security review of capability policies complete.

Related Documents

Document Path Purpose
Release process docs/releasing.md Versioning, tagging, publishing
Testing policy docs/testing-policy.md Suite classification, enforcement
Compatibility matrix docs/ext-compat.md Node/Bun API support
Operator playbook docs/conformance-operator-playbook.md Running conformance tests
Troubleshooting docs/extension-troubleshooting.md Common failure patterns
Benchmarks BENCHMARKS.md Performance budgets
Architecture docs/extension-architecture.md Runtime design
Threat model docs/extension-runtime-threat-model.md Security analysis
Traceability matrix docs/traceability_matrix.json Requirement-to-test mapping