Skip to content

KERNEL_SNAPSHOT.md

Latest commit

 

History

History
439 lines (333 loc) · 19.7 KB

KERNEL_SNAPSHOT.md

File metadata and controls

439 lines (333 loc) · 19.7 KB
id SNAPSHOT-TPL-KERNEL-001
title Kernel Snapshot v3.3.15
template_version 3.3.15
doc_type status
status published
audience maintainers, platform-engineers, forks
tags
kernel
baseline
release
stories
US-TPL-PLT-001
requirements
REQ-PLT-DOCS-CONSISTENCY
REQ-TPL-OPINIONATED-DEFAULTS
acs
AC-PLT-009
AC-PLT-010
AC-TPL-OPINIONS-DOCUMENTED
adrs
ADR-0005
last_updated 2026-02-20

Kernel Snapshot v3.3.15

Kernel Baseline: v3.3.9-kernel

This snapshot describes the kernel at tag v3.3.9-kernel. For machine-readable details, see release_evidence/kernel_contract.v3.3.15.json. For AC-level status, see docs/feature_status.md. For adoption instructions, see docs/how-to/adopt-kernel.md.

Last Updated: 2026-02-20 | Template Version: v3.3.15 | Kernel Baseline: v3.3.9-kernel

Executive Summary

This is the frozen kernel baseline (v3.3.9-kernel) for the Rust-as-Spec platform template. All kernel acceptance criteria pass. All selftest gates pass. Day-0 commands work as documented. This is a stable, forkable baseline.

v3.3.9 highlights:

  • Zero kernel unknowns – All 72 kernel ACs now have test evidence (unit or BDD mappings). KERNEL_UNKNOWN_BUDGET=0 is enforced in CI. See ADR-0024 for the evidence model.
  • Manifest-driven versioning – specs/version_manifest.yaml + versioning engine ensures all version-bearing files are updated atomically via release-prepare
  • Versioning ACs enforced – AC-TPL-VERSION-MANIFEST, AC-TPL-VERSION-DRYRUN, AC-TPL-VERSION-ATOMIC are now kernel contracts
  • IDP-ready platform contract – /platform/status and /platform/docs/index are stable, documented kernel contracts
  • OpenAPI spec – specs/openapi/openapi.yaml includes platform schemas (PlatformStatus, DocsIndex) with 500 error responses
  • TypeScript configuration governance – scripts/validate-ts-config.sh + CI job enforce modern TS standards
  • Backstage reference consumer – examples/backstage-plugin/ demonstrates IDP integration patterns

Note: "Selftest green" means the template meets its own specifications. It does not mean every use case has been validated in production. See ROADMAP.md for known gaps.

AC Status

For current AC counts and per-AC status, see the canonical sources:

These files are regenerated by cargo xtask ac-status and validated by docs-check. Do not rely on manually-maintained AC counts in this snapshot.

Quick verification:

cargo xtask ac-status    # Regenerate and view AC status
cargo xtask selftest     # Full governance validation

Key Kernel Contracts (v3.3.9)

Philosophy & Governance:

  • AC-TPL-BDD-EXIT-CODES: BDD harness exit codes distinguish test failures from skipped tests
  • AC-TPL-FORKS-STATUS-SUMMARY: Fork registry visible in /platform/status
  • AC-TPL-ARTIFACTS-HAVE-REFS: Governance artifacts support refs field for REQ/AC traceability
  • AC-TPL-CLI-JSON-CORE: version and ac-status support --json for AI/IDP integration

Environment & Testing:

  • AC-PLT-001: cargo xtask doctor validates Rust, Nix, conftest, git
  • AC-PLT-020: BDD test execution and reporting (cargo xtask bdd)
  • AC-PLT-NIX-DEVSHELL: Nix devshell provides reproducible environment

Platform APIs:

  • AC-PLT-015: Platform introspection endpoints (/platform/status, /graph, /docs/index)
  • AC-PLT-019: Task management via HTTP (GET /tasks, PATCH /tasks/{id}/status)
  • AC-TPL-PLATFORM-GOVERNANCE-APIS: Governance APIs (/friction, /questions, /forks)
  • AC-TPL-PLATFORM-SCHEMA: Machine-readable OpenAPI contract at /platform/openapi

IDP Integration:

  • /platform/status returns PlatformStatus JSON matching OpenAPI schema
  • /platform/docs/index returns DocsIndex JSON matching OpenAPI schema
  • examples/backstage-plugin/ provides a TypeScript reference consumer
  • Contract details: docs/reference/platform_api_contract.md

IDP Profile

For IDP teams: See docs/IDP_CELL_CONTRACT.md for the complete integration datasheet.

The following surfaces constitute the IDP contract - what an IDP can rely on:

Surface Contract Description
/platform/status AC-PLT-015 Governance health, AC coverage, selftest gates
/platform/docs/index AC-PLT-015 Documentation inventory with health
/platform/graph AC-PLT-015 REQ/AC/test/doc relationships
/platform/tasks AC-PLT-019 Task management with filters
/platform/schema AC-TPL-PLATFORM-SCHEMA Schema index (JSON Schema + endpoint list)
/platform/openapi AC-TPL-PLATFORM-SCHEMA OpenAPI spec
cargo xtask idp-snapshot AC-TPL-IDP-SNAPSHOT Machine-readable tile data

Invariants an IDP can trust:

  • tier1-selftest green = kernel contracts intact
  • idp-snapshot outputs valid JSON with all required keys
  • Kernel tags (vX.Y.Z-kernel) freeze these contract shapes
  • Template tags may add features but won't break IDP surfaces

Kernel vs Template Defaults

This table clarifies which ACs are enforced kernel contracts (must stay must_have_ac: true) vs template defaults (enabled here but forks can demote via must_have_ac: false):

Category Kernel ACs (Enforced) Template Defaults (Can Demote)
JSON CLI AC-TPL-CLI-JSON-CORE AC-TPL-CLI-JSON-OUTPUT
Artifacts & refs AC-TPL-ARTIFACTS-HAVE-REFS –
Fork visibility AC-TPL-FORKS-STATUS-SUMMARY –
Governance artifacts – AC-TPL-GOV-FRICTION, AC-TPL-GOV-FORKS
BDD harness AC-TPL-BDD-EXIT-CODES –

Override path: See docs/how-to/change-template-opinion.md for detailed instructions on promoting or demoting ACs in your fork

For full AC type classification (Kernel/Template/Meta) and detailed guidance: See docs/feature_status_notes.md §5.

Philosophy Contracts (Summary)

These REQs encode the template's opinionated stance. They define how the platform cell behaves, not just what it does:

REQ ID What It Enforces Default ACs
REQ-TPL-OPINIONATED-DEFAULTS Opinions live as testable ACs, not tribal knowledge AC-TPL-OPINIONS-DOCUMENTED
REQ-TPL-OVERRIDE-PATH Forks change ACs/tests, not CI hacks AC-TPL-OVERRIDE-DOC, AC-TPL-OVERRIDE-TRACEABLE
REQ-TPL-AI-IDP-COMPAT AI/IDP surfaces are first-class, not afterthoughts AC-TPL-CLI-JSON-CORE, AC-TPL-PLATFORM-GOVERNANCE-APIS
REQ-TPL-BDD-HARNESS Deterministic exit codes for CI and agents AC-TPL-BDD-EXIT-CODES
REQ-TPL-FLOW-IDEMPOTENCY Platform flows are safe to rerun AC-TPL-FLOW-IDEMPOTENT
REQ-TPL-GRAPH-INVARIANTS Every REQ has an AC, every AC has a test AC-TPL-GRAPH-REQ-HAS-AC, AC-TPL-GRAPH-AC-HAS-TEST

Why this matters: When you fork, these philosophy contracts carry over. If you want different behavior (e.g., no JSON CLI requirement), you explicitly demote the AC in your fork's spec_ledger.yaml. This keeps "what we enforce" visible in spec, not buried in CI config.

Cross-reference: docs/how-to/pre-fork-checklist.md → Phase 5: Choose Your Opinionation Level

Note on ID prefixes: IDs with TPL prefixes are part of the template family. Kernel vs template default is controlled by must_have_ac, not the ID prefix. An AC like AC-TPL-ARTIFACTS-HAVE-REFS with must_have_ac: true is kernel; one with must_have_ac: false is a template default.

Key Capabilities

Runtime & APIs:

  • Service health, version, metrics endpoints
  • Platform introspection APIs:
    • /platform/graph - Full governance graph (REQ/AC/test/doc relationships)
    • /platform/devex/flows - Canonical DevEx flows and commands
    • /platform/docs/index - Documentation inventory (with doc health info)
    • /platform/schema - Schema index (JSON Schema + endpoint list)
    • /platform/openapi - OpenAPI contract
    • /platform/status - Governance health metrics (includes policy status)
  • JSON contracts & schemas:
    • CLI commands support --json output for AI/IDP integration
    • HTTP endpoints return structured JSON conforming to documented schemas
    • Reference: docs/explanation/json-contracts.md for CLI and HTTP specifications
  • Task management APIs:
    • /platform/tasks - Task listing with filters (status, requirement)
    • /platform/tasks/{id}/status - Update task status via HTTP
    • /platform/agent/hints - Prioritized task suggestions for agents
  • Friction & questions APIs:
    • /platform/friction - Friction log entries with statistics
    • /platform/friction/{id} - Individual friction entry details
    • /platform/questions - Question artifacts with status filtering
    • /platform/questions/{id} - Individual question details
  • Fork tracking APIs:
    • /platform/forks - Fork registry with all registered forks
    • /platform/forks/{name} - Individual fork entry details
  • Platform UI dashboard:
    • Interactive graph visualization using Mermaid.js
    • Flows and tasks view
    • Platform health status
  • Configuration validation and IAC alignment (Docker Compose, Kubernetes, Terraform)
  • Task lifecycle and governance write operations

DevEx CLI:

  • Development flows:
    • doctor - Environment validation (Rust, Nix, conftest, git)
    • help-flows - Flow-based command map from specs/devex_flows.yaml
    • check - Fast dev loop (fmt + clippy + tests)
    • test-changed - Run tests affected by git changes
    • ac-status - AC coverage report (supports --json)
    • ac-coverage - Show which ACs need BDD scenarios
    • dev-up - One-command bootstrap (doctor + install-hooks + check)
  • Bundler & agent tools:
    • bundle - Generate LLM context bundles for tasks
    • suggest-next - Task-aware next-step suggestions
  • Governance:
    • adr-new - Create numbered ADR from template
    • ac-new - Create new acceptance criterion with validation
    • docs-check - Validate version alignment across spec_ledger, README, CLAUDE
    • graph-export - Export dependency graph (Mermaid format)
    • selftest - Full template self-test suite (8 gates)
    • kernel-smoke - Quick validation (docs-check + selftest)
    • install-hooks - Install pre-commit governance hooks
    • skills-fmt - Format Agent Skills (SKILL.md)
    • skills-lint - Lint Agent Skills (SKILL.md)
  • Artifact management:
    • friction-new - Create new friction log entry
    • friction-list - List friction entries (with filters, supports --json)
    • question-new - Create new question artifact
    • questions-list - List questions from questions/ directory (supports --json)
  • Fork tracking:
    • fork-register - Register a new template fork
    • fork-list - List registered forks (supports --json)
    • version - Show kernel/template version (supports --json)
  • Task management:
    • tasks-list - List tasks from specs/tasks.yaml
    • task-create - Create new task with validation
    • task-update - Update task fields (status, title, owner)
  • Release management:
    • release-prepare - Bump versions, update changelog
    • release-bundle - Generate release evidence with AC deltas (creates release_evidence/vX.Y.Z.md and release_evidence/kernel_contract.vX.Y.Z.json)
    • release-verify - Full release validation (selftest + audit + docs-check)
  • Operational:
    • audit - Security audit (cargo-audit + cargo-deny)
    • sbom-local - Generate SPDX JSON SBOM
    • ci-local - Full CI simulation (doctor + selftest + audit + docs-check)
    • status - Governance status dashboard
    • config-validate - Validate config schema for an environment

Governance:

  • BDD acceptance tests (see docs/feature_status.md for current counts)
  • Graph invariants for REQ/AC/test/doc relationships
  • Policy tests via conftest
  • Pre-commit hooks and markdown hygiene
  • AC/ADR bidirectional mapping
  • Document type contract validation:
    • Enforces 11 doc_type classifications (how_to, explanation, design_doc, reference, status, adr, guide, impl_plan, requirements_doc, ci_workflow)
    • Structural expectations per doc_type (frontmatter, required fields)
    • Validated by cargo xtask docs-check
    • Reference: docs/reference/doc-sources.md §6.5
  • Agents governance:
    • Agents defined in .claude/agents/*.md with governed YAML frontmatter
    • Validated by cargo xtask agents-lint for name format, descriptions, tools, model policy, skill references
    • Template: docs/AGENTS_TEMPLATE.md, governance rules: docs/AGENTS_GOVERNANCE.md
  • Skills as governed artifacts:
    • .claude/skills/*/SKILL.md are governed workflow recipes with frontmatter validation
    • Validated by cargo xtask skills-lint and formatted by cargo xtask skills-fmt
    • Five recommended skills: bootstrap-dev-env, governed-feature-dev, governed-maintenance, governed-release, governed-governance-debug
    • Template: docs/SKILLS_TEMPLATE.md, governance rules: docs/SKILLS_GOVERNANCE.md

Verification

cargo xtask doctor       # Environment validated
cargo xtask selftest     # All gates pass
cargo xtask ac-status    # View current AC status
cargo run -p app-http    # Listening on :8080

Note: Some ACs are intentionally "unknown" (meta/CI-only contracts). See docs/feature_status_notes.md for:

  • The list of soft/meta ACs and their reasoning
  • The @ci-only testing pattern
  • AC type classification (kernel vs template vs meta)

Detailed AC statuses: docs/feature_status.md

Fork Readiness

The template is ready to fork. Services inheriting from v3.3.9-kernel get:

  • Runtime, APIs, and UI that pass their ACs
  • DevEx tooling for agents and humans
  • Governed workflows with BDD acceptance tests
  • Continuous governance validation via selftest
  • Agent-friendly documentation and bundler

Known gaps (documented in ROADMAP.md):

  • Branch protection not configured (manual GitHub setting required - documented in docs/how-to/setup-branch-protection.md)
  • Tag signing not configured (manual GPG setup required - documented in docs/how-to/setup-tag-signing.md)
  • Template not yet validated by a second service

Recently completed (v3.3.5 polish):

Documentation:

  • ✅ IDP positioning documentation (docs/explanation/idp-positioning.md)
  • ✅ Brownfield adoption guide (docs/guides/brownfield-adoption.md)
  • ✅ Fork feedback workflow (docs/how-to/report-fork-feedback.md)
  • ✅ Quick start guide (docs/QUICKSTART.md)
  • ✅ Troubleshooting guide (docs/TROUBLESHOOTING.md)
  • ✅ Windows development guide (docs/how-to/windows-development.md)
  • ✅ CI workflows reference (docs/reference/ci-workflows.md)
  • ✅ Branch protection setup (docs/how-to/setup-branch-protection.md)
  • ✅ Tag signing setup (docs/how-to/setup-tag-signing.md)
  • ✅ Safe doc change workflow (docs/how-to/change-docs-safely.md)

Operational Tooling:

  • ✅ Questions-as-artifacts (cargo xtask question-new, questions-list)
  • ✅ Friction log API (GET /platform/friction, /platform/friction/{id})
  • ✅ Friction CLI (cargo xtask friction-new, friction-list)
  • ✅ Fork registry (cargo xtask fork-list, fork-register)
  • ✅ Version command (cargo xtask version with --json support)
  • ✅ Release AC deltas in release-bundle
  • ✅ Branch protection script (.github/scripts/setup-branch-protection.sh)

Fixes:

  • ✅ BDD test isolation (tests no longer pollute tracked files)
  • ✅ ADR numbering duplicates resolved

The first real fork will likely discover friction. Capture it in FRICTION_LOG.md and consider feeding systematic issues back to the kernel.

Kernel v3.3.5 Closure

Status: Frozen baseline. Feature-complete for 1.0.

This version represents the first fully selftest-green, opinionated LLM-native Rust cell ready for production forks.

See docs/reference/doc-sources.md for how generated and hand-authored docs are kept aligned.

What This Means

✅ Kernel is closed – The core governance infrastructure (specs, BDD, policies, platform APIs) is stable and tested.

✅ Ready for forks – New services can clone this template and inherit a governed, production-ready skeleton in ~20 minutes.

✅ AI-native workflows enabled – Agents and IDPs have first-class contracts: /platform/* APIs, CLI JSON output, task hints, flow guidance.

What's NOT in v3.3.5

Intentionally out of scope:

  • Zero-UNKNOWN AC mode: The meta/CI ACs remain UNKNOWN by design (they test the testing infrastructure, not domain behavior). This is honest and transparent.
  • Renumbering AC IDs: Kernel IDs are frozen to avoid breaking downstream forks.
  • Portal vendor lock-in: /platform/* contracts are generic. Let portals adapt.

Higher-layer responsibilities (out of scope)

These concerns are intentionally left to the platform that embeds this cell:

  • Authentication & authorization – This template assumes you terminate auth at a gateway or platform layer. It does not ship multi-tenant auth, RBAC, or token validation.
  • SLOs and performance targets – The kernel validates correctness and governance. Latency, throughput, and SLOs are defined and enforced by the consuming platform.
  • Full observability stack – Basic logging is present. Metrics, tracing pipelines, and dashboards live in the platform. Forks may add REQs/ACs to tighten this where needed.

Forks can introduce domain-specific REQs/ACs for these areas, but the kernel contract remains platform-agnostic.

Known gaps (documented, not blockers):

  • ROADMAP.md and BACKLOG.md catalog what's next
  • Second-service validation pending (first fork will inform this)
  • Branch protection rules are template scripts, not enforced by CI

Next: Version 3.4.0

Further kernel evolution will be driven by:

  1. Real fork experience – The Knowledge Hub fork and other real-world uses will surface friction
  2. IDP integration patterns – Lessons learned from Backstage/Port integrations
  3. Supply chain hardening – Dependency health, SBOM evolution, policy refinements

File issues with refs: AC-XXX tags to feed findings back. See ROADMAP.md for the forward plan.

Using v3.3.5

  • If you're forking: Start here. Follow docs/how-to/FIRST_FORK.md.
  • If you're contributing to kernel: Code is frozen. New features go to v3.4.0 planning track.
  • If you're running this as-is: Perfect for reference implementations and policy validation.

Changing the Kernel After v3.3.9-kernel

The kernel contracts (must_have_ac=true ACs, /platform/* APIs, xtask governance commands) are frozen at the v3.3.9-kernel tag.

Any change that:

  • Flips must_have_ac on a kernel AC
  • Changes /platform/* response shapes
  • Changes xtask's DevEx / selftest contracts

must:

  1. Add or update an ADR (see AC-PLT-AC-DEMOTION-GOVERNED)
  2. Bump Template Version in specs/spec_ledger.yaml
  3. Regenerate docs/feature_status.md and release_evidence/*
  4. Cut a new v3.3.X-kernel tag

This keeps kernel changes traceable through ADRs and explicit version bumps. See ADR-0005 for the rationale behind governed version management.

End of Kernel Snapshot