@jstn-sdk/ma 0.1.11 → 0.1.13

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

@@ -0,0 +1,116 @@
+# Release Readiness 0.1.13
+
+## Production bar
+
+`v0.1.13` 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
+- the singular `$maestro` umbrella and helper-skill contract stay coherent
+- release docs, package metadata, and workflows all agree on `0.1.13`
+
+Target release state:
+- npm package: `@jstn-sdk/ma@0.1.13`
+- npm registry state: pending publish
+- publishability note: `0.1.12` is already published, so `0.1.13` is the next publishable package line
+- git tag: `v0.1.13`
+- GitHub release: pending publish for `v0.1.13`
+
+## Production checklist
+
+- skills-first product identity: PASS
+- package/plugin identity aligned to `@jstn-sdk/ma`: PASS
+- version/tag alignment `0.1.13` / `v0.1.13`: 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
+- Linux native package release lane wired: PASS
+- singular `$maestro` umbrella surface: PASS
+- helper skill family shipped but non-gating: PASS
+- native playbooks and support-bundle reference assets aligned: 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
+- issue proof gates for `v0.1.13`: PASS; `release-issue-gates-0.1.13.json` marks issues `#13-#29` passed with implementation, verification, and production evidence, so release verification can enforce the gate artifact instead of blocking on pending issue states
+
+## 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
+
+Linux-native release lane:
+
+```bash
+npm run linux:packages:build
+npm run linux:packages:smoke
+npm run release:assets
+```
+
+That should prove:
+- the Debian-family, Arch-family, and Fedora/openSUSE-style package artifacts are produced
+- the extracted package payload exposes a working `ma` command
+- the GitHub release asset set is complete
+- the packaged support bundle contains the playbooks and reference assets expected by the runtime
+
+## Issue proof gates
+
+Issue gate artifact:
+
+```text
+docs/qa/release-issue-gates-0.1.13.json
+```
+
+Every open issue assigned to `v0.1.13` must remain in this file until it is production-passed. A passed issue requires:
+- implementation evidence
+- verification evidence
+- production evidence
+
+If any issue is `pending`, `in_progress`, `blocked`, or `failed`, `npm run release:verify` must fail and the issue must continue through its recorded loop action.
+
+## Manual/behavioral checks run
+
+Canonical launch:
+
+```bash
+ma --madmax --high
+```
+
+Helper-path validation:
+
+```bash
+ma setup
+ma idea "Harden Meta-Architect v0.1.13 semantic core with Obsidian vault context, Ralph execution proof, context economy, and package-gated release evidence"
+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
+- `$maestro` remains the only umbrella surface
+- helper skills remain non-gating
+- `$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/qa/release-readiness-0.1.5.md

@@ -58,7 +58,7 @@ Helper-path validation:
 
 ```bash
 ma setup
-ma idea "Build a demo app"
+ma idea "Harden Meta-Architect semantic core with evidence-backed gate readiness and package-visible proof"
 ma run '$arch'
 ma run '$sage'
 ma run '$flow'

package/docs/reference/native-engineering-patterns.md

@@ -0,0 +1,35 @@
+# Native Engineering Patterns
+
+Meta-Architect internalizes recurring engineering patterns as native product guidance rather than shipping upstream catalogs as first-class surfaces.
+
+## Helper-skill mapping
+
+- `align`
+  - shared language
+  - ambiguity reduction
+  - documentation clarity
+- `diagnose`
+  - failure slicing
+  - blocked-lane triage
+  - root-cause decomposition
+- `tdd`
+  - regression-first execution
+  - failing-test-first loops
+  - behavior locking
+- `cleanup`
+  - anti-slop cleanup
+  - prose tightening
+  - behavior-preserving simplification
+
+## Gated-lane mapping
+
+- `$maestro`
+  - umbrella routing and next-step synthesis
+- `$sage`
+  - evidence-backed selection and source quality
+- `$vet`
+  - security and trust-boundary playbooks
+
+## Product rule
+
+These patterns are Meta-Architect-native. They are not exposed as raw upstream repo identities or mirror-style catalogs.

package/docs/reference/native-security-playbooks.md

@@ -0,0 +1,27 @@
+# Native Security Playbooks
+
+Security-oriented external patterns are absorbed into Meta-Architect as `$vet` guidance and packaged playbooks.
+
+## Review slices
+
+- identity and session boundaries
+- authorization and tenancy
+- secret handling
+- dependency and supply-chain risk
+- input validation and output exposure
+- abuse cases and operational failure modes
+
+## Routing
+
+- `$vet` remains the only security gate
+- playbooks deepen `$vet`; they do not create a second security umbrella
+
+## Product rule
+
+Meta-Architect can absorb security arsenal patterns aggressively while still presenting them only as native guidance and packaged references.
+
+## Adversarial hardening
+
+- For higher-risk changes, run a bounded adversarial hardening pass before final approval.
+- Keep the hardening work inside the private scratchpad/runtime layer.
+- Return structured findings, not direct gate mutations.

package/docs/reference/native-source-selection.md

@@ -0,0 +1,27 @@
+# Native Source Selection
+
+Meta-Architect uses external discovery surfaces as inputs to native source-selection guidance, not as first-class product faces.
+
+## Evidence ladder
+
+1. known upstream repo and official docs
+2. discovery accelerators for narrowing candidates
+3. exact upstream repo mapping
+4. upstream and official-doc verification before approval
+
+## Product rule
+
+- discovery lists help candidate selection
+- verification still depends on primary sources
+- packaged references should explain the selection posture in Meta-Architect language
+
+## Routing
+
+- `$sage` owns source selection and evidence quality
+- helper skills can support preparation, but they do not replace `$sage`
+
+## Evidence grades
+
+- `VERIFIED`: exact upstream mapping plus primary-source confirmation
+- `PARTIAL`: candidate is mapped, but live proof or maturity proof is incomplete
+- `MISSING`: no trustworthy exact upstream mapping yet

package/docs/reference/native-style-and-deslop.md

@@ -0,0 +1,20 @@
+# Native Style And Deslop
+
+Meta-Architect treats prose cleanup and anti-slop work as helper behavior, not as a separate umbrella workflow.
+
+## Core rules
+
+- prefer deletion over addition
+- preserve behavior while simplifying
+- remove generic AI filler from user-facing docs
+- keep naming concise and Meta-Architect-native
+- lock behavior with tests before cleanup when code paths are involved
+
+## Routing
+
+- use `$cleanup` for final-pass simplification and prose cleanup
+- return to `$maestro` or the owning gated lane after cleanup decisions are made
+
+## Non-goal
+
+Do not ship raw third-party “humanizer” or “stop-slop” identities as first-class product surfaces.

package/docs/release-spec.md

@@ -1,16 +1,17 @@
-# v0.1.11 Requirements & Rules
+# v0.1.13 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.11` is production only when:
+Meta-Architect `v0.1.13` 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
 
-## What `v0.1.11` must have
+## What `v0.1.13` must have
 
 ### 1. Canonical package/runtime path
 
+- recommended POSIX one-line install: `curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh`
 - 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`
@@ -49,12 +50,19 @@ Canonical state files:
 
 ### 4. Required release evidence
 
-- `package.json` version `0.1.11`
-- git tag `v0.1.11`
+- `package.json` version `0.1.13`
+- git tag `v0.1.13`
 - `RELEASE.md`
 - `CHANGELOG.md`
-- `docs/qa/release-readiness-0.1.11.md`
+- `docs/qa/release-readiness-0.1.13.md`
+- `docs/qa/release-issue-gates-0.1.13.json`
 - green `npm run release:check`
+- GitHub release asset `meta-architect_0.1.13_all.deb`
+- GitHub release asset `meta-architect-0.1.13-1-any.pkg.tar.xz`
+- GitHub release asset `meta-architect-0.1.13-1.noarch.rpm`
+- green `npm run linux:packages:build`
+- green `npm run linux:packages:smoke`
+- green `npm run release:assets`
 
 ### 5. Dist-tag discipline
 
@@ -72,12 +80,17 @@ Canonical state files:
 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:
+7. Build and smoke-check the Linux native packages on Linux:
+   - `npm run linux:packages:build`
+   - `npm run linux:packages:smoke`
+   - `npm run release:assets`
+8. Create and push tag `v<version>`
+9. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
+10. 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`
+11. Verify dist-tags with `npm view @jstn-sdk/ma version dist-tags time --json`
+12. Verify the GitHub release contains `dist/meta-architect-skills.tgz`, `meta-architect_<version>_all.deb`, `meta-architect-<version>-1-any.pkg.tar.xz`, and `meta-architect-<version>-1.noarch.rpm`
 
 ### 6.1 Release automation
 
@@ -86,6 +99,20 @@ Canonical state files:
 - `.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
 
+### 6.2 Issue proof gates
+
+Every open next-release issue must be represented in `docs/qa/release-issue-gates-0.1.13.json`.
+
+Production pass rule:
+- issue status must be `passed`
+- issue milestone must match `v0.1.13`
+- implementation evidence must be present
+- verification evidence must be present
+- production evidence must be present
+- pending, blocked, failed, or in-progress issues must continue through their loop action instead of being treated as release-ready
+
+`npm run release:verify` enforces this file. If any issue is not production-passed, the release remains blocked.
+
 ### 7. Provenance rule
 
 - `npm publish --provenance` is valid only from a supported cloud CI/CD provider

package/docs/skills-publishing.md

@@ -26,6 +26,16 @@ Purpose:
 
 Do not confuse these two layers. The repo publishes `skills/`, not `.ma/`.
 
+## Published surface types
+
+The publishable `skills/` surface contains:
+- one umbrella autonomous manager: `$maestro`
+- fixed gated lanes: `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
+- non-gating helper skills: `$align`, `$diagnose`, `$tdd`, `$cleanup`
+
+Only `$maestro` is the umbrella surface. Helper skills are intentionally publishable but non-gating.
+The `ma` terminal helper command is part of the npm package surface, not the publishable skill contract.
+
 ## Canonical packaging flow
 
 ### Generate manifest
@@ -80,13 +90,19 @@ npm run skills:install -- --path ./dist/installed-skills
 Expected effect:
 - all publishable skill folders are copied to the target install path
 - install target should contain:
-  - `meta-architect`
+  - `align`
+  - `maestro`
   - `arch`
   - `sage`
   - `flow`
+  - `diagnose`
+  - `tdd`
+  - `cleanup`
   - `vet`
   - `vibe`
   - `build`
+- install target should not contain:
+  - `meta-architect`
 
 ## Expected outputs
 
@@ -97,6 +113,8 @@ Should contain:
 - skill names
 - repo-local path mapping
 - descriptions
+- only native Meta-Architect skill identities
+- a `maestro` description that matches the bounded autonomous-manager contract
 
 ### `dist/meta-architect-skills.tgz`
 
@@ -174,6 +192,9 @@ Relationship:
 - 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
+- the umbrella in-session entry point is `$maestro`; there is no separately shipped `$meta-architect` skill
+- `$maestro` is the bounded autonomous manager, not a second terminal runtime
+- helper skills remain publishable mirrors, but they do not add release gates or alternate umbrella entry points
 
 If a skill contract changes:
 1. update `skills/`
@@ -212,6 +233,9 @@ npm run pack:inspect
 Before a release is considered real:
 - `skills/index.json` must be current
 - `dist/meta-architect-skills.tgz` must exist
+- `dist/meta-architect_<version>_all.deb` must exist for the Debian-family release lane
+- `dist/meta-architect-<version>-1-any.pkg.tar.xz` must exist for the Arch-family release lane
+- `dist/meta-architect-<version>-1.noarch.rpm` must exist for the Fedora/openSUSE-style release lane
 - install smoke test must pass
 - package inspection must be sane
 - docs must match the published behavior

package/docs/skills.md

@@ -1,18 +1,24 @@
 # Skills
 
-Meta-Architect’s canonical Codex runtime surface is:
-- `$maestro`
-- `$arch`
-- `$sage`
-- `$flow`
-- `$vet`
-- `$vibe`
-- `$build`
+Meta-Architect ships three in-session skill layers:
+
+- umbrella autonomous manager: `$maestro`
+- fixed gated lanes: `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
+- non-gating helper skills: `$align`, `$diagnose`, `$tdd`, `$cleanup`
+
+The package does not ship a separate `$meta-architect` in-session skill. `$maestro` is the umbrella contract for next-step management, bounded lane handoff, and fixed-sequence supervision.
 
 ## Real usage path
 
 Install the package once, start Codex context if needed, and use the skills directly in-session.
 
+Recommended CLI install for macOS, Linux, WSL, and Git-Bash:
+
+```bash
+# One-line install (POSIX shells only; use WSL/Git-Bash on Windows)
+curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh
+```
+
 ```bash
 # Install
 npm i -g @openai/codex@latest @jstn-sdk/ma@latest
@@ -28,11 +34,12 @@ npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
 Then inside the Codex session:
-1. Start with `$maestro` when you want Meta-Architect to choose the best next step
+1. Start with `$maestro` when you want Meta-Architect to act as the bounded autonomous manager for the workflow
 2. Or start with `$arch` when you already know the architecture lane is next
 3. Continue through `$sage -> $flow -> $vet -> $vibe -> $build`
+4. Use `$align`, `$diagnose`, `$tdd`, or `$cleanup` only as publishable non-gating helper skills around that gated path
 
-## Simple difference
+## Two surfaces
 
 Meta-Architect has two surfaces:
 
@@ -46,7 +53,10 @@ ma setup
 ma init
 ma idea "Build a product"
 ma status
+ma status --maestro-view
+ma verify --architect
 ma run '$arch'
+ma run '$maestro' --auto-heal --parallel
 ```
 
 In-session skills are used inside the Codex conversation:
@@ -59,6 +69,10 @@ $flow
 $vet
 $vibe
 $build
+$align
+$diagnose
+$tdd
+$cleanup
 ```
 
 Short rule:
@@ -70,6 +84,13 @@ Important:
 - they only create local support files
 - they do not replace the in-session skill flow
 
+Manager contract:
+- `$maestro` is the only umbrella in-session surface
+- `$maestro` manages the next allowed step, but gated outputs still belong to `$arch -> $sage -> $flow -> $vet -> $vibe -> $build`
+- helper skills are publishable mirrors that can assist a lane, but they do not move release gates
+- `ma run '$maestro' --auto-heal --parallel` enables the bounded runtime repair path and records conductor state in the private scratchpad layer when eligible
+- `ma verify --architect` runs an external architect reviewer command when `MA_ARCHITECT_REVIEW_CMD` is configured
+
 ## Installed support bundle
 
 Meta-Architect also installs a standard packaged support bundle for relevant files.
@@ -95,6 +116,8 @@ Relevant packaged assets there include:
 - `scripts/`
 - `plugins/meta-architect/`
 - `templates/`
+- native skill references such as `skills/maestro/references/`, `skills/sage/references/`, `skills/vet/references/`, `skills/align/references/`, and `skills/cleanup/references/`
+- runtime scratchpad state such as `.ma/state/manager-runs.json` and `.ma/state/maestro-state.json` when local execution is active
 
 This exists so Meta-Architect can use relevant packaged files without guessing paths.
 
@@ -109,7 +132,7 @@ Every skill result must include:
 
 ## Status ownership
 
-- `$maestro` -> next-step recommendation
+- `$maestro` -> umbrella workflow management, next-step recommendation, and bounded helper/gate handoff
 - project brief -> architecture input
 - `$arch` -> `architecture_status`
 - `$sage` -> `evidence_status`
@@ -118,6 +141,8 @@ Every skill result must include:
 - `$vibe` -> `experience_status`
 - `$build` -> `build_status`
 
+`$maestro` may dispatch a gated lane, but it does not own that lane's artifact or release-state field. Helper skills do not own release-state fields. They are publishable but non-gating, so they support the current lane and then hand work back to `$maestro` or the gated lane that owns the decision.
+
 ## Operator note
 
-The in-session skill surface is primary. The `ma` helper commands only exist to start Codex context and to provide repo-local state automation when scripted verification is needed.
+The in-session skill surface is primary. The `ma` terminal helper commands only exist to start Codex context and to provide repo-local state automation when scripted verification is needed.