trackops 1.1.0 → 2.0.1

package/templates/opera/en/agent.md

@@ -1,26 +1,27 @@
 # Project Agent: {{PROJECT_NAME}}
 
-## Identity
-You are the primary agent for **{{PROJECT_NAME}}**. You operate under the O.P.E.R.A. v3.0 protocol.
-
-## Source of Truth
-Your source of truth is `genesis.md`. Before making any architectural or implementation decision, read it first.
-For operational tracking and backlog state, use `project_control.json`.
-
-## Behavior
-- Follow the behavior rules defined in `genesis.md`.
-- Respect the autonomy matrix to determine which actions are allowed.
-- Manage tasks and states from `project_control.json`.
-- Do not edit `task_plan.md`, `progress.md`, or `findings.md` manually; regenerate them with `trackops sync`.
+## Identity
+You are the primary agent for **{{PROJECT_NAME}}**. You operate under the O.P.E.R.A. v3.0 protocol.
+
+## Source of Truth
+Your machine source of truth is `ops/contract/operating-contract.json`.
+Your compiled human view is `ops/genesis.md`.
+For operational tracking and backlog state, use `ops/project_control.json`.
+
+## Behavior
+- Follow the rules defined in `ops/contract/operating-contract.json` and reflected in `ops/genesis.md`.
+- Respect `ops/policy/autonomy.json` to determine which actions are allowed without approval.
+- Manage tasks and states from `ops/project_control.json`.
+- Do not edit `ops/task_plan.md`, `ops/progress.md`, or `ops/findings.md` manually; regenerate them with `trackops sync`.
 
 ## Available Skills
-Check `.agents/skills/_registry.md` to see installed skills.
+Check `ops/.agents/skills/_registry.md` to see installed skills.
 You can also discover new skills with `trackops skill catalog`.
 
-## Work Cycle
-1. Run `trackops status` at the beginning of each work block.
-2. Read `genesis.md` to understand the data and rules.
-3. Use `trackops next` to inspect the prioritized queue.
-4. Before implementing, mark the task with `trackops task start <task-id>`.
-5. Use the router in `.agent/hub/router.md` to choose the right skill.
-6. When you finish, move the task to `review`, `complete`, or `block`, then run `trackops sync`.
+## Work Cycle
+1. Run `trackops status` at the beginning of each work block.
+2. Read `ops/contract/operating-contract.json` and `ops/genesis.md` to understand the contract and its human view.
+3. Use `trackops next` to inspect the prioritized queue.
+4. Before implementing, mark the task with `trackops task start <task-id>`.
+5. Use the router in `ops/.agent/hub/router.md` to choose the right skill.
+6. When you finish, move the task to `review`, `complete`, or `block`, then run `trackops sync`.

package/templates/opera/en/architecture/dependency-graph.md

@@ -0,0 +1,24 @@
+# Dependency Graph
+
+```mermaid
+flowchart TD
+    A[Global runtime bootstrap] --> B[trackops init]
+    B --> C[trackops opera install]
+    C --> D{Routing}
+    D -->|direct_cli| E[Direct intake]
+    D -->|agent_handoff| F[agent-handoff.md/json]
+    F --> G[intake.json + spec-dossier.md]
+    E --> H[quality-report.json]
+    G --> H
+    H --> I[operating-contract.json]
+    I --> J[genesis.md]
+    I --> K[task_plan.md / progress.md / findings.md]
+    I --> L[dashboard + API state]
+    I --> M[env sync + policy enforcement]
+```
+
+## Notes
+
+- `ops/project_control.json` is the operational source of truth for backlog and session state.
+- `ops/contract/operating-contract.json` is the machine contract.
+- `ops/genesis.md` is a compiled human view.

package/templates/opera/en/architecture/runtime-automation.md

@@ -0,0 +1,24 @@
+# SOP - Runtime Automation
+
+## Objective
+
+Keep validation automatic on every relevant change.
+
+## Trigger policy
+
+- Validate on push to `develop` and `master`.
+- Validate on pull requests targeting `develop` or `master`.
+- Allow manual execution with workflow dispatch.
+
+## Validation circuit
+
+1. Install Node 18 and 20.
+2. Install runtime dependencies.
+3. Run `npm run release:check`.
+4. Fail fast on any smoke, skill or packaging regression.
+
+## Release hygiene
+
+- Do not publish if `release:check` fails.
+- Do not treat local runtime state as deployable proof.
+- Re-run smoke after structural or locale changes.

package/templates/opera/en/architecture/runtime-operations.md

@@ -0,0 +1,34 @@
+# SOP - Runtime Operations
+
+## Purpose
+
+Define the minimum operating procedure required to keep a TrackOps + OPERA workspace healthy.
+
+## Inputs
+
+- `ops/project_control.json`
+- `ops/contract/operating-contract.json`
+- `ops/policy/autonomy.json`
+- `ops/bootstrap/quality-report.json`
+
+## Core checks
+
+1. Run `trackops status`.
+2. Run `trackops opera status`.
+3. Run `trackops env status`.
+4. Confirm `contract readiness` is not `hypothesis` for active delivery work.
+5. Confirm `legacyStatus` is `supported`.
+
+## Recovery path
+
+1. If bootstrap is incomplete, run `trackops opera handoff --print`.
+2. If discovery artifacts already exist, run `trackops opera bootstrap --resume`.
+3. If operational docs drift, run `trackops sync`.
+4. If managed artifacts drift, run `trackops opera upgrade --stable`.
+
+## Exit criteria
+
+- Runtime status is readable.
+- OPERA status is readable.
+- Contract and policy files exist.
+- No critical blocker remains undocumented.

package/templates/opera/en/reviews/delivery-audit.md

@@ -0,0 +1,18 @@
+# Delivery Audit
+
+## Scope
+
+Review the final output shape against the active templates and compiled contract.
+
+## Checklist
+
+- `ops/genesis.md` matches the current contract.
+- `ops/task_plan.md`, `ops/progress.md` and `ops/findings.md` are synchronized.
+- Public copy matches runtime behavior.
+- API and dashboard reflect the same operational state.
+- Visual review completed when a UI change exists.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/en/reviews/integration-audit.md

@@ -0,0 +1,18 @@
+# Integration Audit
+
+## Scope
+
+Review credentials, connectivity assumptions and external response shapes before expanding delivery.
+
+## Checklist
+
+- Required keys identified from the contract and environment contract.
+- Missing keys documented without exposing secret values.
+- External services listed in the contract.
+- Response shapes aligned with `ops/contract/operating-contract.json`.
+- Findings recorded in `ops/findings.md` when applicable.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/en/router.md

@@ -15,15 +15,25 @@ This file defines the routing rules between the main agent and the available ski
 - **Skill**: `changelog-updater`
 - **Action**: Run the changelog update flow.
 
-### Context: Project initialization
-- **Trigger**: The user wants to create a new project.
-- **Skill**: `project-starter-skill` (global)
-- **Action**: Run the full initialization protocol.
-
-### Context: Operational tracking
-- **Trigger**: A work block is about to start, resume, or close.
-- **Skill**: No external skill.
-- **Action**: Run `trackops status`, take the next task with `trackops next`, and keep `project_control.json` as the operational source of truth.
+### Context: Agent-led project start
+- **Trigger**: The user has an idea, partial specification, or TrackOps has generated `ops/bootstrap/agent-handoff.md`.
+- **Skill**: `project-starter-skill`
+- **Action**: Turn the user context into `ops/bootstrap/intake.json`, `ops/bootstrap/spec-dossier.md`, and `ops/bootstrap/open-questions.md` when needed.
+
+### Context: Contract audit
+- **Trigger**: `ops/contract/operating-contract.json` or `ops/bootstrap/quality-report.json` exists and there are doubts about gaps or contradictions.
+- **Skill**: `opera-contract-auditor`
+- **Action**: Audit consistency, gaps, and false precision before execution continues.
+
+### Context: Operational risk
+- **Trigger**: The action affects persistent data, deployments, external side effects, or sensitive permissions.
+- **Skill**: `opera-policy-guard`
+- **Action**: Read `ops/policy/autonomy.json` and decide whether explicit approval is required.
+
+### Context: Operational tracking
+- **Trigger**: A work block is about to start, resume, or close.
+- **Skill**: No external skill.
+- **Action**: Run `trackops status`, take the next task with `trackops next`, use `ops/contract/operating-contract.json` as the machine contract, and keep `ops/project_control.json` as the backlog source of truth.
 
 ## Adding New Rules
 

package/templates/opera/reviews/delivery-audit.md

@@ -0,0 +1,18 @@
+# Delivery Audit
+
+## Scope
+
+Review the final output shape against the active templates and compiled contract.
+
+## Checklist
+
+- `ops/genesis.md` matches the current contract.
+- `ops/task_plan.md`, `ops/progress.md` and `ops/findings.md` are synchronized.
+- Public copy matches runtime behavior.
+- API and dashboard reflect the same operational state.
+- Visual review completed when a UI change exists.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/reviews/integration-audit.md

@@ -0,0 +1,18 @@
+# Integration Audit
+
+## Scope
+
+Review credentials, connectivity assumptions and external response shapes before expanding delivery.
+
+## Checklist
+
+- Required keys identified from the contract and environment contract.
+- Missing keys documented without exposing secret values.
+- External services listed in the contract.
+- Response shapes aligned with `ops/contract/operating-contract.json`.
+- Findings recorded in `ops/findings.md` when applicable.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/router.md

@@ -15,15 +15,25 @@ Este archivo define las reglas de enrutamiento entre el agente principal y las s
 - **Skill**: `changelog-updater`
 - **Acción**: Ejecuta el script de actualización del changelog.
 
-### Contexto: Inicialización de proyecto
-- **Trigger**: El usuario quiere crear un nuevo proyecto.
-- **Skill**: `project-starter-skill` (global)
-- **Acción**: Ejecutar el protocolo de inicialización completo.
+### Contexto: Arranque asistido del proyecto
+- **Trigger**: El usuario tiene una idea, una especificación parcial o TrackOps ha generado `ops/bootstrap/agent-handoff.md`.
+- **Skill**: `project-starter-skill`
+- **Acción**: Convertir el contexto del usuario en `ops/bootstrap/intake.json`, `ops/bootstrap/spec-dossier.md` y `ops/bootstrap/open-questions.md` cuando haga falta.
+
+### Contexto: Auditoria del contrato
+- **Trigger**: Existe `ops/contract/operating-contract.json` o `ops/bootstrap/quality-report.json` y hay dudas sobre huecos o contradicciones.
+- **Skill**: `opera-contract-auditor`
+- **Acción**: Auditar consistencia, huecos y pseudoprecision antes de seguir ejecutando.
+
+### Contexto: Riesgo operativo
+- **Trigger**: La accion afecta datos persistentes, despliegues, efectos externos o permisos sensibles.
+- **Skill**: `opera-policy-guard`
+- **Acción**: Consultar `ops/policy/autonomy.json` y decidir si hace falta aprobacion explicita.
 
 ### Contexto: Seguimiento operativo
 - **Trigger**: Se va a empezar, retomar o cerrar un bloque de trabajo.
 - **Skill**: No aplica skill externa.
-- **Acción**: Ejecutar `trackops status`, tomar la siguiente tarea con `trackops next` y mantener `project_control.json` como fuente de verdad operativa.
+- **Acción**: Ejecutar `trackops status`, tomar la siguiente tarea con `trackops next`, usar `ops/contract/operating-contract.json` como contrato de maquina y mantener `ops/project_control.json` como fuente de verdad operativa del backlog.
 
 ## Cómo Añadir Nuevas Reglas
 

package/templates/skills/opera-contract-auditor/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: "opera-contract-auditor"
+description: "Skill para auditar el contrato operativo de OPERA, detectar huecos, contradicciones y pseudoprecision antes de seguir ejecutando."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Contract Auditor
+
+Usa esta skill cuando exista `ops/contract/operating-contract.json` o cuando OPERA haya dejado `ops/bootstrap/quality-report.json`.
+
+## Objetivo
+
+Validar si el contrato operativo ya es suficientemente coherente para pasar de discovery a ejecucion.
+
+## Debes revisar
+
+- `ops/contract/operating-contract.json`
+- `ops/bootstrap/quality-report.json`
+- `ops/bootstrap/open-questions.md`
+- `ops/genesis.md`
+
+## Checklist minimo
+
+- el problema y el usuario objetivo estan definidos
+- el resultado singular deseado es verificable
+- la fuente de verdad esta clara
+- input y output schema no se contradicen
+- no hay reglas de comportamiento ambiguas
+- las integraciones externas son coherentes con el contrato
+- las preguntas abiertas siguen abiertas de forma explicita o estan resueltas
+
+## Salida esperada
+
+- identificar contradicciones o lagunas concretas
+- proponer solo las correcciones necesarias
+- no inventar decisiones de negocio no confirmadas

package/templates/skills/opera-contract-auditor/locales/en/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: "opera-contract-auditor"
+description: "Skill for auditing the OPERA operating contract, spotting gaps, contradictions, and false precision before execution continues."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Contract Auditor
+
+Use this skill when `ops/contract/operating-contract.json` already exists or when OPERA has produced `ops/bootstrap/quality-report.json`.
+
+## Goal
+
+Validate whether the operating contract is coherent enough to move from discovery into execution.
+
+## Review these files
+
+- `ops/contract/operating-contract.json`
+- `ops/bootstrap/quality-report.json`
+- `ops/bootstrap/open-questions.md`
+- `ops/genesis.md`
+
+## Minimum checklist
+
+- the problem and target user are defined
+- the singular desired outcome is verifiable
+- the source of truth is clear
+- input and output schema do not contradict each other
+- behavior rules are not ambiguous
+- external integrations match the contract
+- open questions are either explicitly open or clearly resolved
+
+## Expected output
+
+- identify concrete contradictions or gaps
+- propose only the corrections that are actually needed
+- do not invent unconfirmed business decisions

package/templates/skills/opera-policy-guard/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: "opera-policy-guard"
+description: "Skill para interpretar la politica ejecutable de OPERA y decidir que acciones requieren aprobacion explicita."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Policy Guard
+
+Usa esta skill cuando vayas a ejecutar acciones con riesgo operativo, efectos externos o cambios destructivos.
+
+## Fuente principal
+
+- `ops/policy/autonomy.json`
+
+## Debes responder
+
+- si la accion es verde, amarilla o roja
+- si requiere aprobacion explicita
+- que efecto externo produce
+- que alternativa segura existe si no hay permiso
+
+## Regla
+
+Si la politica deja dudas, no asumas permiso. Marca la accion como bloqueada hasta aclararlo.

package/templates/skills/opera-policy-guard/locales/en/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: "opera-policy-guard"
+description: "Skill for interpreting the OPERA executable policy and deciding which actions require explicit approval."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Policy Guard
+
+Use this skill before actions with operational risk, external side effects, or destructive changes.
+
+## Primary source
+
+- `ops/policy/autonomy.json`
+
+## You must answer
+
+- whether the action is green, yellow, or red
+- whether it requires explicit approval
+- what external side effect it causes
+- what safe alternative exists if approval is missing
+
+## Rule
+
+If the policy is ambiguous, do not assume permission. Mark the action as blocked until it is clarified.