sagaz-ai 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## [0.2.0] - 2026-06-08
+
+### Release Type
+
+Minor
+
+### Added
+
+- Formal workflow contracts and handoff validation across Sagaz workflows.
+- Stronger durable workflow state contract and run-state template.
+- Task-first contracts for reusable Sagaz task definitions.
+- Internal ecosystem manifest and dependency graph validation.
+- Component governance protocol for creating, updating, renaming, deprecating, and removing ecosystem components.
+- Stronger Sagaz evaluation suite with scenario IDs, required evidence, scoring, and release gates.
+- Release/versioning gate for version bumps, tags, GitHub releases, and npm publishes.
+- GitHub Actions enforcement across Linux, Windows, and macOS package checks.
+- Formal changelog and release notes templates.
+- Installed skill synchronization protocol and `npx sagaz-ai sync` command.
+
+### Changed
+
+- `npm test` now validates workflow contracts, task contracts, manifest coverage, dependency graph integrity, release gates, GitHub Actions enforcement, evaluation coverage, and release artifact templates.
+- `npx sagaz-ai doctor` now checks whether the installed Codex Desktop skill is synchronized with the source skill.
+- README and install documentation now include system requirements, Node.js guidance, platform notes, and skill sync instructions.
+- Package release policy now requires manifest validation, dependency graph validation, evaluation evidence, changelog or release notes, and installed skill sync evidence.
+
+### Fixed
+
+- Corrected malformed Markdown code fences in several protocol files.
+- Added missing references so critical protocols remain reachable from the dependency graph.
+
+### Removed
+
+- None.
+
+### Security
+
+- Release and GitHub operations now require clearer approval gates before publishing, tagging, pushing, or releasing.
+
+### Compatibility
+
+- Windows: supported through Codex Desktop and validated by GitHub Actions on `windows-latest`.
+- macOS: supported through Codex Desktop and validated by GitHub Actions on `macos-latest`.
+- Node.js: package baseline remains `>=22.14`; GitHub Actions use Node.js 24.
+- Codex Desktop: Sagaz remains a Codex Desktop skill, not a standalone terminal agent runtime.
+
+### Migration Notes
+
+- Existing users should run `npx sagaz-ai sync` or `npx sagaz-ai install --force` 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.
+- Evaluation scenarios: covered by the strengthened `evals/sagaz-evaluation-suite.md` contract.
+
+### Release Evidence
+
+- Commit: pending.
+- Tag: pending.
+- GitHub release: pending.
+- npm package: pending.
+

package/INSTALL.md

@@ -72,6 +72,7 @@ Sagaz: explain the available workflows.
 ```powershell
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 npx sagaz-ai install --force
 ```
 
@@ -80,9 +81,30 @@ npx sagaz-ai install --force
 ```bash
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 npx sagaz-ai install --force
 ```
 
+## Sync The Installed Skill
+
+When this repository changes, refresh the installed Codex Desktop skill before relying on new Sagaz behavior.
+
+Windows PowerShell:
+
+```powershell
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+macOS Terminal:
+
+```bash
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+Then open a new Codex Desktop thread so the updated skill is discovered.
+
 ## Manual Install
 
 Copy the Sagaz skill folder from the repository.
@@ -127,6 +149,20 @@ Keep this repository available to Codex. Then, inside the project you want to wo
 Sagaz: use the appropriate workflow for this project. Maintain run state, handoffs, and verification evidence.
 ```
 
+For a hand-built static site, Sagaz should use clean URLs by default:
+
+```text
+/blog/post-slug/
+```
+
+with files laid out as:
+
+```text
+blog/post-slug/index.html
+```
+
+When GitHub Pages is the target, Sagaz should also prepare `CNAME`, `.nojekyll`, `404.html`, `robots.txt`, `sitemap.xml`, canonical URLs, social metadata, and Schema.org JSON-LD before recommending publication.
+
 ## GitHub Ops
 
 ### Windows PowerShell

package/README.md

@@ -40,8 +40,10 @@ Sagaz also guides the user through the process. At the end of each phase, it exp
 - **Durable checkpoints:** long projects can resume across threads and refactors without losing context.
 - **Tool registry:** Sagaz verifies and recommends tools such as GitHub CLI, Playwright, Vercel, Expo/EAS, Supabase, Firebase, Stripe, CI/CD, and observability services.
 - **Stack presets:** common web, mobile, backend, database, and dashboard stacks are documented as starting points.
+- **Static site discipline:** hand-built static sites use clean directory URLs by default, GitHub Pages-ready files, and a practical SEO baseline.
 - **Sagaz evaluations:** scenario-based checks help prevent regressions in the orchestration system itself.
 - **Compatibility audits:** Sagaz can check whether Windows, macOS, npm, Node.js, Codex Desktop, AI model behavior, GitHub, package contents, or external platform changes require a Sagaz update.
+- **Future-change safety:** generated projects include detailed documentation for future refactors, improvements, feature additions, design consistency, UX preservation, invariants, and regression checks.
 
 ## How It Works
 
@@ -74,6 +76,37 @@ Key areas:
 - `brownfield-refactor-safe`: refactor an existing project safely.
 - `bugfix-to-release`: fix a bug through verification and release.
 
+## System Requirements
+
+Install these before using Sagaz:
+
+- **Codex Desktop:** required. Sagaz is designed to run as a Codex Desktop skill, not as a standalone terminal agent.
+- **Node.js and npm:** required for the recommended `npx sagaz-ai install` flow. Use Node.js `22.14+` at minimum; Node.js `24 LTS` is preferred for new installations.
+- **Git:** recommended for cloning this repository, inspecting changes, and using Sagaz GitHub workflows.
+- **Operating system:** Windows or macOS with access to the local Codex skills folder.
+
+Optional but recommended for common Sagaz workflows:
+
+- **GitHub CLI (`gh`):** needed for guided GitHub operations such as authentication, pull requests, checks, issues, releases, and repository automation.
+- **Project runtime tools:** install the tools required by the project Sagaz will work on, such as `pnpm`, `yarn`, `bun`, Python, Java, Android Studio, Xcode, Expo/EAS, or database CLIs when that project needs them.
+- **Browser or web testing tools:** useful for visual QA, Playwright flows, accessibility checks, and local web app verification.
+- **Design/tool connectors:** optional connectors such as Figma MCP can be used when available for app-like mockups, design systems, and visual QA.
+
+Verify the core local tools:
+
+```bash
+node --version
+npm --version
+git --version
+```
+
+Verify GitHub CLI only if you want GitHub Ops:
+
+```bash
+gh --version
+gh auth status
+```
+
 ## Installation In Codex Desktop
 
 ### Recommended: Install With npx
@@ -104,6 +137,7 @@ Check installation:
 ```powershell
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 ```
 
 #### macOS Terminal
@@ -123,8 +157,11 @@ Check installation:
 ```bash
 npx sagaz-ai status
 npx sagaz-ai doctor
+npx sagaz-ai sync
 ```
 
+Use `npx sagaz-ai sync` after updating this repository or package to refresh the installed Codex Desktop skill. Then open a new Codex Desktop thread so Sagaz is rediscovered.
+
 Then open a new Codex Desktop thread and run:
 
 ```text
@@ -205,9 +242,11 @@ Sagaz should choose the appropriate workflow, create or update persistent run st
 
 For production-grade work, Sagaz can also apply 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 protocols.
 
+For medium, large, production, web, mobile, refactor, or feature-extension work, Sagaz should create or update a future-change guide covering product intent, architecture, design system, UX rules, components, invariants, testing, safe refactor procedure, safe feature-addition procedure, deployment, and known risks.
+
 For tool-heavy work, Sagaz uses a tool registry to verify local availability and recommend the right connector or platform before asking permission to install, authenticate, deploy, publish, or modify external resources.
 
-For common project types, Sagaz can start from documented stack presets such as Next.js on Vercel, React with Vite, Expo mobile, React Native, Supabase, Firebase, Node APIs, static sites, and admin dashboards.
+For common project types, Sagaz can start from documented stack presets such as Next.js on Vercel, React with Vite, Expo mobile, React Native, Supabase, Firebase, Node APIs, static sites, and admin dashboards. For hand-built static sites, Sagaz should default to clean URLs through directory `index.html` files and verify SEO essentials including canonical URLs, Open Graph/Twitter metadata, Schema.org JSON-LD, sitemap, robots, optimized images, and GitHub Pages files when applicable.
 
 When asked whether Sagaz needs updates, Sagaz should run a compatibility update audit across Windows, macOS, npm, Node.js, Codex Desktop, current model/tool behavior, GitHub, local installed skill, package contents, documentation, CI/CD, and relevant external platforms before recommending a new version.
 

package/RELEASE_NOTES.md

@@ -0,0 +1,84 @@
+# Release Notes
+
+## Release
+
+Version: 0.2.0
+Date: 2026-06-08
+Release type: Minor
+GitHub commit: pending
+Git tag: pending
+GitHub release: pending
+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.
+
+## Audience Impact
+
+- New users: clearer README, requirements, installation guidance, and sync instructions.
+- 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.
+
+## 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.
+
+## 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.
+
+## Compatibility
+
+- Windows: supported and locally verified.
+- 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.
+- GitHub Actions: package checks run on Ubuntu, Windows, and macOS.
+- npm package: still an installer/distribution package, not a standalone Sagaz runtime.
+
+## Migration Notes
+
+Run:
+
+```bash
+npx sagaz-ai sync
+npx sagaz-ai doctor
+```
+
+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.
+- 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.
+
+## Rollback Plan
+
+- Revert the release commit if the GitHub repository update fails.
+- If published to npm, publish a patch version that restores the previous known-good package contents.
+- Users can reinstall a previous npm version with `npx sagaz-ai@<version> install --force` if needed.
+
+## Release Decision
+
+Approved by: Thiago Cabral
+Approval date: 2026-06-08
+Residual risk: GitHub Actions and npm publishing still need remote execution after push.
+

package/ai-orchestration-ecosystem/INDEX.md

@@ -5,6 +5,7 @@
 - `ACTIVATE.md`: ready-to-use activation prompts.
 - `quickstart.md`: minimum operating rules.
 - `README.md`: ecosystem overview.
+- `manifest.json`: internal component registry for validation and navigation.
 
 ## Core
 
@@ -50,17 +51,27 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 - `protocols/dora-metrics.md`
 - `protocols/secure-sdlc.md`
 - `protocols/dependency-governance.md`
+- `protocols/dependency-graph-validation.md`
 - `protocols/data-privacy-lifecycle.md`
 - `protocols/architecture-fitness-functions.md`
 - `protocols/api-contracts.md`
 - `protocols/performance-budgets.md`
 - `protocols/accessibility-compliance.md`
 - `protocols/database-migrations.md`
+- `protocols/release-versioning-gate.md`
 - `protocols/release-strategy.md`
 - `protocols/ai-application-quality.md`
 - `protocols/agent-observability.md`
+- `protocols/component-governance.md`
+- `protocols/communication.md`
+- `protocols/delegation.md`
 - `protocols/durable-run-state.md`
 - `protocols/compatibility-update-audit.md`
+- `protocols/future-change-safety.md`
+- `protocols/installed-skill-sync.md`
+- `protocols/memory.md`
+- `protocols/model-routing.md`
+- `protocols/post-delivery-monitoring.md`
 
 ## Tools
 
@@ -88,7 +99,7 @@ See `protocols/` for quality gates, testing matrix, stack selection, design qual
 
 ## Templates
 
-See `templates/` for task briefs, product specs, technical specs, design systems, stack recommendations, run state, squad handoffs, QA reports, release checklists, changelogs, release notes, and final handoffs.
+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.
 
 ## Governance
 

package/ai-orchestration-ecosystem/README.md

@@ -12,6 +12,7 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 
 ## Structure
 
+- `manifest.json`: internal component registry used to validate and navigate the ecosystem.
 - `workflows/`: named end-to-end flows.
 - `squads/`: specialized teams.
 - `agents/`: role definitions.
@@ -25,6 +26,14 @@ A local AI orchestration ecosystem for Codex, focused on autonomous teams, consi
 
 No delivery is complete without verification evidence proportional to the risk.
 
+## Ecosystem Maintenance
+
+Use `manifest.json` as the component registry and `protocols/component-governance.md` when creating, updating, renaming, deprecating, or removing Sagaz ecosystem components.
+
+Use `protocols/release-versioning-gate.md` before version bumps, Git tags, GitHub releases, or npm publishes. A Sagaz release is not ready until package checks, doctor, manifest coverage, dependency graph validation, relevant evaluation scenarios, and changelog or release notes are complete.
+
+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.
+
 ## 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/agents/ui-systems-designer.md

@@ -9,6 +9,8 @@ Create design systems, tokens, components, and consistent visual rules.
 - Define colors, typography, spacing, radii, borders, elevation, icons, and motion.
 - Create base components and variants.
 - Standardize forms, feedback, cards, tables, navigation, and modals.
+- When Figma MCP is available, create implementation-ready Figma components, variants, tokens, and screen frames for the mockup.
+- Ensure Figma components map cleanly to the chosen frontend stack, component library, or internal design system.
 
 ## Standard Output
 
@@ -16,5 +18,6 @@ Create design systems, tokens, components, and consistent visual rules.
 - Component inventory
 - Responsive rules
 - Component states
+- Figma component and frame plan when applicable
 - Consistency checklist
 

package/ai-orchestration-ecosystem/agents/ux-architect.md

@@ -10,6 +10,8 @@ Design flows, journeys, information architecture, and interactions that reduce f
 - Map happy paths, errors, and empty states.
 - Organize navigation and information hierarchy.
 - Set usability criteria.
+- When Figma MCP is available, define navigable mockup flows that behave like the intended application.
+- Specify interaction states, transitions, and screen-to-screen behavior clearly enough for implementation.
 
 ## Standard Output
 
@@ -17,5 +19,6 @@ Design flows, journeys, information architecture, and interactions that reduce f
 - Navigation map
 - Screen states
 - Interaction requirements
+- Figma mockup flow requirements when applicable
 - Usability criteria
 

package/ai-orchestration-ecosystem/agents/visual-qa.md

@@ -10,10 +10,13 @@ Validate interfaces visually before delivery and block layout, hierarchy, respon
 - Find overlap, overflow, misalignment, clipping, and weak contrast.
 - Validate interactive states.
 - Compare implementation against the design system.
+- When Figma MCP was used, inspect Figma frames or screenshots before handoff and verify that the mockup supports the intended user journeys.
+- Confirm that the mockup includes realistic states and does not create impossible implementation expectations.
 
 ## Standard Output
 
 - Viewports tested
+- Figma frames or screenshots reviewed when applicable
 - Issues found
 - Recommended fixes
 - Verdict