sagaz-ai 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## [0.3.0] - 2026-06-11
+
+### Release Type
+
+Minor
+
+### Added
+
+- Operations runbook for daily starts, project starts, resumes, handoffs, verification, releases, GitHub operations, and stop conditions.
+- Complete examples library covering web SaaS on Vercel, mobile habit tracking, production bugfix releases, and brownfield refactors.
+- Capabilities matrix comparing Sagaz with common orchestration systems and identifying what Sagaz now covers or intentionally defers.
+- Formal permission contract with approval levels for local edits, installs, network access, GitHub operations, releases, secrets, and destructive actions.
+- Stack playbooks for Next.js/Vercel/Supabase, React/Vite/static hosting, Expo/EAS, Node APIs, and Firebase.
+- Execution trace template and stronger observability contract for commands, decisions, failures, handoffs, and release evidence.
+- MCP connector policy for Figma, GitHub, browser automation, deployment providers, databases, Canva, npm registries, observability, and AI providers.
+
+### Changed
+
+- `npm test` now validates stack playbooks, permission policy, execution trace requirements, observability rules, and MCP connector policy coverage.
+- README, INDEX, manifest, tool registry, run-state template, and Sagaz skill instructions now expose the new governance and connector contracts.
+- Release governance now requires stronger evidence around permissions, connector usage, workflow traceability, and stack-specific verification.
+
+### Fixed
+
+- Filled remaining non-CLI governance gaps identified after the 0.2.0 release.
+- Reduced ambiguity around cross-platform execution on Windows and macOS inside Codex Desktop.
+
+### Removed
+
+- None.
+
+### Security
+
+- Added explicit permission levels for secrets, destructive actions, external publishing, GitHub operations, package registries, and MCP connectors.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop and locally verified on Windows.
+- macOS: supported through Codex Desktop and covered by GitHub Actions package checks.
+- Node.js: package baseline remains `>=22.14`; Node.js 24 is preferred for new installs and CI.
+- Codex Desktop: Sagaz remains a Codex Desktop orchestration skill, not a standalone terminal agent runtime.
+
+### Migration Notes
+
+- Existing users should run `npx sagaz-ai@0.3.0 sync` or `npx sagaz-ai sync` to refresh the installed Codex Desktop skill.
+- Open a new Codex Desktop thread after syncing so the updated skill can be discovered.
+
+### Verification
+
+- npm test: passed locally on Windows.
+- npm run doctor: passed locally on Windows with `Synchronized with source: yes`.
+- npm pack --dry-run: passed locally on Windows after allowing npm cache access outside the sandbox.
+- Windows: prepared and verified from a Windows Codex Desktop workspace.
+- macOS: package checks remain covered by GitHub Actions.
+- Codex Desktop: skill sync remains required after install or upgrade.
+
+### Release Evidence
+
+- Commit: pending.
+- Tag: pending.
+- GitHub release: pending.
+- npm package: pending.
+
 ## [0.2.0] - 2026-06-08
 
 ### Release Type
@@ -64,4 +127,3 @@ Minor
 - Tag: pending.
 - GitHub release: pending.
 - npm package: pending.
-

package/RELEASE_NOTES.md

@@ -2,8 +2,8 @@
 
 ## Release
 
-Version: 0.2.0
-Date: 2026-06-08
+Version: 0.3.0
+Date: 2026-06-11
 Release type: Minor
 GitHub commit: pending
 Git tag: pending
@@ -12,34 +12,34 @@ npm package: pending
 
 ## Summary
 
-Sagaz 0.2.0 strengthens the orchestration ecosystem around formal workflows, handoffs, task contracts, registry validation, release gates, GitHub Actions enforcement, evaluation coverage, and installed skill synchronization.
+Sagaz 0.3.0 completes the main non-CLI governance layer for Codex Desktop orchestration. It adds operational runbooks, complete scenario examples, a capabilities matrix, formal permission policy, stack playbooks, execution trace evidence, and MCP connector governance.
 
 ## Audience Impact
 
-- New users: clearer README, requirements, installation guidance, and sync instructions.
+- New users: clearer operating model, examples, stack guidance, and permission expectations before using Sagaz.
 - Existing users: should refresh the installed skill with `npx sagaz-ai sync`.
-- Maintainers: stronger `npm test` coverage catches manifest, dependency graph, release, workflow, task, and evaluation drift.
-- Design team: Figma MCP and app-like mockup guidance are now part of Sagaz operating rules.
-- Engineering team: workflows now behave more like formal contracts with gates, state, handoffs, and evidence.
+- Maintainers: stronger package checks now catch stack playbook, observability, permission, and connector-policy drift.
+- Design team: Figma MCP usage is governed as a formal connector workflow for app-like mockups and design artifacts.
+- Engineering team: workflow evidence now includes traceable commands, decisions, failures, permissions, and handoffs.
 
 ## What Changed
 
-- Added `manifest.json` as an internal component registry.
-- Added dependency graph validation.
-- Added component governance.
-- Added release/versioning gate.
-- Added GitHub Actions package checks across Linux, Windows, and macOS.
-- Added formal changelog and release notes templates.
-- Added installed skill sync protocol and CLI command.
-- Strengthened workflow, task, run-state, and evaluation contracts.
+- Added an operations runbook for everyday Sagaz use.
+- Added complete examples for common delivery scenarios.
+- Added a capabilities matrix against other orchestration ecosystems.
+- Added a formal permission contract for Windows and macOS Codex Desktop usage.
+- Added stack-specific playbooks.
+- Added an execution trace template and stronger observability protocol.
+- Added MCP connector policy across design, deploy, package, data, browser, and AI providers.
+- Expanded package verification to enforce the new governance files.
 
 ## Why It Matters
 
-Sagaz is now harder to accidentally drift, release, or publish in an inconsistent state. The system can validate its own structure, release gates, installed skill sync, and GitHub automation before maintainers ship changes.
+Sagaz now has clearer rules for how agents should choose tools, request permission, preserve workflow state, hand off work, verify stack-specific outcomes, and operate MCP connectors without drifting into ad hoc behavior.
 
 ## Compatibility
 
-- Windows: supported and locally verified.
+- Windows: supported and locally verified from a Codex Desktop workspace.
 - macOS: supported through Codex Desktop and GitHub Actions runner validation.
 - Node.js: `>=22.14` remains the package minimum; Node.js 24 is preferred for new installs and CI.
 - Codex Desktop: required.
@@ -51,7 +51,7 @@ Sagaz is now harder to accidentally drift, release, or publish in an inconsisten
 Run:
 
 ```bash
-npx sagaz-ai sync
+npx sagaz-ai@0.3.0 sync
 npx sagaz-ai doctor
 ```
 
@@ -59,16 +59,16 @@ Then open a new Codex Desktop thread so Sagaz is rediscovered.
 
 ## Verification
 
-- `npm test`: passed locally.
-- `npm run doctor`: passed locally with installed skill synchronization confirmed.
-- `npm pack --dry-run`: passed locally after npm cache access was allowed outside the sandbox.
-- Evaluation scenarios: enforced by the strengthened Sagaz evaluation suite.
+- `npm test`: passed locally on Windows.
+- `npm run doctor`: passed locally on Windows with installed skill synchronization confirmed.
+- `npm pack --dry-run`: passed locally on Windows after npm cache access was allowed outside the sandbox.
 - Manual checks: Git status reviewed before release preparation.
 
 ## Known Limitations
 
-- GitHub release and npm publishing remain manual approval steps.
-- The package still installs Sagaz for Codex Desktop; it is not a standalone terminal orchestration runtime.
+- Sagaz still intentionally skips a standalone CLI runtime; Codex Desktop remains the execution surface.
+- GitHub release and npm publishing remain explicit approval steps.
+- Connector behavior depends on each external MCP/app authorization and platform availability.
 
 ## Rollback Plan
 
@@ -79,6 +79,5 @@ Then open a new Codex Desktop thread so Sagaz is rediscovered.
 ## Release Decision
 
 Approved by: Thiago Cabral
-Approval date: 2026-06-08
+Approval date: 2026-06-11
 Residual risk: GitHub Actions and npm publishing still need remote execution after push.
-

package/ai-orchestration-ecosystem/INDEX.md

@@ -71,6 +71,8 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `protocols/installed-skill-sync.md`
 - `protocols/memory.md`
 - `protocols/model-routing.md`
+- `protocols/mcp-connector-policy.md`
+- `protocols/permission-contract.md`
 - `protocols/post-delivery-monitoring.md`
 
 ## Tools
@@ -89,6 +91,15 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `stack-presets/static-site.md`
 - `stack-presets/admin-dashboard.md`
 
+## Stack Playbooks
+
+- `stack-playbooks/README.md`
+- `stack-playbooks/nextjs-vercel-supabase.md`
+- `stack-playbooks/react-vite-static.md`
+- `stack-playbooks/expo-eas.md`
+- `stack-playbooks/node-api.md`
+- `stack-playbooks/firebase.md`
+
 ## Evaluations
 
 - `evals/sagaz-evaluation-suite.md`
@@ -96,13 +107,21 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 ## Examples
 
 - `examples/README.md`
+- `examples/web-saas-vercel.md`
+- `examples/mobile-habit-tracker.md`
+- `examples/bugfix-production-release.md`
+- `examples/brownfield-refactor.md`
 
 ## Templates
 
 See `templates/` for task briefs, product specs, technical specs, design systems, future-change guides, refactor safety contracts, stack recommendations, run state, squad handoffs, QA reports, release checklists, changelogs, release notes, and final handoffs.
 
+- `templates/execution-trace.md`
+
 ## Governance
 
+- `governance/capabilities-matrix.md`
+- `governance/operations-runbook.md`
 - `governance/quality-policy.md`
 - `governance/security-policy.md`
 - `governance/versioning.md`

package/ai-orchestration-ecosystem/README.md

@@ -4,11 +4,12 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 
 ## How To Use
 
-1. Read `quickstart.md`.
-2. Choose the smallest sufficient workflow or squad.
-3. Use formal tasks, handoffs, and quality gates.
-4. Create or update run state for medium/large work.
-5. Verify before declaring done.
+1. Read `governance/operations-runbook.md` for the daily operating procedure.
+2. Read `quickstart.md`.
+3. Choose the smallest sufficient workflow or squad.
+4. Use formal tasks, handoffs, and quality gates.
+5. Create or update run state for medium/large work.
+6. Verify before declaring done.
 
 ## Structure
 
@@ -18,7 +19,9 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 - `agents/`: role definitions.
 - `tasks/`: formal task contracts.
 - `protocols/`: operating rules and quality gates.
+- `stack-playbooks/`: operational guides for common stack implementation, verification, and deployment.
 - `templates/`: reusable Markdown artifacts.
+- `examples/`: complete web, mobile, bugfix, and refactor flow examples.
 - `engineering/`: software engineering standards.
 - `governance/`: quality, security, and maintenance policies.
 
@@ -34,6 +37,14 @@ Use `protocols/release-versioning-gate.md` before version bumps, Git tags, GitHu
 
 Use `protocols/installed-skill-sync.md` after changing the Sagaz skill or release rules so the installed Codex Desktop skill does not drift from the repository copy.
 
+Use `governance/capabilities-matrix.md` when comparing Sagaz with CrewAI, AutoGen, LangChain, LangGraph, AIOX, Synkra, or similar orchestration systems.
+
+Use `protocols/permission-contract.md` before actions that change local state, remote state, accounts, deployments, packages, credentials, or GitHub history.
+
+Use `protocols/agent-observability.md` and `templates/execution-trace.md` for multi-phase, production, release, deployment, package, or high-risk work.
+
+Use `protocols/mcp-connector-policy.md` before using MCPs or external connectors such as Figma, GitHub, Canva, Browser, Vercel, Supabase, Firebase, npm, or observability tools.
+
 ## Advanced Engineering Coverage
 
 Sagaz includes protocols for SRE readiness, DORA metrics, secure SDLC, dependency governance, data privacy lifecycle, architecture fitness functions, API contracts, performance budgets, accessibility compliance, database migrations, release strategy, and AI application quality.

package/ai-orchestration-ecosystem/examples/README.md

@@ -2,69 +2,47 @@
 
 ## Purpose
 
-Provide reusable, low-token examples for common Sagaz projects. Examples are not templates to copy blindly. They show the expected flow, artifacts, handoffs, and verification depth.
+Provide reusable, low-token examples for common Sagaz projects.
 
-## Example Categories
+Examples are not templates to copy blindly. They show the expected prompt shape, workflow, squads, artifacts, handoffs, verification depth, GitHub actions, deployment path, and final delivery evidence.
 
-- complete marketing website
-- SaaS web app
-- admin dashboard
-- mobile app
-- bugfix to release
-- safe refactor
-- production deploy
-- GitHub release
+## Complete Examples
 
-## Example Structure
-
-Each example should include:
-
-- user prompt
-- selected workflow
-- required squads
-- first questions, if any
-- stack recommendation summary
-- handoff sequence
-- expected artifacts
-- verification plan
-- GitHub actions to suggest
-- deployment path
-- final handoff shape
-
-## Minimal Web App Example
-
-```md
-User prompt:
-Sagaz: create a premium appointment scheduling SaaS for small clinics.
-
-Workflow:
-workflows/greenfield-web-app.md
-
-Squads:
-Product Factory -> Design Studio -> Production Critical -> GitHub Ops
+- `web-saas-vercel.md`: appointment scheduling SaaS using a web production path.
+- `mobile-habit-tracker.md`: Android/iOS habit tracker with mobile release planning.
+- `bugfix-production-release.md`: production bugfix through verification and GitHub release.
+- `brownfield-refactor.md`: safe refactor of an existing project without behavior changes.
 
-Stack recommendation:
-Next.js on Vercel, TypeScript, Supabase, Playwright, GitHub Actions.
-
-Reason:
-Fast delivery, clear deployment path, managed auth/database, strong web ecosystem, good future maintainability.
-
-Required handoffs:
-Intake -> stack -> spec -> design -> architecture -> implementation -> QA -> production readiness -> GitHub/deploy.
-```
-
-## Mobile App Example
-
-```md
-User prompt:
-Sagaz: create an Android/iOS habit tracker with premium UX and store-ready release planning.
-
-Workflow:
-workflows/mobile-app-production.md
+## Example Structure
 
-Likely stack:
-Expo, React Native, TypeScript, SQLite or Supabase depending on sync needs, EAS for builds.
+Each complete example includes:
+
+- User prompt.
+- Selected workflow.
+- Required squads.
+- First actions.
+- Stack recommendation.
+- Handoff sequence.
+- Expected artifacts.
+- Verification plan.
+- GitHub actions to suggest.
+- Deployment or release path.
+- Final handoff shape.
+
+## How To Use
+
+1. Pick the example closest to the user's request.
+2. Load only that example and the named workflow/task/protocol files needed for the current phase.
+3. Adapt constraints to the actual project.
+4. Keep run state for medium, large, production, mobile, or multi-phase work.
+5. Ask permission before moving across major phases or doing remote actions.
+
+## Selection Map
+
+| User Request | Example | Workflow |
+| --- | --- | --- |
+| New SaaS, dashboard, or premium web app | `web-saas-vercel.md` | `workflows/greenfield-web-app.md` |
+| Android/iOS app | `mobile-habit-tracker.md` | `workflows/mobile-app-production.md` |
+| Production bug | `bugfix-production-release.md` | `workflows/bugfix-to-release.md` |
+| Safe refactor | `brownfield-refactor.md` | `workflows/brownfield-refactor-safe.md` |
 
-Required evidence:
-Device-size review, offline behavior decision, accessibility checks, app icon/splash plan, release checklist.
-```

package/ai-orchestration-ecosystem/examples/brownfield-refactor.md

@@ -0,0 +1,90 @@
+# Example: Brownfield Refactor
+
+## User Prompt
+
+```text
+Sagaz: refactor this existing project safely without changing behavior.
+
+Goal:
+Make the billing module easier to maintain before adding new plan types.
+```
+
+## Selected Workflow
+
+`workflows/brownfield-refactor-safe.md`
+
+## Required Squads
+
+- `squads/code-audit.md`
+- `squads/refactor-lab.md`
+- `squads/production-critical.md`
+- `squads/github-ops.md`
+
+## First Actions
+
+1. Inspect git status.
+2. Identify the current behavior and files involved.
+3. Establish baseline tests or manual checks.
+4. Define invariants that must not change.
+5. Create or update run state.
+6. Ask permission before editing code.
+
+## Stack Recommendation
+
+Use the existing project stack. Prefer local patterns and existing helpers over new abstractions.
+
+## Handoff Sequence
+
+| Phase | From | To | Evidence |
+| --- | --- | --- | --- |
+| Baseline | code-audit | refactor-lab | behavior map, tests, invariants |
+| Refactor plan | refactor-lab | production-critical | scoped plan, rollback path |
+| Implementation | production-critical | production-critical | small commits or small logical steps |
+| Verification | production-critical | github-ops | before/after checks, residual risk |
+
+## Expected Artifacts
+
+- `templates/refactor-safety-contract.md`.
+- `templates/future-change-guide.md`.
+- Baseline behavior notes.
+- Changed file summary.
+- `templates/qa-report.md`.
+- Final handoff.
+
+## Verification Plan
+
+- Run existing tests before changes.
+- Add characterization tests if risk is high and coverage is weak.
+- Refactor in small steps.
+- Run tests after each meaningful step.
+- Compare user-facing behavior before and after.
+- Avoid unrelated formatting or churn.
+
+## GitHub Actions To Suggest
+
+- Commit after tests pass.
+- Use PR review when refactor touches shared behavior.
+- Mention that behavior should remain unchanged in PR or release notes.
+
+## Release Path
+
+1. Confirm baseline.
+2. Refactor safely.
+3. Verify no behavior change.
+4. Prepare future-change guide.
+5. Ask approval for GitHub operations.
+
+## Final Handoff Shape
+
+```md
+Current team:
+Refactor scope:
+Behavior preserved:
+Evidence/artifacts:
+Checks run:
+Files changed:
+Residual risk:
+Next recommended action:
+Permission needed:
+```
+

package/ai-orchestration-ecosystem/examples/bugfix-production-release.md

@@ -0,0 +1,90 @@
+# Example: Production Bugfix To Release
+
+## User Prompt
+
+```text
+Sagaz: fix this production bug, test it, and prepare a GitHub release.
+
+Bug:
+Users cannot complete checkout when discount code is empty.
+```
+
+## Selected Workflow
+
+`workflows/bugfix-to-release.md`
+
+## Required Squads
+
+- `squads/code-audit.md`
+- `squads/production-critical.md`
+- `squads/github-ops.md`
+
+## First Actions
+
+1. Inspect current git status.
+2. Reproduce or characterize the bug.
+3. Identify scope and likely affected files.
+4. Create or update run state if the fix is multi-step or production critical.
+5. Ask before changing code if the reproduction path is unclear.
+
+## Stack Recommendation
+
+Use the existing project stack. Do not introduce new dependencies unless the bug cannot be fixed safely without them.
+
+## Handoff Sequence
+
+| Phase | From | To | Evidence |
+| --- | --- | --- | --- |
+| Triage | code-audit | production-critical | reproduction, root cause, affected files |
+| Fix | production-critical | production-critical | minimal patch, regression test |
+| Verification | production-critical | github-ops | test output, risk notes, release recommendation |
+| Release | github-ops | complete | commit, push, tag or release only after approval |
+
+## Expected Artifacts
+
+- Reproduction notes.
+- Root cause summary.
+- Minimal code diff.
+- Regression test or manual verification evidence.
+- `templates/qa-report.md`.
+- `templates/release-notes.md` when a release is prepared.
+
+## Verification Plan
+
+- Test the failing path before and after the fix.
+- Add regression coverage when feasible.
+- Run the smallest relevant test suite first.
+- Run broader checks when checkout, auth, payment, or data integrity may be affected.
+- Smoke test release candidate.
+
+## GitHub Actions To Suggest
+
+- Commit after verification.
+- Push after approval.
+- Create a GitHub release only when the fix is ready for users.
+- Include risk and rollback notes in release notes.
+
+## Release Path
+
+1. Confirm fix scope.
+2. Run checks.
+3. Prepare release notes.
+4. Ask approval for commit and push.
+5. Ask approval for tag or GitHub release.
+6. Monitor post-release if production risk is meaningful.
+
+## Final Handoff Shape
+
+```md
+Current team:
+Bug:
+Root cause:
+Fix:
+Evidence/artifacts:
+Checks run:
+Release status:
+Rollback:
+Residual risk:
+Permission needed:
+```
+

package/ai-orchestration-ecosystem/examples/mobile-habit-tracker.md

@@ -0,0 +1,111 @@
+# Example: Mobile Habit Tracker
+
+## User Prompt
+
+```text
+Sagaz: create an Android/iOS habit tracker with premium UX and store-ready release planning.
+
+Requirements:
+- daily habits
+- streaks
+- reminders
+- offline support
+- clean design
+- future account sync
+```
+
+## Selected Workflow
+
+`workflows/mobile-app-production.md`
+
+## Required Squads
+
+- `squads/mobile-app-studio.md`
+- `squads/design-studio.md`
+- `squads/production-critical.md`
+- `squads/github-ops.md`
+
+## First Actions
+
+1. Clarify offline-first expectations, reminder behavior, sync timing, and target stores.
+2. Create or update run state from `templates/run-state.md`.
+3. Use `tasks/intake-brief.md`.
+4. Use `tasks/product-requirements.md`.
+5. Use `tasks/stack-recommendation.md`.
+6. Ask before installing mobile dependencies or configuring account-linked services.
+
+## Stack Recommendation
+
+Default recommendation:
+
+- Expo.
+- React Native.
+- TypeScript.
+- Local SQLite or AsyncStorage for offline habits.
+- Supabase later if account sync becomes required.
+- EAS Build when store distribution is needed.
+
+Decision points:
+
+- Use local-first storage for simple private habits.
+- Use Supabase when cross-device sync or user accounts become required.
+- Use native modules only when Expo support is not enough.
+
+## Handoff Sequence
+
+| Phase | From | To | Evidence |
+| --- | --- | --- | --- |
+| Intake | mobile-app-studio | design-studio | platform targets, offline rules, notification rules |
+| UX | design-studio | mobile-app-studio | screen map, states, design system, accessibility notes |
+| Build | mobile-app-studio | production-critical | implementation evidence, device checks |
+| Release | production-critical | github-ops | store checklist, QA report, release notes |
+
+## Expected Artifacts
+
+- `templates/product-spec.md`.
+- `templates/stack-recommendation.md`.
+- `templates/design-system-spec.md`.
+- `templates/mobile-release-checklist.md`.
+- `templates/qa-report.md`.
+- `templates/future-change-guide.md`.
+- `templates/final-handoff.md`.
+
+## Verification Plan
+
+- Typecheck and lint.
+- Unit tests for habit streak logic.
+- Manual simulator checks on small and large screens.
+- Offline behavior check.
+- Notification permission and fallback check.
+- Accessibility checks for tap targets, contrast, labels, and dynamic text.
+- EAS readiness review before store release.
+
+## GitHub Actions To Suggest
+
+- Commit once local checks pass.
+- Push after mobile release checklist is current.
+- Use GitHub release only when the build is ready for testers or stores.
+
+## Release Path
+
+1. Confirm bundle identifiers and app metadata.
+2. Prepare icon and splash assets.
+3. Configure EAS.
+4. Produce internal build.
+5. Run smoke tests.
+6. Prepare store checklist.
+7. Ask approval before external submission.
+
+## Final Handoff Shape
+
+```md
+Current team:
+What was completed:
+Evidence/artifacts:
+Device checks:
+Release readiness:
+Risks or pending items:
+Next recommended action:
+Permission needed:
+```
+