Skip to content

Realign Cambium component responsibilities and close governance production chains - #176

Merged
KimGLee merged 15 commits into
mainfrom
refactor/cambium-responsibility-realignment
Aug 29, 2026
Merged

Realign Cambium component responsibilities and close governance production chains#176
KimGLee merged 15 commits into
mainfrom
refactor/cambium-responsibility-realignment

Conversation

@KimGLee

@KimGLee KimGLee commented Aug 29, 2026

Copy link
Copy Markdown
Owner

Owner Issue

Closes #175

Related to #174. This PR removes Standards-version restamping as a source of Card-byte drift, but it does not introduce a generic cross-version recovery protocol for an already-open batch whose frozen components genuinely change.

Change

This PR restores one semantic owner for every in-scope responsibility across Cambium's Kernel, Card, Read Set, Profile, Tool, and adopter-owned runtime state.

It is intentionally one atomic change. Moving the visible components without moving their machine contracts, producers, consumers, tests, generated projections, and public documentation would leave the repository in an intermediate state that cannot satisfy its own governance model.

Responsibility model

Component Sole responsibility
Kernel Cross-instance governance rules, invariants, object and state meaning, extension points, and implementation-independent contracts
Card Short, curated, non-authoritative action checklists for an already selected route or phase
Read Set Machine-resolvable static loading edges and conditional read-back targets
Profile User-confirmed, repository-specific governance requirements and legal extension bindings
Tool Deterministic validation, calculation, generation, controlled state transitions, and implementation of existing contracts
.cambium Adopter-owned current state, bound inputs, evidence, recovery material, temporary work, and rebuildable projections

Structure and ownership

  • Moved the 13 Cards from kernel/Cards/ to top-level Card/.
  • Moved the 13 Read Sets from kernel/Read Sets/ to top-level Read Set/.
  • Removed the nested copies instead of retaining two current path authorities.
  • Reduced Cards to curated, non-authoritative flight checklists with explicit read-back hooks and an independent Card size budget.
  • Made Read Set loading relationships machine-resolvable rather than reconstructing them from headings, ordinary links, or repeated Tool constants.
  • Removed Kernel modules that owned action checklists, loading mechanics, current repository measurements, Python module structure, transport procedure, or runtime handoff state.
  • Preserved stable Kernel module identities: retired numbers are not reused and reading order comes from each Standard's module index.

Machine contracts and generated projections

  • Added unique machine owners for Card and Read Set contracts, component paths, runtime object classes, audit obligations, evidence kinds, producer identities, module boundaries, and generated interfaces.
  • Centralized adopter runtime path spelling and object classification in the Tool layer while leaving actual .cambium values and history adopter-owned.
  • Rebuilt CLI, MCP, metadata, host, Card, Read Set, component, and distribution projections from their canonical owners.
  • Kept generated files as lower-authority outputs that fail when their source contracts drift.

Profile boundary

  • Kept the common Profile extension interface Kernel-owned.
  • Kept repository-specific decisions in the selected Profile.
  • Retained profiles/_template/ as the sole candidate template.
  • Removed profiles/examples/minimal-notes/, which had become a second default-answer source.
  • Updated Profile validation, typed dependency closure, layout contracts, examples, and onboarding material without creating a second minimal/full template hierarchy.

Kernel-to-Tool production closure

The dynamic adopter test exposed missing production paths behind existing Kernel obligations. This PR closes that chain without adding new review duties:

  • AuditPlan freezes the complete obligation definitions, target selectors, due stages, producers, evidence kinds, and acceptance contracts when a batch enters open.
  • L-tier pages use independent substantive review.
  • M-tier pages use the Kernel-owned Batch Review atomic checklist and do not receive a second substantive-review obligation.
  • S-tier samples are selected deterministically using the registered ceiling rule.
  • pre-merge review closes only obligations due before integration.
  • K12/09's eight deterministic close checks bind one shared post-Delta after-image.
  • dimensionless Gate evidence remains its native evidence kind instead of being disguised as an AuditReceipt.
  • closed consumers verify the complete immutable AuditPlan closure, including reuse and invalidation relationships.
  • tests derive expected obligations from Kernel-owned registries instead of copying the implementation under test.

Adoption and migration boundaries

  • Added an explicit component-path migration contract for the responsibility-aligned layout.
  • The old Card and Read Set paths are not current aliases; a bounded producer-era bridge can interpret frozen historical contract paths during an authorized adoption.
  • Standards authority is the exact upstream Git commit SHA. Unpublished semantic-version labels are not used as baseline identity.
  • Standards adoption never restamps or rewrites adopter-held Card bytes.
  • Existing plan, receipt, batch, and page history remains immutable; new authorization uses the current contracts and identities.
  • No active-attempt rebase, legacy-runtime replay, or indefinite compatibility layer is introduced.

Documentation, distribution, and licensing

  • Updated the English and Chinese README and Roadmap, repository navigation, contributor guidance, architecture diagrams, and Tool documentation.
  • Updated distribution and upstream-component boundaries for source distributions and carried adopter runtimes.
  • Preserved the CC BY 4.0 scope for Card and Read Set material after their top-level move.
  • Updated attribution and relicensing records where responsibilities moved between Kernel and Tool machine carriers.

Compatibility and review risk

This PR intentionally changes paths and tightens fail-closed machine contracts. Consumers that bypass the registered adoption and component-migration paths must update their references.

Missing Profile rendering contracts remain contract-gap/HOLD; the Tool layer does not invent renderer policy or record a fabricated pass.

The final diff contains 517 files because every canonical owner, consumer, fixture, test, generated projection, and documentation surface must agree on the same boundary. The recommended review order is:

  1. README.md, README.zh-CN.md, ROADMAP.md, and ROADMAP.zh-CN.md;
  2. top-level Card/ and Read Set/ plus their machine contracts;
  3. Kernel-owned Profile, audit, and runtime registries;
  4. Tool producers, consumers, and controlled writers;
  5. adoption and component-path migration;
  6. Profile single-template cleanup;
  7. compiled artifacts and tests.

Verification

Validated on PR head ca962884c5321f99c9e1df3b0866b27046e47c5a:

  • git diff --check origin/main...HEAD: pass.
  • Public-diff scan: no local paths, adopter task or receipt IDs, validation-branch names, ignored docs/ content, or unpublished semantic-version identity.
  • make check: pass.
    • repository layout: 571 tracked files and 109 CI-impact test mappings;
    • links: 219 Markdown files and 1,029 links, with 0 missing, ambiguous, or invalid heading targets;
    • Kernel size policy: pass across 118 leaves, 22 registered exceptions, and 2 leaves outside the default cap;
    • Card/Read Set projection: 13 curated Cards, 13 Read Sets, 2 indexes, 0 stale;
    • metadata execution contract: current;
    • source-distribution CLI contract: 56 tools, current;
    • MCP projection: 44 tools, current;
    • five host configuration projections: current;
    • selected example Profile: 14/14 interface slots valid;
    • batch-close structural errors: 0.
  • The exact-head full unit suite is assigned to the repository's required GitHub CI and must pass before merge.

Dynamic adopter validation

The final Cambium commit was bound into a clean real adopter runtime through production interfaces:

  • one representative L batch closed with 18 planned obligations;
  • one representative M/S batch closed with 58 planned obligations;
  • M pages produced Batch Review evidence and no independent substantive review;
  • each batch's eight K12/09 checks bound one post-Delta after-image;
  • three real pages passed strict Page Contract validation;
  • both batches remained closed, Queue remaining reached 0, and the task reached completion-candidate;
  • the adopter then formally bound the final Cambium commit without changing its Profile, route, Card, Read Set, governance predicates, or historical evidence;
  • upstream component closure reported 348 present components, 139 permitted omissions, and 0 errors;
  • carried-runtime CLI and MCP projections remained current.

The dynamic test stopped at Terminal Audit handoff. It did not run Terminal Proof and does not claim adopter corpus completion.

Out of scope

This PR does not:

  • extract task classification or route selection into a new subsystem;
  • replace the current Markdown or machine-contract storage formats;
  • decide package distribution, installation, marketplace delivery, or future interaction models;
  • migrate, replay, repair, or preserve compatibility with obsolete adopter runtime objects;
  • add generic active-attempt rebasing, concurrent execution, hard-interruption recovery, cold-state migration, or other runtime hardening;
  • complete optional renderer-specific Profile contracts;
  • run adopter Terminal Proof or claim corpus-wide completion;
  • add adopter-specific or task-specific behavior to Cambium production code.

@KimGLee KimGLee added bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request agent-interface Host-neutral agent interface: contract, projection, MCP server, per-host configs labels Aug 29, 2026
@KimGLee
KimGLee merged commit ee08bf6 into main Aug 29, 2026
24 checks passed
@KimGLee
KimGLee deleted the refactor/cambium-responsibility-realignment branch August 29, 2026 03:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-interface Host-neutral agent interface: contract, projection, MCP server, per-host configs bug Something isn't working documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cambium components have drifted into overlapping authority and incomplete production chains

1 participant