trackops 2.0.6 → 2.2.0

package/lib/opera-phase-dod.js

@@ -0,0 +1,485 @@
+"use strict";
+
+function hasText(value) {
+  return Boolean(String(value || "").trim());
+}
+
+function hasSchema(value) {
+  if (!value) return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return hasText(value);
+}
+
+function nonEmptyList(value) {
+  return Array.isArray(value) ? value.filter((item) => hasText(item)) : [];
+}
+
+function latestVerification(state, scope) {
+  return state.latestVerification?.verification?.runs?.[scope] || null;
+}
+
+function makeBacklogIssueDetail(state) {
+  const parts = [];
+  if (state.derived.circularDeps.length) parts.push(`deps:${state.derived.circularDeps.length}`);
+  if (state.derived.phantomDeps.length) parts.push(`phantomDeps:${state.derived.phantomDeps.length}`);
+  if (state.derived.phantomParents.length) parts.push(`phantomParents:${state.derived.phantomParents.length}`);
+  if (state.derived.hierarchyCycles.length) parts.push(`hierarchy:${state.derived.hierarchyCycles.length}`);
+  return parts.join(", ");
+}
+
+const PHASE_DOD = {
+  O: {
+    id: "O",
+    titleKey: "quality.phase.O.title",
+    checks: [
+      {
+        id: "bootstrap-complete",
+        severity: "high",
+        titleKey: "quality.phase.check.bootstrapComplete.title",
+        recommendationKey: "quality.phase.check.bootstrapComplete.recommendation",
+        evaluate(state) {
+          if (!state.hasOpera) return { status: "skip" };
+          const status = String(state.control.meta?.opera?.bootstrap?.status || "").trim();
+          return {
+            status: status === "completed" ? "pass" : "fail",
+            detail: status || "unknown",
+            evidence: { status: status || null },
+          };
+        },
+      },
+      {
+        id: "discovery-core",
+        severity: "high",
+        titleKey: "quality.phase.check.discoveryCore.title",
+        recommendationKey: "quality.phase.check.discoveryCore.recommendation",
+        evaluate(state) {
+          const missing = ["problemStatement", "targetUser", "singularDesiredOutcome", "sourceOfTruth"]
+            .filter((field) => !hasText(state.bootstrapArtifacts.intake?.[field]));
+          return {
+            status: missing.length ? "fail" : "pass",
+            detail: missing.join(", "),
+            evidence: { missingFields: missing },
+          };
+        },
+      },
+      {
+        id: "bootstrap-artifacts",
+        severity: "high",
+        titleKey: "quality.phase.check.bootstrapArtifacts.title",
+        recommendationKey: "quality.phase.check.bootstrapArtifacts.recommendation",
+        evaluate(state) {
+          const missing = [];
+          if (!state.bootstrapArtifacts.intakeExists) missing.push("intake.json");
+          if (!state.bootstrapArtifacts.specExists) missing.push("spec-dossier.md");
+          if (!state.contract.exists || !state.contract.valid) missing.push("operating-contract.json");
+          if ((state.bootstrapArtifacts.qualityReport?.missingFields || []).length) {
+            missing.push(`quality:${state.bootstrapArtifacts.qualityReport.missingFields.join(",")}`);
+          }
+          return {
+            status: missing.length ? "fail" : "pass",
+            detail: missing.join(", "),
+            evidence: {
+              missing,
+              contractValid: state.contract.valid,
+              bootstrapQuality: state.bootstrapArtifacts.qualityReport || null,
+            },
+          };
+        },
+      },
+      {
+        id: "version-control-recorded",
+        severity: "medium",
+        titleKey: "quality.phase.check.versionControl.title",
+        recommendationKey: "quality.phase.check.versionControl.recommendation",
+        evaluate(state) {
+          const metadata = state.bootstrapArtifacts.intake?.versionControl || null;
+          return {
+            status: metadata ? "pass" : "warn",
+            detail: metadata ? state.bootstrapArtifacts.sources.versionControl : "",
+            evidence: { versionControl: metadata, source: state.bootstrapArtifacts.sources.versionControl || null },
+          };
+        },
+      },
+      {
+        id: "deployment-recorded",
+        severity: "medium",
+        titleKey: "quality.phase.check.deployment.title",
+        recommendationKey: "quality.phase.check.deployment.recommendation",
+        evaluate(state) {
+          const metadata = state.bootstrapArtifacts.intake?.deployment || null;
+          return {
+            status: metadata ? "pass" : "warn",
+            detail: metadata ? state.bootstrapArtifacts.sources.deployment : "",
+            evidence: { deployment: metadata, source: state.bootstrapArtifacts.sources.deployment || null },
+          };
+        },
+      },
+      {
+        id: "schemas-defined",
+        severity: "medium",
+        titleKey: "quality.phase.check.schemas.title",
+        recommendationKey: "quality.phase.check.schemas.recommendation",
+        evaluate(state) {
+          const inputReady = hasSchema(state.bootstrapArtifacts.intake?.inputSchema) || hasSchema(state.contract.data?.system?.inputSchema);
+          const outputReady = hasSchema(state.bootstrapArtifacts.intake?.outputSchema) || hasSchema(state.contract.data?.system?.outputSchema);
+          const missing = [];
+          if (!inputReady) missing.push("input");
+          if (!outputReady) missing.push("output");
+          return {
+            status: missing.length ? "warn" : "pass",
+            detail: missing.join(", "),
+            evidence: { missing },
+          };
+        },
+      },
+      {
+        id: "behavior-rules-documented",
+        severity: "low",
+        titleKey: "quality.phase.check.behaviorRules.title",
+        recommendationKey: "quality.phase.check.behaviorRules.recommendation",
+        evaluate(state) {
+          const rules = nonEmptyList(state.bootstrapArtifacts.intake?.behaviorRules || state.contract.data?.system?.behaviorRules || []);
+          return {
+            status: rules.length ? "pass" : "warn",
+            detail: String(rules.length),
+            evidence: { count: rules.length },
+          };
+        },
+      },
+      {
+        id: "task-plan-synced",
+        severity: "low",
+        titleKey: "quality.phase.check.taskPlanSynced.title",
+        recommendationKey: "quality.phase.check.taskPlanSynced.recommendation",
+        evaluate(state) {
+          const drifted = state.drift.includes("task_plan");
+          return {
+            status: drifted ? "warn" : "pass",
+            detail: drifted ? "task_plan" : "",
+            evidence: { drift: state.drift },
+          };
+        },
+      },
+    ],
+  },
+  P: {
+    id: "P",
+    titleKey: "quality.phase.P.title",
+    checks: [
+      {
+        id: "env-keys-present",
+        severity: "high",
+        titleKey: "quality.phase.check.envKeys.title",
+        recommendationKey: "quality.phase.check.envKeys.recommendation",
+        evaluate(state) {
+          return {
+            status: state.envState.missingKeys.length ? "fail" : "pass",
+            detail: state.envState.missingKeys.join(", "),
+            evidence: { missingKeys: state.envState.missingKeys },
+          };
+        },
+      },
+      {
+        id: "verification-evidence",
+        severity: "medium",
+        titleKey: "quality.phase.check.verificationEvidence.title",
+        recommendationKey: "quality.phase.check.verificationEvidence.recommendation",
+        evaluate(state) {
+          const latestTest = latestVerification(state, "test");
+          const latestSmoke = latestVerification(state, "smoke");
+          const hasEvidence = (latestTest && latestTest.status === "passed") || (latestSmoke && latestSmoke.status === "passed");
+          return {
+            status: hasEvidence ? "pass" : "warn",
+            detail: hasEvidence ? "verified" : "missing",
+            evidence: { test: latestTest || null, smoke: latestSmoke || null },
+          };
+        },
+      },
+      {
+        id: "critical-findings-closed",
+        severity: "high",
+        titleKey: "quality.phase.check.criticalFindings.title",
+        recommendationKey: "quality.phase.check.criticalFindings.recommendation",
+        evaluate(state) {
+          const critical = state.derived.openFindings.filter((finding) => state.normalizeFindingSeverity(finding) === "critical");
+          return {
+            status: critical.length ? "fail" : "pass",
+            detail: String(critical.length),
+            evidence: { findingIds: critical.map((finding) => finding.id) },
+          };
+        },
+      },
+      {
+        id: "blocked-tasks-documented",
+        severity: "medium",
+        titleKey: "quality.phase.check.blockedTasksDocumented.title",
+        recommendationKey: "quality.phase.check.blockedTasksDocumented.recommendation",
+        evaluate(state) {
+          const undocumented = state.derived.blockers.filter((task) => !hasText(task.blocker));
+          return {
+            status: undocumented.length ? "fail" : "pass",
+            detail: String(undocumented.length),
+            evidence: { taskIds: undocumented.map((task) => task.id) },
+          };
+        },
+      },
+    ],
+  },
+  E: {
+    id: "E",
+    titleKey: "quality.phase.E.title",
+    checks: [
+      {
+        id: "backlog-integrity",
+        severity: "high",
+        titleKey: "quality.phase.check.backlogIntegrity.title",
+        recommendationKey: "quality.phase.check.backlogIntegrity.recommendation",
+        evaluate(state) {
+          const hasIssues = state.derived.circularDeps.length || state.derived.phantomDeps.length || state.derived.phantomParents.length || state.derived.hierarchyCycles.length;
+          return {
+            status: hasIssues ? "fail" : "pass",
+            detail: makeBacklogIssueDetail(state),
+            evidence: {
+              circularDeps: state.derived.circularDeps,
+              phantomDeps: state.derived.phantomDeps,
+              phantomParents: state.derived.phantomParents,
+              hierarchyCycles: state.derived.hierarchyCycles,
+            },
+          };
+        },
+      },
+      {
+        id: "required-acceptance",
+        severity: "medium",
+        titleKey: "quality.phase.check.requiredAcceptance.title",
+        recommendationKey: "quality.phase.check.requiredAcceptance.recommendation",
+        evaluate(state) {
+          const missing = state.derived.actionableTasks.filter(
+            (task) => task.required !== false && (!Array.isArray(task.acceptance) || task.acceptance.length === 0),
+          );
+          return {
+            status: missing.length ? "fail" : "pass",
+            detail: String(missing.length),
+            evidence: { taskIds: missing.map((task) => task.id) },
+          };
+        },
+      },
+      {
+        id: "task-tracking",
+        severity: "medium",
+        titleKey: "quality.phase.check.taskTracking.title",
+        recommendationKey: "quality.phase.check.taskTracking.recommendation",
+        evaluate(state) {
+          const tracked = state.derived.actionableTasks.some((task) => Array.isArray(task.history) && task.history.some((entry) => entry.action && entry.action !== "create"));
+          return {
+            status: tracked ? "pass" : "warn",
+            detail: tracked ? "tracked" : "missing",
+            evidence: { tracked },
+          };
+        },
+      },
+      {
+        id: "docs-synced-structure",
+        severity: "medium",
+        titleKey: "quality.phase.check.docsSynced.title",
+        recommendationKey: "quality.phase.check.docsSynced.recommendation",
+        evaluate(state) {
+          return {
+            status: state.drift.length ? "fail" : "pass",
+            detail: state.drift.join(", "),
+            evidence: { drift: state.drift },
+          };
+        },
+      },
+      {
+        id: "repo-committed",
+        severity: "medium",
+        titleKey: "quality.phase.check.repoCommitted.title",
+        recommendationKey: "quality.phase.check.repoCommitted.recommendation",
+        evaluate(state) {
+          if (!state.repo.available) return { status: "skip" };
+          return {
+            status: state.repo.clean ? "pass" : "warn",
+            detail: state.repo.clean ? "" : `staged:${state.repo.staged},unstaged:${state.repo.unstaged},untracked:${state.repo.untracked}`,
+            evidence: { clean: state.repo.clean, ahead: state.repo.ahead, behind: state.repo.behind },
+          };
+        },
+      },
+    ],
+  },
+  R: {
+    id: "R",
+    titleKey: "quality.phase.R.title",
+    checks: [
+      {
+        id: "findings-high-closed",
+        severity: "high",
+        titleKey: "quality.phase.check.findingsHighClosed.title",
+        recommendationKey: "quality.phase.check.findingsHighClosed.recommendation",
+        evaluate(state) {
+          const open = state.derived.openFindings.filter((finding) => {
+            const severity = state.normalizeFindingSeverity(finding);
+            return severity === "critical" || severity === "high";
+          });
+          return {
+            status: open.length ? "fail" : "pass",
+            detail: String(open.length),
+            evidence: { findingIds: open.map((finding) => finding.id) },
+          };
+        },
+      },
+      {
+        id: "docs-synced-refinement",
+        severity: "medium",
+        titleKey: "quality.phase.check.docsSynced.title",
+        recommendationKey: "quality.phase.check.docsSynced.recommendation",
+        evaluate(state) {
+          return {
+            status: state.drift.length ? "fail" : "pass",
+            detail: state.drift.join(", "),
+            evidence: { drift: state.drift },
+          };
+        },
+      },
+      {
+        id: "contract-consistent",
+        severity: "high",
+        titleKey: "quality.phase.check.contractConsistent.title",
+        recommendationKey: "quality.phase.check.contractConsistent.recommendation",
+        evaluate(state) {
+          const contradictions = state.bootstrapArtifacts.qualityReport?.contradictions || [];
+          const invalidContract = !state.contract.exists || !state.contract.valid;
+          return {
+            status: invalidContract || contradictions.length ? "fail" : "pass",
+            detail: invalidContract ? "contract" : contradictions.join(", "),
+            evidence: { invalidContract, contradictions },
+          };
+        },
+      },
+      {
+        id: "review-evidence",
+        severity: "low",
+        titleKey: "quality.phase.check.reviewEvidence.title",
+        recommendationKey: "quality.phase.check.reviewEvidence.recommendation",
+        evaluate(state) {
+          if (!state.verificationConfig.reviewRequired) return { status: "skip" };
+          const latestReview = latestVerification(state, "review");
+          return {
+            status: latestReview?.status === "passed" ? "pass" : "warn",
+            detail: latestReview?.status || "",
+            evidence: { review: latestReview || null },
+          };
+        },
+      },
+    ],
+  },
+  A: {
+    id: "A",
+    titleKey: "quality.phase.A.title",
+    checks: [
+      {
+        id: "tmp-clean",
+        severity: "low",
+        titleKey: "quality.phase.check.tmpClean.title",
+        recommendationKey: "quality.phase.check.tmpClean.recommendation",
+        evaluate(state) {
+          const tmpDir = state.context.paths.tmpDir;
+          if (!tmpDir) return { status: "skip" };
+          const entries = state.fileExists(tmpDir)
+            ? state.fs.readdirSync(tmpDir).filter((entry) => entry !== "upgrade-backups")
+            : [];
+          return {
+            status: entries.length ? "warn" : "pass",
+            detail: entries.join(", "),
+            evidence: { entries },
+          };
+        },
+      },
+      {
+        id: "deployment-ready",
+        severity: "high",
+        titleKey: "quality.phase.check.deploymentReady.title",
+        recommendationKey: "quality.phase.check.deploymentReady.recommendation",
+        evaluate(state) {
+          const deployment = state.bootstrapArtifacts.intake?.deployment || null;
+          const missing = [];
+          if (!deployment?.mode) missing.push("mode");
+          if (!deployment?.smokeCommand) missing.push("smokeCommand");
+          return {
+            status: missing.length ? "fail" : "pass",
+            detail: missing.join(", "),
+            evidence: { deployment, missing },
+          };
+        },
+      },
+      {
+        id: "smoke-passed",
+        severity: "high",
+        titleKey: "quality.phase.check.smokePassed.title",
+        recommendationKey: "quality.phase.check.smokePassed.recommendation",
+        evaluate(state) {
+          const smokeConfigured = state.verificationConfig.smokeCommands.length > 0;
+          const latestSmoke = latestVerification(state, "smoke");
+          if (!smokeConfigured) {
+            return { status: "warn", detail: "not_configured", evidence: { smoke: null } };
+          }
+          return {
+            status: latestSmoke?.status === "passed" ? "pass" : "fail",
+            detail: latestSmoke?.status || "missing",
+            evidence: { smoke: latestSmoke || null },
+          };
+        },
+      },
+      {
+        id: "docs-synced-automation",
+        severity: "medium",
+        titleKey: "quality.phase.check.docsSynced.title",
+        recommendationKey: "quality.phase.check.docsSynced.recommendation",
+        evaluate(state) {
+          return {
+            status: state.drift.length ? "fail" : "pass",
+            detail: state.drift.join(", "),
+            evidence: { drift: state.drift },
+          };
+        },
+      },
+      {
+        id: "remote-pushed",
+        severity: "high",
+        titleKey: "quality.phase.check.remotePushed.title",
+        recommendationKey: "quality.phase.check.remotePushed.recommendation",
+        evaluate(state) {
+          const versionControl = state.bootstrapArtifacts.intake?.versionControl || null;
+          if (!versionControl?.remote) return { status: "skip" };
+          if (!state.repo.available || !state.repo.hasUpstream) {
+            return { status: "fail", detail: "no_upstream", evidence: { repo: state.repo } };
+          }
+          return {
+            status: state.repo.ahead > 0 ? "fail" : "pass",
+            detail: state.repo.ahead > 0 ? String(state.repo.ahead) : "",
+            evidence: { ahead: state.repo.ahead, behind: state.repo.behind },
+          };
+        },
+      },
+      {
+        id: "repo-clean-automation",
+        severity: "high",
+        titleKey: "quality.phase.check.repoClean.title",
+        recommendationKey: "quality.phase.check.repoClean.recommendation",
+        evaluate(state) {
+          if (!state.repo.available) return { status: "skip" };
+          return {
+            status: state.repo.clean ? "pass" : "fail",
+            detail: state.repo.clean ? "" : `staged:${state.repo.staged},unstaged:${state.repo.unstaged},untracked:${state.repo.untracked}`,
+            evidence: { clean: state.repo.clean },
+          };
+        },
+      },
+    ],
+  },
+};
+
+module.exports = {
+  PHASE_DOD,
+};

package/lib/opera.js

@@ -15,7 +15,7 @@ const fmt = require("./cli-format");
 const TEMPLATES_DIR = path.join(__dirname, "..", "templates", "opera");
 const SKILLS_TEMPLATES_DIR = path.join(__dirname, "..", "templates", "skills");
 const OPERA_VERSION = require("../package.json").version;
-const AUXILIARY_SKILLS = ["opera-skill", "project-starter-skill", "opera-contract-auditor", "opera-policy-guard"];
+const AUXILIARY_SKILLS = ["opera-skill", "trackops-quality-guard", "project-starter-skill", "opera-contract-auditor", "opera-policy-guard"];
 
 function nowIso() {
   return new Date().toISOString();
@@ -585,10 +585,13 @@ function upgrade(root, args = []) {
     removePath(context.paths.bootstrapDir);
   }
 
-  installStructure(context, control, locale, { rewriteLocalizedTemplates: true });
-  control.meta.opera = {
-    ...(control.meta.opera || {}),
-    installed: true,
+  installStructure(context, control, locale, { rewriteLocalizedTemplates: true });
+  require("./quality").backfillBootstrapMetadata(context, control, {
+    persist: true,
+  });
+  control.meta.opera = {
+    ...(control.meta.opera || {}),
+    installed: true,
     model: "v3",
     stableTag: "stable",
     version: OPERA_VERSION,