@jstn-sdk/ma 0.1.4 → 0.1.5

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

@@ -0,0 +1,77 @@
+# Release Readiness 0.1.5
+
+## 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:
+
+```bash
+npm run release:check
+```
+
+This must cover:
+- manifest generation
+- skill validation
+- skill tarball packaging
+- package metadata validation
+- release doc/version/tag alignment
+- workflow/provenance configuration validation
+- Biome checks
+- automated tests
+- npm package dry-run inspection
+
+## Additional checks
+
+Runtime posture:
+
+```bash
+ma --madmax --high
+```
+
+Scripted helper path for repo-local validation:
+
+```bash
+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 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
+
+## Known limits
+
+- 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

package/docs/release-spec.md

@@ -1,93 +1,115 @@
-# v0.1.4 Requirements & Rules
+# v0.1.5 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.4` 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
+Meta-Architect `v0.1.5` is production only when all of the following are true:
 
-## What `v0.1.4` must have
+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.
 
-### 1. Canonical package/runtime path
+Production here means safe to recommend for real projects and expensive to break without a major version change.
 
-- 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:
+## 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:
   - `$arch`
   - `$sage`
   - `$flow`
   - `$vet`
   - `$vibe`
   - `$build`
-
-### 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.4`
-- git tag `v0.1.4`
-- `RELEASE.md`
-- `CHANGELOG.md`
-- `docs/qa/release-readiness-0.1.4.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
+- 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

package/docs/skills-publishing.md

@@ -1,231 +1,98 @@
 # Skills Publishing
 
-Meta-Architect ships skills through a deliberate source-to-package pipeline. This repository treats publishable skills as product artifacts, not as raw markdown files.
+Meta-Architect publishes a Codex-native runtime package plus aligned skill-distribution surfaces. Publishable skills are product artifacts, not loose markdown.
 
-## Two skill surfaces
+## Provenance standard
 
-### 1. Internal runtime surface
+Meta-Architect `v0.1.5` uses npm trusted publishing from GitHub Actions as the canonical publish path.
 
-Location:
-- `.ma/skills/`
+Required release conditions:
+- public package name: `@jstn-sdk/ma`
+- canonical source repository: `https://github.com/JustineDevs/meta-architect`
+- GitHub Actions OIDC enabled with `id-token: write`
+- `npm publish --provenance --access public`
+- post-publish verification with npm metadata checks plus `npm audit signatures`
 
-Purpose:
-- local runtime behavior
-- internal command contracts
-- generated or seeded operator surfaces
+## Distribution surfaces
 
-### 2. Publishable skill surface
+Internal runtime surface:
+- `.omx/skills/`
 
-Location:
+Publishable skill surface:
 - `skills/`
 
-Purpose:
-- installable Codex skill folders
-- UI metadata via `agents/openai.yaml`
-- versionable public skill contract
+Plugin-facing bundle:
+- `plugins/meta-architect/`
 
-Do not confuse these two layers. The repo publishes `skills/`, not `.ma/`.
+The runtime story stays the same across all three surfaces:
+- install `@openai/codex` and `@jstn-sdk/ma`
+- launch `ma --madmax --high`
+- operate through `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
 
 ## Canonical packaging flow
 
-### Generate manifest
-
 ```bash
 npm run skills:manifest
-```
-
-Expected effect:
-- writes `skills/index.json`
-- manifest entries should match the actual skill directories
-
-### Validate skills
-
-```bash
 npm run skills:validate
-```
-
-Expected effect:
-- every skill folder passes the validator
-- missing or invalid frontmatter should fail the command
-- missing or structurally incomplete `agents/openai.yaml` should fail the command
-
-### Sync plugin mirror
-
-```bash
-npm run plugin:sync
-npm run plugin:verify
-```
-
-Expected effect:
-- `plugins/meta-architect/skills/` mirrors the canonical `skills/` surface
-- the local marketplace and plugin bundle remain aligned with the package skill contract
-- plugin drift fails verification instead of surviving into release artifacts
-
-### Create bundle
-
-```bash
 npm run skills:pack
-```
-
-Expected effect:
-- creates `dist/meta-architect-skills.tgz`
-- bundle should be non-empty
-
-### Smoke-test install
-
-```bash
 npm run skills:install -- --path ./dist/installed-skills
+npm run pack:inspect
 ```
 
-Expected effect:
-- all publishable skill folders are copied to the target install path
-- install target should contain:
-  - `meta-architect`
-  - `arch`
-  - `sage`
-  - `flow`
-  - `vet`
-  - `vibe`
-  - `build`
+Expected outputs:
+- `skills/index.json`
+- `dist/meta-architect-skills.tgz`
+- installable skill folders under `dist/installed-skills/`
 
-## Expected outputs
+## Public npm package
 
-### `skills/index.json`
-
-Should contain:
-- schema version
-- skill names
-- repo-local path mapping
-- descriptions
-
-### `dist/meta-architect-skills.tgz`
-
-Should contain:
-- `skills/`
-- each skill folder
-- each `SKILL.md`
-- each `agents/openai.yaml`
-- any intended references/assets
-
-It should **not** rely on hidden runtime state.
-
-Important:
-- `npm run skills:pack` creates the **skills bundle tarball only**
-- it is not the same thing as the broader npm package tarball from `npm pack`
-- the npm package surface is controlled separately by `package.json > files`
-
-## Source vs package contents
-
-The npm package and tarball should stay explicit.
-
-Current package intent:
-- package name: `@jstn-sdk/ma`
-- public publish config
-- explicit `files` list in `package.json`
-
-The publishable package should include:
+The npm package should include only the intended public surfaces from `package.json > files`, including:
 - `bin/`
+- `src/`
+- `.codex/`
+- `mcp/`
+- `prompts/`
 - `skills/`
 - `docs/`
-- `scripts/`
-- `index.js`
+- `plugins/`
+- `templates/`
 - `README.md`
 - `LICENSE`
 
-It should not include:
-- runtime `.ma` state
-- local logs
-- temp install targets
-- generated local caches
-
-The `skills:pack` tarball is narrower than the npm package:
-- `skills:pack` => `skills/` distribution bundle
-- `npm pack` => public npm package with the explicit `files` list
-
-## Release and dist-tag discipline
-
-Meta-Architect release behavior is lane-aware:
-- stable versions publish to npm `latest`
-- prerelease versions publish to explicit lanes such as `next`, `beta`, or `canary`
-- prereleases must use `npm publish --tag <lane>`
-- stable releases keep the default `latest` behavior and public scoped access
-
-Before publish:
-1. bump version with `npm version <version> --no-git-tag-version`
-2. update changelog and release docs
-3. run `npm run release:verify`
-4. run `npm run release:check`
-5. create and push tag `v<version>`
-6. publish the package with the correct lane behavior
-   - preferred: run `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
-   - local fallback: omit `--provenance` and publish with `npm publish --access public` or `npm publish --access public --tag <lane>`
-7. verify the resulting dist-tags with `npm view @jstn-sdk/ma version dist-tags time --json`
-
-## Plugin relation
-
-The plugin bundle in:
-- `plugins/meta-architect/`
+It must not include local runtime residue such as:
+- `.omx/logs/`
+- `.omx/state/`
+- `.omx/tmp/`
+- `.omx/cache/`
+- `.omx/metrics.json`
 
-is related but not identical to the npm/package skill bundle.
+## Release verification
 
-Relationship:
-- `skills/` is the canonical publishable skill source
-- `plugins/meta-architect/` is the plugin-installable consumer-facing bundle
-- both should remain aligned in behavior and version intent
-- `.agents/plugins/marketplace.json` advertises the local plugin source for discovery
-- `plugins/meta-architect/.codex-plugin/plugin.json` is the plugin contract entrypoint
+Before a release is considered real:
+- `npm run release:check` passes
+- `skills/index.json` is current
+- `dist/meta-architect-skills.tgz` exists and is non-empty
+- package metadata matches the canonical repo identity
+- release notes, changelog, QA doc, and workflows all reference the same version/tag
+- publish workflow remains provenance-capable
+
+## Post-publish provenance verification
 
-If a skill contract changes:
-1. update `skills/`
-2. regenerate manifest
-3. sync the plugin mirror
-4. validate skills
-5. ensure plugin-facing bundle still reflects the same product contract
+After publish:
 
-## Real commands for a release-minded flow
+1. Verify the published package version on npm.
+2. Install `@jstn-sdk/ma@<version>` in a clean temp directory.
+3. Run:
 
 ```bash
-npm run skills:manifest
-npm run plugin:sync
-npm run skills:validate
-npm run plugin:verify
-npm run skills:pack
-npm run skills:install -- --path ./dist/installed-skills
-npm run pack:inspect
+npm audit signatures
 ```
 
-## Expected failure modes
-
-- manifest drift:
-  - `skills/index.json` does not match actual skill directories
-- invalid skill:
-  - malformed frontmatter
-  - missing `SKILL.md`
-  - invalid `agents/openai.yaml`
-- package drift:
-  - tarball includes files not intended for public distribution
-- plugin drift:
-  - plugin bundle no longer matches the published skill contract
-
-## Release artifact expectations
-
-Before a release is considered real:
-- `skills/index.json` must be current
-- `dist/meta-architect-skills.tgz` must exist
-- install smoke test must pass
-- package inspection must be sane
-- docs must match the published behavior
+4. Confirm the npm package provenance points back to `JustineDevs/meta-architect` and the GitHub Actions publish workflow.
 
 ## Related surfaces
 
 - [README.md](../README.md)
 - [docs/skills.md](./skills.md)
 - [plugins/meta-architect/README.md](../plugins/meta-architect/README.md)
-- [plugins/meta-architect/.codex-plugin/plugin.json](../plugins/meta-architect/.codex-plugin/plugin.json)
-- [../.agents/plugins/marketplace.json](../.agents/plugins/marketplace.json)
 - [package.json](../package.json)
-- [scripts/skills-manifest.js](../scripts/skills-manifest.js)
-- [scripts/plugin-sync.js](../scripts/plugin-sync.js)
-- [scripts/skills-validate.js](../scripts/skills-validate.js)
-- [scripts/skills-pack.js](../scripts/skills-pack.js)
-- [scripts/skills-install.js](../scripts/skills-install.js)