trackops 2.1.0 → 2.2.0

package/scripts/validate-skill.js

@@ -1,103 +1,188 @@
-#!/usr/bin/env node
-
-const fs = require("fs");
-const path = require("path");
-
-const ROOT = path.resolve(__dirname, "..");
-const PACKAGE_FILE = path.join(ROOT, "package.json");
-const SKILL_DIR = path.join(ROOT, "skills", "trackops");
-const SKILL_FILE = path.join(SKILL_DIR, "skill.json");
-const REQUIRED_FILES = [
-  path.join(SKILL_DIR, "SKILL.md"),
-  path.join(SKILL_DIR, "skill.json"),
-  path.join(SKILL_DIR, "references", "activation.md"),
-  path.join(SKILL_DIR, "references", "workflow.md"),
-  path.join(SKILL_DIR, "references", "troubleshooting.md"),
-];
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
-
-function main() {
-  const pkg = JSON.parse(fs.readFileSync(PACKAGE_FILE, "utf8"));
-  const skill = JSON.parse(fs.readFileSync(SKILL_FILE, "utf8"));
-  const skillMd = fs.readFileSync(path.join(SKILL_DIR, "SKILL.md"), "utf8");
-
-  for (const file of REQUIRED_FILES) {
-    if (!fs.existsSync(file)) {
-      fail(`Missing required skill file: ${path.relative(ROOT, file)}`);
-    }
-  }
-
-  if (!Array.isArray(pkg.files) || !pkg.files.includes("skills/")) {
-    fail("package.json must publish the skills/ directory.");
-  }
-
-  if (skill.name !== "trackops") {
-    fail("skills/trackops/skill.json must declare name 'trackops'.");
-  }
-
-  if (skill.skillVersion !== pkg.version || skill.trackopsVersion !== pkg.version) {
-    fail(`skills/trackops/skill.json must be synced to package version ${pkg.version}.`);
-  }
-
-  if (skill.npmPackage !== pkg.name) {
-    fail(`skills/trackops/skill.json must target npm package '${pkg.name}'.`);
-  }
-
-  if (skill.bootstrapPolicy !== "explicit_install") {
-    fail("skills/trackops/skill.json must use bootstrapPolicy 'explicit_install'.");
-  }
-
-  const supportedAgents = Array.isArray(skill.supportedAgentsV1) ? skill.supportedAgentsV1 : [];
-  for (const agent of ["antigravity", "claude-code", "codex", "cursor", "gemini-cli", "github-copilot", "kiro-cli"]) {
-    if (!supportedAgents.includes(agent)) {
-      fail(`skills/trackops/skill.json must include supported agent '${agent}'.`);
-    }
-  }
-
-  if (!skill.distribution || skill.distribution.source !== "Baxahaun/trackops") {
-    fail("skills/trackops/skill.json must declare distribution.source 'Baxahaun/trackops'.");
-  }
-
-  if (skill.distribution.skill !== "trackops") {
-    fail("skills/trackops/skill.json must declare distribution.skill 'trackops'.");
-  }
-
-  if (skill.distribution.fullDepth !== true) {
-    fail("skills/trackops/skill.json must declare distribution.fullDepth true.");
-  }
-
-  for (const requiredPhrase of [
-    "npx skills add Baxahaun/trackops",
-    "npm install -g trackops",
-    "trackops --version",
-    "trackops init",
-    "trackops opera install",
-    "trackops opera bootstrap --resume",
-  ]) {
-    if (!skillMd.includes(requiredPhrase)) {
-      fail(`skills/trackops/SKILL.md must mention '${requiredPhrase}'.`);
-    }
-  }
-
-  for (const forbiddenPhrase of [
-    "node scripts/bootstrap-trackops.js",
-    "ensures the runtime on first use",
-    "asegura el runtime en el primer uso",
-  ]) {
-    if (skillMd.includes(forbiddenPhrase)) {
-      fail(`skills/trackops/SKILL.md must not mention '${forbiddenPhrase}'.`);
-    }
-  }
-
-  if (fs.existsSync(path.join(SKILL_DIR, "scripts", "bootstrap-trackops.js"))) {
-    fail("skills/trackops must not publish scripts/bootstrap-trackops.js.");
-  }
-
-  console.log("skills/trackops validated successfully.");
-}
-
-main();
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const PACKAGE_FILE = path.join(ROOT, "package.json");
+const SKILLS_ROOT = path.join(ROOT, "skills");
+const REQUIRED_AGENTS = ["antigravity", "claude-code", "codex", "cursor", "gemini-cli", "github-copilot", "kiro-cli"];
+const REQUIRED_PUBLIC_SKILLS = ["trackops", "trackops-quality-guard"];
+
+const SKILL_REQUIREMENTS = {
+  trackops: {
+    requiredFiles: [
+      "SKILL.md",
+      "skill.json",
+      "agents/openai.yaml",
+      "references/activation.md",
+      "references/workflow.md",
+      "references/troubleshooting.md",
+      "locales/en/SKILL.md",
+      "locales/en/references/activation.md",
+      "locales/en/references/workflow.md",
+      "locales/en/references/troubleshooting.md",
+    ],
+    requiredPhrases: [
+      "npx skills add Baxahaun/trackops",
+      "npm install -g trackops",
+      "trackops --version",
+      "trackops init",
+      "trackops opera install",
+      "trackops opera bootstrap --resume",
+      "trackops-quality-guard",
+    ],
+    forbiddenPhrases: [
+      "node scripts/bootstrap-trackops.js",
+      "ensures the runtime on first use",
+      "asegura el runtime en el primer uso",
+    ],
+    validate(skill, skillMd, pkg, skillDir) {
+      if (skill.bootstrapPolicy !== "explicit_install") {
+        fail("skills/trackops/skill.json must use bootstrapPolicy 'explicit_install'.");
+      }
+      if (fs.existsSync(path.join(skillDir, "scripts", "bootstrap-trackops.js"))) {
+        fail("skills/trackops must not publish scripts/bootstrap-trackops.js.");
+      }
+      for (const phrase of [
+        "npx skills add Baxahaun/trackops",
+        "npm install -g trackops",
+        "trackops --version",
+      ]) {
+        if (!skillMd.includes(phrase)) {
+          fail(`skills/trackops/SKILL.md must mention '${phrase}'.`);
+        }
+      }
+      if (skill.npmPackage !== pkg.name) {
+        fail(`skills/trackops/skill.json must target npm package '${pkg.name}'.`);
+      }
+    },
+  },
+  "trackops-quality-guard": {
+    requiredFiles: [
+      "SKILL.md",
+      "skill.json",
+      "agents/openai.yaml",
+      "references/commands.md",
+      "references/decision-policy.md",
+      "references/output-format.md",
+      "locales/en/SKILL.md",
+      "locales/en/references/commands.md",
+      "locales/en/references/decision-policy.md",
+      "locales/en/references/output-format.md",
+    ],
+    requiredPhrases: [
+      "trackops quality status",
+      "trackops quality verify",
+      "trackops quality release-readiness",
+      "trackops quality promote-readiness --target production",
+      "Estado actual",
+      "Blockers reales",
+      "Acción siguiente",
+      "Decisión final",
+    ],
+    forbiddenPhrases: [
+      "opera-quality-guard",
+    ],
+  },
+};
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function discoverPublicSkills() {
+  if (!fs.existsSync(SKILLS_ROOT)) return [];
+  return fs.readdirSync(SKILLS_ROOT, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_ROOT, entry.name, "skill.json")))
+    .map((entry) => ({
+      name: entry.name,
+      dir: path.join(SKILLS_ROOT, entry.name),
+      configPath: path.join(SKILLS_ROOT, entry.name, "skill.json"),
+      skillMdPath: path.join(SKILLS_ROOT, entry.name, "SKILL.md"),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function validateCommon(pkg, descriptor, skill, skillMd) {
+  if (!Array.isArray(pkg.files) || !pkg.files.includes("skills/")) {
+    fail("package.json must publish the skills/ directory.");
+  }
+  if (skill.name !== descriptor.name) {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must declare name '${descriptor.name}'.`);
+  }
+  if (skill.skillVersion !== pkg.version || skill.trackopsVersion !== pkg.version) {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must be synced to package version ${pkg.version}.`);
+  }
+  if (skill.npmPackage !== pkg.name) {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must target npm package '${pkg.name}'.`);
+  }
+  if (!skill.distribution || skill.distribution.source !== "Baxahaun/trackops") {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must declare distribution.source 'Baxahaun/trackops'.`);
+  }
+  if (skill.distribution.skill !== descriptor.name) {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must declare distribution.skill '${descriptor.name}'.`);
+  }
+  if (skill.distribution.fullDepth !== true) {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must declare distribution.fullDepth true.`);
+  }
+  const expectedSkillPath = path.relative(ROOT, descriptor.dir).replace(/\\/g, "/");
+  if (skill.repository?.skillPath !== expectedSkillPath) {
+    fail(`${path.relative(ROOT, descriptor.configPath)} must declare repository.skillPath '${expectedSkillPath}'.`);
+  }
+
+  const supportedAgents = Array.isArray(skill.supportedAgentsV1) ? skill.supportedAgentsV1 : [];
+  for (const agent of REQUIRED_AGENTS) {
+    if (!supportedAgents.includes(agent)) {
+      fail(`${path.relative(ROOT, descriptor.configPath)} must include supported agent '${agent}'.`);
+    }
+  }
+
+  const requirements = SKILL_REQUIREMENTS[descriptor.name] || { requiredPhrases: [], forbiddenPhrases: [] };
+  for (const phrase of requirements.requiredPhrases) {
+    if (!skillMd.includes(phrase)) {
+      fail(`${path.relative(ROOT, descriptor.skillMdPath)} must mention '${phrase}'.`);
+    }
+  }
+  for (const phrase of requirements.forbiddenPhrases) {
+    if (skillMd.includes(phrase)) {
+      fail(`${path.relative(ROOT, descriptor.skillMdPath)} must not mention '${phrase}'.`);
+    }
+  }
+}
+
+function main() {
+  const pkg = JSON.parse(fs.readFileSync(PACKAGE_FILE, "utf8"));
+  const skills = discoverPublicSkills();
+  if (!skills.length) {
+    fail("No public skills were found under skills/.");
+  }
+  for (const skillName of REQUIRED_PUBLIC_SKILLS) {
+    if (!skills.some((descriptor) => descriptor.name === skillName)) {
+      fail(`Missing required public skill under skills/: ${skillName}`);
+    }
+  }
+
+  for (const descriptor of skills) {
+    const requirements = SKILL_REQUIREMENTS[descriptor.name] || { requiredFiles: ["SKILL.md", "skill.json"] };
+    for (const relativeFile of requirements.requiredFiles) {
+      const filePath = path.join(descriptor.dir, relativeFile);
+      if (!fs.existsSync(filePath)) {
+        fail(`Missing required skill file: ${path.relative(ROOT, filePath)}`);
+      }
+    }
+
+    const skill = JSON.parse(fs.readFileSync(descriptor.configPath, "utf8"));
+    const skillMd = fs.readFileSync(descriptor.skillMdPath, "utf8");
+    validateCommon(pkg, descriptor, skill, skillMd);
+
+    if (typeof requirements.validate === "function") {
+      requirements.validate(skill, skillMd, pkg, descriptor.dir);
+    }
+
+    console.log(`${path.relative(ROOT, descriptor.dir)} validated successfully.`);
+  }
+}
+
+main();

package/skills/trackops/SKILL.md

@@ -20,11 +20,12 @@ Esta skill es la puerta de entrada al sistema. Úsala cuando alguien:
 
 Esta skill:
 
-- explica qué es TrackOps y cuándo conviene usarlo
-- exige una instalación explícita y visible del runtime
-- guía la activación por repositorio
-- ayuda a decidir si OPERA debe seguir por `direct bootstrap` o por `agent handoff`
-- explica que al instalar OPERA se activa un equipo de agentes coordinados por `opera-skill`
+- explica qué es TrackOps y cuándo conviene usarlo
+- exige una instalación explícita y visible del runtime
+- guía la activación por repositorio
+- ayuda a decidir si OPERA debe seguir por `direct bootstrap` o por `agent handoff`
+- explica que al instalar OPERA se activa un equipo de agentes coordinados por `opera-skill`
+- deriva decisiones de calidad, release y producción hacia `trackops-quality-guard`
 
 ## Que no hace esta skill
 
@@ -115,8 +116,25 @@ trackops opera bootstrap --resume
 - la skill global instala instrucciones en el agente
 - el runtime se instala por separado con npm
 - `trackops init` activa el proyecto
-- `trackops opera install` anade el framework operativo completo solo cuando hace falta
-- TrackOps separa producto y operacion para que el repo no se vuelva caotico
+- `trackops opera install` anade el framework operativo completo solo cuando hace falta
+- TrackOps separa producto y operacion para que el repo no se vuelva caotico
+
+## Cuándo delegar a `trackops-quality-guard`
+
+Si TrackOps ya está activo y el usuario pide:
+
+- una auditoría de calidad del proyecto
+- validar si algo está listo para release
+- validar si algo puede ir a producción
+- revisar blockers antes de entregar
+
+entonces deriva a `trackops-quality-guard`.
+
+Si esa skill no está instalada todavía, la instalación explícita es:
+
+```bash
+npx skills add Baxahaun/trackops --skill trackops-quality-guard --agent "*" --global -y
+```
 
 ## Que referencia leer y cuando
 

package/skills/trackops/locales/en/SKILL.md

@@ -20,11 +20,12 @@ This skill is the entry point to the system. Use it when someone:
 
 This skill:
 
-- explains what TrackOps is and when to use it
-- requires an explicit and visible runtime installation
-- guides per-repository activation
-- helps route OPERA into either `direct bootstrap` or `agent handoff`
-- explains that installing OPERA activates a team of agents coordinated by `opera-skill`
+- explains what TrackOps is and when to use it
+- requires an explicit and visible runtime installation
+- guides per-repository activation
+- helps route OPERA into either `direct bootstrap` or `agent handoff`
+- explains that installing OPERA activates a team of agents coordinated by `opera-skill`
+- routes quality, release, and production decisions to `trackops-quality-guard`
 
 ## What this skill does not do
 
@@ -115,8 +116,25 @@ trackops opera bootstrap --resume
 - the global skill installs instructions into the agent
 - the runtime is installed separately with npm
 - `trackops init` activates the project
-- `trackops opera install` adds the full operating framework only when needed
-- TrackOps separates product and operations so the repository stays manageable
+- `trackops opera install` adds the full operating framework only when needed
+- TrackOps separates product and operations so the repository stays manageable
+
+## When to delegate to `trackops-quality-guard`
+
+If TrackOps is already active and the user asks for:
+
+- a project quality audit
+- a release-readiness decision
+- a production-readiness decision
+- a blocker review before delivery
+
+then delegate to `trackops-quality-guard`.
+
+If that skill is not installed yet, the explicit install is:
+
+```bash
+npx skills add Baxahaun/trackops --skill trackops-quality-guard --agent "*" --global -y
+```
 
 ## Which reference to read and when
 

package/skills/trackops/locales/en/references/activation.md

@@ -27,9 +27,9 @@ trackops init
 trackops opera install
 ```
 
-`trackops opera install` also activates the project agent team:
-- `opera-skill` (coordinator)
-- `project-starter-skill`, `opera-contract-auditor`, `opera-policy-guard`
+`trackops opera install` also activates the project agent team:
+- `opera-skill` (coordinator)
+- `trackops-quality-guard`, `project-starter-skill`, `opera-contract-auditor`, `opera-policy-guard`
 
 By default, `trackops init` creates a split workspace with:
 

package/skills/trackops/locales/en/references/workflow.md

@@ -37,10 +37,11 @@ If OPERA is installed:
 
 When OPERA is installed, a team of specialized agents is activated:
 
-- `opera-skill` — coordinator. Decides phase, state, delegation, and blocking.
-- `project-starter-skill` — discovery and structuring
-- `opera-contract-auditor` — operating contract audit
-- `opera-policy-guard` — risk control
+- `opera-skill` — coordinator. Decides phase, state, delegation, and blocking.
+- `trackops-quality-guard` — quality, verification, and readiness guard
+- `project-starter-skill` — discovery and structuring
+- `opera-contract-auditor` — operating contract audit
+- `opera-policy-guard` — risk control
 
 Additional skills available:
 

package/skills/trackops/references/activation.md

@@ -27,9 +27,9 @@ trackops init
 trackops opera install
 ```
 
-`trackops opera install` también activa el equipo de agentes del proyecto:
-- `opera-skill` (coordinadora)
-- `project-starter-skill`, `opera-contract-auditor`, `opera-policy-guard`
+`trackops opera install` también activa el equipo de agentes del proyecto:
+- `opera-skill` (coordinadora)
+- `trackops-quality-guard`, `project-starter-skill`, `opera-contract-auditor`, `opera-policy-guard`
 
 Por defecto, `trackops init` crea un workspace split con:
 

package/skills/trackops/references/workflow.md

@@ -37,10 +37,11 @@ Si OPERA está instalado:
 
 Cuando OPERA está instalado, se activa un equipo de agentes especializados:
 
-- `opera-skill` — coordinadora. Decide fase, estado, delegación y bloqueo.
-- `project-starter-skill` — descubrimiento y estructuración
-- `opera-contract-auditor` — auditoría del contrato operativo
-- `opera-policy-guard` — control de riesgo
+- `opera-skill` — coordinadora. Decide fase, estado, delegación y bloqueo.
+- `trackops-quality-guard` — guardia de calidad, verificación y readiness
+- `project-starter-skill` — descubrimiento y estructuración
+- `opera-contract-auditor` — auditoría del contrato operativo
+- `opera-policy-guard` — control de riesgo
 
 También se pueden instalar:
 

package/skills/trackops/skill.json

@@ -2,8 +2,8 @@
   "name": "trackops",
   "shortDescription": "Global TrackOps skill that explains TrackOps, requires explicit runtime install, and guides per-repository activation.",
   "description": "Explains what TrackOps does, installs the global skill layer, requires explicit runtime installation with npm, supports Spanish and English, activates TrackOps repository by repository, and routes OPERA onboarding into either direct bootstrap or agent-led discovery.",
-  "skillVersion": "2.1.0",
-  "trackopsVersion": "2.1.0",
+  "skillVersion": "2.2.0",
+  "trackopsVersion": "2.2.0",
   "npmPackage": "trackops",
   "bootstrapPolicy": "explicit_install",
   "supportedAgentsV1": [

package/skills/trackops-quality-guard/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: "trackops-quality-guard"
+description: "Skill pública de TrackOps para inspeccionar calidad, ejecutar verificaciones declaradas y decidir readiness antes de release o recomendaciones de producción."
+metadata:
+  version: "1.0"
+  type: "global"
+  triggers:
+    - "quality"
+    - "calidad"
+    - "auditar"
+    - "auditoría"
+    - "readiness"
+    - "release readiness"
+    - "production readiness"
+    - "verifica calidad"
+---
+
+# TrackOps Quality Guard
+
+Si la conversación y el proyecto deben trabajar en inglés, lee `locales/en/SKILL.md` antes de seguir.
+
+## Misión
+
+Complementar TrackOps con una guardia explícita de calidad y readiness de salida.
+
+## Cuándo usarla
+
+Usa esta skill cuando el usuario:
+
+- pida una auditoría de calidad del proyecto
+- quiera validar si algo está listo para release
+- quiera validar si algo puede ir a producción
+- necesite revisar blockers reales antes de cerrar fase o entregar
+
+## Qué no hace
+
+Esta skill no:
+
+- sustituye al runtime `trackops quality ...`
+- inventa checks o criterios fuera del runtime
+- reinterpretar blockers para hacerlos “más suaves”
+- publica, despliega o aprueba por su cuenta
+
+## Comandos obligatorios
+
+- antes de cerrar una fase o declarar estabilidad, ejecuta `trackops quality status`
+- si la decisión afecta a fase, consulta también `trackops quality phase-readiness`
+- tras cambios relevantes en código, entorno, build o smoke, ejecuta `trackops quality verify`
+- antes de `trackops release`, ejecuta `trackops quality release-readiness`
+- antes de recomendar producción, ejecuta `trackops quality promote-readiness --target production`
+
+## Reglas de decisión
+
+- `phase-readiness` es informativo
+- `release-readiness` decide si se puede liberar
+- `promote-readiness` decide si se puede recomendar producción
+- si el runtime marca bloqueo, no inventes excepciones
+
+## Política de waivers
+
+- solo usa waivers si existe aprobación humana explícita
+- un waiver debe tener caducidad
+- un waiver no borra la evidencia ni convierte un bloqueo en “no pasó nada”
+
+## Salida obligatoria
+
+Responde siempre con este orden exacto:
+
+1. `Estado actual`
+2. `Blockers reales`
+3. `Acción siguiente`
+4. `Decisión final`
+
+## Qué referencia leer y cuándo
+
+- lee `references/commands.md` para decidir qué comando corre en cada momento
+- lee `references/decision-policy.md` para interpretar advisory vs gate duro
+- lee `references/output-format.md` antes de responder si la salida puede afectar una decisión de release o producción

package/skills/trackops-quality-guard/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "TrackOps Quality Guard"
+  short_description: "Inspect quality and decide release readiness"
+  default_prompt: "Use $trackops-quality-guard to inspect TrackOps quality status, run declared verification, and decide release or production readiness without inventing blockers."
+
+policy:
+  allow_implicit_invocation: true

package/skills/trackops-quality-guard/locales/en/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: "trackops-quality-guard"
+description: "Public TrackOps skill for inspecting quality, running declared verification, and deciding readiness before release or production recommendations."
+metadata:
+  version: "1.0"
+  type: "global"
+  triggers:
+    - "quality"
+    - "calidad"
+    - "auditar"
+    - "auditoría"
+    - "readiness"
+    - "release readiness"
+    - "production readiness"
+    - "verifica calidad"
+---
+
+# TrackOps Quality Guard
+
+Use this localized file when the conversation and project should run in English.
+
+## Mission
+
+Complement TrackOps with an explicit quality and production-readiness guard.
+
+## When to use it
+
+Use this skill when the user:
+
+- asks for a project quality audit
+- wants to know whether something is ready for release
+- wants to know whether something can go to production
+- needs a real blocker review before closing a phase or delivering
+
+## What it does not do
+
+This skill does not:
+
+- replace the `trackops quality ...` runtime
+- invent checks or criteria outside the runtime
+- soften blockers to make them look acceptable
+- publish, deploy, or approve by itself
+
+## Mandatory commands
+
+- before closing a phase or declaring stability, run `trackops quality status`
+- if the decision affects a phase, also run `trackops quality phase-readiness`
+- after relevant code, environment, build, or smoke changes, run `trackops quality verify`
+- before `trackops release`, run `trackops quality release-readiness`
+- before recommending production, run `trackops quality promote-readiness --target production`
+
+## Decision rules
+
+- `phase-readiness` is advisory
+- `release-readiness` decides whether release is allowed
+- `promote-readiness` decides whether production can be recommended
+- if the runtime blocks, do not invent exceptions
+
+## Waiver policy
+
+- only use waivers when there is explicit human approval
+- a waiver must have an expiration
+- a waiver does not erase evidence or turn a blocker into “nothing happened”
+
+## Required output
+
+Always answer in this exact order:
+
+1. `Current state`
+2. `Real blockers`
+3. `Next action`
+4. `Final decision`
+
+## Which reference to read and when
+
+- read `locales/en/references/commands.md` to decide which command to run
+- read `locales/en/references/decision-policy.md` to interpret advisory vs hard gate
+- read `locales/en/references/output-format.md` before replying when the answer may affect a release or production decision

package/skills/trackops-quality-guard/locales/en/references/commands.md

@@ -0,0 +1,36 @@
+# Commands
+
+Use the `trackops quality ...` runtime as the single source of truth.
+
+## Execution order
+
+1. If the user wants a status check or phase close review:
+
+   ```bash
+   trackops quality status
+   trackops quality phase-readiness
+   ```
+
+2. If there were relevant code, environment, build, or smoke changes:
+
+   ```bash
+   trackops quality verify --scope all
+   ```
+
+3. If the decision affects release:
+
+   ```bash
+   trackops quality release-readiness
+   ```
+
+4. If the decision affects production:
+
+   ```bash
+   trackops quality promote-readiness --target production
+   ```
+
+## Rules
+
+- do not replace these commands with subjective judgment
+- if the user requests a specific scope, you may run `trackops quality verify --scope <scope>`
+- if the runtime fails, report the failure before drawing conclusions