简体中文

Architecture Boundaries

This page is the stable architecture projection of Skill Family Foundation for users. It explains only structure, responsibilities, boundaries, and routing; it does not carry dynamic release state (release state is recorded solely in docs/status/current.md and mechanically verified by scripts/docs/fact-check.mjs). All versions, commands, package counts, and support states are recomputed from the machine source of truth.

Layers

The layering established by the 2026-08-09 architecture hand-off (FND-ADR-001~007, active, see artifacts/decisions/): a vertical dependency chain of four layers, with horizontal capability attachments, and no new vertical layers added.

Skill Family business (per-product repositories: release-skill, loop-agent, skill-eval, etc.)
        │ depends on
        ▼
Engineering Kit (scaffold / adopt-plan / projection / check)
        │ depends on
        ▼
Harness Node (Contracts mechanism-protocol implementation)
        │ depends on
        ▼
Contracts (structure, protocols, error codes, protocol-name registry)
        ▲
        └---------------- independent Audit consumer

Horizontal (attachment surfaces, no new vertical layers):
- profiles/       declarations of host and project-shape differences; implements only the stable SPI
- host            external AI coding runtime environment: owns semantics; Foundation unifies structural differences
- release-skill   release state and all remote writes; does not enter Foundation
- Artifact Graph  the `artifacts/` architecture artifact system; its gate is check:artifacts

Arrows point to the depended-upon party. The public core must not depend in reverse on a concrete Profile or a concrete skill family; where a new capability's dependency direction lands is specified in artifacts/design/FND-DES-001.md, and asset-by-asset ownership is in FND-ADR-002.

Responsibility Matrix

Each layer assumes only the responsibilities listed below; out-of-scope capabilities are owned by external projects or consumers.

Layer	Owns	Does not own (lands elsewhere)
Contracts	Structure, protocols, error codes, protocol-name registry; 37 top-level object kinds; 9 mandatory rules	Business-field semantics, domain auditing, remote writes, model generation
Harness	Node mechanism implementation of Contracts; path containment, atomic write, closures, request handling, report rendering, host-access mechanism, state substrate	Business semantics, workflow orchestration, model invocation, git writes, network remotes
Engineering Kit	The four engineering commands and their read-only / restricted-write boundaries; host sub-action injection of concrete Profiles	Auto-fix, auto-migration, remote release, a fifth command
Profile	Declarative SPI for host and project-shape differences; implements only the stable SPI	Business semantics, executable-script entry points, public-core changes
release-skill	Release state and all remote writes	Foundation contains no publish/remote-write entry point
loop-agent	Tasks, retries, rework, acceptance, self-iteration	Foundation does not define a workflow state machine
Artifact Graph	Artifact relationships, context, packet, version-lock	Foundation does not own the artifact graph
Audit	Independent fixtures, expected values, adjudication	Domain-semantic conclusions are owned by external review

Capability Ownership Algorithm

Given an architecture requirement, decide ownership in the following order, stopping at the first match:

1. Contains domain semantics, a business state machine, or an audit oracle → keep it with the consumer; connect only business-neutral mechanisms.
2. Is structure, a protocol, a stable error code, or an object Schema → Contracts.
3. Is a Node mechanism reusable across skill families → Harness.
4. Is scaffold/adopt-plan/projection/check or a concrete host Profile injection → Kit / Profile.
5. Involves publishing remote state → release-skill.
6. Involves tasks/retries/rework/acceptance → loop-agent.
7. Involves artifact relationships / version-lock → artifact-graph.
8. Has only one consumer, or has not been proven to repeat across two real consumers → keep it with the consumer; do not expand Foundation.

Step 8 is the expansion gate: a new component must justify that deleting it would force two or more real consumers to re-implement it, and this must be verified by an independent fixture; admission gate 1 additionally requires at least one existing real consumer plus one structurally isomorphic foreseeable consumer (the second consumer need not be live, but its need must be expressible with the same structure; adjustment record in FND-ADR-009). Step 9 is the finite-closed-semantics gate (FND-ADR-001 gate 8): a capability carrying limited domain semantics must satisfy either — its semantics are covered by a small stable closed enumeration, or it is a deterministic estimation primitive whose algorithm, scope, and bias direction are declared in the contract; this gate does not cancel gate 2's "semantics-free" veto. The machine-readable version is in docs/agents/architecture-routing.md.

Trust and Side-Effect Boundaries

Foundation's trust assumptions and side-effect conventions are solidified per layer; callers judge risk accordingly:

• Contracts: pure functions, no file/Git/network/process side effects; error codes are frozen and do not drift (foundation.contracts.error-codes).
• Harness: the mechanism layer reads and writes only within contained paths; HARNESS_EXCLUSIONS excludes release-state, remote-network-access, business-semantics, workflow-orchestration, model-calls, git-writes (foundation.harness.errors).
• Engineering Kit: FORBIDDEN_SIDE_EFFECTS includes git-init/commit/push/tag, publish, remote-write; REFUSED_MUTATION_FLAGS are refused at the CLI entry point (foundation.kit.cli).
• Profile: declarative differences; the entry point must be a JSON data resource; coreOwned (packages/commands/namespacePrefixes) is a forbidden target (foundation.profile.extension-spi).
• State substrate: the event log is the sole authority, and the snapshot is a derived cache; confirmOwnerTerminated is an external trust anchor provided by the caller, and does not promise resistance against same-privilege malicious processes (foundation.harness.state-store).

Architecture Decision Tree

Requirement contains domain semantics/state machine/audit? ──yes──▶ keep with consumer
        │no
Is it structure/protocol/error code/Schema? ──yes──▶ Contracts
        │no
Is it a Node mechanism across skill families? ──yes──▶ Harness
        │no
Is it scaffold/adopt/projection/check or Profile injection? ──yes──▶ Kit / Profile
        │no
Involves publishing remote state? ──yes──▶ release-skill
        │no
Involves tasks/retries/rework/acceptance? ──yes──▶ loop-agent
        │no
Involves artifact relationships/version-lock? ──yes──▶ artifact-graph
        │no
Only one consumer / not proven across two real consumers? ──yes──▶ keep with consumer, do not expand
        │no
Carries limited domain semantics? ──yes──▶ finite closed semantics: covered by a
         │                stable closed enumeration, or a deterministic estimation
         │                primitive (algorithm/scope/bias declared in the contract)
         │                → admissible; otherwise keep with consumer
         │                (FND-ADR-001 gate 8; does not cancel gate 2's veto)
         │no
        ──▶ admissible

Routing Relationships with External Projects

Foundation is not an all-powerful base. The following responsibilities are explicitly outside Foundation:

• Release and remote writes: owned by release-skill; Foundation provides no publish/remote-write entry point (foundation.unsupported.remote-publish).
• Task lifecycle: owned by loop-agent (tasks, retries, rework, acceptance); Foundation contains no workflow state machine (foundation.unsupported.business-state-machine).
• Artifact governance: artifact-graph owns the artifacts/ relationship contract and version-lock; its gate is check:artifacts.
• Domain auditing: an independent audit consumer owns the semantics and final accept/reject; Foundation provides only a deterministic audit surface (foundation.unsupported.domain-audit-semantics).
• Host apply and lifecycle: the package API applyHostPlan supports digest-bound local install/update for registered supported hosts. Executing an uninstall plan returns manual-recovery-required without deleting files. The four-command Kit CLI, generic or remote apply, and the full Qoder driver remain unsupported (foundation.unsupported.host-apply, foundation.unsupported.host-install-update-uninstall, foundation.unsupported.qoder-driver).

Capability Identity and Maturity

Capability identity and maturity are separate dimensions (FND-ADR-016). Consumers of historical ./candidate/** entrypoints migrate once to the canonical entrypoints introduced in 0.10.0, while the old entrypoints remain same-source compatibility surfaces during deprecation. Capabilities introduced from 0.10.0 onward use their final canonical entrypoint, Schema $id, and operation from the first candidate release. Stable promotion changes the compatibility promise only and does not trigger another source or contract-identity migration. A consumer must still update all three exact package pins to obtain a newly published stable promise. Existing package-identity, source-digest, and provenance bindings continue to determine whether a Bundle rebuild is required; the maturity label does not add a separate rebuild condition.

The physical candidate/ directory is not an architecture layer and does not determine public stability. The Contracts machine policy and capability-catalog stability field are authoritative. Removing a historical entrypoint requires a separate major-version decision and consumer-exit evidence; it cannot be bundled into promotion.

Next-Phase Capability Lines (Architecture Hand-off)

All three capability lines were included via the FND-ADR-001 capability admission-gate adjudication and all land within the existing layers:

• Host-access line (FND-FR-001/FND-FR-002/FND-FR-008/FND-FR-009): Contracts registers descriptor/source/manifest/probe/plan/receipt and peer-verification request/result; Harness implements generic source closure, atomic build/materialize, probe classification, and read-only peer verification; Kit injects the concrete Profile and trusted driver. The package API supports bounded local install/update through applyHostPlan; uninstall execution remains non-destructive and requires manual recovery. Kit CLI apply and generic or remote apply remain refused.
• Durable state-substrate line (FND-FR-003, FND-ADR-004): append-only events, hash chain, snapshots, and verification recovery; provides only the state substrate, not business semantics such as state machines, task nodes, retries, terminal states, or memory.
• Human-report line (FND-FR-004, FND-ADR-005): a two-layer contract — machine results are the sole source of truth, and the human report is deterministically rendered from machine results (Markdown + digest binding + graded checks), not freely authored.
• Finite-closed-semantics tools line (FND-ADR-009): baseline materialization + contentGuard (digest mismatch, mid-materialization change, and guard rejection all fail closed), generic read chokepoint (allowed-root set + optional identity predicate), strategy-driven surface scan (policy contract + injection self-test), token upper-bound estimation (deterministic estimation primitive with no model/network/tokenizer dependency), and a generic upper-bound guard (reusing the state-store event ledger and token-lock; the bound and over-limit policy are consumer-configured).

The three-package structure is preserved and a fourth package is not split out (FND-ADR-007); artifact governance uses the artifact-graph CLI and version-lock (FND-ADR-006).

First-Version Budget

• Top-level Contracts objects: 42 kinds, including the three 1.13.0 candidate objects plugin-verification-request, plugin-verification-result, and filesystem-tree-observation, with packages/skill-family-contracts/src/registry.json as the sole source of truth;
• Kit top-level commands: 4 (scaffold, adopt-plan, projection, check);
• Mandatory mechanical rules: currently 9, budget not exceeding 20, absolute ceiling 30; CR-001 uniformly compiles all Schemas within the registry;
• Leaf packages: 3 (skill-family-contracts, skill-family-harness-node, skill-family-engineering-kit);
• Schema validator: Ajv 8.20.0 (exact version pin), supporting both draft-07 and 2020-12 dialects;
• kernel protocol: skill-family.kernel.operation (stable), Contracts specification 1.13.0; the Kernel document remains at its 1.8.0 lifecycle coordinate and byte baseline;
• Default runtime language: Node; first-version implementations in a second language: 0.

Any new component must justify the two-or-more real-consumer re-implementation that deleting it would cause, and be verified by an independent fixture.

Machine Source of Truth and File Classification

Source of truth	Content
.foundation/skeleton-manifest.json	Package manifest, Profiles, fixtures, top-level commands
.foundation/version-lock.json	Exact versions and lock points for projen, pnpm, Node
.foundation/file-registry.json	Registration of managed / handwritten / artifact file classes
package.json and packages/*/package.json	Versions, commands, dependencies (all projen-managed)
packages/skill-family-contracts/src/registry.json	Protocol-name and Schema $id registry
scripts/release-artifact-contract.json	Fixed three-package release byte contract (members, required items, and content-digest rules)

Managed files can only be modified via .projenrc.js and regenerated by running pnpm synth; handwritten files (including all documentation) are not overwritten by synth. The authoritative classification is in .foundation/file-registry.json.

Documentation System and Fact-Check

The documentation system aims to eliminate manual drift through deterministic checks:

1. Frozen fact package: documentation writing consumes only the machine sources of truth listed in the table above. Models or authors must not write versions, commands, or package counts from memory; model names, credentials, and scheduling information do not enter documentation, nor do they enter Contracts.
2. Fact-check: node scripts/docs/fact-check.mjs verifies package names, commands, gate facts, version pins, and key numbers in the documentation against the source of truth, and cross-checks consistency across sources (manifest vs package.json, version-lock vs packageManager, rule count vs budget, etc.).
3. Link-check: node scripts/docs/link-check.mjs resolves in-repo relative links and heading anchors across the README and all docs/**/*.md, and verifies that mkdocs.yml nav is complete.
4. No-workflow boundary and public-boundary verification: this repository has no CI/CD workflow at all (the old topology's three Actions — ci/docs/docs-deploy — have been entirely deleted); all gates run within the private workspace (pnpm check); the public boundary is mechanically verified by check:public-snapshots and the release byte contract. The public static site is rendered by scripts/render-public-site.mjs (with the sole output docs/public/site/** and the deterministic baseline docs/public/site-baseline.json).
5. Version lock: the site toolchain is locked in scripts/docs/toolchain.json and scripts/docs/requirements.txt; the build uses only an out-of-repo Python virtual environment, with no system-level pip install.

Both check scripts can be run directly via node scripts/docs/<name>.mjs: fact-check.mjs consumes the root-pinned semver@7.8.5 via in-repo modules and requires pnpm install --frozen-lockfile to be completed first; link-check.mjs is a pure Node implementation. See scripts/docs/README.md for responsibilities.

Stable Product Gates

The root pnpm check orchestrates only the 11 stable product gate IDs (check:structure~check:artifacts, each ID listed in Current Product Status), and no longer hard-pins the original command list; each stable ID composes a few product checks within its own package script. Gate facts are mechanically derived by node scripts/docs/fact-check.mjs from the root package.json's scripts.check and verified verbatim. Documentation and setup invoke or list only the 11 stable IDs or the root pnpm check, and do not duplicate the underlying command list.

The honest boundary of in-repo checks: structural checks only prove "byte/structural consistency (provable in-repo)"; one-time migration completeness, ordinary prose semantics, and the final accept/reject conclusion belong to the responsibility of external review; no second gate registry, baseline, or command comparator is maintained within the target repository.