Foundry Pack System v0 contract

Status: design gate approved for implementation briefing
Owner: Bob
Date: 2026-05-02
Project: forge

Purpose

Define the first shippable Foundry pack contract for pre-skilled local workflow agents.

A pack is a versioned, auditable bundle that tells Foundry:

what workflow is being installed
which local models and routes it requires
which Hermes skills/workflows it carries
which grouped permissions it needs
how to install, check, run, evaluate, update, and roll back it
which evidence proves the pack is safe and truthful

Explicit non-goals

This contract does not define:

a generic agent platform
a marketplace
a new harness decision
free-form third-party pack execution
automatic approval of arbitrary shell commands

Hermes remains the V1 default harness. Foundry remains the control plane, installer, evidence spine, and policy surface.

Why packs exist

Ged's modular thesis is accepted here as the product direction: value comes from specialist local models + pre-wired workflow skills + explicit routing + evidence, not one giant general model.

Commercially, the pack is the unit we can sell, install, support, and audit.

Pack contract principles

Workflow-first: each pack serves one bounded job.
Local-first: default path is localhost/local-network inference and local data handling.
Pre-skilled: packs ship with named workflow skills, prompts, templates, and evals already chosen.
Auditable permissions: approvals are granted by capability group, not one exec at a time.
Evidence-backed: install/check/run claims are only valid if the required artifacts exist.
Foundry truth: Foundry owns status, routing truth, permission state, and support/evidence summaries.
Default deny for external send: no outbound customer/system send unless the pack explicitly requests and the operator explicitly grants it.

1) Pack object model

A Foundry pack v0 is a directory with this minimum shape:

pack-root/
  pack.yaml
  README.md
  skills/
  evals/
  demo-data/
  scripts/
  evidence/

Required top-level artifacts

pack.yaml — canonical manifest
README.md — human install/use/support notes
skills/ — workflow skill definitions, prompts, templates, and config fragments the pack requires
evals/ — runnable eval specs and expected pass criteria
demo-data/ — safe local fixtures for install-check/demo/evidence generation
scripts/ — installer/check/run helper commands referenced by the manifest
evidence/ — templates or schemas for required evidence outputs, not customer data

2) Manifest schema (`pack.yaml`)

All fields below are required unless marked optional.

2.1 Identity and scope

Field	Type	Contract
`schema_version`	string	Must be `foundry-pack/v0`.
`pack_id`	string	Stable machine ID, kebab-case, globally unique within Foundry.
`name`	string	Human pack name.
`version`	string	Semver.
`domain`	string	Business/workflow domain, e.g. `pdf-ops`.
`summary`	string	One-sentence bounded promise.
`owner`	string	Implementation owner/team.
`harness`	string	Must name the approved harness, V0 default `hermes`.
`entry_surfaces`	list	Allowed invocation surfaces, e.g. `api`, `watched-folder`, `slack`.
`workflow_id`	string	Stable workflow identifier inside the harness/pack.
`customer_profile`	string	Intended operator/buyer type.
`data_classification`	string	Must declare sensitivity, e.g. `customer-documents-local-only`.

2.2 Models and routing

Field	Type	Contract
`required_models`	list	Named model dependencies with runtime, source, quantization if relevant, and required/optional flag.
`model_routes`	list	Explicit task-to-model routing table.
`route_policy`	object	Fallback, timeout, retry, and no-route behavior.
`eval_hooks`	list	Route-specific evals that must pass before a route is marked ready.

Each required_models item must include:

model_id
runtime (mlx, ollama, llama.cpp, lm-studio, or other blessed runtime)
endpoint
role (e.g. ocr-summary, classifier, fallback-general)
required: true|false
license_note

Each model_routes item must include:

route_id
task_type
primary_model
fallback_models (may be empty)
input_contract
output_contract
max_latency_ms
quality_gate
on_failure (fallback, fail-closed, human-review)

2.3 Skills and workflow contents

Field	Type	Contract
`skills`	list	Named skills/configured capabilities the pack ships or wraps.
`workflow_steps`	list	Ordered workflow stages with responsible skill/model route.
`human_review_points`	list	Mandatory review gates before external or destructive actions.
`memory_policy`	object	What session memory is allowed, retained, and prohibited.

Each skills item must include:

skill_id
source (existing, wrapped, pack-local)
purpose
required: true|false

2.4 Permissions

Field	Type	Contract
`permission_profile`	object	Grouped capability grants requested by the pack.
`defaults`	object	Must show default deny posture for unlisted capabilities and outbound send.
`approval_notes`	string	Plain-language explanation of why the requested groups are necessary.

2.5 Operations

Field	Type	Contract
`install`	object	Canonical install command(s), prerequisites, and success criteria.
`check`	object	Canonical readiness/doctor command(s) and pass criteria.
`run`	object	Canonical demo or production invocation command(s).
`support_bundle`	object	Command and expected outputs for pack evidence/support collection.

2.6 Validation and evidence

Field	Type	Contract
`evals`	list	Named eval suites and pass thresholds.
`demo_data`	list	Required local fixtures for reproducible proof.
`evidence_outputs`	list	Exact artifacts the pack must emit on install/check/run.
`truthful_limitations`	list	Known limits that must be preserved in operator/customer-facing summaries.

2.7 Lifecycle

Field	Type	Contract
`update_policy`	object	Allowed upgrade path, migration behavior, and recheck requirements.
`rollback_policy`	object	How to revert to prior working version and restore previous config.
`compatibility`	object	Required Foundry version, harness version, and platform assumptions.

3) Grouped permission model

Packs request capability groups. Foundry grants or denies these groups at install/enable time and records the resulting policy in pack status.

Permission groups

Group ID	What it allows	Default	Notes
`fs.read_only`	Read approved local directories only	allow if path-scoped	No writes, deletes, or moves.
`shell.local_safe`	Non-destructive local commands from an allowlisted command family	allow only if declared	For checks, OCR, indexing, hashing, validation.
`packages.install`	Package install/update commands	deny	Needed only during install/update flows.
`services.control`	Start/stop/restart approved local services	deny	Must be service-scoped.
`network.fetch`	HTTP(S) fetch/read to declared endpoints	deny	For model pulls, docs fetch, or local service probes.
`outbound.send`	Send messages/email/webhook payloads externally	deny	Default deny always unless explicitly granted.
`ops.destructive`	Delete, overwrite, purge, uninstall, or irreversible file/state changes	deny	Must require human review point.
`credentials.access`	Read/inject secrets or auth tokens	deny	Must be source-scoped and audited.
`data.customer_process`	Process declared customer content locally	deny until operator accepts	Required for real workflow use, not for installer alone.

Contract rules for permission groups

Pack manifests must request permissions by group ID, not by ad-hoc command.
Every group must declare:

requested: true|false
scope
reason
human_review_required: true|false

Foundry must store the final resolved permission state in pack status and support bundles.
outbound.send must remain denied by default even if network fetch is allowed.
ops.destructive and credentials.access cannot be implicitly inherited from other groups.
data.customer_process must be separately visible because demo/install proof may be safe while real customer use is sensitive.
A pack with denied required permissions is installable only as partial or demo-only, never falsely ready.

Minimum status shape for resolved permissions

resolved_permissions:
  fs.read_only:
    state: granted
    scope:
      - /approved/input
      - /approved/output
  shell.local_safe:
    state: granted
    scope:
      - pdfsig
      - md5
      - sqlite
  outbound.send:
    state: denied
    reason: default-deny-external-send

4) Model routing contract

Packs must support specialist routing and explicit fallback.

Required route behavior

Every workflow step that uses a model must map to a named route_id.
Every route must identify one primary model and zero or more fallback models.
Every route must declare whether failure causes:

local fallback
fail-closed
human review

Every route must have at least one eval hook before it is marked production-ready.
Foundry status must show route readiness per route, not just pack-level green.
Foundry support bundles must preserve route decisions and failure reasons.

Example route shape

model_routes:
  - route_id: classify-document
    task_type: document-classification
    primary_model: mlx-community/Qwen3-0.6B-8bit
    fallback_models: []
    input_contract: extracted-pdf-text
    output_contract: document-type-json
    max_latency_ms: 3000
    quality_gate: eval:pdfops-classify-smoke
    on_failure: fail-closed

V0 honesty rule

If a pack has not proven a route with local evidence, Foundry must report that route as declared-not-proven, not ready.

5) Install / check / run contract

Each pack must define three canonical operator actions.

Install

Install means:

prerequisites verified
pack contents placed/registered
required local directories created
required runtime/service/model checks performed
permission groups requested and resolved
pack status written

Install output must be machine-readable and include:

ok
pack_id
version
install_mode (demo-only, partial, ready)
missing_permissions
missing_models
next_steps

Check

Check means:

all declared routes checked
all required skills present
all permission states re-read
harness readiness verified
required eval smoke tests run

Check output must include:

ok
pack_ready
failed_clauses
route_status
permission_summary
evidence_path

Run

Run means one reproducible invocation using demo data or approved local input.

Run output must include:

ok
workflow_id
input_count
output_count
route_decisions
human_review_events
evidence_path

6) Evidence bundle requirements

Every pack must define a support/evidence bundle with exact file names. V0 packs are not considered supportable without this.

Minimum required evidence classes

install evidence
readiness/check evidence
demo/run evidence
eval evidence
permission resolution evidence
route readiness evidence
truthful limitations note
executed manifest copy

Minimum evidence bundle contents

For any pack run, Foundry must emit a timestamped bundle containing at minimum:

00-pack-manifest.yaml
01-install.json
02-check.json
03-run.json
04-route-status.json
05-permissions.json
06-evals.json
07-truthful-limitations.md
08-support-summary.md
copy of invoked scripts or command transcript references

Packs may add domain-specific evidence files, but cannot omit the common spine above.

Evidence honesty rule

If a pack depends on a side artifact because a status counter or summary is not yet truthful, the contract must say so explicitly, just as the Foundry V1 Hermes contract does for signed-PDF runtime proof.

7) Update and rollback policy contract

Update policy must define

whether updates are in-place or side-by-side
whether old demo/eval evidence remains valid
which checks must be re-run after update
whether permission grants must be re-confirmed
whether route readiness resets to declared-not-proven

Rollback policy must define

previous pack version restoration method
config rollback method
state/data preservation rules
evidence reference for the last known-good run

V0 rule

A pack update that changes required models, permissions, workflow behavior, or evidence contract must force a new check run before status can return to ready.

8) PDF Ops Pack v0 — reference pack contract only

This is the first reference pack. It is contract-level only here; implementation follows in separate MC tasks.

Pack identity

schema_version: foundry-pack/v0
pack_id: pdf-ops-pack
name: PDF Ops Pack
version: 0.1.0
domain: pdf-ops
summary: Local PDF ingest, extract, preserve, index, and retrieve workflow for PDF-heavy operators.
owner: Pam
harness: hermes
workflow_id: pdf-ops
entry_surfaces:
  - api
  - watched-folder
customer_profile: pdf-heavy businesses
data_classification: customer-documents-local-only

Anchoring evidence and reuse

This pack must reuse, not reinvent, already-approved evidence and assets from:

/Users/lilly/clawd/projects/foundry-commercialisation/contracts/foundry-v1-contract.md
/Users/lilly/clawd/projects/foundry-commercialisation/adapters/hermes/README.md
/Users/lilly/clawd/projects/foundry-commercialisation/adapters/hermes/demo-scenario.md
/Users/lilly/clawd/projects/foundry-commercialisation/adapters/hermes/mason-integration-check.md
/Users/lilly/clawd/projects/foundry-commercialisation/release-candidate/

Required skills

The first reference pack must be built from these existing skills/patterns:

ocr-and-documents
nano-pdf
llama-cpp or equivalent local inference serving pattern where needed
local-llm-stats-maintenance
mission-control-integration

Optional later extensions, not required for v0:

webhook-subscriptions
himalaya
site-audit

Required workflow steps

ingest approved PDF input
fingerprint source file
extract text/fields
generate bounded local summary where configured
preserve/archive original bytes unchanged
write structured JSON sidecar
index into local retrieval store
answer retrieval/query request with provenance
emit evidence

Required model routes

At minimum the reference pack must declare routes for:

pdf-summary
document-classification
retrieval-answer

The initial primary model anchor may reuse the approved local Hermes gate model:

mlx-community/Qwen3-0.6B-8bit at http://127.0.0.1:8085/v1

If OCR/classification/retrieval later split across multiple specialists, the pack must express those as separate routes rather than hiding them behind one “general model” label.

Required permissions for PDF Ops Pack v0

Group	State target	Why
`fs.read_only`	required	read approved input corpus and fixtures
`shell.local_safe`	required	hashing, signature verification, sqlite, OCR/index helpers
`packages.install`	installer-only if needed	only for explicit setup steps
`services.control`	required for local runtime checks	verify/start local services where approved
`network.fetch`	optional/minimal	local endpoint probe; model/document fetch only if explicitly declared
`outbound.send`	denied by default	no external customer sends in v0
`ops.destructive`	not required for standard run	purge/cleanup only behind human review
`credentials.access`	not required by default	only if later surfaces like email/webhook are enabled
`data.customer_process`	required for real operation	process customer PDFs locally

Required evals

Minimum eval suite for PDF Ops Pack v0:

install smoke
readiness smoke
five-PDF demo run
50-field extraction assertion
archive byte-identity assertion
signed-PDF preservation assertion
retrieval/query assertion with citation
no-cloud posture assertion

Required demo data

safe demo PDF set of five documents
at least one genuinely signed PDF fixture
expected JSON outputs/schema
expected retrieval query and answer fixture

Required commands

The reference pack must expose contract-level commands equivalent to:

foundry pack install pdf-ops-pack
foundry pack check pdf-ops-pack
foundry pack run pdf-ops-pack --demo
foundry pack support-bundle pdf-ops-pack

Exact CLI implementation is Tes-owned, but the pack contract must target these operator verbs.

Required evidence outputs

In addition to the common pack bundle spine, PDF Ops must emit:

09-pdf-demo-report.json
10-signed-pdf-report.json
11-index-query-report.json
12-no-cloud-posture.json

Truthful limitations to preserve

outbound customer send is disabled by default
signed-PDF truth may rely on explicit artifact proof until all status counters are truthful
corpus scope must remain explicit and bounded
no claim of autonomous business process completion

9) Exact implementation tasks and owners

These are the next MC briefs to route. They are implementation tasks, not already-complete work.

Tes — Foundry pack CLI and installer

What this delivers A Foundry pack runtime/CLI path that can install, resolve grouped permissions, check, run, and bundle evidence for v0 packs.

Must implement

pack manifest loader/validator for foundry-pack/v0
grouped permission resolution and persisted status
foundry pack install/check/run/support-bundle
route readiness/status reporting
pack evidence bundle spine
declared-not-proven route honesty state

Binary acceptance criteria

foundry pack install <pack> validates manifest and writes machine-readable install result
denied required permission prevents false ready state
foundry pack check <pack> emits route and permission summaries
foundry pack support-bundle <pack> emits the required common spine files
Foundry status shows resolved permissions and per-route readiness

Pam — Hermes PDF Ops pack contents

What this delivers The concrete pdf-ops-pack contents for Hermes, built by wrapping existing Hermes/PDF evidence and skills rather than reinventing them.

Must implement

pack manifest for PDF Ops Pack v0
Hermes workflow/profile/config contents for PDF ingest/extract/archive/index/query
skill wiring using existing document/PDF skills
eval definitions and demo-data layout
truthful limitations note copied from approved evidence where required

Binary acceptance criteria

pack contents can be installed by Tes's pack CLI without manifest edits
five-PDF demo, 50-field extraction, archive identity, and signed-PDF checks all map into pack eval/evidence outputs
outbound send remains disabled by default
all required pack evidence files are emitted on a demo run

Mason — integration and check

What this delivers An integration pass confirming the Foundry pack CLI and Hermes PDF Ops contents work together honestly on the Mac Studio.

Must implement/check

integration check document for pack install/check/run/support-bundle
validation that Foundry remains truth owner and Hermes remains harness/package content owner
verification that permission groups are surfaced cleanly, not hidden as raw command approvals

Binary acceptance criteria

a fresh Mac Studio run passes install/check/run for pdf-ops-pack
support bundle contains common spine plus PDF-specific evidence files
any unproven route is flagged declared-not-proven, not silently green
any denied required permission yields partial/demo-only state, not false readiness

Quinn — QA gate

What this delivers Final QA on the first pack contract implementation.

Must verify

pack install story is stranger-test passable
permissions are auditable by group
route readiness/fallback behavior is visible and truthful
PDF-specific evidence matches approved claims

Binary acceptance criteria

Quinn can run the documented commands without builder intervention
Quinn can identify granted/denied permission groups from status/support bundle alone
Quinn rejects if external send is enabled by default
Quinn rejects if signed-PDF or no-cloud claims lack explicit evidence

10) Final rulings

The pack is the supported commercial unit for pre-skilled local workflow agents.
Grouped capability permissions are mandatory; per-exec approval is not the pack model.
Foundry owns manifest truth, permission resolution, route readiness, and evidence/status outputs.
Hermes remains the default V1 harness and the first reference pack is PDF Ops Pack v0.
No public claims, marketplace claims, or external outreach are authorized by this contract.

Foundry Pack System v0 contract

Purpose

Explicit non-goals

Why packs exist

Pack contract principles

1) Pack object model

Required top-level artifacts

2) Manifest schema (pack.yaml)

2.1 Identity and scope

2.2 Models and routing

2.3 Skills and workflow contents

2.4 Permissions

2.5 Operations

2.6 Validation and evidence

2.7 Lifecycle

3) Grouped permission model

Permission groups

Contract rules for permission groups

Minimum status shape for resolved permissions

4) Model routing contract

Required route behavior

Example route shape

V0 honesty rule

5) Install / check / run contract

Install

Check

Run

6) Evidence bundle requirements

Minimum required evidence classes

Minimum evidence bundle contents

Evidence honesty rule

7) Update and rollback policy contract

Update policy must define

Rollback policy must define

V0 rule

8) PDF Ops Pack v0 — reference pack contract only

Pack identity

Anchoring evidence and reuse

Required skills

Required workflow steps

Required model routes

Required permissions for PDF Ops Pack v0

Required evals

Required demo data

Required commands

Required evidence outputs

Truthful limitations to preserve

9) Exact implementation tasks and owners

Tes — Foundry pack CLI and installer

Pam — Hermes PDF Ops pack contents

Mason — integration and check

Quinn — QA gate

10) Final rulings

2) Manifest schema (`pack.yaml`)