@jstn-sdk/ma 0.1.5 → 0.1.6

package/docs/onboarding.md

@@ -1,35 +1,65 @@
 # Onboarding
 
-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.
+This is the shortest entrypoint for the real first-run Meta-Architect path.
 
-## First reading order
+## Read first
 
 1. `README.md`
 2. `docs/getting-started.md`
-3. `docs/release-spec.md`
-4. `docs/skills.md`
+3. `example/usage-workflow.md`
+4. `docs/release-spec.md`
 5. `docs/skills-publishing.md`
 
-## First commands
+## Canonical install and start
 
 ```bash
-npm i -g @openai/codex @jstn-sdk/ma
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# Start Codex context if needed
 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]
 ```
 
-Inside Codex, use the runtime tags directly:
-- `$arch`
+Then continue through:
 - `$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 `.omx` state.
+- Do not commit runtime `.ma` 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.

package/docs/qa/release-readiness-0.1.5.md

@@ -2,42 +2,62 @@
 
 ## Production bar
 
-`v0.1.5` is production only when:
-- the Codex-hosted runtime workflow is reliable end-to-end
-- the runtime/help/release contract is stable
-- package metadata, manifests, docs, workflows, and release artifacts all agree on `0.1.5`
-- provenance-capable publishing and post-publish verification are in place
-
-## Automated checks
-
-Release-critical verification command:
+`v0.1.5` is treated as production only when:
+- the package installs cleanly from the canonical public install command
+- the Codex-hosted runtime path works end to end
+- the helper flow remains valid for scripted verification
+- release docs, package metadata, and workflows all agree on `0.1.5`
+
+Target release state:
+- npm package: `@jstn-sdk/ma@0.1.5`
+- npm registry state: pending publish
+- publishability note: `0.1.4` is already published, so `0.1.5` is the next publishable package line
+- git tag: `v0.1.5`
+- GitHub release: pending publish for `v0.1.5`
+
+## Production checklist
+
+- skills-first product identity: PASS
+- package/plugin identity aligned to `@jstn-sdk/ma`: PASS
+- version/tag alignment `0.1.5` / `v0.1.5`: PASS
+- install/uninstall docs aligned: PASS
+- onboarding is concise and sequential: PASS
+- helper command documented as secondary: PASS
+- skills/prompts/manifests aligned: PASS
+- packaging includes required assets: PASS
+- tests pass: PASS
+- package dry-run passes: PASS
+- installed-package behavior passes: PASS
+- workflow/release/provenance docs aligned: PASS
+- no stale package names remain in tracked repo surfaces: PASS
+- no conflicting CLI-first product story remains in tracked product docs: PASS
+
+## Automated checks run
 
 ```bash
 npm run release:check
 ```
 
-This must cover:
-- manifest generation
+That must cover:
+- skills manifest generation
 - skill validation
-- skill tarball packaging
-- package metadata validation
-- release doc/version/tag alignment
-- workflow/provenance configuration validation
-- Biome checks
+- skill bundle packaging
+- repo checks
 - automated tests
 - npm package dry-run inspection
 
-## Additional checks
+## Manual/behavioral checks run
 
-Runtime posture:
+Canonical launch:
 
 ```bash
 ma --madmax --high
 ```
 
-Scripted helper path for repo-local validation:
+Helper-path validation:
 
 ```bash
+ma setup
 ma idea "Build a demo app"
 ma run '$arch'
 ma run '$sage'
@@ -48,30 +68,12 @@ ma status
 ma run '$build'
 ```
 
-Expected result:
-- all helper commands succeed in sequence
-- `$build` remains blocked until upstream gates are green
-- ready builds emit bounded `feature/*` branch suggestions
-
-## Provenance checklist
-
-- `.github/workflows/npm-publish.yml` uses GitHub Actions trusted publishing
-- workflow permissions include `contents: read` and `id-token: write`
-- publish command is `npm publish --provenance --access public`
-- post-publish workflow verifies the published package version on npm
-- post-publish workflow installs the published package in a clean directory and runs `npm audit signatures`
-
-## Release artifact checklist
-
-- `package.json` version is `0.1.5`
-- `package-lock.json` version is `0.1.5`
-- `CHANGELOG.md` contains `## v0.1.5`
-- `RELEASE.md` title is `# Meta-Architect v0.1.5`
-- `docs/release-spec.md` references `v0.1.5`
-- `dist/meta-architect-skills.tgz` exists and is non-empty
+Expected evidence:
+- `.ma/release.json` remains the source of truth
+- `.ma/decisions.json` records the helper-path activity
+- `$build` stays blocked until upstream gates are green, then becomes ready
 
-## Known limits
+## Known limitations
 
-- worktree execution remains operator-driven
-- merge and release policy is enforced by helper commands rather than raw git hooks
-- npm publish still requires the external trusted-publishing configuration on npm to be enabled for the repository
+- interactive Codex conversation quality depends on the installed Codex host
+- release publication still depends on npm ownership/authorization for the target package name

package/docs/qa/release-readiness-0.1.6.md

@@ -0,0 +1,79 @@
+# Release Readiness 0.1.6
+
+## Production bar
+
+`v0.1.6` is treated as production only when:
+- the package installs cleanly from the canonical public install command
+- the Codex-hosted runtime path works end to end
+- the helper flow remains valid for scripted verification
+- release docs, package metadata, and workflows all agree on `0.1.6`
+
+Target release state:
+- npm package: `@jstn-sdk/ma@0.1.6`
+- npm registry state: pending publish
+- publishability note: `0.1.5` is already published, so `0.1.6` is the next publishable package line
+- git tag: `v0.1.6`
+- GitHub release: pending publish for `v0.1.6`
+
+## Production checklist
+
+- skills-first product identity: PASS
+- package/plugin identity aligned to `@jstn-sdk/ma`: PASS
+- version/tag alignment `0.1.6` / `v0.1.6`: PASS
+- install/uninstall docs aligned: PASS
+- onboarding is concise and sequential: PASS
+- helper command documented as secondary: PASS
+- skills/prompts/manifests aligned: PASS
+- packaging includes required assets: PASS
+- tests pass: PASS
+- package dry-run passes: PASS
+- installed-package behavior passes: PASS
+- workflow/release/provenance docs aligned: PASS
+- no stale package names remain in tracked repo surfaces: PASS
+- no conflicting CLI-first product story remains in tracked product docs: PASS
+
+## Automated checks run
+
+```bash
+npm run release:check
+```
+
+That must cover:
+- skills manifest generation
+- skill validation
+- skill bundle packaging
+- repo checks
+- automated tests
+- npm package dry-run inspection
+
+## Manual/behavioral checks run
+
+Canonical launch:
+
+```bash
+ma --madmax --high
+```
+
+Helper-path validation:
+
+```bash
+ma setup
+ma idea "Build a demo app"
+ma run '$arch'
+ma run '$sage'
+ma run '$flow'
+ma run '$vet'
+ma run '$vibe'
+ma status
+ma run '$build'
+```
+
+Expected evidence:
+- `.ma/release.json` remains the source of truth
+- `.ma/decisions.json` records the helper-path activity
+- `$build` stays blocked until upstream gates are green, then becomes ready
+
+## Known limitations
+
+- interactive Codex conversation quality depends on the installed Codex host
+- release publication still depends on npm ownership/authorization for the target package name

package/docs/release-spec.md

@@ -1,115 +1,93 @@
-# v0.1.5 Requirements & Rules
+# v0.1.6 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.5` is production only when all of the following are true:
+Meta-Architect `v0.1.6` is production only when:
+1. the package/install surface works
+2. the in-session skill workflow from `$arch` through `$build` works
+3. the release evidence matches the actual package and git tag
 
-1. The Codex-hosted runtime workflow is reliable end-to-end.
-2. The public runtime, helper, and release contract is stable.
-3. There is documented release evidence for the exact version and tag.
+## What `v0.1.6` must have
 
-Production here means safe to recommend for real projects and expensive to break without a major version change.
+### 1. Canonical package/runtime path
 
-## What `v0.1.5` must have
-
-### 1. Runtime-first operation
-
-- `ma --madmax --high` launches the Codex-hosted Meta-Architect posture.
-- The primary operating surface inside Codex is:
+- install: `npm i -g @openai/codex@latest @jstn-sdk/ma@latest`
+- optional helper launch: `ma --madmax --high`
+- uninstall Meta-Architect only: `npm uninstall -g @jstn-sdk/ma`
+- uninstall Meta-Architect and Codex: `npm uninstall -g @jstn-sdk/ma @openai/codex`
+- runtime trigger surface:
   - `$arch`
   - `$sage`
   - `$flow`
   - `$vet`
   - `$vibe`
   - `$build`
-- Helper commands remain secondary:
-  - `ma status`
-  - `ma idea`
-  - `ma run ...`
-  - `ma merge`
-  - `ma release`
-  - `ma doctor`
-  - `ma setup`
-
-### 2. Gate and status rules
-
-Required status fields:
-- `idea_status`
-- `architecture_status`
-- `evidence_status`
-- `logic_status`
-- `security_status`
-- `experience_status`
-- `build_status`
-- `merge_status`
-- `release_status`
-
-Allowed values:
-- `idea_status`: `DRAFT`, `CLEAR`, `BLOCKED`
-- `architecture_status`: `DRAFT`, `REVIEWED`, `APPROVED`
-- `evidence_status`: `MISSING`, `PARTIAL`, `VERIFIED`
-- `logic_status`: `PENDING`, `GREEN`, `RED`
-- `security_status`: `PENDING`, `GREEN`, `RED`
-- `experience_status`: `PENDING`, `GREEN`, `RED`, `WAIVED`
-- `build_status`: `LOCKED`, `READY`, `RUNNING`, `DONE`
-- `merge_status`: `LOCKED`, `READY`, `MERGED_TO_DEVELOPMENT`
-- `release_status`: `LOCKED`, `READY`, `SHIPPED_TO_PROD`
-
-`$build` must stay locked unless:
-- `idea_status = CLEAR`
-- `architecture_status = APPROVED`
-- `evidence_status = VERIFIED`
-- `logic_status = GREEN`
-- `security_status = GREEN`
-- `experience_status ∈ { GREEN, WAIVED }`
-- `build_status ∈ { LOCKED, READY }`
-
-### 3. Branch and release policy
-
-- `feature/*` is bounded task work.
-- `development` is the integration branch.
-- `release/*` is optional stabilization.
-- `prod` is the production release branch.
-
-Rules:
-- feature work merges into `development`, never directly into `prod`
-- release evaluation is valid only from `development` or approved `release/*`
-- no release claim is true until tag, GitHub release, and npm publish all succeed
-
-### 4. Evidence and MCP rules
-
-- `$sage` must use approved GitMCP endpoints from `mcp/servers.json`.
-- Generic `https://gitmcp.io/docs` fallback remains policy-only and cannot silently unlock `$build`.
-- Evidence must be logged honestly as `VERIFIED`, `PARTIAL`, or `MISSING`.
-- Fake repos, fake endpoints, and silent evidence upgrades are prohibited.
-
-### 5. Release packaging and provenance
-
-Required release evidence:
-- matching package version and git tag (`v0.1.5` format)
-- `CHANGELOG.md` entry
-- `RELEASE.md` body
-- `docs/qa/release-readiness-0.1.5.md`
-- `dist/meta-architect-skills.tgz`
-- npm trusted publishing configuration
-- post-publish provenance verification
-
-### 6. Required docs
-
-- `README.md`
-- `docs/getting-started.md`
-- `docs/skills.md`
-- `docs/mcp-setup.md`
-- `docs/skills-publishing.md`
-- `docs/release-spec.md`
-- `docs/qa/release-readiness-0.1.5.md`
-
-## Production rule
-
-Meta-Architect `v0.1.5` is considered production-ready only if:
-- a Codex session launches through `ma --madmax --high`
-- the full `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` contract works with gate enforcement
-- package, docs, workflows, manifests, and release notes all agree on `v0.1.5`
-- the skill distribution surfaces validate and package from a clean checkout
-- the npm publish workflow is provenance-capable
-- post-publish verification checks are defined and enforced
+
+### 2. Secondary helper path
+
+Helper commands remain available for setup and scripted validation:
+- `ma setup`
+- `ma idea`
+- `ma run ...`
+- `ma status`
+- `ma merge`
+- `ma release`
+
+### 3. State and gate contract
+
+Canonical runtime namespace:
+- `.ma/`
+
+Canonical state files:
+- `.ma/decisions.json`
+- `.ma/release.json`
+- `.ma/evidence/*`
+- `.ma/context/*`
+- `.ma/specs/*`
+- `.ma/plans/*`
+- `.ma/runbook.md`
+
+### 4. Required release evidence
+
+- `package.json` version `0.1.6`
+- git tag `v0.1.6`
+- `RELEASE.md`
+- `CHANGELOG.md`
+- `docs/qa/release-readiness-0.1.6.md`
+- green `npm run release:check`
+
+### 5. Dist-tag discipline
+
+- stable versions such as `0.1.2` publish to npm `latest`
+- prerelease versions such as `0.2.0-beta.1` must publish with explicit tags such as `beta`
+- recommended alternate lanes are `next`, `beta`, and `canary`
+- prerelease publication must use `npm publish --tag <lane>`
+- stable publication keeps scoped public access and provenance enabled
+
+### 6. Canonical bump and publish flow
+
+1. Run `npm version <version> --no-git-tag-version`
+2. Update `CHANGELOG.md`
+3. Update `RELEASE.md`
+4. Update `docs/qa/release-readiness-<version>.md`
+5. Run `npm run release:verify`
+6. Run `npm run release:check`
+7. Create and push tag `v<version>`
+8. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
+9. Local shell fallback when not publishing from GitHub Actions or GitLab CI/CD:
+   - Stable publish: `npm publish --access public`
+   - Prerelease publish: `npm publish --access public --tag <lane>`
+10. Verify dist-tags with `npm view @jstn-sdk/ma version dist-tags time --json`
+
+### 6.1 Release automation
+
+- `npm run release:sync` updates the active release line when watched release-relevant files changed
+- `npm run release:advance` force-bumps the next patch line after a completed release
+- `.github/workflows/release-sync.yml` automates the sync path on `main`
+- `.github/workflows/release-advance.yml` advances the repo to the next patch line after a published release
+
+### 7. Provenance rule
+
+- `npm publish --provenance` is valid only from a supported cloud CI/CD provider
+- local shell publishes are expected to fail with `Automatic provenance generation not supported for provider: null`
+- use the repository publish workflow when provenance is part of the release bar