# Atomic Knowledge Unit Standard

Code Factory is designed around Knowledge Activation: convert private
institutional knowledge into compact, executable guidance that an agent can use
at the moment of action.

The practical unit is the Atomic Knowledge Unit, or AKU. An AKU is not a wiki
page. It is a small, action-ready skill with deterministic checks.

## Why AKUs

Generic agents know public patterns, not your private architecture, deployment
rituals, compliance rules, or team conventions. Without explicit activation,
they guess, fail, get corrected, and fill the context window with noise.

AKUs reduce that tax by optimizing for knowledge density:

```text
value for this task / token cost
```

High-density AKUs give the agent the exact operating rules without dumping long
manuals into the prompt.

## Seven-Part Schema

Every durable Code Factory skill should have these seven parts:

| Part | Purpose |
|---|---|
| Intent | When this unit should activate. |
| Procedure | The ordered steps the agent follows. |
| Tools | Exact CLIs, APIs, files, or functions it may use. |
| Metadata | Owner, service, environment, tier, and source of truth. |
| Governance | Permission boundaries, blast radius, compliance constraints. |
| Continuations | Where to route next on success, failure, or escalation. |
| Validators | Deterministic pre, post, and invariant checks. |

## How The Five Repos Map

```mermaid
flowchart LR
    A["Codify tacit knowledge"] --> B["1 SpecLine<br/>strict AKU inputs"]
    B --> C["Compress into task packets"]
    C --> D["2 ForgeLine<br/>state machine and review gates"]
    D --> E{"Artifact type"}
    E -->|"Decision workflow"| F["3 HSF<br/>compiled static code"]
    E -->|"Public UI"| G["4 Prestige<br/>design trust gate"]
    F --> H["Receipts, badges, validators"]
    G --> H
    H --> I["Baseplate<br/>activation and metering"]
    I --> J["VS Code + JetBrains\nlocal control surfaces"]
    classDef knowledge fill:#e0f2fe,stroke:#0284c7,color:#10233f
    classDef planning fill:#fef3c7,stroke:#d97706,color:#10233f
    classDef build fill:#dcfce7,stroke:#16a34a,color:#10233f
    classDef proof fill:#ccfbf1,stroke:#0f766e,color:#10233f
    classDef editor fill:#ede9fe,stroke:#7c3aed,color:#10233f
    class A knowledge
    class B,C planning
    class D,E,F,G build
    class H,I proof
    class J editor
```

## Governance Gradient

| Level | Required evidence | Good fit |
|---|---|---|
| Human-controlled | Minimal validators; human signs each step. | Production-risky or irreversible changes. |
| Supervised | Pre/post validators plus human checkpoints. | Staging, medium-risk changes, new AKUs. |
| Autonomous | Pre, post, and invariant validators with clean history. | Reversible, repeated, well-tested workflows. |

The rule is simple: more autonomy requires more deterministic evidence.

## AKU: Content-addressed validation reuse

**Intent.** Activate when an already-completed, read-only validation may be
relevant to the exact current source, toolchain, environment, and outputs.

**Procedure.** Declare a `factory.proof-request.v1` manifest; record the green
run; route the next request with `factory proofs plan`; independently verify or
challenge any REUSE receipt; then review the paired savings receipt when one
was requested. Ambiguous or incomplete evidence routes to RUN.

**Tools.** `factory proofs record`, `plan`, `verify`, and `challenge`; local
files under `.factory/proofs/` and `.factory/savings/`; SHA-256 hashing.

**Metadata.** Owner: repository maintainer. Version: 1. Schemas:
`factory.proof-request.v1`, `factory.proof-receipt.v1`, and
`factory.proof-plan.v1`. Source of truth: the request plus hash-bound receipt.

**Governance.** Supervised. Only explicitly read-only gates qualify. This AKU
may read workspace files and write local receipts; it cannot execute the gate,
publish, deploy, sign, approve, use credentials, or send external messages.

**Continuations.** REUSE continues to receipt review; SKIP continues only with
reviewed relevance; RUN returns to the declared validator; BLOCK escalates the
unsafe or malformed request to a human.

**Validators.** Pre: paths are regular files inside the workspace and the gate
is read-only. Post: receipt self-hash, proof key, inputs, and outputs verify.
Invariant: an isolated input mutation invalidates reuse, and unknown token
observations remain null rather than estimated.

## Topology

AKUs should compose into a navigable topology:

- Registry answers: what units exist?
- Topology answers: what comes next?
- Activation policy answers: may this agent use this unit here?

That topology is the long-term shape of Code Factory: many small, validated
units that route agents through paved lanes.
