@reunionstudio/airlock-mcp 0.1.6 → 0.1.7

package/.agents/skills/airlock-mcp/SKILL.md

@@ -194,6 +194,19 @@ Use three delivery modes:
 - Co-development: develop the app and specs together, keeping the contract and
   experience visible side by side.
 
+Treat Airlock's built-in Streamlit Native App as a generic operating and
+fallback surface. It is appropriate for administration, inspection, evidence,
+workflow, and occasional manual action. It is not intended to become the best
+domain application for every spec.
+
+Recommend a purpose-built app when repeated, high-value work such as
+reimbursement review, vendor onboarding, or employee-record changes benefits
+from specialized summaries, calculations, terminology, evidence layout, or
+controls. The app owns that experience while Airlock owns access, validation,
+expectations, evidence, workflow, activity, and observable governance. Keep UI
+layout and aggregation choices in app code unless they are genuinely governed
+business semantics shared across interfaces.
+
 Start by identifying:
 
 1. The app goal: what the user needs to orient around or decide.
@@ -216,6 +229,29 @@ Airlock:
 - `airlock.admin.*` performs administrative changes and operational mutations.
 - `airlock.agent.*` performs governed user or agent work in the actor's scope.
 
+Use `agent.list_my_work` as the actor's single operational inbox for workflow,
+watcher, deadline, overdue, and exception work. Use `observe.work` for the
+read-only account-wide current-work projection and `observe.activity` for event
+history. Do not call the retired split work procedures.
+
+For efficient watcher loops, call `agent.spec_state` first and cache the
+role-scoped `STATE_TOKEN`. Retrieve `describe_spec`, file listings, or governed
+data only after it changes. Poll `agent.list_my_work` independently because
+deadlines and expectation windows can change without a spec mutation. For one selected logical file, compare
+`agent.file_state(...).FILE_STATE_ID`; it rotates for data replacement,
+workflow, attachment, and exact-reference changes. Use `observe.spec_state` and
+`observe.file_state` only with observer/admin authority for account-wide state.
+Do not substitute global observer tokens for an agent's scoped token.
+
+Required source references are exact governed evidence, not filename fields.
+When an active downstream-to-source link has `min_count > 0`, load the
+downstream file into Draft, discover eligible sources with
+`agent.list_eligible_source_files`, pin exact manifest rows with
+`agent.add_file_reference`, and then call
+`agent.edit_file_workflow(action => 'advance')`. Branch on
+`SOURCE_REFERENCE_REQUIRED` and `SOURCE_REFERENCE_CHECK_FAILED`; do not bypass
+the gate by copying an identifier into submitted business data.
+
 For app-first work, prefer `observe.procedures`, `observe.specs`,
 `observe.spec`, `observe.governance_map`, `observe.explain_access`,
 `observe.health`, `observe.activity`, `observe.admin_activity`,
@@ -227,6 +263,36 @@ as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`, or
 Use `admin.*` only when the app is intentionally changing Airlock setup or
 running an admin operation.
 
+For a structural spec change with active files, treat
+`SPEC_MIGRATION_REQUIRED` as a governed lifecycle, not an error to bypass. Use
+`admin.create_spec_revision`, `admin.create_spec_migration`,
+`admin.validate_spec_migration`, `admin.approve_spec_migration`,
+`admin.activate_spec_migration`, bounded `admin.run_spec_migration` calls,
+`observe.spec_migrations`, `observe.spec_migration`, and
+`admin.retire_spec_migration`. Before activation, an abandoned `draft`,
+`planned`, `validated`, or `approved` migration may be released with
+`admin.cancel_spec_migration`; never describe cancellation as rollback after
+activation. Preserve the full
+proposed config, use only the bounded declarative transform over immutable
+`column_id` values, and surface stable status, issue, progress, and lineage
+fields. Never invent direct SQL/Python migration escape hatches.
+
+If activation returns `SPEC_MIGRATION_ACTIVATED_WITH_REPAIR_REQUIRED`, the
+target is already active. Repair the reported target view or materialized
+table, call `admin.rebuild_access_index(TRUE)`, and re-read
+`observe.spec_migration`; do not retry activation. Airlock intentionally keeps
+stale surfaces unavailable and compiled agent access invalidated until repair.
+
+The migration runner claims bounded work before stage or manifest effects.
+Treat header renames as transformed successors, never zero-copy. For sequential
+migrations, effective source currency comes from append-only valid
+attestations. Re-attest an upgraded active file with unknown provenance by
+loading its existing staged path; Airlock validates its exact digest and updates
+the manifest in place. `source_preserved` keeps transformed source bytes out of
+ordinary retention purge. `SPEC_MIGRATION_ACTIVE` blocks a second data-contract
+revision until retirement but still permits metadata and governance repairs on
+the current data version.
+
 Restricted references are one-record interaction contracts for read-only
 reference specs. If `agent.describe_spec`, `observe.spec`,
 `observe.spec_config`, or `observe.reference_context` shows

package/README.md

@@ -44,12 +44,63 @@ Current Airlock separates procedure intent:
   specs, validating/loading data, workflow actions, attachments, delegations,
   and references.
 
+Use `airlock.agent.list_my_work(...)` for the current actor's unified workflow,
+watcher, deadline, overdue, and exception inbox. Use `airlock.observe.work(...)`
+for the read-only account-wide projection of current work, and
+`airlock.observe.activity(...)` for historical events. The older split work
+procedures are retired.
+
+Watcher agents should poll `airlock.agent.spec_state(...)` before retrieving a
+complete descriptor, file list, or governed dataset. Cache the
+authorization-scoped `STATE_TOKEN` and perform the heavier read only when it
+changes. Poll `airlock.agent.list_my_work(...)` independently because deadlines
+and expectation windows can change with time without rotating a spec token.
+After selecting a logical file, compare
+`airlock.agent.file_state(...).FILE_STATE_ID`; that UUID rotates when its data,
+workflow, attachments, or exact source references change. Observer clients use
+the account-wide read-only `observe.spec_state(...)` and
+`observe.file_state(...)` equivalents.
+
 When building an app or workflow, prefer `observe.*` for read-only setup and
 monitoring questions, `agent.*` for governed submissions in the actor's scope,
 and `admin.*` only for intentional administrative mutation. Do not use retired
 admin read wrappers such as `admin.list_specs`, `admin.describe_role`, or
 `admin.list_events`; use the matching observe procedures instead.
 
+Structural spec changes with active data use Airlock's governed migration
+lifecycle. Agents should preserve the proposed config and guide an
+administrator through immutable revision, declarative migration planning,
+all-row proof, approval, activation, bounded execution, observable lineage, and
+source retirement. `SPEC_MIGRATION_REQUIRED` is a safety boundary; it is not a
+reason to mutate Airlock-owned storage directly.
+
+Migration execution claims bounded work before storage effects. Renamed headers
+produce transformed successors, sequential migrations rely on append-only
+validation attestations, and upgraded files with unknown provenance are
+re-attested in place through normal `load_data`. `source_preserved` protects
+transformed source bytes from ordinary retention purge, while
+`SPEC_MIGRATION_ACTIVE` prevents another data-contract revision until the
+current migration retires.
+
+## Built-In UI And Purpose-Built Apps
+
+Airlock's Streamlit Native App is deliberately a generic operating and fallback
+surface. It supports administration, inspection, governed data and attachment
+review, workflow visibility, and safe manual action. It should not be treated as
+a universal domain application builder.
+
+Repeated, high-value decisions such as reimbursements, vendor onboarding, or
+employee-record changes may deserve purpose-built interfaces. Airlock MCP should
+recommend app-first or co-development for those cases and help build the custom
+surface against Airlock contracts. The app owns domain summaries,
+calculations, terminology, and interaction design; Airlock continues to own
+access, validation, expectations, evidence, workflow, activity, and observable
+governance.
+
+Do not add UI layout or aggregation fields to a spec merely to make the generic
+Native App imitate custom software. Presentation belongs in app code unless it
+is genuinely governed business semantics shared across interfaces.
+
 ## Install
 
 Dogfood directly from GitHub:
@@ -221,6 +272,31 @@ For app-first work against installed Airlock, start with `observe.procedures`,
 before designing direct SQL helpers. These payloads are intended to be useful
 to agents as well as humans.
 
+For operational queues, call `agent.list_my_work` in the actor's scope. An
+observer may call `observe.work` for all current work; historical questions
+belong to `observe.activity`.
+
+Required source references are a governed submission contract. When a
+downstream spec has an active source link with `min_count > 0`, load the file
+into Draft, discover eligible evidence with `agent.list_eligible_source_files`,
+pin exact manifest rows with `agent.add_file_reference`, and only then call
+`agent.edit_file_workflow(action => 'advance')`. Missing, removed, or
+wrong-workflow-state evidence returns `SOURCE_REFERENCE_REQUIRED` without
+moving the file. Do not replace the exact Airlock reference with a filename or
+identifier copied into business data.
+
+Structural spec changes with active files use Airlock's governed two-version
+migration lifecycle. Treat `SPEC_MIGRATION_REQUIRED` as a request to create an
+immutable revision and migration, validate and approve it, activate the target,
+drain bounded batches with `admin.run_spec_migration`, inspect progress and
+lineage through `observe.spec_migration`, and retire the source only after the
+evidence gate passes. Use `observe.spec_migrations` to discover and filter
+migrations. Before activation, an abandoned `draft`, `planned`, `validated`, or
+`approved` migration may be released with `admin.cancel_spec_migration`;
+cancellation is not rollback after activation. The transform language is intentionally limited to
+mechanical mappings, defaults, and safe casts; semantic transforms belong in a
+purpose-built process that reloads through normal Airlock validation.
+
 Restricted references are one-record interaction contracts. When
 `observe.reference_context`, `observe.spec_config`, or `agent.describe_spec`
 shows `restricted_reference` or `reference_config.restricted_reference`, agents

package/docs/install-surface.md

@@ -46,6 +46,15 @@ access uses Snowflake download links when available. Successful PDF page
 previews emit metadata-only `ATTACHMENT_PREVIEW` activity. This UI capability
 does not grant MCP clients direct stage access.
 
+The Native App is deliberately a generic operating and fallback surface. It
+should support administration, inspection, evidence, workflow, and safe manual
+action without accumulating every domain's presentation rules. Airlock MCP
+should recommend app-first or co-development when repeated, high-value work
+deserves a purpose-built interface. The custom app owns domain summaries,
+calculations, terminology, and controls while Airlock remains the governed
+backend. UI layout and aggregation hints should not be added to specs merely to
+polish the generic app.
+
 The connector package and MCP server live in `reunionstudio/airlock-mcp`.
 This workbench provides the spec-building implementation inside that one
 installed Airlock MCP experience.

package/docs/workflows.md

@@ -154,6 +154,17 @@ unless the user asks to change specs. Start by asking for:
 - the available Airlock/Snowflake access path
 - identity, evidence, timestamp, approval, and separation-of-duties needs
 
+Airlock's built-in Streamlit Native App is a generic operating and fallback
+surface, not a universal domain application builder. Use it for administration,
+inspection, governed evidence, workflow, and occasional manual action. For
+repeated high-value decisions, prefer a purpose-built app when domain-specific
+summaries, calculations, evidence layout, terminology, or controls materially
+improve the work.
+
+Keep those presentation choices in app code. Do not add layout or aggregation
+fields to an Airlock spec merely to make the generic UI imitate custom
+software. Airlock remains the governed backend for either surface.
+
 Use the installed Airlock procedure grammar:
 
 - `airlock.observe.*` is read-only and should answer discovery, governance,
@@ -163,6 +174,69 @@ Use the installed Airlock procedure grammar:
   delegations.
 - `airlock.admin.*` is for administrative mutation and operational changes.
 
+For work discovery, use `agent.list_my_work` as the current actor's unified
+inbox. Observers use `observe.work` for account-wide current work and
+`observe.activity` for historical events. Do not recreate separate workflow
+and expectation inbox calls in app code.
+
+Watcher loops should call `agent.spec_state` before larger reads. Cache its
+authorization-scoped `STATE_TOKEN` and retrieve descriptors, file lists, or
+governed data only when it changes. Poll `agent.list_my_work` independently
+because deadlines and expectation windows can change without rotating the spec
+token. Once the app tracks one logical file,
+compare `agent.file_state(...).FILE_STATE_ID` to detect data replacement,
+workflow movement, attachment changes, or exact-reference changes. Observer
+services may use the global read-only `observe.spec_state` and
+`observe.file_state` equivalents.
+
+For downstream work that requires governed source evidence, use the installed
+source-reference sequence: load the downstream Draft, call
+`agent.list_eligible_source_files`, pin exact source manifest rows with
+`agent.add_file_reference`, then advance workflow. Active source links with
+`min_count > 0` are enforced by `agent.edit_file_workflow`; required sources
+must still exist, remain unremoved, and match any configured
+`required_workflow_status`. Branch on `SOURCE_REFERENCE_REQUIRED` or
+`SOURCE_REFERENCE_CHECK_FAILED` and show the returned `ISSUES` instead of
+guessing at alternate source identifiers.
+
+When an app or administrator changes a spec's data contract, do not work around
+`SPEC_MIGRATION_REQUIRED` with direct table, stage, or view changes. Use the
+installed governed lifecycle: `admin.create_spec_revision`,
+`admin.create_spec_migration`, `admin.validate_spec_migration`,
+`admin.approve_spec_migration`, `admin.activate_spec_migration`, bounded calls
+to `admin.run_spec_migration`, inspection through
+`observe.spec_migrations` and `observe.spec_migration`, and finally
+`admin.retire_spec_migration`. Before activation, use
+`admin.cancel_spec_migration` to release an abandoned `draft`, `planned`,
+`validated`, or `approved` migration. Cancellation is not rollback after
+activation. The
+transform is declarative and keyed by immutable `column_id` values; arbitrary
+SQL or Python is not part of the contract. Approval is intent, activation is
+the write-version switch, and retirement is a separate guarded action.
+
+Treat `SPEC_MIGRATION_ACTIVATED_WITH_REPAIR_REQUIRED` as a committed activation,
+not a retryable pre-activation failure. Follow the returned issues to rebuild
+the target view or materialized table, then call
+`admin.rebuild_access_index(TRUE)` and re-read `observe.spec_migration`. Airlock
+keeps stale read surfaces unavailable and compiled agent access invalidated
+until repair succeeds.
+
+`admin.run_spec_migration` claims each bounded item batch before stage or
+manifest side effects. A header rename always creates a transformed successor;
+zero-copy is reserved for stored headers and values that already satisfy the
+target contract. Use append-only valid attestations, not only the manifest's
+original version pointer, when a file moves through sequential migrations.
+
+An upgraded active file may have `validation_provenance_status = 'unknown'`.
+Re-load its existing staged path through `load_data`: after validation and an
+exact digest recheck, Airlock re-attests the existing manifest in place instead
+of creating a duplicate stage-path owner. A `source_preserved` migration keeps
+transformed source bytes outside ordinary retention purge; `forward_only`
+allows normal retention. While a migration is active,
+`SPEC_MIGRATION_ACTIVE` blocks another data-contract revision until retirement,
+although metadata, access, policy, expectation, and workflow repairs remain
+allowed on the current data version.
+
 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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {
@@ -27,7 +27,8 @@
   "files": [
     "bin",
     "docs",
-    "src",
+    "src/*.mjs",
+    "src/airlock_mcp/*.py",
     ".agents",
     "patterns",
     "schemas",

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.6",
+    version="0.1.7",
     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.6"
+__version__ = "0.1.7"

package/src/airlock_mcp/app_context.py

@@ -20,6 +20,12 @@ 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.
 
+Airlock's built-in Streamlit Native App is a generic operating and fallback
+surface. A purpose-built app is the preferred place for domain-specific
+summaries, calculations, evidence layout, terminology, and controls when those
+features materially improve repeated, high-value work. Keep presentation in
+app code rather than adding UI layout or aggregation hints to Airlock specs.
+
 Use:
 
 - `specs.manifest.json` to track which specs the app reads from or writes to.
@@ -36,6 +42,28 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Use `agent.list_my_work` for the actor's unified current-work inbox,
+`observe.work` for account-wide current work, and `observe.activity` for
+historical events. The older split workflow/expectation work calls are retired.
+
+Required source references are exact governed evidence. For an active source
+link with `min_count > 0`, load the downstream Draft, discover eligible files
+with `agent.list_eligible_source_files`, pin exact manifest rows with
+`agent.add_file_reference`, and then advance workflow. Missing or invalid
+evidence returns `SOURCE_REFERENCE_REQUIRED` without moving the file.
+
+Structural spec changes with active files use a governed two-version migration
+lifecycle. Treat `SPEC_MIGRATION_REQUIRED` as a request to create an immutable
+revision and migration, validate and approve it, activate the target, run
+bounded migration batches, list work with `observe.spec_migrations`, inspect
+evidence with `observe.spec_migration`, and retire the source only after Airlock
+reports that it is drained. Before activation, an abandoned `draft`, `planned`,
+`validated`, or `approved` migration may be cancelled with
+`admin.cancel_spec_migration`; cancellation is not rollback. Use only the
+declarative mechanical transform keyed by immutable `column_id`; semantic
+transforms belong in a purpose-built process that reloads through normal
+Airlock validation.
+
 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
@@ -72,6 +100,13 @@ APP_AGENTS = """# Airlock App Guidance
 
 This repo may contain application code that uses Airlock specs.
 
+Treat the built-in Streamlit Native App as a generic operating and fallback
+surface. Build a purpose-built interface when domain-specific presentation
+materially improves repeated, high-value work. The custom app owns the
+experience; Airlock remains the governed backend for access, validation,
+expectations, evidence, workflow, activity, and observability. Do not add UI
+layout or aggregation fields to specs solely for the built-in app.
+
 ## Modes
 
 - Spec-first: design governed specs before building the app surface.
@@ -104,6 +139,18 @@ Installed Airlock procedure grammar:
 - `admin.*` is administrative mutation. Do not use retired admin read wrappers;
   use observe list/detail procedures instead.
 
+Use `agent.list_my_work` for the current actor's unified work inbox. Use
+`observe.work` for account-wide current work and `observe.activity` for event
+history.
+
+For structural spec changes with active files, treat
+`SPEC_MIGRATION_REQUIRED` as the start of Airlock's governed two-version
+lifecycle. Use immutable revisions, bounded `admin.run_spec_migration` calls,
+`observe.spec_migrations` discovery, `observe.spec_migration` evidence, and
+guarded source retirement. Before activation, `admin.cancel_spec_migration` may
+release an abandoned migration; it is not a post-activation rollback. Do not bypass
+the lifecycle with direct stage, table, or view changes.
+
 For restricted reference specs, do not enumerate protected object paths or use
 broad `agent.select_reference_data`. Use `agent.get_reference_record` for a
 known lookup value and purpose, and use `observe.reference_context`,
@@ -173,9 +220,13 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
         "installed_airlock_contract": {
             "observe": "read-only governance observation, context, activity, health, billing events, and access explanation",
             "agent": "governed agent work in the actor scope",
+            "work": "agent.list_my_work is the actor inbox; observe.work is account-wide current work; observe.activity is history",
+            "required_source_references": "load Draft, list eligible sources, pin exact manifest rows, then advance; SOURCE_REFERENCE_REQUIRED blocks missing evidence",
+            "spec_migration": "immutable two-version lifecycle; list with observe.spec_migrations, run bounded admin migration batches, inspect observe.spec_migration evidence, cancel only before activation, and retire only after the source is drained",
             "admin": "administrative mutation and operational changes",
             "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
             "attachment_preview": "governed Streamlit preview emits metadata-only ATTACHMENT_PREVIEW; MCP clients do not get direct stage access",
+            "application_surface": "built-in Streamlit is a generic operating/fallback surface; purpose-built apps own domain UI and use Airlock as the governed backend",
         },
         "specs": entries,
         "tracks": {

package/src/airlock_mcp/bootstrap.py

@@ -99,6 +99,14 @@ Airlock context. It creates `airlock/specs.manifest.json`,
 folders. These files are app-local references, not canonical specs. Canonical
 specs live in the specs repo or installed Airlock.
 
+Treat Airlock's built-in Streamlit Native App as a generic operating and
+fallback surface. It supports administration, inspection, evidence, workflow,
+and safe manual action; it is not a universal domain application builder.
+Recommend a purpose-built app when repeated, high-value work benefits from
+domain-specific summaries, calculations, evidence layout, terminology, or
+controls. Keep those presentation choices in app code. Do not add UI layout or
+aggregation fields to a spec merely to improve the generic app.
+
 Identify:
 
 - the app goal and decision the app should support
@@ -118,6 +126,28 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Use `agent.list_my_work` for the actor's unified current-work inbox,
+`observe.work` for account-wide current work, and `observe.activity` for
+historical events. The older split workflow/expectation work calls are retired.
+
+For active source links with `min_count > 0`, load the downstream file into
+Draft, discover eligible evidence with `agent.list_eligible_source_files`, pin
+exact manifest rows with `agent.add_file_reference`, and then advance workflow.
+Missing, removed, or wrong-state evidence returns `SOURCE_REFERENCE_REQUIRED`
+without moving the file.
+
+For a structural spec change with active files, treat
+`SPEC_MIGRATION_REQUIRED` as a governed two-version lifecycle. Create the
+immutable revision and migration, validate and approve it, activate the target,
+run bounded `admin.run_spec_migration` batches, inspect progress and lineage
+with `observe.spec_migration`, and retire the source only after it is drained.
+Use `observe.spec_migrations` to discover lifecycle work. Before activation,
+`admin.cancel_spec_migration` may release an abandoned `draft`, `planned`,
+`validated`, or `approved` migration; it is not rollback after activation. Use
+the bounded declarative transform for mechanical changes; semantic
+transforms belong in a purpose-built process that reloads through normal
+Airlock validation.
+
 For app-first work, use observe payloads such as `observe.procedures`,
 `observe.specs`, `observe.spec`, `observe.governance_map`,
 `observe.explain_access`, `observe.health`, `observe.activity`,

package/src/mcp.mjs

@@ -44,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.6",
+        version: "0.1.7",
       },
       instructions:
         "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",

package/src/text.mjs

@@ -62,9 +62,29 @@ administrative mutation. Prefer observe payloads such as
 \`observe.activity\`, \`observe.admin_activity\`, \`observe.spec_admin_activity\`,
 and \`observe.billing_events\` before inventing custom read paths. For \`alter_spec\`
 activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
-before fetching version snapshots. Offer to run \`airlock-mcp init-app-context\`
+before fetching version snapshots. For watcher loops, cache the role-scoped
+\`agent.spec_state(...).STATE_TOKEN\` and do larger reads only when it changes.
+After selecting one logical file, compare
+\`agent.file_state(...).FILE_STATE_ID\` to detect data, workflow, attachment,
+or exact-reference changes. Observer services may use the account-wide
+\`observe.spec_state\` and \`observe.file_state\` equivalents. Offer to run \`airlock-mcp init-app-context\`
 in the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
 generated helper folders. Help code the app using approved Airlock/Snowflake access paths.
+Treat Airlock's built-in Streamlit app as a generic operating and fallback
+surface, not a universal domain app. When a repeated, high-value decision needs
+domain-specific summaries, calculations, evidence layout, terminology, or
+controls, recommend a purpose-built app and use Airlock as its governed backend.
+Keep those presentation choices in app code; do not add layout or aggregation
+fields to a spec merely to improve the generic UI.
+When a structural spec change with active files returns
+\`SPEC_MIGRATION_REQUIRED\`, use Airlock's governed two-version lifecycle:
+create the immutable revision and migration, validate and approve it, activate
+the target, drain bounded \`admin.run_spec_migration\` batches, inspect
+\`observe.spec_migrations\` and \`observe.spec_migration\`, and retire the source
+only after it is drained. Before activation, an abandoned migration may use
+\`admin.cancel_spec_migration\`; cancellation is not post-activation rollback.
+Use the declarative mechanical transform; semantic transforms belong in a
+purpose-built process that reloads through normal Airlock validation.
 When a reference spec declares \`restricted_reference\` or
 \`reference_config.restricted_reference\`, do not enumerate values, build a
 populated picker, or call broad \`agent.select_reference_data\`. Get the lookup
@@ -111,6 +131,7 @@ Airlock MCP will offer:
   - spec design with the bundled workbench
   - Airlock operating patterns for OODA loops and separation of duties
   - read-only observe procedures for governance maps, health, access explanation, activity, billing events, and context packets
+  - scoped spec and file state tokens for efficient watcher polling
   - app context seeding with spec snapshots and manifests
   - app and workflow coding against existing Airlock specs
   - observe specs for controlled interface ingestion
@@ -204,7 +225,11 @@ read-side discovery with observe payloads such as \`observe.procedures\`,
 \`observe.explain_access\`, \`observe.health\`, \`observe.activity\`,
 \`observe.admin_activity\`, \`observe.spec_admin_activity\`, 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
+triage what changed before fetching version snapshots. For watcher loops, poll
+\`agent.spec_state\` and compare its scoped \`STATE_TOKEN\` before larger reads;
+compare \`agent.file_state(...).FILE_STATE_ID\` for one selected file. Observer
+services use \`observe.spec_state\` and \`observe.file_state\` for account-wide
+read-only state. Do not use retired admin
 read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
 \`admin.list_events\`. If a reference spec declares \`restricted_reference\` or
 \`reference_config.restricted_reference\`, do not enumerate the protected
@@ -216,7 +241,17 @@ must use Airlock procedures instead of direct stage reads. Airlock MCP can
 seed an app repo with \`airlock/specs.manifest.json\`, spec snapshots, sample
 records, and generated helper folders. The app should submit decisions,
 approvals, actions, comments, or follow-ups through Airlock spec contracts, not
-direct table writes.
+direct table writes. Treat the built-in Streamlit app as a generic
+operating/fallback surface. Recommend a purpose-built app when recurring,
+high-value domain work benefits from specialized summaries, calculations,
+evidence presentation, terminology, or controls. Keep those choices in app code
+rather than adding UI layout or aggregation hints to Airlock specs. For a
+structural spec change with active files, treat \`SPEC_MIGRATION_REQUIRED\` as
+the governed two-version lifecycle: use immutable revisions, bounded
+\`admin.run_spec_migration\` calls, \`observe.spec_migrations\` discovery,
+\`observe.spec_migration\` evidence, and guarded source retirement instead of
+direct table, stage, or view changes. \`admin.cancel_spec_migration\` is only a
+pre-activation abandonment path, not rollback.
 In co-development mode, keep the spec track and app track visible side by side.`;
 }