@jstn-sdk/ma 0.1.12 → 0.14.0

package/data/clone-data.ledger.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": "1.0.0",
+  "record_type": "clone_data_ledger",
+  "product": "Meta-Architect",
+  "package": "@jstn-sdk/ma",
+  "release_version": "0.1.13",
+  "records_as": "production_evidence",
+  "build_evidence": true,
+  "entries": [
+    {
+      "id": "clone-data-proof",
+      "path": "data/clone-data.proof.json",
+      "type": "proof",
+      "purpose": "Records the clone-data proof claims and verification commands.",
+      "required": true
+    },
+    {
+      "id": "clone-data-ledger",
+      "path": "data/clone-data.ledger.json",
+      "type": "ledger",
+      "purpose": "Tracks clone-data artifact inventory and package visibility.",
+      "required": true
+    },
+    {
+      "id": "clone-data-rvf",
+      "path": "data/clone-data.rvf",
+      "type": "runtime_verification_file",
+      "purpose": "Defines pass/fail verification criteria for clone-data artifacts.",
+      "required": true
+    }
+  ],
+  "package_visibility": {
+    "package_json_files_entry": "data/",
+    "pack_dry_run_required": true
+  },
+  "integrity_policy": {
+    "empty_files_allowed": false,
+    "placeholder_claims_allowed": false,
+    "must_reference_real_paths": true
+  }
+}

package/data/clone-data.proof.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "1.0.0",
+  "record_type": "clone_data_proof",
+  "product": "Meta-Architect",
+  "package": "@jstn-sdk/ma",
+  "release_version": "0.1.13",
+  "records_as": "production_evidence",
+  "build_evidence": true,
+  "subject": "clone data install and package proof contract",
+  "claims": [
+    {
+      "id": "jsdelivr_posix_installer",
+      "claim": "The recommended POSIX CLI install path is backed by a repository script addressable through jsDelivr.",
+      "evidence": [
+        "scripts/install.sh",
+        "README.md",
+        "docs/getting-started.md",
+        "docs/onboarding.md",
+        "docs/skills.md",
+        "plugins/meta-architect/README.md",
+        "docs/release-spec.md"
+      ]
+    },
+    {
+      "id": "clone_data_artifacts",
+      "claim": "Clone-data proof, ledger, and RVF artifacts exist as package-visible data files.",
+      "evidence": [
+        "data/clone-data.proof.json",
+        "data/clone-data.ledger.json",
+        "data/clone-data.rvf",
+        "package.json files includes data/"
+      ]
+    },
+    {
+      "id": "release_gate_contract",
+      "claim": "Release verification must preserve the jsDelivr installer and canonical npm install command in public install docs.",
+      "evidence": ["scripts/release-verify.js", "npm run release:check"]
+    }
+  ],
+  "verification_commands": [
+    "sh -n scripts/install.sh",
+    "node scripts/release-verify.js",
+    "node --test test/clone-data-artifacts.test.js",
+    "npm run release:check"
+  ],
+  "authority_boundary": {
+    "may_mutate_release_state": false,
+    "authoritative_changes_return_through": "$maestro_or_owning_lane"
+  }
+}

package/data/clone-data.rvf

@@ -0,0 +1,37 @@
+# Clone Data RVF
+
+schemaVersion: 1.0.0
+record_type: clone_data_runtime_verification_file
+product: Meta-Architect
+package: @jstn-sdk/ma
+release_version: 0.1.13
+
+## Purpose
+
+This RVF defines the pass criteria for the clone-data proof and ledger artifacts.
+
+## Required Artifacts
+
+- `data/clone-data.proof.json`
+- `data/clone-data.ledger.json`
+- `data/clone-data.rvf`
+
+## Pass Criteria
+
+- Proof JSON has `record_type: clone_data_proof`.
+- Ledger JSON has `record_type: clone_data_ledger`.
+- Both JSON files use `schemaVersion: 1.0.0`.
+- Both JSON files record as `production_evidence`.
+- Ledger entries reference all required clone-data artifacts.
+- `package.json` includes `data/` so clone-data artifacts are visible in package dry-runs.
+- `scripts/install.sh` remains POSIX-shell syntax valid.
+- Public install docs preserve the jsDelivr one-line installer.
+
+## Verification Commands
+
+```bash
+sh -n scripts/install.sh
+node scripts/release-verify.js
+node --test test/clone-data-artifacts.test.js
+npm run release:check
+```

package/docs/README.md

@@ -5,10 +5,17 @@ Meta-Architect documentation is organized by operator task.
 ## Start here
 
 - [Getting Started](./getting-started.md)
+- [Production Demo Guide](../DEMO.md)
+- [Real Demo Runbook](./demo/REAL_DEMO_RUNBOOK.md)
+- [Demo Story](./demo/DEMO_STORY.md)
+- [Prospect Checklist](./demo/PROSPECT_CHECKLIST.md)
+- [Coverage Matrix](../COVERAGE.md)
 - [Release Spec](./release-spec.md)
 - [Skills Reference](./skills.md)
 - umbrella, gated lanes, and helper skill distinctions live in the Skills Reference
 - [Installed Support Bundle](./installed-sdk.md)
+- [Runtime retention](./runtime-retention.md)
+- [External architect review](./architect-review.md)
 
 ## Packaging and installation
 
@@ -16,11 +23,13 @@ Meta-Architect documentation is organized by operator task.
 - published helper-skill and plugin-mirror expectations live in Skills Publishing
 - Linux-native distro package expectations live in the Release Spec and release-readiness docs
 - [MCP Setup](./mcp-setup.md)
+- [Continuity Graph](./continuity-graph.md)
 - [Plugin Bundle](../plugins/meta-architect/README.md)
 
 ## QA and readiness
 
-- [Release Readiness 0.1.12](./qa/release-readiness-0.1.12.md)
+- [Release Readiness 0.14.0](./qa/release-readiness-0.14.0.md)
+- [Release Issue Gates 0.14.0](./qa/release-issue-gates-0.14.0.json)
 
 ## Repo structure references
 

package/docs/autonomous-tasks.md

@@ -0,0 +1,46 @@
+# Autonomous tasks
+
+Meta-Architect persists autonomous work in `.ma/tasks/autonomous-queue.json`.
+The queue is separate from the team-run registry and is driven by the existing
+Maestro manager.
+
+## Intake
+
+```bash
+ma task add "Implement the parser" --priority high --label backend
+ma task bulk tasks.json
+cat tasks.yaml | ma task bulk - --format yaml
+ma task list --json
+```
+
+Each task receives a durable contract, status, retry budget, dependencies,
+labels, optional deadline, selected environment capabilities, and evidence.
+Duplicate IDs, malformed contracts, unknown dependencies, and dependency
+cycles are rejected before persistence.
+
+## Execution
+
+```bash
+ma task run --concurrency 3
+ma task run --max-tasks 20 --json
+ma task cancel task-123 "No longer needed"
+```
+
+Independent queued tasks run up to the configured concurrency. Dependencies
+run first; failed, blocked, cancelled, expired, or unsafe tasks do not run
+their downstream work. A failed task is retried up to `maxAttempts`, and the
+queue remains resumable after interruption.
+
+Environment discovery records installed project and user capabilities before
+execution. Existing skills are observed rather than claimed or modified, and
+vendor invocation metadata uses the environment's native `$`, `/`, or plain
+command convention when a vendor is selected.
+
+Every state transition emits a Maestro event under `.ma/events/` and persists
+the latest queue atomically. Safe local work proceeds automatically; goals
+that imply credentials, destructive changes, publication, production, or
+other external mutations are blocked with an actionable reason.
+
+The default runner delegates to the existing Maestro manager. Tests and host
+integrations can inject `execute(task)` into `runAutonomousTasks` without
+changing the queue contract.

package/docs/codex-integration.md

@@ -0,0 +1,16 @@
+# Codex integration
+
+Meta-Architect drives the installed Codex binary; it does not reproduce Codex's TUI or runtime.
+
+`CodexAppServerClient` uses the real stdio JSON-RPC app-server lifecycle: initialize, thread start/resume/fork/list/archive, turn start/interrupt, configuration read/write, and streamed notifications. `runCodexExec()` uses `codex exec --json` for bounded automation, and `generateCodexBindings()` delegates type/schema generation to the running Codex binary.
+
+All child processes use argument arrays with `shell: false`, time out, and surface non-zero exits. Goal support remains Codex-owned: prompts may request the installed `create_goal`, `get_goal`, and `update_goal` tools, while Meta-Architect only consumes the resulting notifications.
+
+```js
+import { CodexAppServerClient } from "@jstn-sdk/ma";
+
+const codex = new CodexAppServerClient();
+await codex.initialize();
+const thread = await codex.startThread({ ephemeral: true });
+await codex.startTurn({ threadId: thread.id, input: [{ type: "text", text: "Run the quality gate" }] });
+```

package/docs/getting-started.md

@@ -22,6 +22,20 @@ By the end of this guide you should be able to:
 
 ## 1. Default install and launch
 
+Recommended CLI install for macOS, Linux, WSL, and Git-Bash:
+
+```bash
+# One-line install (POSIX shells only; use WSL/Git-Bash on Windows)
+curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh && curl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256 && sed 's#scripts/install.sh#install.sh#' install.sh.sha256 | sha256sum -c - && sh install.sh
+```
+
+The jsDelivr installer runs `npm i -g @openai/codex@latest @jstn-sdk/ma@latest`, then `ma setup`.
+Use `sh install.sh --dry-run` to inspect the plan, `--no-setup` to skip local
+runtime writes, or `--no-skills` to skip skill/support-bundle writes. The
+installer prints Node/npm/Codex versions and an uninstall command after a real
+install. Package postinstall supports `MA_SKIP_AUTO_INSTALL=1`,
+`MA_SKIP_SKILLS=1`, and `MA_POSTINSTALL_DRY_RUN=1`.
+
 Debian-family install:
 
 ```bash
@@ -42,6 +56,11 @@ sudo dnf install ./meta-architect-<version>-1.noarch.rpm
 
 Default supported npm fallback:
 
+On the first interactive `ma` launch, Meta-Architect detects supported CLI and
+IDE host markers and asks once for the installation scope and targets. The
+selection is recorded in `.ma/prelaunch.json`; CI and piped/non-interactive
+launches skip the prompt and preserve the default Codex bootstrap behavior.
+
 ```bash
 # Install
 npm i -g @openai/codex@latest @jstn-sdk/ma@latest
@@ -56,7 +75,7 @@ npm uninstall -g @jstn-sdk/ma
 npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
-Linux-native distro packages are the default install surface. The npm path remains a supported fallback. The product experience is still the in-session skill workflow in [example/usage-workflow.md](../example/usage-workflow.md). The `ma` command is only a helper for starting or supporting that flow.
+The jsDelivr CLI installer is the recommended quick-start path for POSIX shells. Linux-native distro packages remain supported release assets, and the npm path remains the canonical package install underneath the installer. The product experience is still the in-session skill workflow in [example/usage-workflow.md](../example/usage-workflow.md). The `ma` command is only a helper for starting or supporting that flow.
 
 ## 2. Real usage workflow
 
@@ -92,7 +111,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.12
+8. Delivery plan for v0.14.0
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -152,6 +171,10 @@ Expected effects:
 - `mcp/`, `docs/`, and `sprint/` surfaces exist
 - `ma` opens Codex with the Meta-Architect helper posture when run with no arguments
 
+`.ma/` is the canonical Meta-Architect project namespace. A legacy `.omx/` directory may
+exist for oh-my-codex orchestration history, but new MA setup and generated guidance never
+use it as runtime state.
+
 Expected output:
 
 ```text
@@ -233,6 +256,11 @@ Contract split:
 - it runs the same environment checks without changing files
 - it prints the current readiness state and exact next step
 
+Maintainers use `npm run package:doctor` (also available as
+`npm run release:doctor`) for release and package artifact completeness. It
+does not inspect the installed user environment; both commands use the same
+status vocabulary so their scopes remain explicit.
+
 `ma sdk-path` prints the installed packaged support-bundle root for relevant files such as prompts, MCP files, sprint files, scripts, plugin metadata, and templates.
 
 ## 5. Configure MCP / GitMCP
@@ -282,7 +310,7 @@ See [docs/mcp-setup.md](./mcp-setup.md) for endpoint policy and evidence semanti
 ## 6. Secondary helper flow
 
 ```bash
-ma idea "Build a real-time collaborative whiteboard for product teams"
+ma idea "Prepare Meta-Architect v0.14.0 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
 ```
 
 Expected effects:
@@ -295,7 +323,7 @@ If this fails:
 
 ## 7. Run the helper skill sequence
 
-### 5.0 Autonomous manager
+### 7.1 Autonomous manager
 
 ```bash
 ma run '$maestro'
@@ -320,7 +348,7 @@ Optional non-gating helper skills that can run before or between gated lanes:
 - `$tdd` for regression-first execution setup
 - `$cleanup` for simplification and final-pass polish
 
-### 5.1 Architecture
+### 7.2 Architecture
 
 ```bash
 ma run '$arch'
@@ -337,7 +365,7 @@ Generated or updated:
 - `.ma/specs/architecture.md`
 - `.ma/plans/implementation.md`
 
-### 5.2 Evidence
+### 7.3 Evidence
 
 ```bash
 ma run '$sage'
@@ -366,7 +394,7 @@ If this fails:
 - verify network access
 - rerun after correcting the endpoint or environment
 
-### 5.3 Logic
+### 7.4 Logic
 
 ```bash
 ma run '$flow'
@@ -380,7 +408,7 @@ Expected effects:
 Generated or updated:
 - `.ma/specs/logic.md`
 
-### 5.4 Security
+### 7.5 Security
 
 ```bash
 ma run '$vet'
@@ -394,7 +422,7 @@ Expected effects:
 Generated or updated:
 - `.ma/specs/security.md`
 
-### 5.5 Experience
+### 7.6 Experience
 
 ```bash
 ma run '$vibe'
@@ -463,11 +491,11 @@ If `$build` fails:
 - fix the corresponding upstream lane
 - rerun that lane, then rerun `$build`
 
-## 10. Example walkthrough: collaborative whiteboard
+## 10. Example walkthrough: MA release hardening
 
 ```bash
 ma setup
-ma idea "Build a collaborative whiteboard with live cursors and shared boards"
+ma idea "Prepare Meta-Architect v0.14.0 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
 ma run '$arch'
 ma run '$sage'
 ma run '$flow'
@@ -480,17 +508,17 @@ ma run '$build'
 If you want an interactive Codex session during the walkthrough, start it separately with `ma`.
 
 What should happen:
-- `$arch` records a structured first-pass blueprint
-- `$sage` binds major choices to configured GitMCP-backed sources
-- `$flow` records the kernel’s baseline state review for the mission
-- `$vet` records a baseline security review
-- `$vibe` records baseline DX/UX guidance
-- `$build` suggests bounded concerns like `feature/implementation` and `feature/verification`
+- `$arch` records the architecture and release-hardening blueprint
+- `$sage` binds package, Obsidian, prompt-strategy, and MCP choices to configured evidence sources
+- `$flow` records state-transition and gate-order review
+- `$vet` records security, package exposure, and provider-bound context review
+- `$vibe` records operator/demo/docs usability guidance
+- `$build` suggests bounded implementation and verification branches after gates pass
 
-Related mission:
-- [missions/collaborative-whiteboard/mission.md](../missions/collaborative-whiteboard/mission.md)
+Canonical demo reference:
+- [DEMO.md](../DEMO.md)
 
-## 9. Merge and release path
+## 11. Merge and release path
 
 After implementation work is complete:
 
@@ -499,6 +527,11 @@ ma merge feature/ui development
 ma release development prod
 ```
 
+These commands record approval by default; they do not execute Git. Use
+`--dry-run` to run preflight and print the exact merge command without changing
+state, or `--execute` to run the checked, explicit merge on the target branch.
+Both modes require a clean worktree and a valid source branch.
+
 Expected effects:
 - merge only succeeds for `feature/* -> development`
 - release only succeeds for `development|release/* -> prod`
@@ -507,7 +540,7 @@ Expected effects:
   - `merge_status = MERGED_TO_DEVELOPMENT`
   - `release_status = SHIPPED_TO_PROD`
 
-## 10. Files generated or updated during a normal run
+## 12. Files generated or updated during a normal run
 
 - `.ma/decisions.json`
 - `.ma/release.json`
@@ -516,6 +549,13 @@ Expected effects:
 - `.ma/evidence/cves.json`
 - `.ma/evidence/outcomes.json`
 - `.ma/context/project.md`
+- `.ma/context/recording-core.json`
+- `.ma/context/learning-loop-core.json`
+- `.ma/context/workspace-context-pack.json`
+- `.ma/context/workspace-effectiveness.json`
+- `.ma/context/prompt-strategy-core.json`
+- `.ma/context/context-economy-core.json`
+- `.ma/context/obsidian-bridge.json`
 - `.ma/specs/architecture.md`
 - `.ma/specs/evidence.md`
 - `.ma/specs/logic.md`
@@ -527,7 +567,7 @@ Expected effects:
 
 These are local product artifacts created by the runtime. They are not a reason to bypass gate logic manually.
 
-## 11. If a gate fails
+## 13. If a gate fails
 
 Rule:
 - do not edit statuses manually

package/docs/mcp-setup.md

@@ -1,5 +1,9 @@
 # MCP / GitMCP Setup
 
+The MCP client advertises the installed Meta-Architect version read from the
+package metadata. `ma doctor` reports the same value, while `0.0.0-dev` is used
+only when development metadata is unavailable.
+
 1. Use approved discovery accelerators when you need to find OSS candidates faster than browsing GitHub directly.
 2. Add repo-specific GitMCP endpoints in `mcp/servers.json` for any project you want to treat as approved evidence.
 3. Confirm categories in `mcp/collections.json`.
@@ -15,6 +19,7 @@
 - `team_run`
 - `code_intel`
 - `playbooks`
+- `context`
 
 `playbooks` is a read-only packaged capability. It does not point at external MCP servers and it does not repurpose `mcp/collections.json`.
 
@@ -69,9 +74,68 @@ To move from discovery to VERIFIED evidence:
 - map that repo to an exact `https://gitmcp.io/{owner}/{repo}` endpoint in `mcp/servers.json`
 - validate the choice against the upstream repo and official docs through `$sage`
 
+## Remote MCP transport
+
+`$sage` opens configured GitMCP endpoints as live MCP servers. Some remote MCP hosts reject direct SSE probes with HTTP 405 and require a host-supported remote MCP bridge. Meta-Architect treats that as a transport blocker, not as verified evidence.
+
+To enable bridge-backed live verification, configure a trusted local bridge command:
+
+```bash
+export MA_MCP_REMOTE_BRIDGE_CMD="mcp-remote {url}"
+export MA_MCP_REMOTE_BRIDGE_ALLOWLIST="mcp-remote"
+```
+
+The `{url}` placeholder is replaced with the exact repo endpoint from `mcp/servers.json`. The command must be explicitly allowlisted by basename or exact path in `MA_MCP_REMOTE_BRIDGE_ALLOWLIST`, or by a project-local `mcp/bridge.json` file such as `{ "allowedCommands": ["mcp-remote"] }`. Use a preinstalled, trusted bridge binary or wrapper; do not depend on automatic package downloads in production verification.
+
+Bridge startup, exit, failure, and bounded stderr diagnostics are recorded as
+redacted receipts under `.ma/evidence/mcp-bridge-receipts/`. The bridge receives
+only a minimal environment allowlist, and request timeouts are bounded by
+`MA_MCP_REQUEST_TIMEOUT_MS` (15 seconds by default). `ma doctor` should be used
+to verify the command policy before live evidence collection.
+
+When no bridge is configured:
+- direct-SSE-compatible MCP servers can still verify normally
+- GitMCP 405 responses are recorded as bridge-required blockers
+- `evidence_status` remains `PARTIAL`, so `$flow` and `$build` stay locked
+
 ## Separation of concerns
 
 - `mcp/servers.json` remains for repo-specific GitMCP evidence sources
 - `mcp/collections.json` remains GitMCP-oriented evidence categorization for this release
 - `mcp/local-capabilities.json` is the first-party in-process capability registry
 - `mcp/native-playbooks.json` is internal native curation metadata, not an upstream mirror or user-edited evidence source list
+
+## Current semantic source routing
+
+`mcp/collections.json` maps configured repository evidence into MA lanes.
+The current release intentionally includes both broad discovery lists and core-specific upstream sources.
+
+| Collection | Why it exists | Typical lanes |
+| --- | --- | --- |
+| `meta-list` and language collections | broad OSS candidate discovery before exact upstream selection | `$arch`, `$sage` |
+| `system-design` | architecture and flow reasoning references | `$arch`, `$sage`, `$flow`, `$build` |
+| `security` | trust-boundary and security review evidence | `$vet` |
+| `obsidian-api-docs` | Obsidian API evidence for vault, metadata, workspace, and plugin behavior | `$arch`, `$sage`, `$vibe` |
+| `obsidian-plugin-scaffold` | compatibility reference for MA's in-app Obsidian plugin surface | `$arch`, `$sage` |
+| `context-economy` | context-budget and terse-output source evidence | `$sage`, `$vet`, `$vibe`, `$build` |
+| `prompt-techniques` | prompt strategy source evidence for MA-owned prompt policies | `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build` |
+
+Obsidian-derived notes remain `vault_context`.
+They do not count as `build_evidence` unless `$sage`, `$vet`, or another owning lane promotes a specific claim with source-backed proof.
+## Local context capability
+
+The setup-owned local MCP registry exposes read-only context evidence through
+the `context` capability. Its resources are:
+
+- `context://project-index` — source-truth project fingerprint and file metadata.
+- `context://freshness` — incremental refresh status and changed-file evidence.
+- `context://learning` — validated learning-loop state.
+- `context://obsidian` — validated vault index and operation receipts when configured.
+- `context://hooks` — hook configuration and audit evidence.
+- `context://commands` — source-derived command map.
+- `context://agent-brief` — bounded first-read generated context.
+- `context://architecture` — bounded generated architecture map.
+
+Every response includes `record_type`, `authority`, `source`, and `available`
+metadata. Missing optional artifacts return an unavailable result; writes are
+not exposed by this capability.