SEAL

SEAL is a Codex plugin that helps Codex inspect a repository or Markdown plan before you change or launch it. It turns "what are we building?" into local .seal artifacts that define the system, show what exists, what may change, what would prove it, and what still blocks launch.

Use it when you want Codex to behave less like a code patcher and more like a careful systems engineer: source-aware, gap-aware, and honest about what it cannot prove.

Quick Start

1. Enable the SEAL plugin in Codex.

   This repository is currently a local plugin scaffold. For local setup, follow plugin/docs/first-run.md. If SEAL is available in your Codex plugin browser or marketplace, install it there and start a new Codex thread after enabling it.

2. Open the project you want Codex to inspect.

3. Ask SEAL for a mission:

   Ask SEAL which mission fits this project.
   

   Or start directly:

   Use SEAL to establish the baseline for this repository and tell me what is unknown.
   

4. Review the result in Codex, then inspect the generated .seal folder when you need the underlying records.

What You Get

SEAL exposes mission-oriented plugin skills and a local seal command for deterministic validation.

Need	Start With	What SEAL Produces
Define a system or feature	"Use SEAL to formulate this feature."	System Definition records for purpose, stakeholders, boundaries, constraints, requirements, architecture concerns, risks, and gaps
Understand an existing repository	"Use SEAL to establish the baseline for this repo."	MAP, source records, file coverage, visible gaps, and readable map views
Turn rough intent into a plan	"Use SEAL to formulate this feature."	Draft requirements, assumptions, risks, proof needs, launch gates, and follow-up work
Check a planned change	"Use SEAL to qualify this change against the baseline."	IMPACT records, affected files/components, proof obligations, blockers, and authority gaps
Check proof or launch readiness	"Use SEAL to check proof and launch readiness."	PROVE records, proof-gap reports, gate policy results, and launch-readiness reports
Hand work to another agent	"Use SEAL to prepare context for this change."	Context packs, traceability matrices, or technical data packages

If you are unsure which path fits, ask SEAL first. The router is meant to choose the smallest useful mission before artifact mechanics matter.

How SEAL Works Today

SEAL is local-first. It reads files Codex can inspect and writes artifacts into the target project's .seal directory.

• seal map and seal plan bootstrap draft .seal artifacts from a repository or Markdown plan.
• SEAL records source authority separately from generated interpretation. Observed repo facts, user plans, inferred claims, evidence, and human approval are not treated as the same thing.
• Generated views and reports are derived outputs. They help humans and agents inspect the state, but they are not source authority by themselves.
• The Model Compiler currently backs trace graph/query APIs, traceability matrices, and technical data packages. Other outputs such as map views, proof-gap reports, docs proposals, dashboards, launch-readiness reports, and context packs use their own generators over the same .seal workspace.
• Validation checks schema shape, references, file coverage, source authority, proof bindings, derived-output freshness, and launch gates.

The important promise is not that SEAL knows the truth. The promise is that SEAL keeps evidence, assumptions, weak authority, missing proof, and launch blockers visible.

Systems Engineering View

From a systems-engineering lens, SEAL is a small assurance loop around a project. It starts with things Codex can inspect, keeps each claim tied to where it came from, and turns the result into artifacts that people can review before a change or launch.

flowchart LR
  Input["Intent, repo, plan, or existing .seal artifacts"] --> Definition["System Definition: what this system is"]
  Definition --> Map["MAP: what exists"]
  Map --> Impact["IMPACT: what may change"]
  Impact --> Prove["PROVE: what would prove it"]
  Prove --> Gates["Gates: what blocks movement"]
  Gates --> Views["Views, diagrams, and reports"]
  Views --> Decisions["Human decisions, beads, accepted gaps, or launch cautions"]
  Decisions --> Definition

Loading

System Definition is the method step that keeps the loop from becoming a pile of reports. It records the system boundary, purpose, stakeholders, constraints, architecture concerns, requirements, risks, gaps, and source authority before SEAL maps, changes, or proves work. SEAL may render System Definition with simplified C4-style architecture views and arc42-shaped narrative sections, but those renderings are not source authority by themselves.

The current SEAL checkout is organized around the same idea:

• plugin/ defines the Codex plugin surface, skill guidance, schemas, product docs, and user-facing contracts.
• src/ implements the local command, artifact handling, inventory, ingestion, proof, validation, model compiler, launch readiness, and generated views.
• tests/ covers the command surface, artifact contracts, docs, inventory, proof, gates, plugin packaging, and generated reports.
• .seal/ records the current observed model, including repo maps, viewpoints, dashboards, proof state, and launch-readiness output.

The implementation modules are easier to understand as responsibilities than as folders:

flowchart TB
  CLI["CLI and plugin skills"] --> Ingestion["Ingestion and inventory"]
  Ingestion --> Artifacts["Artifacts and source authority"]
  Artifacts --> Compiler["Model compiler and trace views"]
  Artifacts --> Proof["Proof, evidence, and gaps"]
  Artifacts --> Validation["Validation and file coverage"]
  Proof --> Gates["Gate policy and launch readiness"]
  Validation --> Gates
  Compiler --> Reports["Dashboards, maps, matrices, and packages"]
  Gates --> Reports

Loading

SEAL also tracks viewpoint and audience on purpose. The documented audiences include plan owners, founders or product builders, developers working in an existing repo, delivery leads, and launch reviewers. The generated launch-owner viewpoint is aimed at people who need gate status, stop rules, rollback evidence, and a way to feed real-world learning back into the records.

That is not the same as formal ownership. In this repository's current .seal records, component boundaries and business requirements are still visible map gaps, and formal named stakeholder ownership plus approved business or component authority are not yet approved baseline facts. SEAL keeps those gaps explicit so a user can decide whether to accept the caution, add evidence, or assign real authority before launch.

Typical Plugin Prompts

Ask SEAL which mission fits this project and explain why.

Use SEAL to establish the baseline for this existing repository and show the important gaps.

Use SEAL to formulate this new feature from rough intent into requirements, assumptions, proof needs, and launch gates.

Use SEAL to qualify this planned change against the current baseline and classify blockers.

Use SEAL to check proof and launch readiness.

Local Command Reference

Plugin users can usually stay in Codex. The terminal command is for maintainers, smoke tests, and reproducible artifact checks.

Install dependencies from this checkout:

npm install

Run against a repository:

npm exec -- seal map <directory>
npm exec -- seal impact <directory> <target> [summary]
npm exec -- seal docs ai <directory> [--target <file-or-artifact>]
npm exec -- seal prove <directory> [--profile explore|standard|launch|mission-critical]
npm exec -- seal traceability-matrix <directory> [--viewpoint <id>]
npm exec -- seal technical-data-package <directory> <element-id> [--viewpoint <id>]
npm exec -- seal fly <directory> [--profile explore|standard|launch|mission-critical]
npm exec -- seal dashboard <directory> [--profile explore|standard|launch|mission-critical]
npm exec -- seal validate <directory> [--bootstrap-ontology]

Run against a Markdown plan:

npm exec -- seal plan <directory|plan.md>
npm exec -- seal prove <workspace>
npm exec -- seal fly <workspace>
npm exec -- seal validate <workspace>

For a plan file, follow-up commands should use the containing workspace directory, not the Markdown file path.

Other useful commands:

npm exec -- seal docs human <directory> [--write] [--target <file>] [--approve-target]
npm exec -- seal docs <directory>
npm exec -- seal guide [request] [--profile explore|standard|launch|mission-critical]

What SEAL Writes

Common outputs include:

• .seal/map.yaml - observed files, components, requirements, source authority, and unknowns.
• .seal/impacts/IMPACT-*.yaml - change impact records and proof obligations.
• .seal/proof.yaml and .seal/evidence/index.yaml - claims, evidence links, limitations, and gaps.
• .seal/debt.yaml - unresolved unknowns and follow-up work.
• .seal/context-pack.yaml and .seal/ai-docs/context.yaml - compact context for AI handoff.
• .seal/reports/map.md and .seal/reports/map.mmd - readable and Mermaid map views.
• .seal/reports/proof-gaps.md - claims that still need evidence.
• .seal/reports/launch-readiness.md - pass, warn, or block launch decisions with reasons.
• .seal/reports/traceability-matrix.json - compiler-backed traceability matrix.
• .seal/reports/technical-data-package.json - compiler-backed handoff package for one system element.
• .seal/audit/artifact-writes.jsonl - audit trail for artifact writes.

Commit these files when they describe real project state that future Codex sessions should reuse.

Accuracy And Scope

SEAL does not approve launch, accept risk, or make inferred records true. It can discover, propose, compare, validate, and summarize. Human or project authority still owns product intent, risk acceptance, and approved baseline status.

Treat a clean validation result as "the records are structured, traceable, and honest about known gaps." It is not the same as "the project is correct" or "the project is safe to ship."

Deeper Docs

• First run guide - plugin-first setup and first-use flow.
• Example workflows - plan, gstack-style plan, and repository examples.
• Product contract - audience, inputs, outputs, and trust model.
• Mission contract - baseline states, source authority, gaps, and human authority boundaries.
• Agentic MBSE roadmap - longer-term systems-engineering direction.
• Assurance-Grade evaluation - evaluation doctrine and benchmark strategy.
• Release checklist - quality gates and landing checklist.

Maintainer Checks

npm test

npm run smoke:plugin