@reunionstudio/airlock-mcp 0.1.0

package/docs/ooda-loop.md

@@ -0,0 +1,40 @@
+# OODA Loop For Airlock Specs
+
+Airlock specs should support a business loop, not just a table.
+
+## Observe
+
+Name the evidence and systems that matter:
+
+- human entries
+- agent observations
+- screenshots, PDFs, receipts, exports, or source files
+- source APIs or app objects
+- existing Airlock specs or reference data
+- downstream system state
+
+## Orient
+
+Turn observations into a governed shape:
+
+- one row grain
+- durable identifiers
+- business timestamps
+- typed fields
+- validated variants
+- attachments
+- guest access
+- workflow
+- references
+- expectations
+
+## Decide
+
+Choose the smallest governed output worth creating now. If uncertainty is high,
+start with `posts` and let real feedback shape the next spec.
+
+## Act
+
+Create the spec in Airlock only after local drafting is coherent. Then collect
+records, review them, and decide whether to revise the spec or add the next
+small spec.

package/docs/spec-workbench-architecture.md

@@ -0,0 +1,161 @@
+# Architecture
+
+Airlock MCP is intentionally small:
+
+- Codex is the conversational interface.
+- The repo is the durable workspace.
+- The CLI is deterministic local tooling.
+- Airlock stored procedures remain the authority for live validation and
+  mutation.
+
+## Module Boundaries
+
+- `cli.py`: argument parsing and command dispatch only.
+- `art.py`: small terminal identity and about text.
+- `bootstrap.py`: specs-repo bootstrap files, including `AGENTS.md` and the
+  repo-scoped Codex skill.
+- `manage.py`: workspace discovery, archive, restore, rename, and next-action
+  helpers.
+- `project.py`: checkout discovery and environment override handling.
+- `patterns.py`: pattern manifest loading.
+- `workspace.py`: create, import, and clone workspace file operations.
+- `specs.py`: spec-config extraction, identity retitling, and sample-record
+  generation.
+- `records.py`: deterministic records JSON to CSV rendering.
+- `summary.py`: compact workspace recap for session re-entry.
+- `updater.py`: self-update planning and execution.
+- `validation.py`: local workspace and records checks.
+- `sql.py`: validate-only SQL rendering.
+- `jsonio.py`: JSON/text file helpers.
+
+Keep product data in `patterns/`, workspace templates in `workspaces/_template/`,
+and Airlock-specific validation rules in `validation.py`. Do not put another
+copy of a pattern into Python code.
+
+## Source-Of-Truth Rules
+
+`patterns/manifest.json` lists CLI-visible starter patterns. Each listed
+pattern directory must include:
+
+- `README.md`
+- `spec.config.json`
+- `sample.records.json`
+
+The CLI reads those files directly. That makes pattern edits reviewable as data
+changes instead of code changes.
+
+## Create, Import, Clone
+
+The old Airlock Streamlit editor used mode-specific hydration:
+
+- create: start from defaults
+- edit: hydrate canonical config and preserve unmodeled sections
+- clone: hydrate source config, but blank/reset identity fields
+
+Airlock MCP maps that to files:
+
+- `init-repo`: prepare a separate specs repo for Codex and Airlock MCP
+- `init`: create from a pattern
+- `import-spec`: edit/import an existing canonical or spec-library config in a
+  new workspace
+- `clone`: copy a workspace, reset `core_config.spec_name` and
+  `core_config.spec_alias`, and regenerate sample records
+- `rename`: move a workspace and, by default, retitle its spec identity
+- `archive` and `restore`: move drafts in and out of `_archive`
+- `list-workspaces`: show active drafts, with archived drafts available via
+  `--all`
+
+This repo does not try to be the installed Airlock editor. It gives Codex and
+humans a careful drafting surface before Airlock receives the final config.
+
+## Update Boundary
+
+`self-update` supports two intentionally simple paths:
+
+- checkout mode: `git pull --ff-only`
+- installed package mode: `pip install --upgrade <source>`
+
+The command prints the selected plan first, supports `--dry-run`, and refuses a
+git checkout with uncommitted changes unless `--force` is passed. Keep update
+logic in `updater.py`; do not hide network or package-manager side effects in
+other commands.
+
+## Validation Boundary
+
+Local checks catch:
+
+- missing workspace files
+- invalid JSON
+- missing core fields
+- duplicate columns
+- unsupported column types
+- missing date/datetime strftime formats
+- `variant_shape` rules pointing at non-variant columns
+- variant columns with no `variant_shape` rule
+- shared guest-role access levels without matching enabled public subfolders
+- sample records with undeclared or missing required fields
+- payload fields that look like Airlock workflow/reviewer state
+
+Local checks do not prove that installed Airlock will accept a spec. Always use
+installed Airlock validation before mutation.
+
+## Records Boundary
+
+`sample.records.json` is the authoring shape. It supports nested JSON for
+variant fields and is easy for Codex to patch over multiple sessions.
+
+`export-csv` is the handoff adapter. It writes fields in `column_config` order,
+ignores undeclared extras after validation has reported them, and serializes
+objects or arrays as compact JSON strings. Keep other record-format adapters in
+`records.py` so the CLI stays thin.
+
+## Install Boundary
+
+The public install surface is expected to be Airlock MCP shaped:
+
+```bash
+npx @reunionstudio/airlock-mcp install
+```
+
+The connector implementation belongs in `reunionstudio/airlock-mcp`. Airlock
+MCP is the single installed interface for agents working with Airlock: building
+specs, using specs to pull and push governed data, and capturing improvements
+from real use cases. This workbench owns the spec-building implementation:
+patterns, bootstrap, workspace files, local checks, and the Codex skill.
+
+That command is the agent connector/setup entry point, not the user's spec
+workspace. After installing or registering the connector, the user still creates
+a separate `<project>-specs` repo and works there with Codex. Users should ask
+for Airlock, not install a separate spec-building tool.
+
+For Codex, the install command should use the platform MCP manager rather than
+editing config files directly:
+
+```bash
+codex mcp add airlock -- npx -y @reunionstudio/airlock-mcp server
+```
+
+The npm package is an installer and launcher. The production MCP server can be
+Rust when Airlock MCP grows beyond bootstrap guidance. If implemented with
+stdio, stdout must remain protocol-only and all logging must go to stderr.
+
+The current dogfood/development path can install Airlock MCP into the specs
+repo before the MCP package is published, then run:
+
+```bash
+airlock-mcp init-repo
+```
+
+That command writes the Codex-facing repo instructions and skill into the specs
+repo. Keep those bootstrap assets as files, not generated prose hidden in the
+CLI, so product guidance remains reviewable.
+
+The normal development path for Airlock MCP itself is from a checkout:
+
+```bash
+python3 -m pip install -e .
+```
+
+The CLI discovers the checkout by walking upward for `patterns/manifest.json`.
+Set `AIRLOCK_MCP_HOME=/path/to/airlock-mcp` if the command is launched from
+another working directory.

package/docs/spec-workspace.md

@@ -0,0 +1,33 @@
+# Spec Workspace Files
+
+Every draft workspace should preserve context for future Codex sessions.
+
+- `brief.md`: business goal, users, systems, and first useful outcome.
+- `decisions.md`: row grain, evidence, access, workflow, references, and OODA
+  decisions.
+- `questions.md`: unresolved questions that materially affect the model.
+- `spec.config.json`: draft full Airlock admin spec config.
+- `sample.records.json`: example records in agent-friendly records JSON.
+- `review.md`: local review notes, Airlock validation results, and next steps.
+
+The workspace is intentionally plain files. Diffs are the design history.
+
+Use `airlock-mcp summary <workspace>` to re-enter a draft. Use
+`airlock-mcp next <workspace>` to choose the next conservative action. Use
+`airlock-mcp export-csv <workspace>` to render `sample.records.json` in the
+CSV shape Airlock loading paths commonly expect. Do not treat the CSV as the
+source of truth; edit the JSON and regenerate it.
+
+Use `airlock-mcp rename`, `archive`, and `restore` to organize draft folders.
+`rename` retitles spec identity by default; pass `--keep-spec-identity` for a
+pure folder move.
+
+`review.md` should identify the workspace source mode:
+
+- `create`: started from an Airlock MCP pattern
+- `import`: hydrated from an existing spec JSON shape such as `specConfig` or
+  exported `SPEC_CONFIG`
+- `clone`: copied from another workspace with spec identity reset
+
+For clone and import flows, preserve the source path/name so future sessions can
+tell whether changes are deliberate adaptations or accidental drift.

package/docs/workflows.md

@@ -0,0 +1,229 @@
+# Workflows
+
+## Start A New Specs Repo
+
+Use this when a person opens a blank Codex project and wants to start working
+with real Airlock specs. The project repo is where they work. Public users
+should come through the single Airlock MCP install; this repo provides the
+spec-building capability behind that experience.
+
+Ask for the project or organization name first, then lowercase it, replace
+spaces with hyphens, and append `-specs`. For example, `Home` becomes
+`home-specs`. Reserve `airlock-specs` for the canonical reusable spec library.
+Airlock itself does not create this repo; Codex can create it locally while
+helping the user start an Airlock specs project.
+Start in Codex, not Snowflake Cortex. Snow CLI or Cortex only matters later when
+validating, creating, or operating specs against an installed Airlock app.
+
+The preferred Codex prompt is:
+
+```text
+I want to use Airlock MCP to start working with Airlock specs for Home.
+
+Set up this project as an Airlock specs repo. Use the Airlock MCP
+spec-building capability when we need to draft or revise specs. Welcome me,
+help me think through real Airlock use cases, and ask only for the missing
+decisions. Do not create the first workspace until I choose a path.
+```
+
+When dogfooding this implementation repo before the MCP package is published,
+Codex can install the spec-building workbench from GitHub:
+
+```bash
+git init
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install git+https://github.com/reunionstudio/airlock-mcp.git
+airlock-mcp init-repo
+```
+
+This does not require a PyPI release. `pip` installs the package directly from
+GitHub. It is a dogfood/developer path, not the public primary install.
+
+The target public install shape should be:
+
+```bash
+npx @reunionstudio/airlock-mcp install
+```
+
+The connector implementation lives in `reunionstudio/airlock-mcp`; this
+workbench keeps the Airlock MCP spec-building capability.
+
+That should install or register the Airlock MCP connector for the user's agent
+environment. After that, the user still creates a blank `<slug>-specs` project
+and starts chatting there. Airlock MCP covers building specs, using specs to
+pull and push governed data, and improving specs from real use cases.
+
+For Codex, the install command should register the server with:
+
+```bash
+codex mcp add airlock -- npx -y @reunionstudio/airlock-mcp server
+```
+
+The MCP-style flow should be:
+
+1. Run `npx @reunionstudio/airlock-mcp install` once for the agent environment.
+2. Open Codex.
+3. Create a new blank project named for the org or project, such as
+   `home-specs`.
+4. Tell Codex: `Use Airlock to help me build and use specs.`
+5. Airlock MCP welcomes, offers OODA brainstorming, a known-process draft, a
+   `posts` feedback loop, or installed-Airlock validation/use.
+
+`init-repo` creates `AGENTS.md`, `.agents/skills/airlock-mcp/SKILL.md`, and
+`workspaces/`. That is what lets Codex understand prompts such as
+`Use $airlock-mcp` inside the specs repo.
+
+After bootstrap, offer three paths before creating a workspace:
+
+- brainstorm possible specs using the OODA loop
+- start from a known process and create a blank workspace
+- create a `posts` feedback loop for humans and agents to submit requests,
+  observations, and responses
+
+## Start From Feedback
+
+Use this when the user chooses a shared feedback loop for humans and agents.
+If they are not sure what to model yet, offer OODA brainstorming before creating
+this workspace.
+
+```bash
+airlock-mcp init feedback-loop --pattern posts
+airlock-mcp check workspaces/feedback-loop
+```
+
+Then ask Codex to help decide what the posts should observe, who responds, and
+what next spec should grow from the feedback.
+
+## Start From A Known Process
+
+Use this when the process is known but the data shape is not.
+
+```bash
+airlock-mcp init weekly-timesheets --pattern blank
+```
+
+Replace the draft columns once row grain, event timestamps, typed fields,
+evidence, access, and workflow are clear.
+
+## Import An Existing Spec
+
+Use this for an Airlock spec-library file, exported `SPEC_CONFIG`, or a canonical
+config from another repo.
+
+```bash
+airlock-mcp import-spec ../airlock-specs/specs/internal/posts.json imported-posts
+airlock-mcp check workspaces/imported-posts
+```
+
+Supported input shapes:
+
+- `{"specConfig": {...}}`
+- `{"spec_config": {...}}`
+- `{"SPEC_CONFIG": "{...}"}`
+- a raw canonical object with `core_config` or `column_config`
+- a legacy `{"specs": [{"config": ...}]}`
+
+## Clone A Workspace
+
+Use this when a related spec should preserve most design choices but needs a new
+identity.
+
+```bash
+airlock-mcp clone workspaces/imported-posts team-posts
+airlock-mcp check workspaces/team-posts
+```
+
+Clone resets `core_config.spec_name`, `core_config.spec_alias`, and sample
+records. It keeps the surrounding brief and decisions so Codex can adapt them.
+
+## Organize Workspaces
+
+Use this when a workbench has more than one draft in motion.
+
+```bash
+airlock-mcp list-workspaces
+airlock-mcp list-workspaces --all
+airlock-mcp rename workspaces/weekly-timesheets weekly-time-entries
+airlock-mcp archive workspaces/old-draft
+airlock-mcp restore workspaces/_archive/old-draft
+```
+
+`rename` retitles `core_config.spec_name`, `core_config.spec_alias`, and sample
+record spec names by default so the folder and spec identity stay together. Use
+`--keep-spec-identity` when the move is purely organizational.
+
+`archive` moves a workspace under `_archive`. `list-workspaces` hides internal
+underscore directories by default and shows archived drafts with `--all`.
+
+## Resume A Session
+
+Use this at the start of a later Codex session before changing JSON.
+
+```bash
+airlock-mcp summary workspaces/team-posts
+airlock-mcp next workspaces/team-posts
+```
+
+The summary shows the current spec identity, required fields, variant fields,
+attachment posture, guest access model, sample record count, note-file status,
+and local check counts.
+
+`next` prints the same recap plus a conservative next action: fix local errors,
+review warnings, fill open design prompts in `decisions.md`, add sample records,
+or prepare export and validate-only SQL. Inline answers such as
+`One row is: a submitted receipt` count as filled.
+
+## Export Sample Records
+
+Use this when the JSON examples should be reviewed or loaded through an
+Airlock CSV-oriented path.
+
+```bash
+airlock-mcp export-csv workspaces/team-posts
+airlock-mcp export-csv workspaces/team-posts --output /tmp/team-posts.csv
+```
+
+`sample.records.json` remains the authoring shape because it is easier for
+Codex and humans to edit. `export-csv` writes columns in `column_config` order
+and serializes `variant` values as compact JSON strings.
+
+## Render Validate-Only SQL
+
+Use this as a handoff artifact for an admin or agent with Snowflake access.
+
+```bash
+airlock-mcp render-sql workspaces/team-posts
+airlock-mcp render-sql workspaces/team-posts --operation alter
+```
+
+The rendered SQL uses `validate_only => TRUE` positionally. Review installed
+Airlock documentation before changing it to a mutating call.
+
+## Update The Workbench
+
+Use dry-run first so the command is visible before anything changes.
+
+```bash
+airlock-mcp self-update --dry-run
+airlock-mcp self-update
+```
+
+From a checkout, `self-update` uses `git pull --ff-only` and refuses to run with
+uncommitted changes unless `--force` is passed. From an installed package, it
+uses `pip install --upgrade` with the configured source.
+
+## Session Rhythm
+
+1. Run `airlock-mcp check <workspace>`.
+2. Run `airlock-mcp summary <workspace>` and `airlock-mcp next <workspace>`
+   to re-enter the draft.
+3. Use `airlock-mcp list-workspaces` when choosing which draft to resume.
+4. Ask Codex to read the workspace and continue the draft.
+5. Update `decisions.md` before changing `spec.config.json` when a decision
+   affects row grain, evidence, business time, access, workflow, or references.
+6. Keep `questions.md` for decisions that need the human.
+7. Use `review.md` for local check results, Airlock validation results, and the
+   next safe action.
+8. Export CSV only after the local checker is clean or the exception is
+   deliberate and recorded.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@reunionstudio/airlock-mcp",
+  "version": "0.1.0",
+  "description": "Single-install MCP interface for Airlock agents.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reunionstudio/airlock-mcp.git"
+  },
+  "homepage": "https://github.com/reunionstudio/airlock-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/reunionstudio/airlock-mcp/issues"
+  },
+  "keywords": [
+    "airlock",
+    "mcp",
+    "codex",
+    "agents",
+    "specs"
+  ],
+  "bin": {
+    "airlock-mcp": "bin/airlock-mcp.mjs"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "src",
+    ".agents",
+    "patterns",
+    "schemas",
+    "workspaces",
+    "setup.py",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/patterns/blank/README.md

@@ -0,0 +1,14 @@
+# Starter Pattern: Blank Draft
+
+Use `blank` when the user already has a process in mind and needs a small,
+neutral observation-style starting point.
+
+This pattern keeps the first draft intentionally plain:
+
+- one stable record id
+- one business timestamp
+- one summary
+- one validated `variant` context field
+
+Replace the draft columns once the row grain and typed business facts are clear.
+Do not keep this shape just because it is convenient.

package/patterns/blank/sample.records.json

@@ -0,0 +1,19 @@
+{
+  "spec_name": "draft_spec",
+  "filename": "draft_001",
+  "records": [
+    {
+      "record_id": "REC-001",
+      "observed_at": "2026-06-13 09:00:00",
+      "summary": "Example draft record.",
+      "details": {
+        "source": {
+          "system": "manual"
+        },
+        "notes": {
+          "reason": "Used to test the draft shape."
+        }
+      }
+    }
+  ]
+}

package/patterns/blank/spec.config.json

@@ -0,0 +1,72 @@
+{
+  "core_config": {
+    "spec_name": "draft_spec",
+    "spec_alias": "Draft Spec",
+    "description": "Draft Airlock spec.",
+    "owner_role": "app_admin",
+    "is_published": false,
+    "is_archived": false
+  },
+  "column_config": [
+    {
+      "name": "record_id",
+      "type": "string",
+      "description": "Stable record identifier.",
+      "tests": ["not_null", "unique"]
+    },
+    {
+      "name": "observed_at",
+      "type": "datetime",
+      "description": "Business timestamp for the observed event.",
+      "format": "%Y-%m-%d %H:%M:%S",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "summary",
+      "type": "string",
+      "description": "Short business-readable summary.",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "details",
+      "type": "variant",
+      "description": "Optional validated context.",
+      "tests": []
+    }
+  ],
+  "rules": [
+    {
+      "type": "variant_shape",
+      "field": "details",
+      "allowed_root_keys": ["source", "notes"],
+      "paths": [
+        {
+          "json_path": "$.source.system",
+          "type": "string",
+          "required": false
+        },
+        {
+          "json_path": "$.notes.reason",
+          "type": "string",
+          "required": false
+        }
+      ]
+    }
+  ],
+  "file_rules": {
+    "file_format": {
+      "file_type": "csv",
+      "record_delimiter": "\n",
+      "field_delimiter": ",",
+      "field_optionally_enclosed_by": "\"",
+      "escape_unenclosed_field": "\\",
+      "encoding": "UTF8",
+      "parse_header": true,
+      "save_header": true
+    }
+  },
+  "attachment_policy": {
+    "attachments_enabled": true,
+    "attachment_required": false
+  }
+}

package/patterns/guest-access/individual-isolation.md

@@ -0,0 +1,27 @@
+# Guest Access: Individual Isolation
+
+Use this when each person or agent should submit into an isolated path and
+should not see another submitter's files.
+
+Good fit:
+
+- reimbursements by employee
+- private intake drafts
+- delegated assistant work for one principal
+- sensitive observations where cross-user visibility is risky
+
+Design notes:
+
+- Enable isolated directories.
+- Give each guest role the narrowest useful access level.
+- Keep manager, reviewer, or owner visibility in Airlock roles rather than
+  payload columns.
+- Use delegation when an agent acts for a specific person. Do not impersonate
+  the human by reusing their role assignment.
+
+Questions to answer:
+
+- Who owns the submitted record after review?
+- Does a reviewer need managed-role visibility across isolated submitters?
+- Can the submitter read returned drafts, approved files, or only their own
+  working path?

package/patterns/guest-access/role-isolation.md

@@ -0,0 +1,26 @@
+# Guest Access: Role Isolation
+
+Use this when groups such as departments, store locations, teams, or external
+partners need separate contribution areas.
+
+Good fit:
+
+- location-level operations logs
+- department budget packets
+- partner submissions
+- team-owned weekly reports
+
+Design notes:
+
+- Model the group as an Airlock role.
+- Use `managed_by_role` only when a non-admin business role should manage or
+  include subordinate roles.
+- Keep role membership and assignment outside the submitted payload.
+- Prefer reference specs for shared project, location, department, or partner
+  catalogs.
+
+Questions to answer:
+
+- Are records owned by the role, by individual contributors, or by both?
+- Does a parent role need read or review visibility?
+- Do role groups share a public read path after approval?