@reunionstudio/airlock-mcp 0.1.2 → 0.1.4

package/docs/workflows.md

@@ -87,9 +87,13 @@ The MCP-style flow should be:
 4. If Codex is creating it, choose where the repo directory should live before
    files are written.
 5. Tell Codex: `Use Airlock to help me improve a process with specs.`
-6. Airlock MCP welcomes, asks what process the user wants to improve, explains
-   the loop around the process, and proposes a small first spec plus a plan for
-   more.
+6. Airlock MCP welcomes and asks which delivery mode the user wants:
+   spec-first, app-first from existing specs, or co-development.
+7. For spec-first or co-development, Airlock MCP asks what process the user
+   wants to improve, explains the loop around the process, and proposes a small
+   first spec plus a plan for more.
+8. For app-first or co-development, Airlock MCP identifies the app goal,
+   available specs, read specs, write specs, runtime, and approved access path.
 
 `init-repo` creates `AGENTS.md`, `.agents/skills/airlock-mcp/SKILL.md`, and
 `workspaces/`. That is what lets Codex understand prompts such as
@@ -130,6 +134,104 @@ current artifacts and record the divergence.
 Ask for the messy version. Help turn it into a small first Airlock spec and a
 plan for more.
 
+## Build An App From Existing Specs
+
+Use this when the user already has access to specs and wants to build an app,
+dashboard, approval queue, decision UI, analysis workflow, scheduled agent, or
+other code that reads from and submits through Airlock.
+
+Do not bootstrap or edit a specs workspace by default. Work in the app repo
+unless the user asks to change specs. Start by asking for:
+
+- the app goal and decision the app should support
+- the specs the user can access
+- read specs, such as budgets, expenses, requests, forecasts, observations,
+  payouts, or reference data
+- write specs, such as decisions, approvals, comments, commitments, actions, or
+  follow-ups
+- where the app should run, such as Streamlit, web app, CLI, notebook,
+  scheduled agent, or an existing framework
+- the available Airlock/Snowflake access path
+- identity, evidence, timestamp, approval, and separation-of-duties needs
+
+Use the installed Airlock procedure grammar:
+
+- `airlock.observe.*` is read-only and should answer discovery, governance,
+  audit, health, activity, billing-event, and access-explanation questions.
+- `airlock.agent.*` is for governed work by the current actor, including
+  validation, loading, workflow actions, attachments, references, and
+  delegations.
+- `airlock.admin.*` is for administrative mutation and operational changes.
+
+For app-first work, start with observe payloads such as `observe.procedures`,
+`observe.specs`, `observe.spec`, `observe.governance_map`,
+`observe.explain_access`, `observe.health`, `observe.activity`,
+`observe.admin_activity`, `observe.spec_admin_activity`, `observe.billing`, and
+`observe.billing_events`. For `alter_spec` activity, use `CHANGED_SECTIONS` and
+`CHANGED_FIELDS` to triage what changed before fetching version snapshots. Do not use retired admin read
+wrappers such as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`,
+or `admin.list_events`; use observe list/detail procedures instead.
+
+The app should follow the loop:
+
+1. Observe/read governed records through approved Airlock or Snowflake surfaces.
+2. Orient with summaries, comparisons, ranked options, recommendations,
+   exception queues, dashboards, or proposals.
+3. Decide by capturing the human or agent choice with rationale and evidence.
+4. Act/write by submitting the decision, approval, action, comment, or follow-up
+   through an Airlock spec contract.
+
+Keep the boundary explicit: do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Do not bypass spec workflow just
+because the app can connect to Snowflake. If no suitable decision or action spec
+exists, explain the gap and propose a small spec-design step.
+
+If the app repo needs local context for coding, seed it with spec snapshots and
+a manifest:
+
+```bash
+airlock-mcp init-app-context . --mode app-first --spec ../home-specs/workspaces/expenses
+```
+
+Use `--mode co-development` when the app and specs will evolve together. Repeat
+`--spec` for each workspace or spec JSON file the app should know about. The
+command creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The app repo can import or generate helper code from these snapshots, but the
+snapshots are not canonical. Canonical specs remain in the specs repo or
+installed Airlock. Mark each manifest spec as read, write, or read_write for
+the app before building data access and submission flows.
+
+## Co-Develop Specs And App
+
+Use this when the app surface and the Airlock contracts need to shape each
+other. This is common when a dashboard, queue, approval flow, or agent workflow
+reveals which observations, proposals, decisions, or actions need governed
+records.
+
+Keep two tracks visible:
+
+- Spec track: row grain, columns, samples, attachments, access, validation,
+  workflow, and installed Airlock validation.
+- App track: screens, reads, summaries, ranked options, decision capture,
+  governed writes, runtime, and tests.
+
+Start with the smallest useful contract. The app may expose a thin prototype
+against samples while the spec is being drafted, but live submissions should
+wait for installed Airlock validation and the approved read/write path.
+
 ## Start From Feedback
 
 Use this when the user chooses a shared feedback loop for humans and agents.
@@ -144,6 +246,28 @@ 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 Governed Knowledge
+
+Use this when the user wants accepted Markdown business context for people or
+agents: policies, runbooks, metric definitions, investigations, decisions, or
+operating notes.
+
+```bash
+airlock-mcp init sales-context --pattern okf-knowledge-bundle
+airlock-mcp check workspaces/sales-context
+```
+
+This pattern sets `core_config.payload_adapter` to `okf_knowledge_bundle`.
+Installed Airlock loads locally validated bundles with
+`airlock.admin.load_okf_bundle(...)`, can refresh parsed metadata with
+`airlock.admin.sync_okf_bundle_metadata(...)`, and exposes authoritative
+accepted concept metadata through
+`AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA`.
+
+Do not treat draft or rejected Markdown bundles as authoritative agent context.
+The MCP local checker validates the spec workspace; bundle validation belongs
+to Airlock's OKF validator and installed procedures.
+
 ## Start From A Known Process
 
 Use this when the process is known but the data shape is not.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {

package/patterns/manifest.json

@@ -11,6 +11,12 @@
       "title": "Posts feedback loop",
       "summary": "Small governed feedback stream for discovering what to build next.",
       "directory": "starter-posts"
+    },
+    {
+      "name": "okf-knowledge-bundle",
+      "title": "OKF knowledge bundle",
+      "summary": "Governed Markdown knowledge bundles for accepted agent context.",
+      "directory": "okf-knowledge-bundle"
     }
   ]
 }

package/patterns/okf-knowledge-bundle/README.md

@@ -0,0 +1,64 @@
+# Starter Pattern: OKF Knowledge Bundle
+
+Use `okf-knowledge-bundle` when the team wants governed Markdown knowledge for
+people and agents to use as accepted business context.
+
+This pattern is for Airlock's `okf_knowledge_bundle` payload adapter. It is
+inspired by Google's Open Knowledge Format, but Airlock applies a narrower
+profile so accepted bundles can become governed context instead of loose wiki
+content.
+
+## Use When
+
+- Policies, runbooks, metrics, definitions, decisions, investigations, or
+  operating context need a governed place to land.
+- Agents need business context that can be accepted, audited, and queried from
+  Snowflake.
+- The team has useful Markdown knowledge, but needs Airlock workflow, PDP,
+  Expectations, evidence, and acceptance boundaries around it.
+
+## Bundle Shape
+
+- Bundle source is a directory or `.zip` archive of UTF-8 Markdown files.
+- Root `index.md` may contain bundle frontmatter such as `okf_version`,
+  `bundle_name`, `bundle_version`, `domain`, `owner`, and `purpose`.
+- Every non-reserved Markdown file is a concept document with YAML frontmatter.
+- Concept documents require `type`.
+- Recommended concept fields are `title`, `description`, `resource`, `tags`,
+  `timestamp`, and `source_links`.
+- `index.md` and `log.md` are reserved at every hierarchy level.
+
+## Airlock Contract
+
+The spec must declare:
+
+```json
+{
+  "core_config": {
+    "payload_adapter": "okf_knowledge_bundle"
+  }
+}
+```
+
+Installed Airlock provides two admin procedures for this adapter:
+
+- `airlock.admin.load_okf_bundle(...)`: load a locally validated bundle into
+  Airlock stage storage and `FILE_MANIFEST`, then project concept metadata.
+- `airlock.admin.sync_okf_bundle_metadata(...)`: project parsed concept
+  metadata for an existing active manifest row.
+
+Use `validate_only => TRUE` before writing. Treat accepted context as
+authoritative only from:
+
+```sql
+AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA
+```
+
+Draft and rejected bundles are not authoritative agent context.
+
+## Local Workbench Notes
+
+`airlock-mcp check` validates the Airlock spec draft and sample metadata. It
+does not validate a Markdown bundle. Bundle validation currently lives in the
+Airlock source repo's `airlock.okf_knowledge_bundle.validate_okf_bundle`
+helper and the installed Airlock OKF procedures.

package/patterns/okf-knowledge-bundle/sample.records.json

@@ -0,0 +1,16 @@
+{
+  "spec_name": "okf_knowledge",
+  "filename": "okf_knowledge_sample.csv",
+  "records": [
+    {
+      "concept_path": "runbooks/monthly-close",
+      "concept_type": "Runbook",
+      "bundle_version": "2026.06"
+    },
+    {
+      "concept_path": "metrics/net-revenue",
+      "concept_type": "Metric",
+      "bundle_version": "2026.06"
+    }
+  ]
+}

package/patterns/okf-knowledge-bundle/spec.config.json

@@ -0,0 +1,64 @@
+{
+  "core_config": {
+    "spec_name": "okf_knowledge",
+    "spec_alias": "OKF Knowledge",
+    "description": "Governed OKF-style Markdown knowledge bundles for accepted agent context.",
+    "owner_role": "app_admin",
+    "current_mode": "append",
+    "is_published": false,
+    "is_locked": false,
+    "is_archived": false,
+    "is_multi_role": false,
+    "file_workflow": false,
+    "workflow_steps": [],
+    "materialize_as_table": false,
+    "payload_adapter": "okf_knowledge_bundle"
+  },
+  "column_config": [
+    {
+      "name": "concept_path",
+      "type": "string",
+      "description": "Stable normalized Markdown concept path without the .md suffix.",
+      "tests": ["not_null", "unique"]
+    },
+    {
+      "name": "concept_type",
+      "type": "string",
+      "description": "Concept type from OKF frontmatter.",
+      "tests": ["not_null"]
+    },
+    {
+      "name": "bundle_version",
+      "type": "string",
+      "description": "Bundle version containing the concept.",
+      "tests": ["not_null"]
+    }
+  ],
+  "rules": [],
+  "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
+    },
+    "filename_rules": {
+      "enforce_filename_pattern": false,
+      "filename_pattern": null,
+      "sample_filenames": null
+    }
+  },
+  "sample_data": {
+    "sample_data_acknowledged": true,
+    "sample_rows": [],
+    "edited_sample_data": "concept_path,concept_type,bundle_version\nrunbooks/monthly-close,Runbook,2026.06\nmetrics/net-revenue,Metric,2026.06\n"
+  },
+  "attachment_policy": {
+    "attachments_enabled": true,
+    "attachment_required": false
+  }
+}

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.2",
+    version="0.1.4",
     description="Codex-first workbench and CLI for drafting Airlock specs.",
     packages=find_packages("src"),
     package_dir={"": "src"},

package/src/airlock_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Airlock MCP CLI package."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"

package/src/airlock_mcp/app_context.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .jsonio import read_json, write_json, write_text
+from .specs import extract_spec_config, spec_name
+
+
+APP_CONTEXT_MODES = ("spec-first", "app-first", "co-development")
+
+
+APP_README = """# Airlock App Context
+
+This folder is app-local context for building software that uses Airlock specs.
+
+The canonical specs live in the specs repo or installed Airlock. Files here are
+snapshots, samples, generated helpers, and planning context for app development.
+Refresh them when the canonical spec changes.
+
+Use:
+
+- `specs.manifest.json` to track which specs the app reads from or writes to.
+- `spec-snapshots/` for app-local copies of spec configs.
+- `sample-records/` for app-local sample records used in UI and test fixtures.
+- `generated/types/` for generated application types.
+- `generated/sql/` for reviewed SQL helpers or query templates.
+
+Installed Airlock separates procedure intent:
+
+- `observe.*`: read-only governance observation for discovery, health, access
+  explanation, activity, admin activity, billing events, governance maps, and
+  context packets.
+- `agent.*`: governed agent work in the actor's scope.
+- `admin.*`: administrative mutation and operational changes.
+
+Prefer `observe.*` for app read-side setup and monitoring questions. Use
+`observe.admin_activity` for broad admin mutation and maintenance audit
+questions, and `observe.spec_admin_activity` for one spec's definition-change
+timeline. For `alter_spec` activity, use `CHANGED_SECTIONS` and
+`CHANGED_FIELDS` to triage what changed before fetching version snapshots.
+Do not use retired admin read wrappers such as `admin.list_specs`,
+`admin.describe_role`, or `admin.list_events`; use the matching observe procedure.
+
+Do not store credentials here. Do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Use approved Airlock/Snowflake
+access paths and submit governed decisions or actions through spec contracts.
+"""
+
+
+APP_AGENTS = """# Airlock App Guidance
+
+This repo may contain application code that uses Airlock specs.
+
+## Modes
+
+- Spec-first: design governed specs before building the app surface.
+- App-first: use existing specs to build an app, dashboard, queue, or workflow.
+- Co-development: evolve the app and specs together while keeping the contract
+  explicit.
+
+## App Context
+
+The `airlock/` folder is app-local. Its spec snapshots are references for
+development, not canonical specs. Canonical specs live in the specs repo or
+installed Airlock.
+
+Keep two tracks visible during co-development:
+
+- Spec track: row grain, columns, samples, access, validation, and workflow.
+- App track: screens, reads, decisions, writes, user actions, and runtime.
+
+Use approved Airlock/Snowflake access paths. Do not bypass spec workflow or
+write directly to Airlock-owned tables, stages, generated views, or generated
+tables. If the app needs to submit a decision or action and no suitable write
+spec exists, propose a small spec-design step.
+
+Installed Airlock procedure grammar:
+
+- `observe.*` is read-only governance observation. Use it for discovery,
+  health, access explanation, governance maps, activity, billing events, and
+  context packets.
+- `agent.*` is governed agent work in the actor's scope.
+- `admin.*` is administrative mutation. Do not use retired admin read wrappers;
+  use observe list/detail procedures instead.
+"""
+
+
+@dataclass(frozen=True)
+class AppContextResult:
+    root: Path
+    mode: str
+    created: tuple[Path, ...]
+    updated: tuple[Path, ...]
+    kept: tuple[Path, ...]
+    specs: tuple[str, ...]
+
+
+def _safe_name(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_.-]+", "_", value.strip())
+    cleaned = cleaned.strip("._-").lower()
+    return cleaned or "spec"
+
+
+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)
+    write_text(path, text, force=True)
+    return "created"
+
+
+def _write_json_if_needed(path: Path, value: Any, *, force: bool) -> str:
+    if path.exists() and not force:
+        return "kept"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(path, value, force=True)
+    return "created"
+
+
+def _load_spec_source(source: Path) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    if source.is_dir():
+        raw_spec = read_json(source / "spec.config.json")
+        if not isinstance(raw_spec, dict):
+            raise ValueError(f"invalid spec workspace: {source}")
+        raw_sample = read_json(source / "sample.records.json")
+        return raw_spec, raw_sample if isinstance(raw_sample, dict) else None
+
+    raw = read_json(source)
+    if raw is None:
+        raise FileNotFoundError(source)
+    return extract_spec_config(raw), None
+
+
+def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "mode": mode,
+        "canonical_source": "specs repo or installed Airlock",
+        "snapshot_policy": "Snapshots are app-local development references, not canonical specs.",
+        "installed_airlock_contract": {
+            "observe": "read-only governance observation, context, activity, health, billing events, and access explanation",
+            "agent": "governed agent work in the actor scope",
+            "admin": "administrative mutation and operational changes",
+        },
+        "specs": entries,
+        "tracks": {
+            "spec_track": "row grain, columns, samples, access, validation, workflow",
+            "app_track": "screens, reads, decisions, writes, user actions, runtime",
+        },
+    }
+
+
+def _merge_manifest(existing: Any, new_manifest: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(existing, dict):
+        return new_manifest
+
+    merged = dict(existing)
+    merged.update(
+        {
+            "schema_version": new_manifest["schema_version"],
+            "mode": new_manifest["mode"],
+            "canonical_source": new_manifest["canonical_source"],
+            "snapshot_policy": new_manifest["snapshot_policy"],
+            "installed_airlock_contract": new_manifest["installed_airlock_contract"],
+            "tracks": new_manifest["tracks"],
+        }
+    )
+
+    existing_entries = existing.get("specs")
+    by_name: dict[str, dict[str, Any]] = {}
+    if isinstance(existing_entries, list):
+        for entry in existing_entries:
+            if isinstance(entry, dict) and isinstance(entry.get("spec_name"), str):
+                by_name[entry["spec_name"]] = dict(entry)
+
+    for entry in new_manifest["specs"]:
+        previous = by_name.get(entry["spec_name"], {})
+        merged_entry = {**previous, **entry}
+        if previous.get("role") and entry.get("role") == "unknown":
+            merged_entry["role"] = previous["role"]
+        by_name[entry["spec_name"]] = merged_entry
+
+    merged["specs"] = list(by_name.values())
+    return merged
+
+
+def init_app_context(
+    target: Path,
+    *,
+    mode: str = "app-first",
+    spec_sources: list[Path] | None = None,
+    force: bool = False,
+) -> AppContextResult:
+    if mode not in APP_CONTEXT_MODES:
+        raise ValueError(f"mode must be one of: {', '.join(APP_CONTEXT_MODES)}")
+
+    root = target.expanduser().resolve()
+    if root.exists() and not root.is_dir():
+        raise NotADirectoryError(str(root))
+    root.mkdir(parents=True, exist_ok=True)
+
+    airlock_root = root / "airlock"
+    created: list[Path] = []
+    updated: list[Path] = []
+    kept: list[Path] = []
+
+    for directory in (
+        airlock_root,
+        airlock_root / "spec-snapshots",
+        airlock_root / "sample-records",
+        airlock_root / "generated",
+        airlock_root / "generated" / "types",
+        airlock_root / "generated" / "sql",
+    ):
+        if directory.exists():
+            kept.append(directory)
+        else:
+            directory.mkdir(parents=True)
+            created.append(directory)
+
+    entries: list[dict[str, Any]] = []
+    spec_names: list[str] = []
+    for source in spec_sources or []:
+        spec_config, sample_records = _load_spec_source(source.expanduser())
+        name = spec_name(spec_config)
+        safe = _safe_name(name)
+        snapshot_path = airlock_root / "spec-snapshots" / f"{safe}.spec.config.json"
+        bucket = created if _write_json_if_needed(snapshot_path, spec_config, force=force) == "created" else kept
+        bucket.append(snapshot_path)
+
+        sample_relative: str | None = None
+        if sample_records is not None:
+            sample_path = airlock_root / "sample-records" / f"{safe}.sample.records.json"
+            bucket = created if _write_json_if_needed(sample_path, sample_records, force=force) == "created" else kept
+            bucket.append(sample_path)
+            sample_relative = str(sample_path.relative_to(root))
+
+        core = spec_config.get("core_config")
+        core = core if isinstance(core, dict) else {}
+        entries.append(
+            {
+                "spec_name": name,
+                "spec_alias": core.get("spec_alias"),
+                "source": str(source),
+                "snapshot": str(snapshot_path.relative_to(root)),
+                "sample_records": sample_relative,
+                "role": "unknown",
+                "snapshot_only": True,
+            }
+        )
+        spec_names.append(name)
+
+    for path, content in (
+        (airlock_root / "README.md", APP_README),
+        (airlock_root / "AGENTS.md", APP_AGENTS),
+        (airlock_root / "generated" / "types" / ".gitkeep", ""),
+        (airlock_root / "generated" / "sql" / ".gitkeep", ""),
+    ):
+        bucket = created if _write_text_if_needed(path, content, force=force) == "created" else kept
+        bucket.append(path)
+
+    manifest_path = airlock_root / "specs.manifest.json"
+    manifest = _manifest(mode, entries)
+    if manifest_path.exists() and not force:
+        write_json(manifest_path, _merge_manifest(read_json(manifest_path), manifest), force=True)
+        updated.append(manifest_path)
+    else:
+        bucket = created if _write_json_if_needed(manifest_path, manifest, force=force) == "created" else kept
+        bucket.append(manifest_path)
+
+    return AppContextResult(
+        root=airlock_root,
+        mode=mode,
+        created=tuple(created),
+        updated=tuple(updated),
+        kept=tuple(kept),
+        specs=tuple(spec_names),
+    )
+
+
+def format_app_context_result(result: AppContextResult) -> str:
+    lines = [f"initialized app context {result.root}", f"mode: {result.mode}"]
+    for path in result.created:
+        lines.append(f"created {path.relative_to(result.root.parent)}")
+    for path in result.updated:
+        lines.append(f"updated {path.relative_to(result.root.parent)}")
+    for path in result.kept:
+        lines.append(f"kept {path.relative_to(result.root.parent)}")
+    lines.append("seeded_specs: " + (", ".join(result.specs) if result.specs else "none"))
+    lines.extend(
+        [
+            "",
+            "next:",
+            "1. Treat spec snapshots as app-local references, not canonical specs.",
+            "2. Mark each manifest spec as read, write, or read_write for the app.",
+            "3. Use observe.* for read-only governance discovery and agent.* for governed actor work.",
+            "4. Build governed submissions through approved Airlock/Snowflake access paths.",
+        ]
+    )
+    return "\n".join(lines)

package/src/airlock_mcp/art.py

@@ -21,6 +21,6 @@ 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
+commands: init-repo, init-app-context, 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.
 """