@jstn-sdk/ma 0.1.3 → 0.1.5

package/docs/getting-started.md

@@ -1,166 +1,22 @@
 # Getting Started
 
-This guide takes Meta-Architect from install to a green-gated skill workflow on a real project.
+Meta-Architect is a Codex-native runtime layer. Install Codex, install Meta-Architect, launch the runtime posture, then operate through skill tags inside Codex.
 
-## Goal
+## Canonical path
 
-By the end of this guide you should be able to:
-- install Meta-Architect
-- configure MCP/GitMCP sources
-- run the full architecture-to-build sequence
-- understand how each gate moves
-- diagnose blocked gates
-- use the merge/release path safely
-
-## Prerequisites
-
-- Node.js 20+
-- npm 10+
-- Git 2.30+
-- an MCP-capable runtime
-- network access if you want live `$sage` verification against a real GitMCP server
-
-## 1. Canonical install and launch
-
-Canonical public install:
-
-```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-
-# Launch
-ma --madmax --high
-
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
-
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
-```
-
-That is the default product path. The product experience is 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
-
-Start with the structured `$arch` prompt:
-
-```text
-$arch I want to build: [PROJECT IDEA]
-
-Context:
-- Product type: [web app / mobile app / API / marketplace / agent system / internal tool]
-- Users: [who will use it]
-- Core problem: [what problem it solves]
-- Main features:
-  1. [feature one]
-  2. [feature two]
-  3. [feature three]
-- Constraints:
-  - Budget: [low / medium / high]
-  - Team size: [solo / small / medium]
-  - Timeline: [e.g. 2 weeks MVP, 3 months beta]
-  - Preferred stack: [optional]
-  - Avoid: [optional]
-- Quality priorities:
-  - [e.g. speed, low cost, security, DX, maintainability, scalability]
-- Deployment target:
-  - [Vercel / Docker / VPS / AWS / GCP / local-first / hybrid]
-
-Required output:
-1. Problem framing
-2. Recommended architecture
-3. Stack decision with justification
-4. System components and responsibilities
-5. Data model and storage choices
-6. Auth/security considerations
-7. DX/UX considerations
-8. Delivery plan for v0.1.3
-9. Risks and trade-offs
-10. Decision log
-11. Exact next trigger to run after this
-```
-
-Then continue with:
-
-```text
-$sage
-$flow
-$vet
-$vibe
-$build
-```
-
-Use the full prompt blocks from [example/usage-workflow.md](../example/usage-workflow.md) when you want the exact handoff format between lanes.
-
-## 3. Contributor clone and link
-
-```bash
-git clone https://github.com/JustineDevs/meta-architect.git
-cd meta-architect
-npm install
-npm link
-```
-
-Why `npm link` matters:
-- it makes the local helper command available without requiring a global publish step
-
-## 4. Secondary repository setup flow
+Install:
 
 ```bash
-ma setup
-```
-
-Optional interactive session:
-
-```bash
-ma
-```
-
-Expected effects:
-- `.codex/agents/` exists
-- `.codex/prompts/` exists
-- local `.ma/skills/`, `.ma/evidence/`, `.ma/context/`, `.ma/specs/`, `.ma/plans/`, and `.ma/runbook.md` are seeded
-- `mcp/`, `docs/`, and `sprint/` surfaces exist
-- `ma` opens Codex with the Meta-Architect helper posture when run with no arguments
-
-Expected output:
-
-```text
-meta-architect setup
-====================
-ready: .codex/agents
-ready: .codex/prompts
-ready: .ma/skills
-ready: .ma/evidence
-ready: .ma/context
-ready: .ma/specs
-ready: .ma/plans
-ready: mcp
-ready: docs
-ready: docs/qa
-ready: sprint
+npm i -g @openai/codex @jstn-sdk/ma
 ```
 
-This setup path is secondary to the canonical in-session skill workflow. Use it when you need local repo scaffolding.
-
-## 4.1 Understand the two surfaces
-
-Meta-Architect works in two simple ways:
-
-- terminal commands
-- in-session skills
-
-Terminal commands are normal shell commands:
+Launch:
 
 ```bash
-ma setup
-ma init
-ma sdk-path
-ma status
-ma run '$arch'
+ma --madmax --high
 ```
 
-In-session skills are prompts used after you are already inside Codex:
+Operate inside Codex with:
 
 ```text
 $arch
@@ -171,283 +27,62 @@ $vibe
 $build
 ```
 
-Easy rule:
-- `ma ...` = terminal helper command
-- `$...` = in-session skill
-
-`ma setup` and `ma init` currently do the same thing:
-- they create local `.ma/` support files
-- they prepare context, specs, plans, evidence, and runbook files
-- they do not automatically run the skill workflow
-
-`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
-
-Edit:
-- `mcp/servers.json`
-- `mcp/collections.json`
-- `mcp/fallback.json`
-
-Minimum live example:
-
-```json
-{
-  "category": "meta-list",
-  "repo": "sindresorhus/awesome",
-  "endpoint": "https://gitmcp.io/sindresorhus/awesome"
-}
-```
-
-Recommended first set:
-- `sindresorhus/awesome`
-- `dzharii/awesome-typescript`
-- `sbilly/awesome-security`
-
-See [docs/mcp-setup.md](./mcp-setup.md) for endpoint policy and evidence semantics.
-
-## 6. Secondary helper flow
-
-```bash
-ma idea "Build a real-time collaborative whiteboard for product teams"
-```
-
-Expected effects:
-- an idea decision entry is appended to `.ma/decisions.json`
-- `idea_status = CLEAR`
-
-If this fails:
-- ensure the idea text is not empty
-- inspect `.ma/decisions.json` for malformed local data
-
-## 7. Run the helper skill sequence
-
-### 5.1 Architecture
-
-```bash
-ma run '$arch'
-```
-
-Expected effects:
-- a structured first-pass architecture blueprint is appended
-- `architecture_status = APPROVED`
-
-Generated or updated:
-- `.ma/decisions.json`
-- `.ma/release.json`
-- `.ma/context/project.md`
-- `.ma/specs/architecture.md`
-- `.ma/plans/implementation.md`
-
-### 5.2 Evidence
-
-```bash
-ma run '$sage'
-```
-
-Expected effects:
-- `architecture_status` must already be approved
-- configured GitMCP endpoints are validated
-- the latest architecture summary is used as the probe query basis
-- the first configured live source is probed when live mode is enabled
-- `.ma/evidence/sources.json` is updated
-- `evidence_status` becomes:
-  - `VERIFIED` on a real successful live probe
-  - `PARTIAL` when configured evidence exists but live proof is incomplete or disabled
-  - `MISSING` when no usable approved source exists
-
-Generated or updated:
-- `.ma/evidence/sources.json`
-- `.ma/decisions.json`
-- `.ma/release.json`
-- `.ma/specs/evidence.md`
-
-If this fails:
-- check endpoint URLs in `mcp/servers.json`
-- ensure architecture was approved first
-- verify network access
-- rerun after correcting the endpoint or environment
-
-### 5.3 Logic
-
-```bash
-ma run '$flow'
-```
-
-Expected effects:
-- a structured first-pass logic/state review is appended
-- `logic_status = GREEN` when current prerequisites and transition modeling are acceptable
-- `logic_status = RED` when prerequisite gates are not ready
-
-Generated or updated:
-- `.ma/specs/logic.md`
-
-### 5.4 Security
-
-```bash
-ma run '$vet'
-```
-
-Expected effects:
-- `.ma/evidence/audits.json` and `.ma/evidence/cves.json` are updated
-- `security_status = GREEN` on a baseline pass
-- `security_status = RED` when prerequisite gates are not ready
-
-Generated or updated:
-- `.ma/specs/security.md`
-
-### 5.5 Experience
-
-```bash
-ma run '$vibe'
-ma run '$vibe' --waive --reason "Accepted for this release line"
-```
+## Runtime expectations
 
-Expected effects:
-- `.ma/evidence/outcomes.json` is updated
-- `experience_status = GREEN` on a baseline pass
-- `experience_status = RED` when prerequisite gates are not ready
-- `experience_status = WAIVED` when the waiver path is used explicitly
+- Codex is the host runtime.
+- Meta-Architect is the runtime extension.
+- The skill tags are the primary product surface.
+- `ma` is a runtime launcher plus a small maintenance/helper interface.
 
-Generated or updated:
-- `.ma/specs/experience.md`
+## When to use helper commands
 
-## 8. Inspect gate status
+Use helper commands only when you need scripted repo validation or repo-local scaffolding:
 
 ```bash
 ma status
-```
-
-Expected green-state output:
-
-```text
-Meta-Architect Status
-=====================
-Idea: CLEAR
-Architecture: APPROVED
-Evidence: VERIFIED
-Logic: GREEN
-Security: GREEN
-Experience: GREEN
-Build: LOCKED
-Next allowed triggers:
-$build
-```
-
-## 9. Unlock and run build planning
-
-```bash
-ma run '$build'
-```
-
-Expected effects:
-- build gate is evaluated
-- if allowed, `build_status = READY`
-- branch suggestions are printed
-- worktree commands are suggested
-- `.ma/plans/build.md` is updated
-
-Expected output shape:
-
-```text
-Build gate is green.
-Suggested branches:
-- feature/ui
-- feature/api
-Optional worktree commands:
-git worktree add ../ui feature/ui
-git worktree add ../api feature/api
-```
-
-If `$build` fails:
-- run `ma status`
-- read the blocking statuses
-- fix the corresponding upstream lane
-- rerun that lane, then rerun `$build`
-
-## 10. Example walkthrough: collaborative whiteboard
-
-```bash
-ma setup
-ma idea "Build a collaborative whiteboard with live cursors and shared boards"
+ma idea "Build a real-time collaborative whiteboard"
 ma run '$arch'
 ma run '$sage'
 ma run '$flow'
 ma run '$vet'
 ma run '$vibe'
-ma status
 ma run '$build'
+ma doctor
+ma setup
 ```
 
-If you want an interactive Codex session during the walkthrough, start it separately with `ma`.
+`ma setup` repairs or seeds repo-local support files such as:
+- `AGENTS.md`
+- `.codex/`
+- `.omx/`
+- `mcp/`
+- `templates/`
 
-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/ui` and `feature/api`
+That path is secondary. The main experience remains the Codex session launched with `ma --madmax --high`.
 
-Related mission:
-- [missions/collaborative-whiteboard/mission.md](../missions/collaborative-whiteboard/mission.md)
+## MCP / GitMCP
 
-## 9. Merge and release path
+Meta-Architect expects approved GitMCP endpoints for evidence-heavy lanes such as `$sage`.
 
-After implementation work is complete:
-
-```bash
-ma merge feature/ui development
-ma release development prod
-```
-
-Expected effects:
-- merge only succeeds for `feature/* -> development`
-- release only succeeds for `development|release/* -> prod`
-- final statuses advance to:
-  - `build_status = DONE`
-  - `merge_status = MERGED_TO_DEVELOPMENT`
-  - `release_status = SHIPPED_TO_PROD`
-
-## 10. Files generated or updated during a normal run
-
-- `.ma/decisions.json`
-- `.ma/release.json`
-- `.ma/evidence/sources.json`
-- `.ma/evidence/audits.json`
-- `.ma/evidence/cves.json`
-- `.ma/evidence/outcomes.json`
-- `.ma/context/project.md`
-- `.ma/specs/architecture.md`
-- `.ma/specs/evidence.md`
-- `.ma/specs/logic.md`
-- `.ma/specs/security.md`
-- `.ma/specs/experience.md`
-- `.ma/plans/implementation.md`
-- `.ma/plans/build.md`
-- `.ma/runbook.md`
+Edit:
+- `mcp/servers.json`
+- `mcp/collections.json`
+- `mcp/fallback.json`
 
-These are local product artifacts created by the runtime. They are not a reason to bypass gate logic manually.
+See [docs/mcp-setup.md](./mcp-setup.md) for exact-endpoint policy and fallback rules.
 
-## 11. If a gate fails
+## Release-aware usage
 
-Rule:
-- do not edit statuses manually
-- rerun the correct upstream command
-- use `ma status` as the authority
+`$build` is locked until all upstream review gates are green or explicitly waived by policy.
 
-Common examples:
-- `evidence_status = MISSING` -> fix `mcp/servers.json`, rerun `$sage`
-- `logic_status = RED` -> fix upstream evidence/architecture issues, rerun `$flow`
-- `security_status = RED` -> resolve issues surfaced by `$vet`
-- `experience_status = RED` -> rerun `$vibe` after clearing prerequisites
-- `experience_status = WAIVED` -> verify the waiver reason recorded in `.ma/release.json`
+Before claiming a release is ready, make sure:
+- `npm run release:check` passes
+- [docs/release-spec.md](./release-spec.md) still matches behavior
+- [docs/qa/release-readiness-0.1.5.md](./qa/release-readiness-0.1.5.md) matches the actual release line
 
 ## Related docs
 
-- [README.md](../README.md)
 - [Skills Reference](./skills.md)
 - [MCP Setup](./mcp-setup.md)
 - [Release Spec](./release-spec.md)
-- [Skills Publishing](./skills-publishing.md)
 - [Plugin Bundle](../plugins/meta-architect/README.md)

package/docs/mcp-setup.md

@@ -1,5 +1,136 @@
 # MCP / GitMCP Setup
 
-1. Add repo-specific GitMCP endpoints in `mcp/servers.json`.
-2. Confirm categories in `mcp/collections.json`.
-3. Use `https://gitmcp.io/docs` only when no approved exact endpoint exists.
+Meta-Architect uses MCP as the protocol layer and GitMCP as the remote evidence surface for curated OSS repositories.
+
+## Files that matter
+
+- `mcp/servers.json`
+- `mcp/collections.json`
+- `mcp/fallback.json`
+
+These are committed product config files, not hidden runtime state.
+
+## How server mappings work
+
+### `mcp/servers.json`
+
+Defines the approved exact GitMCP-backed repositories the runtime may probe.
+
+Each entry should include:
+- `category`
+- `repo`
+- `endpoint`
+
+Example:
+
+```json
+{
+  "category": "security",
+  "repo": "sbilly/awesome-security",
+  "endpoint": "https://gitmcp.io/sbilly/awesome-security"
+}
+```
+
+### `mcp/collections.json`
+
+Defines the committed lane-to-category policy:
+- which categories belong to `arch`
+- which belong to `sage`
+- which belong to `vet`
+
+The current runtime probes `mcp/servers.json` directly, while `mcp/collections.json` remains the committed contract for how category routing should be understood and evolved.
+
+### `mcp/fallback.json`
+
+Defines the documented fallback rule for:
+- `https://gitmcp.io/docs`
+
+Fallback is a policy declaration, not permission to skip exact endpoints when those are already known.
+
+## Endpoint strategy
+
+Preferred rule:
+- use repo-specific `https://gitmcp.io/{owner}/{repo}` endpoints
+- avoid generic discovery when an exact approved repo is already known
+
+This keeps recommendations scoped and auditable.
+
+## GitMCP collection examples
+
+Useful committed examples:
+- `sindresorhus/awesome`
+- `dzharii/awesome-typescript`
+- `rust-unofficial/awesome-rust`
+- `sbilly/awesome-security`
+- `awesome-selfhosted/awesome-selfhosted`
+
+## How `$sage` uses live evidence
+
+Current `$sage` behavior:
+1. requires `architecture_status = APPROVED`
+2. reads `mcp/servers.json`
+3. validates endpoint shape
+4. derives the query from the latest architecture summary
+5. opens a live GitMCP SSE connection when live probing is enabled
+6. negotiates the MCP message endpoint
+7. runs `tools/list`
+8. runs one repo-specific tool call
+9. writes probe metadata into `.omx/evidence/sources.json`
+
+This is enough to provide real runtime evidence for the first configured approved source. It is not a full multi-source reasoning engine yet.
+
+## VERIFIED vs PARTIAL vs MISSING
+
+### `VERIFIED`
+- at least one approved endpoint is configured
+- a real live probe succeeds
+- usable evidence is written
+
+### `PARTIAL`
+- configured evidence exists
+- but live proof is incomplete, disabled, or degraded
+
+### `MISSING`
+- no valid approved source exists
+
+Do not silently mark evidence as verified when the live source did not succeed.
+
+## What to do when MCP is unavailable
+
+If MCP or GitMCP is unavailable:
+- keep evidence partial or missing
+- record the failure explicitly
+- do not fabricate evidence
+- fix the endpoint or network condition first
+- rerun `$sage`
+
+## How to keep committed MCP config honest
+
+- commit real or intentionally documented example endpoints only
+- do not leave fake placeholders in production config
+- update this file if category policy changes
+- treat endpoint drift as a release-sensitive change
+
+## Example setup workflow
+
+1. edit `mcp/servers.json`
+2. confirm categories in `mcp/collections.json`
+3. inspect fallback policy in `mcp/fallback.json`
+4. ensure `$arch` already approved the architecture
+5. run:
+
+```bash
+ma run '$sage'
+```
+
+6. inspect:
+- `.omx/evidence/sources.json`
+- `.omx/decisions.json`
+- `.omx/release.json`
+
+## Related surfaces
+
+- [README.md](../README.md)
+- [docs/skills.md](./skills.md)
+- [docs/release-spec.md](./release-spec.md)
+- [plugins/meta-architect/README.md](../plugins/meta-architect/README.md)

package/docs/onboarding.md

@@ -1,65 +1,35 @@
 # Onboarding
 
-This is the shortest entrypoint for the real first-run Meta-Architect path.
+This file is the short operator entrypoint for someone who just opened the repo and needs to
+understand the Codex-native Meta-Architect runtime model.
 
-## Read first
+## First reading order
 
 1. `README.md`
 2. `docs/getting-started.md`
-3. `example/usage-workflow.md`
-4. `docs/release-spec.md`
+3. `docs/release-spec.md`
+4. `docs/skills.md`
 5. `docs/skills-publishing.md`
 
-## Canonical install and start
+## First commands
 
 ```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
-
-# Start Codex context if needed
+npm i -g @openai/codex @jstn-sdk/ma
 ma --madmax --high
-
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
-
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
-```
-
-## First runtime action
-
-Start with the structured `$arch` prompt from [example/usage-workflow.md](../example/usage-workflow.md):
-
-```text
-$arch I want to build: [PROJECT IDEA]
 ```
 
-Then continue through:
+Inside Codex, use the runtime tags directly:
+- `$arch`
 - `$sage`
 - `$flow`
 - `$vet`
 - `$vibe`
 - `$build`
 
-## Secondary helper path
-
-Only use this when you need local repo scaffolding or scripted validation:
-
-```bash
-ma setup
-ma
-ma idea "..."
-ma run '$arch'
-ma run '$sage'
-ma run '$flow'
-ma run '$vet'
-ma run '$vibe'
-ma run '$build'
-```
-
 ## First safety rules
 
-- Do not commit runtime `.ma` state.
+- Do not commit runtime `.omx` state.
 - Do not bypass gates by editing status files manually.
 - Do not assume a release channel succeeded without evidence.
 - Do not treat fallback MCP docs mode as normal verified evidence.
+- Do not present `ma setup` as the main daily workflow.