@reunionstudio/airlock-mcp 0.1.0

package/patterns/guest-access/shared-contribution.md

@@ -0,0 +1,25 @@
+# Guest Access: Shared Contribution
+
+Use this when many people or agents contribute to the same governed dataset.
+
+Good fit:
+
+- posts and feedback
+- general ops issues
+- shared observations
+- public append-only signal streams
+
+Design notes:
+
+- Enable a public append path for normal contribution.
+- Consider a public read path only when contributors may safely see the shared
+  data.
+- Use workflow for moderation, triage, and pushback.
+- Use typed routing fields or tags for simple triage; create specialized specs
+  only when lifecycle, evidence, validation, or ownership diverges.
+
+Questions to answer:
+
+- Can contributors read all records, or only append?
+- Does moderation happen before records become visible?
+- What downstream agent or human watches the shared dataset?

package/patterns/manifest.json

@@ -0,0 +1,16 @@
+{
+  "patterns": [
+    {
+      "name": "blank",
+      "title": "Blank draft",
+      "summary": "Minimal observation-style draft for a known process.",
+      "directory": "blank"
+    },
+    {
+      "name": "posts",
+      "title": "Posts feedback loop",
+      "summary": "Small governed feedback stream for discovering what to build next.",
+      "directory": "starter-posts"
+    }
+  ]
+}

package/patterns/spec-types/commitment.md

@@ -0,0 +1,24 @@
+# Spec Type: Commitment
+
+A commitment spec records a decision or promise the business intends to honor or
+send downstream.
+
+Good fit:
+
+- approved budget requests
+- payment commitments
+- outbound product updates
+- accepted offers or invitations
+
+Design notes:
+
+- Distinguish the observed inputs from the committed output.
+- Use workflow for approval and pushback.
+- Use references to link back to source observations, requests, projects, or
+  counterparties.
+- Use expectations when commitments must happen in order or by a due date.
+
+Avoid:
+
+- copying every upstream observation field into the commitment
+- hiding approval state in payload columns instead of Airlock workflow

package/patterns/spec-types/observation.md

@@ -0,0 +1,22 @@
+# Spec Type: Observation
+
+An observation spec records something a person, agent, export, browser capture,
+or API observed.
+
+Use typed columns for:
+
+- observed object id
+- source system or URL
+- observed or captured timestamp
+- status, amount, category, or score used in decisions
+- capture method
+
+Use attachments for screenshots, PDFs, exports, receipts, or other evidence.
+Use a validated `variant` for optional source payload context.
+
+Avoid:
+
+- using Airlock load time as the event timestamp
+- placing raw attachment bytes in payload fields
+- mixing observations and commitments in one row unless `record_type` is an
+  intentional design choice

package/patterns/spec-types/reconciliation.md

@@ -0,0 +1,19 @@
+# Spec Type: Reconciliation
+
+A reconciliation spec compares two or more systems, datasets, or expectations
+and records the business difference that needs attention.
+
+Good fit:
+
+- commerce listing gaps
+- payment versus invoice matching
+- ad spend versus campaign records
+- inventory or order discrepancies
+
+Design notes:
+
+- Make the row grain the discrepancy, match group, or reconciliation finding.
+- Preserve stable keys from every compared system.
+- Use typed fields for match status, amounts, dates, and source identifiers.
+- Use a validated `variant` for optional comparison detail.
+- Use workflow when a human must resolve or accept the finding.

package/patterns/spec-types/reference-master-data.md

@@ -0,0 +1,21 @@
+# Spec Type: Reference Or Master Data
+
+A reference/master-data spec provides controlled data that other specs validate
+against or read from.
+
+Good fit:
+
+- projects
+- departments
+- vendors
+- employees
+- locations
+- chart-of-accounts segments
+
+Design notes:
+
+- Use stable keys and readable aliases.
+- Keep lifecycle simple unless changes require review.
+- Use references from transactional specs into these keys.
+- Consider a read-only reference spec over a materialized table for high-read
+  agent workflows.

package/patterns/starter-posts/README.md

@@ -0,0 +1,32 @@
+# Starter Pattern: Posts
+
+Use `posts` when the team does not yet know which larger Airlock spec to build.
+It creates a small governed feedback loop:
+
+- a person or agent submits a post, request, observation, or response
+- optional structured details are captured in a validated `variant`
+- other people or agents can review the feed and decide what spec to build next
+
+This pattern is intentionally humble. It gives the organization a safe place to
+observe demand before designing a bigger workflow.
+
+## When To Use
+
+- You are starting from fuzzy process needs.
+- You want feedback from users inside Snowflake.
+- You want agents to ask for, respond to, or triage requests.
+- You need a governed signal stream before committing to specialized specs.
+
+## Adapt Carefully
+
+Keep the core small:
+
+- one row is one post
+- `post_id` is stable and retry-safe
+- `body` is the human-readable signal
+- `tags` supports light routing
+- `details` holds optional structured context
+
+Create separate specs later when posts become reimbursements, budget requests,
+project issues, support tickets, or outbound commitments with different
+validation, evidence, workflow, or ownership.

package/patterns/starter-posts/sample.records.json

@@ -0,0 +1,27 @@
+{
+  "spec_name": "posts",
+  "filename": "post_001",
+  "records": [
+    {
+      "post_id": "POST-001",
+      "reply_to_post_id": "",
+      "submitted_by": "agent.deb",
+      "posted_at": "2026-06-13 09:00:00",
+      "body": "Please make reimbursements easier to prepare and submit.",
+      "tags": "#request #finance #reimbursements",
+      "related_area": "finance",
+      "related_process": "employee reimbursements",
+      "details": {
+        "source": {
+          "system": "codex"
+        },
+        "request": {
+          "desired_outcome": "An approved agent can prepare a draft reimbursement with receipt evidence."
+        },
+        "agent": {
+          "name": "Deb"
+        }
+      }
+    }
+  ]
+}

package/patterns/starter-posts/spec.config.json

@@ -0,0 +1,135 @@
+{
+  "core_config": {
+    "spec_name": "posts",
+    "spec_alias": "Posts",
+    "description": "Governed feedback, requests, observations, and responses from people or agents.",
+    "owner_role": "app_admin",
+    "is_published": false,
+    "is_archived": false
+  },
+  "column_config": [
+    {
+      "name": "post_id",
+      "type": "string",
+      "description": "Stable post identifier supplied by the submitting person or agent.",
+      "tests": ["not_null", "unique"]
+    },
+    {
+      "name": "reply_to_post_id",
+      "type": "string",
+      "description": "Optional parent post id when this post is a response.",
+      "tests": []
+    },
+    {
+      "name": "submitted_by",
+      "type": "string",
+      "description": "Business-facing submitter label or upstream user id.",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "posted_at",
+      "type": "datetime",
+      "description": "Business timestamp when the post was authored or captured.",
+      "format": "%Y-%m-%d %H:%M:%S",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "body",
+      "type": "string",
+      "description": "Plain-language feedback, request, observation, or response.",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "tags",
+      "type": "string",
+      "description": "Optional routing tags such as #request, #bug, #finance, or #spec-gap.",
+      "tests": []
+    },
+    {
+      "name": "related_area",
+      "type": "string",
+      "description": "Optional business area such as finance, operations, support, product, or commerce.",
+      "tests": []
+    },
+    {
+      "name": "related_process",
+      "type": "string",
+      "description": "Optional process this post may lead to, such as reimbursements or budget requests.",
+      "tests": []
+    },
+    {
+      "name": "details",
+      "type": "variant",
+      "description": "Optional structured context for source, request, evidence metadata, or agent notes.",
+      "tests": []
+    }
+  ],
+  "rules": [
+    {
+      "type": "variant_shape",
+      "field": "details",
+      "allowed_root_keys": ["source", "request", "evidence", "agent"],
+      "paths": [
+        {
+          "json_path": "$.source.system",
+          "type": "string",
+          "required": false
+        },
+        {
+          "json_path": "$.request.desired_outcome",
+          "type": "string",
+          "required": false
+        },
+        {
+          "json_path": "$.evidence.url",
+          "type": "string",
+          "required": false
+        },
+        {
+          "json_path": "$.agent.name",
+          "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
+  },
+  "guest_access": {
+    "isolated_directories_enabled": false,
+    "public_folder": {
+      "enabled": true,
+      "subfolders": {
+        "append_access": {
+          "enabled": true
+        },
+        "read_access": {
+          "enabled": true
+        },
+        "full_access": {
+          "enabled": false
+        }
+      }
+    },
+    "guest_roles": [
+      {
+        "role_name": "agent",
+        "access_level": "append_access"
+      }
+    ]
+  }
+}

package/schemas/airlock-mcp-workspace.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Airlock MCP Workspace",
+  "type": "object",
+  "required": ["brief", "decisions", "spec_config", "sample_records"],
+  "properties": {
+    "brief": { "type": "string" },
+    "decisions": { "type": "string" },
+    "questions": { "type": "string" },
+    "review": { "type": "string" },
+    "spec_config": { "type": "object" },
+    "sample_records": { "type": "object" }
+  }
+}

package/setup.py

@@ -0,0 +1,41 @@
+from glob import glob
+from os.path import isfile
+
+from setuptools import find_packages, setup
+
+
+def data_files():
+    files = [
+        (
+            "airlock_mcp/.agents/skills/airlock-mcp",
+            [path for path in glob(".agents/skills/airlock-mcp/*") if isfile(path)],
+        ),
+        (
+            "airlock_mcp/.agents/skills/airlock-mcp/agents",
+            [path for path in glob(".agents/skills/airlock-mcp/agents/*") if isfile(path)],
+        ),
+        ("airlock_mcp/patterns", ["patterns/manifest.json"]),
+        ("airlock_mcp/workspaces/_template", glob("workspaces/_template/*")),
+    ]
+    for pattern_dir in glob("patterns/*"):
+        if pattern_dir.endswith("manifest.json"):
+            continue
+        if glob(f"{pattern_dir}/*"):
+            files.append((f"airlock_mcp/{pattern_dir}", glob(f"{pattern_dir}/*")))
+    return files
+
+
+setup(
+    name="airlock-mcp",
+    version="0.1.0",
+    description="Codex-first workbench and CLI for drafting Airlock specs.",
+    packages=find_packages("src"),
+    package_dir={"": "src"},
+    python_requires=">=3.9",
+    data_files=data_files(),
+    entry_points={
+        "console_scripts": [
+            "airlock-mcp=airlock_mcp.cli:main",
+        ],
+    },
+)

package/src/airlock_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Airlock MCP CLI package."""
+
+__version__ = "0.1.0"

package/src/airlock_mcp/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/airlock_mcp/art.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from . import __version__
+
+
+MCP_MARK = r"""
+      airlock-mcp
+
+          __
+     ____/ /__        draft specs
+    / __  / _ \       check the shape
+   /_/ /_/\___/       forge the handoff
+
+        _________
+   ____/_______/ \____
+       \_______\_/
+"""
+
+
+def about_text() -> str:
+    return f"""{MCP_MARK.rstrip()}
+
+version: {__version__}
+commands: init-repo, init, import-spec, clone, rename, archive, restore, list-workspaces, summary, next, check, export-csv, render-sql, self-update
+principle: Codex is the conversation; files are memory; Airlock is authority.
+"""

package/src/airlock_mcp/bootstrap.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .project import repo_root
+
+
+AGENTS_MD = """# Airlock Spec Workspace Guidance
+
+This repo is an Airlock MCP workspace for drafting Airlock specs with Codex.
+
+## Product Shape
+
+The public install surface is Airlock MCP, for example
+`npx @reunionstudio/airlock-mcp install`. Airlock MCP is the single installed
+interface for building specs, using specs, pulling and pushing governed data,
+and discovering improvements from real use cases. This project repo remains
+the durable memory for the specs being drafted.
+
+## Repo Naming
+
+When helping create a new specs repo, ask for the project or organization name
+and suggest `<slug>-specs`: lowercase the name, replace spaces with hyphens,
+and append `-specs`. For example, `Home` becomes `home-specs`.
+
+Reserve `airlock-specs` for the canonical reusable Airlock spec library. A
+team, customer, domain, or project should use its own scoped repo name such as
+`home-specs`, `acme-finance-specs`, or `customer-onboarding-specs`.
+
+Airlock itself does not create this repo. Codex can create it locally while
+helping the user start an Airlock MCP project, then Airlock receives the
+finished spec later. Start in Codex, not Snowflake Cortex. Snow CLI or Cortex
+only matters later when validating, creating, or operating specs against an
+installed Airlock app.
+
+## Starting A Spec Project
+
+After bootstrap, welcome the user and orient before creating a workspace. Ask
+whether they want to:
+
+- brainstorm possible specs with the OODA loop
+- start from a known process they already have in mind
+- create a shared `posts` feedback loop for humans and agents to submit
+  requests, observations, and responses
+
+Create `posts` only when the user chooses a feedback loop or explicitly asks
+for the posts pattern.
+
+## Working Style
+
+- Use the repo-scoped `$airlock-mcp` skill for spec drafting, review, and
+  pattern selection.
+- Keep drafts small and concrete. Prefer one useful governed output over a
+  large speculative process map.
+- Preserve decisions in workspace files so future Codex sessions can resume
+  without relying on chat memory.
+- Use `airlock-mcp list-workspaces` before guessing which draft to resume.
+- Use `airlock-mcp summary <workspace>` and `airlock-mcp next <workspace>`
+  before editing an existing draft.
+- Keep `sample.records.json` as the editable authoring shape, then use
+  `airlock-mcp export-csv <workspace>` when Airlock-ready CSV examples are
+  needed.
+- Treat Airlock as the execution authority. Local checks are guardrails, not a
+  replacement for installed Airlock validation.
+
+## Spec Design Priorities
+
+Resolve these before final JSON:
+
+- row grain
+- durable identifiers
+- business event timestamps
+- typed columns versus validated variants
+- attachment evidence
+- guest access and path isolation
+- workflow and pushback
+- references and expectations
+- delegation and agent identity
+- observe-orient-decide-act loop
+
+Do not encode Airlock lifecycle state, reviewer notes, approval status, or
+workflow transitions as submitted payload fields unless they are true upstream
+business facts.
+"""
+
+
+@dataclass(frozen=True)
+class BootstrapResult:
+    root: Path
+    created: tuple[Path, ...]
+    kept: tuple[Path, ...]
+
+
+def _write_text_if_needed(path: Path, text: str, *, force: bool) -> str:
+    if path.exists() and not force:
+        return "kept"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    return "created"
+
+
+def _copy_file_if_needed(source: Path, target: Path, *, force: bool) -> str:
+    if target.exists() and not force:
+        return "kept"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+    return "created"
+
+
+def bootstrap_repo(target: Path, *, force: bool = False) -> BootstrapResult:
+    root = target.expanduser().resolve()
+    if root.exists() and not root.is_dir():
+        raise NotADirectoryError(str(root))
+
+    created: list[Path] = []
+    kept: list[Path] = []
+    root.mkdir(parents=True, exist_ok=True)
+
+    workspace_root = root / "workspaces"
+    if workspace_root.exists():
+        kept.append(workspace_root)
+    else:
+        workspace_root.mkdir()
+        created.append(workspace_root)
+
+    agents_path = root / "AGENTS.md"
+    bucket = created if _write_text_if_needed(agents_path, AGENTS_MD, force=force) == "created" else kept
+    bucket.append(agents_path)
+
+    source_skill = repo_root() / ".agents" / "skills" / "airlock-mcp"
+    if not source_skill.exists():
+        raise FileNotFoundError(str(source_skill))
+
+    target_skill = root / ".agents" / "skills" / "airlock-mcp"
+    for source_file in sorted(path for path in source_skill.rglob("*") if path.is_file()):
+        relative = source_file.relative_to(source_skill)
+        target_file = target_skill / relative
+        bucket = created if _copy_file_if_needed(source_file, target_file, force=force) == "created" else kept
+        bucket.append(target_file)
+
+    return BootstrapResult(root=root, created=tuple(created), kept=tuple(kept))
+
+
+def format_bootstrap_result(result: BootstrapResult) -> str:
+    lines = [f"initialized {result.root}"]
+    for path in result.created:
+        lines.append(f"created {path.relative_to(result.root)}")
+    for path in result.kept:
+        lines.append(f"kept {path.relative_to(result.root)}")
+    lines.extend(
+        [
+            "",
+            "next:",
+            "1. Open this repo in Codex.",
+            "2. Ask: Use Airlock to help me build and use specs.",
+            "3. Choose OODA brainstorming, a known process, or a posts feedback loop.",
+        ]
+    )
+    return "\n".join(lines)