sinapse-ai 7.7.2 → 7.7.4

package/docs/codex-total-parity-orchestration-plan.md

@@ -0,0 +1,301 @@
+# Codex Total Parity Orchestration Plan
+
+## Mission
+
+Drive SINAPSE-AI in Codex to the closest practical equivalent of the Claude Code experience while preserving:
+
+- the same squad and orqx names
+- the same specialist naming model
+- the same starred command surface
+- the same skills entry points
+- the same workflow/task availability
+- the same MCP-backed capability model where Codex can support it
+
+Hard constraint:
+
+- no regression in `.claude/**`
+- no speculative shared-runtime surgery
+- prefer Codex-only compatibility layers until a shared change is provably required
+
+## Truth Constraint
+
+Exact runtime identity with Claude Code is not mechanically achievable in every area because Codex does not expose the same lifecycle hooks.
+
+The working target is therefore:
+
+- exact naming parity
+- exact command discoverability
+- exact catalog availability
+- exact practical workflow reachability
+- equivalent operator outcomes for normal usage
+- explicit Codex replacements wherever runtime parity is impossible
+
+## Current Baseline
+
+Already in place:
+
+- expanded Codex catalog in `.codex/catalog.json`
+- local-first Codex skill/export path
+- Codex greeting fallback for `sinapse-orqx`
+- validated command/task registry for the core workflow agents
+- Codex-only Imperator tasks for `onboard`, `route`, `plan`, `status`, `brief`, `resolve`, and `council`
+
+Still missing for practical total parity:
+
+- true delegation parity for orqx -> squad -> specialist execution
+- full specialist routing contract across the expanded catalog
+- Codex-ready MCP bootstrap and health verification
+- golden-journey validation for end-to-end operator flows
+- cross-IDE diffing between Codex outputs and Claude reference behavior
+
+## Phases
+
+### Phase 1 - Delegation Matrix Parity
+
+Objective:
+Make `sinapse-orqx` and the squad orqx delegate predictably in Codex using explicit, validator-backed handoff contracts.
+
+Outputs:
+
+- Codex delegation matrix
+- handoff artifact format
+- resolver-backed orqx -> workflow -> specialist routing rules
+- smoke tests for the master workflow agents
+
+Primary owner:
+
+- `@swarm-orqx`
+
+Supporting handoffs:
+
+- `@sinapse-orqx` -> orchestration priorities and final routing policy
+- `@architect` -> Codex-only versus shared-surface boundary
+- `@developer` -> delegation artifacts and resolver/runtime glue
+- `@quality-gate` -> parity and regression review
+
+Exit criteria:
+
+- Codex can route from `sinapse-orqx` to the correct orqx and workflow path without manual file hunting
+- direct specialist routing rules are explicit and validated where supported
+- unsupported delegation paths degrade clearly instead of silently failing
+
+### Phase 2 - Specialist Activation Parity
+
+Objective:
+Close the gap between the expanded `.codex/agents` catalog and the practical activation surface available to Codex operators.
+
+Outputs:
+
+- specialist coverage matrix
+- specialist activation rules by squad
+- explicit fallback policy for specialists without validator-backed execution paths
+
+Primary owner:
+
+- `@architect`
+
+Supporting handoffs:
+
+- `@brand-orqx`, `@content-orqx`, `@copy-orqx`, `@research-orqx`, `@product-orqx`, `@design-orqx`, `@animations-orqx`, `@cyber-orqx`, `@finance-orqx`, `@paidmedia-orqx`, `@growth-orqx`, `@commercial-orqx`, `@courses-orqx`, `@cloning-orqx`, `@storytelling-orqx`, `@council-orqx`, `@claude-orqx`
+
+Exit criteria:
+
+- same orqx names and specialist names are cataloged and callable in Codex
+- each specialist is classified as `validated`, `exploratory`, or `blocked-by-runtime`
+- no hidden source-of-truth split remains between catalog, skills, and routing docs
+
+### Phase 3 - Workflow Chain Parity
+
+Objective:
+Make stories, epics, subtasks, checklists, and quality gates execute in Codex with the same practical chain available in Claude.
+
+Outputs:
+
+- story lifecycle matrix
+- epic workflow matrix
+- subtask and QA handoff rules
+- golden-path walkthroughs for PM -> PO -> SM -> Dev -> QA
+
+Primary owner:
+
+- `@product-orqx`
+
+Supporting handoffs:
+
+- `@project-lead`
+- `@product-lead`
+- `@sprint-lead`
+- `@developer`
+- `@quality-gate`
+
+Exit criteria:
+
+- the core delivery loop is validator-backed end-to-end
+- command mappings and handoff artifacts stay aligned with operator-visible commands
+- no critical workflow step requires guessing repository paths
+
+### Phase 4 - MCP Parity
+
+Objective:
+Make Codex MCP setup reproducible and equivalent enough for normal SINAPSE operation.
+
+Outputs:
+
+- project-level `.mcp.json`
+- Codex bootstrap guide for `sinapse mcp setup` and `sinapse mcp link`
+- minimal/full presets
+- MCP health validator and smoke checks
+
+Primary owner:
+
+- `@claude-orqx`
+
+Supporting handoffs:
+
+- `@devops`
+- `@developer`
+- `@quality-gate`
+
+Exit criteria:
+
+- a clean Codex environment can be bootstrapped repeatably
+- required MCPs are classified as `required`, `recommended`, or `optional`
+- missing MCPs fail loudly with fallback guidance
+
+### Phase 5 - Golden Journey And Diff Parity
+
+Objective:
+Prove parity claims with repeatable, operator-facing journeys and Claude/Codex output comparison.
+
+Outputs:
+
+- golden journeys for activation, routing, planning, delegation, workflow execution, and MCP usage
+- Codex vs Claude comparison rubric
+- release-safe parity checklist
+
+Primary owner:
+
+- `@quality-gate`
+
+Supporting handoffs:
+
+- `@claude-orqx`
+- `@swarm-orqx`
+- `@analyst`
+- `@devops`
+
+Exit criteria:
+
+- Codex parity is measured by outcome, not just by docs or file presence
+- gaps are categorized as `fixed`, `Codex-limited but compensated`, or `still blocked`
+
+## Handoff Matrix
+
+| From | To | Purpose | Artifact |
+|------|----|---------|----------|
+| `@sinapse-orqx` | `@swarm-orqx` | Define delegation topology and handoff protocol | delegation matrix |
+| `@sinapse-orqx` | `@architect` | Approve Codex-only vs shared boundary per phase | boundary decision log |
+| `@sinapse-orqx` | `@claude-orqx` | Map Claude-only runtime behaviors to Codex-compatible replacements | parity gap map |
+| `@sinapse-orqx` | `@product-orqx` | Sequence work into stories, phases, and acceptance criteria | phased delivery plan |
+| `@swarm-orqx` | `@developer` | Implement Codex handoff artifacts, resolvers, and routing helpers | code/doc patches |
+| `@architect` | `@developer` | Keep implementation inside safe surfaces | architecture constraints |
+| `@claude-orqx` | `@developer` | Provide exact naming/behavior parity targets from Claude | reference behavior notes |
+| `@developer` | `@devops` | Add validators, smoke checks, and release-safe guardrails | validation scripts |
+| `@developer` | `@quality-gate` | Request structural and parity review | review findings |
+| `@devops` | `@quality-gate` | Verify CI/release safety of the Codex layer | gate verdict |
+| `@quality-gate` | `@sinapse-orqx` | Approve or bounce the phase based on parity evidence | phase gate decision |
+
+## Lowest-Blast-Radius Sequence
+
+1. Story `7.7.8`: Delegation matrix and handoff artifact contract
+2. Story `7.7.9`: Specialist coverage classification and activation matrix
+3. Story `7.7.10`: Orqx delegation resolver and handoff smoke tests
+4. Story `7.7.11`: MCP bootstrap parity for Codex
+5. Story `7.7.12`: Golden journey suite and Codex-vs-Claude diff rubric
+
+Rationale:
+
+- start with routing contracts before runtime mechanics
+- classify catalog reality before promising specialist parity
+- delay MCP and cross-IDE assertions until the delegation surface is stable
+- preserve the option to stop at a clean Codex-only layer if a shared change becomes too risky
+
+## Handoff Packet Standard
+
+Every execution slice in this plan should move with the same handoff packet so the orqx can delegate consistently in Codex.
+
+Required fields:
+
+1. `mission`
+2. `phase`
+3. `owner`
+4. `inputs`
+5. `outputs`
+6. `validators`
+7. `shared-surface-risk`
+8. `next-handoff`
+
+This keeps delegation explicit, reviewable, and validator-friendly even where Codex lacks Claude-style lifecycle hooks.
+
+## Risks And Mitigations
+
+### Risk 1 - Shared Runtime Pressure
+
+Risk:
+Pursuing exact parity may tempt changes in `.sinapse-ai/development/**` or `.claude/**` before the Codex-only layer is exhausted.
+
+Mitigation:
+
+- require an explicit "Codex-only path exhausted" note before any shared change
+- force Review A + Review B before touching shared surfaces
+
+### Risk 2 - Catalog/Skill Drift
+
+Risk:
+Expanded `.codex/agents`, `.codex/skills`, and command/delegation registries can drift apart.
+
+Mitigation:
+
+- keep one explicit Codex catalog
+- extend validators to cover delegation and specialist classification
+
+### Risk 3 - False Parity Claims
+
+Risk:
+Docs and registry may look complete while real operator journeys still fail.
+
+Mitigation:
+
+- add golden journeys
+- gate claims on smoke tests and comparison rubrics, not only on file existence
+
+### Risk 4 - MCP Fragility
+
+Risk:
+Codex parity may remain partial if MCP bootstrap is manual or inconsistent.
+
+Mitigation:
+
+- define required MCP presets
+- validate health at the project level and in user guidance
+
+### Risk 5 - Story Tracking Drift
+
+Risk:
+`docs/stories/` is currently git-ignored, which weakens long-term traceability of story artifacts.
+
+Mitigation:
+
+- keep the tracked plan in `docs/`
+- treat the story file as workspace process support until story tracking policy is revisited
+
+## Done Condition
+
+This initiative is only "100% pronto" for practical Codex use when all of the following are true:
+
+- all required orqx names, aliases, and skills are available in Codex
+- the master workflow agents resolve commands deterministically
+- orqx -> squad -> specialist handoffs are explicit and validated where supported
+- MCP bootstrap is reproducible
+- golden journeys pass
+- remaining gaps are only true Codex platform limits with explicit compensating behavior

package/docs/codex-workflow-task-parity.md

@@ -0,0 +1,87 @@
+# Codex Workflow And Task Parity
+
+## Goal
+
+Make the core SINAPSE workflow commands in Codex resolve to concrete repository artifacts without manual file hunting.
+
+## Command Registry
+
+The Codex workflow bridge now lives in:
+
+- `.codex/command-registry.json`
+
+This registry is the Codex-only contract for the critical workflow path:
+
+- `sinapse-orqx`
+- `sinapse-pm`
+- `sinapse-po`
+- `sinapse-sm`
+- `sinapse-dev`
+- `sinapse-qa`
+
+For each agent, it maps:
+
+- command
+- command aliases
+- target task or Codex-only task
+- supporting resources
+- source reference used for parity
+
+## Resolver
+
+Use the resolver to inspect a command before executing it:
+
+```bash
+node .codex/scripts/resolve-codex-command.js sinapse-dev develop
+node .codex/scripts/resolve-codex-command.js sinapse-sm draft --json
+node .codex/scripts/resolve-codex-command.js sinapse-orqx onboard
+```
+
+This is especially useful in Codex when a command exists in the agent persona but the execution path is spread across tasks, checklists, templates, and workflows.
+
+## Covered Flow
+
+Critical workflow coverage now includes:
+
+- Imperator: `onboard`, `route`, `plan`, `status`, `brief`, `resolve`, `council`
+- PM: `create-prd`, `create-brownfield-prd`, `create-epic`, `create-story`, `research`, `execute-epic`, `gather-requirements`, `write-spec`, `shard-prd`
+- PO: `validate-story`, `validate-story-draft`, `backlog-review`, `backlog-prioritize`, `backlog-schedule`, `close-story`, `execute-checklist-po`, `sync-story`, `pull-story`, `stories-index`
+- SM: `draft`, `story-checklist`
+- Developer: `develop`, `run-tests`, `apply-qa-fixes`, `execute-subtask`, `verify-subtask`, `backlog-debt`, build commands
+- QA: `review`/`review-story`/`code-review`, `gate`, `review-build`, `create-fix-request`, `test-design`, `run-tests`, `nfr-assess`, `validate-libraries`, `security-check`, `validate-migrations`, `evidence-check`, `false-positive-check`, `console-check`
+
+## Validation
+
+The registry is enforced by:
+
+- `npm run validate:codex-commands`
+- `npm run validate:codex-sync`
+
+The validator checks that:
+
+- the registry exists and parses
+- each mapped agent points to a real Codex skill
+- each mapped target exists
+- each declared resource exists
+- the critical workflow agents keep their minimum required command coverage
+- agent aliases and in-agent command aliases do not collide
+
+## Imperator Tasks
+
+Because the shared `sinapse-orqx` runtime is still partially broken upstream, Codex now has explicit local tasks for:
+
+- `.codex/tasks/onboard-sinapse-codex.md`
+- `.codex/tasks/route-sinapse-request.md`
+- `.codex/tasks/plan-sinapse-initiative.md`
+- `.codex/tasks/status-sinapse-capabilities.md`
+- `.codex/tasks/create-sinapse-strategic-brief.md`
+- `.codex/tasks/resolve-sinapse-conflict.md`
+- `.codex/tasks/convene-sinapse-council.md`
+
+These keep the workflow Codex-only and avoid risky shared-runtime edits.
+
+## Current Limit
+
+This layer solves deterministic command discovery and routing for the critical workflow path.
+It does not yet provide full specialist coverage across all 178 agents, and it does not replace MCP parity.
+Direct specialist routing from `.codex/agents` should still be treated as exploratory unless the path is covered by the command registry and its validators.

package/docs/collaboration-autonomy-plan.md

@@ -0,0 +1,243 @@
+# SINAPSE Collaboration Autonomy Plan
+
+**Date:** 2026-04-02
+**Author:** @sinapse-orqx
+**Status:** Approved with scope reduction
+**Decision Type:** Orchestration plan
+
+---
+
+## Executive Decision
+
+The previous "safe collaboration" suggestions should be **partially approved**, not adopted wholesale.
+
+### Approved now
+
+- Standardize how Caio and Soier work in parallel inside the same repository
+- Create a clear contributor operating model for framework changes
+- Define which changes Soier can make autonomously without waiting for Caio
+- Reuse the existing SINAPSE infrastructure already present in the repository
+
+### Not approved now
+
+- Turning `safe-collab` into a universal template product for all repositories
+- Investing first in cross-platform bootstrap polish for the template
+- Building a dedicated test suite for the reusable template before the internal workflow is stable
+- Enabling automation flags that are not yet proven in the current operating model
+
+---
+
+## Critical Assessment
+
+The core need is **not only Git safety**.
+
+The real requirement is:
+
+1. Caio and Soier must be able to work in sync without overwriting each other.
+2. Soier must be able to add framework features without depending on Caio to explain where things go or how to wire them in.
+
+The repository already contains strong building blocks for this:
+
+- Safe collaboration rule: `.claude/rules/safe-collaboration.md`
+- Reusable safe-collab template: `.sinapse-ai/infrastructure/templates/safe-collab/`
+- Human parallel guide: `docs/guides/parallel-workflow.md`
+- Worktree isolation: `.sinapse-ai/infrastructure/scripts/worktree-manager.js`
+- Component creation scaffolding: `.sinapse-ai/core/docs/component-creation-guide.md`
+- Source tree standard: `docs/framework/source-tree.md`
+- Contributor mode already enabled: `.sinapse-ai/core-config.yaml` with `boundary.frameworkProtection: false`
+
+This means the framework is **not missing raw capability**.
+
+What is missing is a **single operating model** that tells a collaborator:
+
+- where they can move fast alone
+- when they must coordinate
+- which commands and sync steps are mandatory
+- how to hand work off safely
+
+---
+
+## Why Scope Reduction Is Correct
+
+If the team prioritizes generic template hardening first, it will improve portability but **not solve the immediate bottleneck**: Soier still may not know when a framework change is autonomous, coordinated, or blocked.
+
+If the team prioritizes contributor autonomy first, the outcome is immediately useful inside the active repository and can later be extracted into a stronger reusable template.
+
+Therefore the correct order is:
+
+1. Fix the operating model inside `sinapse-ai`
+2. Prove it with Caio + Soier
+3. Only then generalize it into the reusable template
+
+---
+
+## Real Gaps To Solve
+
+### Gap 1: Divergent branch strategy
+
+There are two branch models in the repository context:
+
+- Safe collaboration rule suggests human prefixes like `caio/feat/...` and `soier/fix/...`
+- Worktree infrastructure currently creates `auto-claude/{storyId}`
+
+This divergence creates ambiguity and weakens adoption.
+
+### Gap 2: Contributor autonomy is implicit, not explicit
+
+The repo has generators, tasks, workflows, and standards, but there is no short operational guide saying:
+
+- "Soier can do these classes of framework changes alone"
+- "These paths require coordination first"
+- "After this type of change, run these sync commands"
+
+### Gap 3: Current session behavior does not match the intended safe model
+
+The current repository state is still on `main` with local modifications, which shows the desired collaboration protocol is not yet the lived default.
+
+### Gap 4: Reviewer automation exists in principle, but not in default config
+
+Reviewer auto-assignment is documented, but `auto_assign_reviewers` is still `false` in the current config.
+
+---
+
+## Orchestration Objective
+
+Create a **framework contributor mode** for Caio and Soier with these outcomes:
+
+- Soier can add supported framework features end-to-end without waiting for Caio
+- Git collisions are minimized by isolation plus coordination rules
+- Core-risk edits are routed through a tighter review path
+- Sync steps are deterministic for agent, workflow, template, and manifest changes
+
+---
+
+## Orchestration Plan
+
+## Phase 1: Normalize the collaboration operating model
+
+**Lead:** @sinapse-orqx
+**Execution:** @architect + @developer + @devops
+**Goal:** define a single way of working for framework contributors
+
+### Deliverables
+
+- A contributor guide specific to framework work
+- Explicit change lanes: autonomous, coordinated, protected
+- A temporary rule for resolving the current branch/worktree strategy mismatch
+- A mandatory sync matrix for common change types
+
+### Exit Criteria
+
+- Caio and Soier can classify any proposed change in under 1 minute
+- Both know whether they can proceed alone or need coordination
+- No feature work starts directly on `main`
+
+---
+
+## Phase 2: Establish self-service feature lanes
+
+**Lead:** @architect
+**Execution:** @developer + @quality-gate
+**Goal:** make supported framework changes easy to add without tribal knowledge
+
+### Autonomous Lane
+
+Changes Soier should be able to make without waiting for Caio, as long as the story and quality gates are respected:
+
+- new or updated agent definitions
+- new or updated tasks
+- new or updated workflows
+- new or updated templates and checklists
+- documentation for supported framework capabilities
+- squad-level extensions that use existing conventions
+
+### Coordinated Lane
+
+Changes that should require alignment before implementation:
+
+- `.sinapse-ai/core/**`
+- `.sinapse-ai/infrastructure/**`
+- `bin/**`
+- `.sinapse-ai/constitution.md`
+- package/release/versioning behavior
+- hook behavior and Git enforcement logic
+
+### Protected Lane
+
+Changes that should stay under explicit authority:
+
+- remote push and PR merge authority
+- branch protection and release flow
+- destructive Git operations
+
+### Exit Criteria
+
+- Soier can add a framework feature from story to PR inside the Autonomous Lane without asking where things belong
+- Coordinated Lane is clearly documented and followed
+
+---
+
+## Phase 3: Harden only the pieces that unblock the team
+
+**Lead:** @devops
+**Execution:** @developer + @quality-gate
+**Goal:** implement only the automation hardening that materially reduces team friction now
+
+### Recommended hardening now
+
+- enforce "no work on main" as team habit and documented rule
+- make reviewer routing explicit for Caio/Soier handoff
+- standardize when to use worktrees versus plain feature branches
+- ensure manifest and sync steps are part of the contribution workflow
+
+### Hardening to defer
+
+- full productization of the safe-collab template
+- universal GitHub ruleset automation
+- template-specific automated test suite
+- broader cross-project portability work
+
+### Exit Criteria
+
+- daily collaboration no longer depends on ad hoc verbal coordination
+- PR handoff between Caio and Soier is predictable
+- no accidental drift in agent/config sync for framework changes
+
+---
+
+## Proposed Routing
+
+### Strategic routing
+
+- `@sinapse-orqx`: orchestration, policy, lane design
+- `@architect`: define change boundaries and supported extension surfaces
+- `@developer`: implement contributor docs and any supporting workflow changes
+- `@quality-gate`: validate that the operating model is enforceable and testable
+- `@devops`: own reviewer routing, branch/PR discipline, and release-safe collaboration
+
+---
+
+## Success Metrics
+
+- Soier can independently ship a framework feature inside the Autonomous Lane
+- Fewer edits start on `main`
+- Fewer handoffs depend on Caio explaining structure manually
+- Reduced accidental omissions in `sync:ide`, skills sync, and manifest updates
+- PR review becomes the coordination point instead of synchronous chat
+
+---
+
+## Immediate Recommendation
+
+Approve the initiative, but with this narrowed scope:
+
+**Do not start by polishing the generic safe-collab template.**
+
+Start by formalizing the contributor operating model inside `sinapse-ai`, because that is the shortest path to real autonomy for Soier and safe parallel optimization for both of you.
+
+---
+
+## Next Artifacts
+
+- `docs/guides/framework-contributor-mode.md`
+- optional follow-up story to operationalize the highest-value automation gaps after the guide is proven in use