Architecture Boundary

Architecture Boundary

Layered Architecture

flowchart TD
    L0["GitHub source of truth<br/>issue, checklist, PR, CI, merge"] --> L1["Governance harness<br/>context start, edit gate, finish gate"]
    L1 --> L2["Preview repository<br/>scripts, policies, skills, templates, docs, tests"]
    L2 --> L3["Runtime contract anchor<br/>agent-governance-runtime v0.1.1"]
    L2 --> L4["Context aids<br/>qmd, Hermes, Graphify, runtime projections"]
    L2 --> L5["Public validation seam<br/>compileall, pytest, GitHub Actions, CodeQL"]
    L3 -. "private wheel access required" .-> L6["Private runtime release asset"]
    L4 -. "advisory only" .-> L1
    L5 --> L0

    classDef authority fill:#172554,stroke:#60a5fa,color:#ffffff
    classDef preview fill:#064e3b,stroke:#34d399,color:#ffffff
    classDef private fill:#7f1d1d,stroke:#f87171,color:#ffffff
    classDef advisory fill:#3f3f46,stroke:#a1a1aa,color:#ffffff
    class L0,L1 authority
    class L2,L5 preview
    class L3,L6 private
    class L4 advisory

Loading

The diagram separates authority from context. GitHub readback and the harness gate decide whether work may proceed. qmd, Hermes, Graphify, runtime projections, and Wiki pages can explain or recover context, but they do not grant edit authority by themselves.

Responsibility Map

• README.md and docs/: public reviewer contract and project orientation
• scripts/: CLI entrypoints and governance workflow implementation
• policies/: policy source used by generated agent shims
• registry/skills/: reusable skill instructions for engineering workflows
• templates/shims/: generated shim contract and template material
• tests/: public validation seam for the sanitized preview
• GitHub remote: publication boundary and CI readback

Dependency Direction

The preview repository is self-contained. Runtime and documentation must not depend on:

• the private source checkout
• source Git history
• private issue or pull request state
• local machine paths
• local task cache files

The preview may describe the governance model, but public validation must run from the preview checkout itself.

flowchart LR
    Preview["agent_bootstrap-preview"] --> Scripts["scripts"]
    Preview --> Policies["policies"]
    Preview --> Skills["registry/skills"]
    Preview --> Templates["templates/shims"]
    Preview --> Docs["README and docs"]
    Preview --> Tests["public tests"]

    Scripts --> RuntimeAnchor["runtime contract anchor"]
    RuntimeAnchor -. "private release asset" .-> RuntimeWheel["agent-governance-runtime wheel"]

    GitHub["GitHub issue and release readback"] --> Preview
    Tests --> GitHub

    PrivateState["private issues, local state, completion ledgers"] -. "excluded" .- Preview

Loading

Test Seam

The public smoke tests validate that:

• the CLI help command runs
• required reviewer-facing files exist
• private artifact directories are absent
• common long credential-like token forms are not present in tracked text files

Scope Map

• Selection: public-safe scripts, policies, registry skills, templates, docs, tests
• Sanitization: removal or rewriting of source repo URLs, local paths, private evidence markers, and generated artifacts
• Validation: local pytest, whitespace check, targeted sensitive-string scans, and GitHub Actions
• Publication: clean preview commits pushed to the public preview repository

Residual Risk

The public preview is intentionally narrow. It contains smoke tests rather than the full private operational test corpus. Future public hardening can add broader behavioral tests after any private-only fixtures are replaced with public fixtures.