trackops 2.0.6 → 2.1.0

package/bin/trackops.js

@@ -143,22 +143,30 @@ async function run() {
         break;
       }
 
-      case "skill": {
-        const skills = require("../lib/skills");
-        const sub = args[0];
-        const root = config.resolveProjectRoot() || process.cwd();
-        if (sub === "install") skills.cmdInstall(root, args[1]);
-        else if (sub === "list") skills.cmdList(root);
-        else if (sub === "remove") skills.cmdRemove(root, args[1]);
-        else if (sub === "catalog") skills.cmdCatalog();
-        else { console.log(t("cli.usage.skill")); }
-        break;
-      }
-
-      case "version":
-      case "--version":
-      case "-v":
-        console.log(pkg.version);
+      case "skill": {
+        const skills = require("../lib/skills");
+        const sub = args[0];
+        const root = config.resolveProjectRoot() || process.cwd();
+        if (sub === "install") skills.cmdInstall(root, args[1]);
+        else if (sub === "list") skills.cmdList(root);
+        else if (sub === "remove") skills.cmdRemove(root, args[1]);
+        else if (sub === "catalog") skills.cmdCatalog();
+        else { console.log(t("cli.usage.skill")); }
+        break;
+      }
+
+      case "plan":
+        require("../lib/plans").cmdPlan(config.resolveProjectRoot() || process.cwd(), args);
+        break;
+
+      case "quality":
+        require("../lib/quality").cmdQuality(config.resolveProjectRoot() || process.cwd(), args);
+        break;
+
+      case "version":
+      case "--version":
+      case "-v":
+        console.log(pkg.version);
         break;
 
       case "help":

package/lib/config.js

@@ -22,12 +22,27 @@ const DEFAULT_PHASE_LABELS = {
   },
 };
 
-const DEFAULT_LOCALE = "es";
-const WORKSPACE_MANIFEST = ".trackops-workspace.json";
-const DEFAULT_APP_DIR = "app";
-const DEFAULT_OPS_DIR = "ops";
-const DEFAULT_DEV_BRANCH = "develop";
-const DEFAULT_PUBLISH_BRANCH = "master";
+const DEFAULT_LOCALE = "es";
+const WORKSPACE_MANIFEST = ".trackops-workspace.json";
+const DEFAULT_APP_DIR = "app";
+const DEFAULT_OPS_DIR = "ops";
+const DEFAULT_DEV_BRANCH = "develop";
+const DEFAULT_PUBLISH_BRANCH = "master";
+const DEFAULT_CONTROL_VERSION = 3;
+const DEFAULT_MANAGED_PLAN_FIELDS = [
+  "title",
+  "summary",
+  "acceptance",
+  "dependsOn",
+  "phase",
+  "stream",
+  "priority",
+  "required",
+  "parentId",
+  "sequence",
+];
+const DEFAULT_EXECUTION_OWNER = "shared";
+const EXECUTION_OWNERS = ["agent", "user", "shared"];
 
 function buildDefaultPhases(locale) {
   const normalized = normalizeLocale(locale) || DEFAULT_LOCALE;
@@ -82,11 +97,11 @@ function createSplitContext(workspaceRoot, manifest = {}) {
       progress: path.join(opsRoot, "progress.md"),
       findings: path.join(opsRoot, "findings.md"),
     },
-    paths: {
-      taskPlan: path.join(opsRoot, "task_plan.md"),
-      progress: path.join(opsRoot, "progress.md"),
-      findings: path.join(opsRoot, "findings.md"),
-      architectureDir: path.join(opsRoot, "architecture"),
+    paths: {
+      taskPlan: path.join(opsRoot, "task_plan.md"),
+      progress: path.join(opsRoot, "progress.md"),
+      findings: path.join(opsRoot, "findings.md"),
+      architectureDir: path.join(opsRoot, "architecture"),
       hooksDir: path.join(opsRoot, ".githooks"),
       tmpDir: path.join(opsRoot, ".tmp"),
       bootstrapDir: path.join(opsRoot, "bootstrap"),
@@ -96,10 +111,16 @@ function createSplitContext(workspaceRoot, manifest = {}) {
       autonomyPolicyFile: path.join(opsRoot, "policy", "autonomy.json"),
       reviewsDir: path.join(opsRoot, "reviews"),
       skillsDir: path.join(opsRoot, ".agents", "skills"),
-      registryPath: path.join(opsRoot, ".agents", "skills", "_registry.md"),
-      agentHubDir: path.join(opsRoot, ".agent", "hub"),
-      genesisFile: path.join(opsRoot, "genesis.md"),
-    },
+      registryPath: path.join(opsRoot, ".agents", "skills", "_registry.md"),
+      agentHubDir: path.join(opsRoot, ".agent", "hub"),
+      genesisFile: path.join(opsRoot, "genesis.md"),
+      plansDir: path.join(opsRoot, "plans"),
+      plansRegistryFile: path.join(opsRoot, "plans", "_registry.json"),
+      qualityDir: path.join(opsRoot, "quality"),
+      qualityLatestFile: path.join(opsRoot, "quality", "latest.json"),
+      qualityRunsDir: path.join(opsRoot, "quality", "runs"),
+      qualityWaiversFile: path.join(opsRoot, "quality", "waivers.json"),
+    },
     env: {
       rootFile: path.join(workspace, env.rootFile || ".env"),
       exampleFile: path.join(workspace, env.exampleFile || ".env.example"),
@@ -140,11 +161,11 @@ function createLegacyContext(rootDir) {
       progress: path.join(root, "progress.md"),
       findings: path.join(root, "findings.md"),
     },
-    paths: {
-      taskPlan: path.join(root, "task_plan.md"),
-      progress: path.join(root, "progress.md"),
-      findings: path.join(root, "findings.md"),
-      architectureDir: path.join(root, "architecture"),
+    paths: {
+      taskPlan: path.join(root, "task_plan.md"),
+      progress: path.join(root, "progress.md"),
+      findings: path.join(root, "findings.md"),
+      architectureDir: path.join(root, "architecture"),
       hooksDir: path.join(root, ".githooks"),
       tmpDir: path.join(root, ".tmp"),
       bootstrapDir: path.join(root, "bootstrap"),
@@ -154,10 +175,16 @@ function createLegacyContext(rootDir) {
       autonomyPolicyFile: path.join(root, "policy", "autonomy.json"),
       reviewsDir: path.join(root, "reviews"),
       skillsDir: path.join(root, ".agents", "skills"),
-      registryPath: path.join(root, ".agents", "skills", "_registry.md"),
-      agentHubDir: path.join(root, ".agent", "hub"),
-      genesisFile: path.join(root, "genesis.md"),
-    },
+      registryPath: path.join(root, ".agents", "skills", "_registry.md"),
+      agentHubDir: path.join(root, ".agent", "hub"),
+      genesisFile: path.join(root, "genesis.md"),
+      plansDir: path.join(root, "plans"),
+      plansRegistryFile: path.join(root, "plans", "_registry.json"),
+      qualityDir: path.join(root, "quality"),
+      qualityLatestFile: path.join(root, "quality", "latest.json"),
+      qualityRunsDir: path.join(root, "quality", "runs"),
+      qualityWaiversFile: path.join(root, "quality", "waivers.json"),
+    },
     env: {
       rootFile: path.join(root, ".env"),
       exampleFile: path.join(root, ".env.example"),
@@ -265,14 +292,178 @@ function isOperaInstalled(control) {
   return control.meta?.opera?.installed === true;
 }
 
-function getOperaVersion(control) {
-  return control.meta?.opera?.version || null;
-}
-
-function validateControl(control) {
-  if (!control || typeof control !== "object") throw new Error("project_control.json is not a valid object.");
-  if (!control.meta || typeof control.meta !== "object") throw new Error("project_control.json is missing required field: meta");
-  if (!Array.isArray(control.tasks)) throw new Error("project_control.json is missing required field: tasks");
+function getOperaVersion(control) {
+  return control.meta?.opera?.version || null;
+}
+
+function normalizeStringList(values) {
+  return Array.isArray(values)
+    ? values.map((value) => String(value || "").trim()).filter(Boolean)
+    : [];
+}
+
+function normalizeExecutionOwner(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return EXECUTION_OWNERS.includes(normalized) ? normalized : DEFAULT_EXECUTION_OWNER;
+}
+
+function normalizeTaskExecution(execution) {
+  const normalized = execution && typeof execution === "object" ? { ...execution } : {};
+  normalized.owner = normalizeExecutionOwner(normalized.owner);
+  normalized.lastActor = normalized.lastActor ? String(normalized.lastActor).trim() : null;
+  normalized.lastSource = normalized.lastSource ? String(normalized.lastSource).trim() : null;
+  normalized.currentSessionId = normalized.currentSessionId ? String(normalized.currentSessionId).trim() : null;
+  normalized.lastSessionId = normalized.lastSessionId ? String(normalized.lastSessionId).trim() : null;
+  normalized.lastSessionStatus = normalized.lastSessionStatus ? String(normalized.lastSessionStatus).trim() : null;
+  normalized.awaitingUserConfirmation = normalized.awaitingUserConfirmation === true;
+  normalized.verificationPending = normalized.verificationPending === true;
+  normalized.updatedAt = normalized.updatedAt ? String(normalized.updatedAt).trim() : null;
+  return normalized;
+}
+
+function normalizeAgentInboxItem(item) {
+  const normalized = item && typeof item === "object" ? { ...item } : {};
+  normalized.id = String(normalized.id || "").trim();
+  normalized.taskId = normalized.taskId ? String(normalized.taskId).trim() : null;
+  normalized.kind = String(normalized.kind || "verify_status").trim();
+  normalized.message = String(normalized.message || "").trim();
+  normalized.status = String(normalized.status || "pending").trim();
+  normalized.createdAt = normalized.createdAt ? String(normalized.createdAt).trim() : null;
+  normalized.updatedAt = normalized.updatedAt ? String(normalized.updatedAt).trim() : null;
+  normalized.createdBy = normalized.createdBy ? String(normalized.createdBy).trim() : null;
+  normalized.source = normalized.source ? String(normalized.source).trim() : null;
+  normalized.expectedStatus = normalized.expectedStatus ? String(normalized.expectedStatus).trim() : null;
+  normalized.sessionId = normalized.sessionId ? String(normalized.sessionId).trim() : null;
+  normalized.resolvedAt = normalized.resolvedAt ? String(normalized.resolvedAt).trim() : null;
+  normalized.resolutionNote = normalized.resolutionNote ? String(normalized.resolutionNote).trim() : null;
+  return normalized;
+}
+
+function normalizeAgentInbox(metaInbox) {
+  const normalized = metaInbox && typeof metaInbox === "object" ? { ...metaInbox } : {};
+  normalized.pending = Array.isArray(normalized.pending)
+    ? normalized.pending.map((item) => normalizeAgentInboxItem(item)).filter((item) => item.id)
+    : [];
+  normalized.history = Array.isArray(normalized.history)
+    ? normalized.history.map((item) => normalizeAgentInboxItem(item)).filter((item) => item.id)
+    : [];
+  normalized.lastIssuedAt = normalized.lastIssuedAt ? String(normalized.lastIssuedAt).trim() : null;
+  return normalized;
+}
+
+function normalizeTaskShape(task) {
+  const normalized = { ...(task || {}) };
+  normalized.id = String(normalized.id || "").trim();
+  normalized.title = String(normalized.title || normalized.id || "").trim();
+  normalized.phase = String(normalized.phase || DEFAULT_PHASE_IDS[0]).trim() || DEFAULT_PHASE_IDS[0];
+  normalized.stream = String(normalized.stream || "Operations").trim() || "Operations";
+  normalized.priority = String(normalized.priority || "P1").trim() || "P1";
+  normalized.status = String(normalized.status || "pending").trim() || "pending";
+  normalized.required = normalized.required !== false;
+  normalized.dependsOn = normalizeStringList(normalized.dependsOn);
+  normalized.summary = String(normalized.summary || "").trim();
+  normalized.acceptance = normalizeStringList(normalized.acceptance);
+  normalized.history = Array.isArray(normalized.history) ? normalized.history.map((entry) => ({ ...entry })) : [];
+  normalized.parentId = normalized.parentId == null ? null : String(normalized.parentId).trim() || null;
+  const numericSequence = Number(normalized.sequence);
+  normalized.sequence = Number.isFinite(numericSequence) ? numericSequence : null;
+
+  const origin = normalized.origin && typeof normalized.origin === "object"
+    ? { ...normalized.origin }
+    : {};
+  const kind = origin.kind === "plan_import" ? "plan_import" : "manual";
+  origin.kind = kind;
+  origin.sourceId = origin.sourceId ? String(origin.sourceId).trim() : null;
+  origin.adapter = origin.adapter ? String(origin.adapter).trim() : null;
+  origin.externalNodeId = origin.externalNodeId ? String(origin.externalNodeId).trim() : null;
+  origin.importId = origin.importId ? String(origin.importId).trim() : null;
+  origin.fingerprint = origin.fingerprint ? String(origin.fingerprint).trim() : null;
+  origin.lastImportedAt = origin.lastImportedAt ? String(origin.lastImportedAt).trim() : null;
+  origin.detached = origin.detached === true;
+  origin.managedFields = Array.isArray(origin.managedFields) && origin.managedFields.length
+    ? origin.managedFields.map((field) => String(field || "").trim()).filter(Boolean)
+    : kind === "plan_import"
+      ? [...DEFAULT_MANAGED_PLAN_FIELDS]
+      : [];
+  normalized.origin = origin;
+  normalized.execution = normalizeTaskExecution(normalized.execution);
+  return normalized;
+}
+
+function normalizePlansMeta(meta) {
+  const normalized = meta && typeof meta === "object" ? { ...meta } : {};
+  normalized.activeSourceId = normalized.activeSourceId ? String(normalized.activeSourceId).trim() : null;
+  normalized.lastImportAt = normalized.lastImportAt ? String(normalized.lastImportAt).trim() : null;
+  normalized.unresolvedConflicts = Number.isFinite(Number(normalized.unresolvedConflicts))
+    ? Number(normalized.unresolvedConflicts)
+    : 0;
+  normalized.sources = Array.isArray(normalized.sources)
+    ? normalized.sources.map((source) => ({
+        id: String(source?.id || "").trim(),
+        title: String(source?.title || source?.id || "").trim(),
+        adapter: String(source?.adapter || "unknown").trim(),
+        status: String(source?.status || "previewed").trim(),
+        lastPreviewAt: source?.lastPreviewAt ? String(source.lastPreviewAt).trim() : null,
+        lastApplyAt: source?.lastApplyAt ? String(source.lastApplyAt).trim() : null,
+        warnings: Number.isFinite(Number(source?.warnings)) ? Number(source.warnings) : 0,
+        conflicts: Number.isFinite(Number(source?.conflicts)) ? Number(source.conflicts) : 0,
+        managedTaskCount: Number.isFinite(Number(source?.managedTaskCount)) ? Number(source.managedTaskCount) : 0,
+      })).filter((source) => source.id)
+    : [];
+  return normalized;
+}
+
+function normalizeCommandList(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || "").trim()).filter(Boolean);
+  }
+  if (typeof value === "string" && value.trim()) {
+    return [value.trim()];
+  }
+  return [];
+}
+
+function normalizeQualityMeta(meta) {
+  const normalized = meta && typeof meta === "object" ? { ...meta } : {};
+  normalized.baselineProfile = String(normalized.baselineProfile || "baseline").trim() || "baseline";
+  normalized.activeProfiles = normalizeStringList(normalized.activeProfiles);
+  normalized.verification = normalized.verification && typeof normalized.verification === "object"
+    ? { ...normalized.verification }
+    : {};
+  normalized.verification.testCommands = normalizeCommandList(normalized.verification.testCommands);
+  normalized.verification.buildCommands = normalizeCommandList(normalized.verification.buildCommands);
+  normalized.verification.smokeCommands = normalizeCommandList(normalized.verification.smokeCommands);
+  normalized.verification.reviewRequired = normalized.verification.reviewRequired === true;
+  normalized.lastReportAt = normalized.lastReportAt ? String(normalized.lastReportAt).trim() : null;
+  normalized.lastVerificationAt = normalized.lastVerificationAt ? String(normalized.lastVerificationAt).trim() : null;
+  normalized.lastReleaseReadiness = normalized.lastReleaseReadiness ? String(normalized.lastReleaseReadiness).trim() : null;
+  normalized.lastPromotionReadiness = normalized.lastPromotionReadiness ? String(normalized.lastPromotionReadiness).trim() : null;
+  return normalized;
+}
+
+function normalizeControlShape(control) {
+  const normalized = { ...(control || {}) };
+  normalized.meta = normalized.meta && typeof normalized.meta === "object" ? { ...normalized.meta } : {};
+  normalized.meta.controlVersion = DEFAULT_CONTROL_VERSION;
+  normalized.meta.plans = normalizePlansMeta(normalized.meta.plans);
+  normalized.meta.quality = normalizeQualityMeta(normalized.meta.quality);
+  normalized.meta.agentInbox = normalizeAgentInbox(normalized.meta.agentInbox);
+  normalized.tasks = Array.isArray(normalized.tasks)
+    ? normalized.tasks.map((task) => normalizeTaskShape(task))
+    : [];
+  const changed = JSON.stringify(control || {}) !== JSON.stringify(normalized);
+  Object.defineProperty(normalized, "__trackopsMigrated", {
+    value: changed,
+    enumerable: false,
+    configurable: true,
+  });
+  return normalized;
+}
+
+function validateControl(control) {
+  if (!control || typeof control !== "object") throw new Error("project_control.json is not a valid object.");
+  if (!control.meta || typeof control.meta !== "object") throw new Error("project_control.json is missing required field: meta");
+  if (!Array.isArray(control.tasks)) throw new Error("project_control.json is missing required field: tasks");
   for (let i = 0; i < control.tasks.length; i++) {
     const task = control.tasks[i];
     if (!task.id) throw new Error(`Task at index ${i} is missing required field: id`);
@@ -289,24 +480,30 @@ function loadControl(contextOrRoot) {
     throw new Error(`No se puede leer project_control.json.\n  Ruta: ${filePath}\n  Detalle: ${err.code === "ENOENT" ? "El archivo no existe. Ejecuta 'trackops init' primero." : err.message}`);
   }
   let control;
-  try {
-    control = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`project_control.json esta corrupto o no es JSON valido.\n  Ruta: ${filePath}\n  Detalle: ${err.message}`);
-  }
-  validateControl(control);
-  return control;
-}
-
-function saveControl(contextOrRoot, control, options) {
-  control.meta = control.meta || {};
-  if (!(options && options.skipTimestamp)) {
-    control.meta.updatedAt = new Date().toISOString();
-  }
-  const filePath = controlFilePath(contextOrRoot);
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(control, null, 2) + "\n", "utf8");
-}
+  try {
+    control = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`project_control.json esta corrupto o no es JSON valido.\n  Ruta: ${filePath}\n  Detalle: ${err.message}`);
+  }
+  control = normalizeControlShape(control);
+  validateControl(control);
+  return control;
+}
+
+function saveControl(contextOrRoot, control, options) {
+  const normalized = normalizeControlShape(control);
+  if (process.env.TRACKOPS_ASSERT === "1") {
+    require("./quality-assert").assertControlInvariants(normalized, { context: ensureContext(contextOrRoot) });
+  }
+  normalized.meta = normalized.meta || {};
+  if (!(options && options.skipTimestamp)) {
+    normalized.meta.updatedAt = new Date().toISOString();
+  }
+  const filePath = controlFilePath(contextOrRoot);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(normalized, null, 2) + "\n", "utf8");
+  return normalized;
+}
 
 function loadWorkspaceManifest(contextOrRoot) {
   const context = ensureContext(contextOrRoot);
@@ -326,9 +523,13 @@ module.exports = {
   DEFAULT_LOCALE,
   DEFAULT_APP_DIR,
   DEFAULT_OPS_DIR,
-  DEFAULT_DEV_BRANCH,
-  DEFAULT_PUBLISH_BRANCH,
-  WORKSPACE_MANIFEST,
+  DEFAULT_DEV_BRANCH,
+  DEFAULT_PUBLISH_BRANCH,
+  DEFAULT_CONTROL_VERSION,
+  DEFAULT_MANAGED_PLAN_FIELDS,
+  DEFAULT_EXECUTION_OWNER,
+  EXECUTION_OWNERS,
+  WORKSPACE_MANIFEST,
   buildDefaultPhases,
   createSplitContext,
   createLegacyContext,
@@ -345,8 +546,14 @@ module.exports = {
   saveWorkspaceManifest,
   getPhases,
   getLocale,
-  isOperaInstalled,
-  getOperaVersion,
-  loadControl,
-  saveControl,
-};
+  isOperaInstalled,
+  getOperaVersion,
+  normalizeExecutionOwner,
+  normalizeTaskExecution,
+  normalizeAgentInbox,
+  normalizeTaskShape,
+  normalizeQualityMeta,
+  normalizeControlShape,
+  loadControl,
+  saveControl,
+};