@duypham93/openkit 0.2.0

package/.opencode/README.md

@@ -0,0 +1,47 @@
+# .opencode Runtime Internals
+
+This directory is the checked-in repository-local OpenKit runtime layer.
+
+It remains live in this repository today.
+
+For phase-1 navigation, treat this file as a local runtime boundary note, not as a replacement for the audience index layers in `README.md`, `docs/operator/README.md`, or `docs/maintainer/README.md`.
+
+What lives here:
+
+- `.opencode/opencode.json`: the current repository-local runtime manifest
+- `.opencode/workflow-state.json`: the active compatibility mirror
+- `.opencode/work-items/`: per-item backing store
+- `.opencode/workflow-state.js`: lower-level runtime utility CLI
+- `.opencode/lib/`: runtime internals
+- `.opencode/tests/`: runtime regression tests
+
+Related routing layers outside this directory:
+
+- `README.md`: top-level repository boundary and current docs layout
+- `docs/operator/README.md`: operator-facing routing for the live surfaces
+- `docs/maintainer/README.md`: maintainer-facing routing for canonical docs and internals
+- `docs/operations/README.md`: operational support routing for runbooks and internal records
+
+What this directory is not:
+
+- not the preferred top-level onboarding surface for everyday OpenKit usage now that the global install path exists
+- not proof that end users should install the kit into each repository
+- not a separate product from the repository itself
+
+When the global OpenKit install exists elsewhere, the intended product path is:
+
+- `npm install -g openkit`
+- `openkit doctor`
+- `openkit run`
+- `openkit upgrade`
+- `openkit uninstall`
+
+`openkit install-global` remains available as a manual or compatibility setup command when you need it.
+
+In this repository, `.opencode/` is still the concrete checked-in runtime that powers the lower-level workflow-state path and supports maintainer/runtime inspection.
+
+Authority guardrail:
+
+- `.opencode/` remains the live runtime layer
+- `context/core/workflow.md` remains the canonical workflow-semantics document
+- the phase-1 audience directories remain index layers only and do not relocate canonical runtime or workflow sources

package/.opencode/install-manifest.json

@@ -0,0 +1,41 @@
+{
+  "schema": "openkit/install-manifest@1",
+  "manifestVersion": 1,
+  "kit": {
+    "name": "OpenKit AI Software Factory",
+    "version": "0.1.0"
+  },
+  "registry": {
+    "path": "registry.json",
+    "schema": "openkit/component-registry@1",
+    "registryVersion": 1
+  },
+  "installation": {
+    "type": "checked-in-local-metadata",
+    "activeProfile": "openkit-core",
+    "installedAt": "repository-root",
+    "managedRemotely": false,
+    "mode": "additive-non-destructive",
+    "installReadiness": "emerging",
+    "notes": "This manifest describes additive metadata checked into this repository. It does not fetch remote components, remove the repository-local runtime, or replace the preferred global OpenKit install path.",
+    "repositoryInternalRuntime": ".opencode/opencode.json",
+    "wrapperFacingMetadata": [
+      "registry.json",
+      ".opencode/install-manifest.json"
+    ]
+  },
+  "migration": {
+    "currentRuntimeManifest": ".opencode/opencode.json",
+    "status": "staged-not-complete",
+    "notes": "The checked-in repository runtime remains the authoring and compatibility surface. Everyday operator usage should prefer the global OpenKit install path."
+  },
+  "components": {
+    "agents": "present",
+    "skills": "present",
+    "commands": "present",
+    "artifacts": "present",
+    "runtime": "present",
+    "hooks": "present",
+    "docs": "present"
+  }
+}

package/.opencode/lib/artifact-scaffolder.js

@@ -0,0 +1,111 @@
+const fs = require("fs")
+const path = require("path")
+
+const SUPPORTED_SCAFFOLDS = {
+  task_card: {
+    templatePath: "docs/templates/quick-task-template.md",
+    outputDir: "docs/tasks",
+  },
+  plan: {
+    templatePath: "docs/templates/implementation-plan-template.md",
+    outputDir: "docs/plans",
+  },
+  migration_report: {
+    templatePath: "docs/templates/migration-report-template.md",
+    outputDir: "docs/plans",
+  },
+}
+
+const PLAN_TEMPLATE_BY_MODE = {
+  full: "docs/templates/implementation-plan-template.md",
+  migration: "docs/templates/migration-plan-template.md",
+}
+
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function formatDate(date = new Date()) {
+  return date.toISOString().slice(0, 10)
+}
+
+function titleFromSlug(slug) {
+  return slug
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ")
+}
+
+function replaceTemplatePlaceholders(template, values) {
+  return template
+    .replace(/TASK-000/g, values.featureId)
+    .replace(/FEATURE-000/g, values.featureId)
+    .replace(/example-task/g, values.featureSlug)
+    .replace(/example-feature/g, values.featureSlug)
+    .replace(/example-migration/g, values.featureSlug)
+    .replace(/docs\/architecture\/YYYY-MM-DD-[^\s]+\.md/g, values.sourceArchitecture)
+    .replace(/docs\/plans\/YYYY-MM-DD-[^\s]+\.md/g, values.sourcePlan)
+    .replace(/<Task Name>/g, values.title)
+    .replace(/<Feature Name>/g, values.title)
+    .replace(/<Migration Name>/g, values.title)
+}
+
+function scaffoldArtifact({ projectRoot, kind, mode, slug, featureId, featureSlug, sourceArchitecture, sourcePlan }) {
+  const config = SUPPORTED_SCAFFOLDS[kind]
+  if (!config) {
+    throw new Error(`Unsupported scaffold kind '${kind}'`)
+  }
+
+  if (!SLUG_PATTERN.test(slug)) {
+    throw new Error("artifact slug must use lowercase kebab-case")
+  }
+
+  const resolvedTemplatePath =
+    kind === "plan" ? PLAN_TEMPLATE_BY_MODE[mode] ?? config.templatePath : config.templatePath
+  const templatePath = path.join(projectRoot, resolvedTemplatePath)
+  const outputDir = path.join(projectRoot, config.outputDir)
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template not found for scaffold kind '${kind}': '${resolvedTemplatePath}'`)
+  }
+
+  if (!fs.existsSync(outputDir)) {
+    throw new Error(`Output directory does not exist for scaffold kind '${kind}': '${config.outputDir}'`)
+  }
+
+  const date = formatDate()
+  const outputRelativePath = path.posix.join(config.outputDir, `${date}-${slug}.md`)
+  const outputPath = path.join(projectRoot, outputRelativePath)
+  const resolvedOutputDir = path.resolve(outputDir)
+  const resolvedOutputPath = path.resolve(outputPath)
+
+  if (!resolvedOutputPath.startsWith(`${resolvedOutputDir}${path.sep}`)) {
+    throw new Error(`artifact path escapes output directory for kind '${kind}'`)
+  }
+
+  if (fs.existsSync(resolvedOutputPath)) {
+    throw new Error(`Artifact already exists at '${outputRelativePath}'`)
+  }
+
+  const template = fs.readFileSync(templatePath, "utf8")
+  const content = replaceTemplatePlaceholders(template, {
+    date,
+    featureId,
+    featureSlug,
+    sourceArchitecture: sourceArchitecture ?? "docs/architecture/YYYY-MM-DD-<feature>.md",
+    sourcePlan: sourcePlan ?? "docs/plans/YYYY-MM-DD-<migration>.md",
+    title: titleFromSlug(slug),
+  })
+
+  fs.writeFileSync(resolvedOutputPath, content.endsWith("\n") ? content : `${content}\n`, "utf8")
+
+  return {
+    artifactPath: outputRelativePath,
+    kind,
+  }
+}
+
+module.exports = {
+  SLUG_PATTERN,
+  SUPPORTED_SCAFFOLDS,
+  scaffoldArtifact,
+}

package/.opencode/lib/contract-consistency.js

@@ -0,0 +1,218 @@
+const fs = require("fs")
+const path = require("path")
+
+const {
+  ARTIFACT_KINDS,
+  MODE_VALUES,
+  MODE_STAGE_SEQUENCES,
+  MODE_APPROVAL_GATES,
+} = require("./workflow-state-rules")
+
+function listExistingMarkdownLiterals(markdown, values) {
+  return values.filter((value) => markdown.includes(`\`${value}\``))
+}
+
+function matchesAnyPattern(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text))
+}
+
+function normalizeText(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, " ")
+}
+
+function includesAllTerms(text, terms) {
+  const normalized = normalizeText(text)
+  return terms.every((term) => normalized.includes(normalizeText(term).trim()))
+}
+
+function readTextIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null
+  }
+
+  return fs.readFileSync(filePath, "utf8")
+}
+
+function getManifestSurfacePaths(projectRoot, manifest) {
+  const agents = manifest?.agents ?? {}
+  const commands = manifest?.commands ?? {}
+
+  return {
+    primaryAgentPath: agents.primary ? path.resolve(projectRoot, agents.primary) : null,
+    teamRolePaths: (agents.teamRoles ?? []).map((entry) => path.resolve(projectRoot, entry)),
+    commandPaths: (commands.available ?? []).map((entry) => path.resolve(projectRoot, entry)),
+  }
+}
+
+function makeCheck(label, ok) {
+  return { label, ok }
+}
+
+function getContractConsistencyReport({ projectRoot, manifest }) {
+  const workflowPath = path.join(projectRoot, "context", "core", "workflow.md")
+  const schemaPath = path.join(projectRoot, "context", "core", "workflow-state-schema.md")
+  const sessionResumePath = path.join(projectRoot, "context", "core", "session-resume.md")
+  const fullDeliverySpecPath = path.join(
+    projectRoot,
+    "docs",
+    "specs",
+    "2026-03-21-openkit-full-delivery-multi-task-runtime.md",
+  )
+  const fullDeliveryPlanPath = path.join(
+    projectRoot,
+    "docs",
+    "plans",
+    "2026-03-21-openkit-full-delivery-multi-task-runtime.md",
+  )
+  const workflowText = readTextIfExists(workflowPath)
+  const schemaText = readTextIfExists(schemaPath)
+  const sessionResumeText = readTextIfExists(sessionResumePath) ?? ""
+  const fullDeliverySpecText = readTextIfExists(fullDeliverySpecPath) ?? ""
+  const fullDeliveryPlanText = readTextIfExists(fullDeliveryPlanPath) ?? ""
+  const surfacePaths = getManifestSurfacePaths(projectRoot, manifest)
+  const taskBoardContractText = [workflowText, sessionResumeText, fullDeliverySpecText, fullDeliveryPlanText]
+    .filter(Boolean)
+    .join("\n")
+  const compatibilityText = [schemaText, fullDeliverySpecText, fullDeliveryPlanText].filter(Boolean).join("\n")
+
+  const allStageNames = Object.values(MODE_STAGE_SEQUENCES).flat()
+  const allApprovalGates = Object.values(MODE_APPROVAL_GATES).flat()
+
+  const checks = [
+    makeCheck("workflow contract doc found", Boolean(workflowText)),
+    makeCheck("workflow schema doc found", Boolean(schemaText)),
+    makeCheck(
+      "declared primary agent exists",
+      !surfacePaths.primaryAgentPath || fs.existsSync(surfacePaths.primaryAgentPath),
+    ),
+    makeCheck(
+      "declared team role files exist",
+      surfacePaths.teamRolePaths.every((entry) => fs.existsSync(entry)),
+    ),
+    makeCheck(
+      "declared command files exist",
+      surfacePaths.commandPaths.every((entry) => fs.existsSync(entry)),
+    ),
+  ]
+
+  if (!workflowText || !schemaText) {
+    return summarizeChecks(checks)
+  }
+
+  checks.push(
+    makeCheck(
+      "workflow contract documents runtime mode enums",
+      MODE_VALUES.every((value) => workflowText.includes(`\`${value}\``)),
+    ),
+    makeCheck(
+      "workflow contract states Quick Task+ is not a third lane",
+      /`?Quick Task\+`?/i.test(workflowText) &&
+        matchesAnyPattern(workflowText, [
+          /not a third lane/i,
+          /not a third operating mode/i,
+          /not a third mode/i,
+        ]),
+    ),
+    makeCheck(
+      "workflow contract keeps migration lane free of task boards",
+      includesAllTerms(taskBoardContractText, ["migration", "task", "board"]) &&
+        matchesAnyPattern(taskBoardContractText, [
+          /migration[^\n.]{0,120}(free of|without|must stay free of|must not carry|no) [^\n.]{0,80}task board/i,
+          /task board[^\n.]{0,120}(not allowed|forbidden|disallowed|full[- ]delivery only)[^\n.]{0,80}migration/i,
+          /migration[^\n.]{0,120}execution[- ]task[- ]board/i,
+          /migration[^\n.]{0,120}task[- ]board/i,
+        ]),
+    ),
+    makeCheck(
+      "workflow contract states migration lane is for upgrades",
+      includesAllTerms(workflowText, ["migration", "upgrade"]),
+    ),
+    makeCheck(
+      "workflow contract states migration preserves behavior and decouples blockers first",
+      includesAllTerms(workflowText, ["migration", "behavior"]) &&
+        matchesAnyPattern(workflowText, [
+          /preserve[^\n.]{0,80}behavior/i,
+          /freeze[^\n.]{0,80}invariant/i,
+          /decouple[^\n.]{0,120}blocker/i,
+          /seam/i,
+        ]),
+    ),
+    makeCheck(
+      "workflow contract documents lane tie-breakers and examples",
+      includesAllTerms(workflowText, ["lane", "tie breaker"]) && includesAllTerms(workflowText, ["decision", "matrix"]),
+    ),
+    makeCheck(
+      "workflow contract keeps quick lane free of task boards",
+      includesAllTerms(taskBoardContractText, ["quick", "task", "board"]) &&
+        matchesAnyPattern(taskBoardContractText, [
+          /quick[^\n.]{0,120}(free of|without|must stay free of|must not carry|no) [^\n.]{0,80}task board/i,
+          /task board[^\n.]{0,120}(not allowed|forbidden|disallowed|full[- ]delivery only)[^\n.]{0,80}quick/i,
+          /quick[^\n.]{0,120}execution[- ]task[- ]board/i,
+          /do not invent a quick task board/i,
+        ]),
+    ),
+    makeCheck(
+      "workflow contract states full delivery owns execution task boards",
+      includesAllTerms(taskBoardContractText, ["full", "task", "board"]) &&
+        matchesAnyPattern(taskBoardContractText, [
+          /(full delivery|full mode|full work)[^\n.]{0,120}(owns|uses|carries|gains|has|contains|belong)[^\n.]{0,80}task board/i,
+          /task board[^\n.]{0,120}(full delivery|full mode|full work)[^\n.]{0,80}(only|owns|belong)/i,
+          /execution task boards? belong only to full delivery/i,
+          /only `?full delivery`? work items gain an execution[- ]task board/i,
+        ]),
+    ),
+    makeCheck(
+      "workflow schema matches runtime mode enums",
+      listExistingMarkdownLiterals(schemaText, MODE_VALUES).length === MODE_VALUES.length,
+    ),
+    makeCheck(
+      "workflow schema matches runtime stage sequences",
+      listExistingMarkdownLiterals(schemaText, allStageNames).length === allStageNames.length,
+    ),
+    makeCheck(
+      "workflow schema matches runtime artifact slots",
+      listExistingMarkdownLiterals(schemaText, ARTIFACT_KINDS).length === ARTIFACT_KINDS.length,
+    ),
+    makeCheck(
+      "workflow schema documents routing profile fields",
+      includesAllTerms(schemaText, ["routing_profile", "dominant_uncertainty", "behavior_delta"]),
+    ),
+    makeCheck(
+      "workflow schema matches runtime approval keys",
+      listExistingMarkdownLiterals(schemaText, allApprovalGates).length === allApprovalGates.length,
+    ),
+    makeCheck(
+      "workflow schema documents compatibility mirror behavior",
+      includesAllTerms(compatibilityText, ["work item"]) &&
+        matchesAnyPattern(compatibilityText, [
+          /(compatibility|mirrored|mirror)[^\n.]{0,120}(state file|workflow state|repo root)/i,
+          /(state file|workflow state|repo root)[^\n.]{0,120}(compatibility|mirrored|mirror)/i,
+          /mirrored compatibility surface/i,
+          /compatibility mirror/i,
+          /compatibility rule/i,
+        ]),
+    ),
+  )
+
+  return summarizeChecks(checks)
+}
+
+function summarizeChecks(checks) {
+  const summary = checks.reduce(
+    (counts, check) => {
+      if (check.ok) {
+        counts.ok += 1
+      } else {
+        counts.error += 1
+      }
+      return counts
+    },
+    { ok: 0, warn: 0, error: 0 },
+  )
+
+  return { checks, summary }
+}
+
+module.exports = {
+  getContractConsistencyReport,
+}

package/.opencode/lib/parallel-execution-rules.js

@@ -0,0 +1,261 @@
+const ALLOWED_WORKTREE_PREFIX = ".worktrees/"
+const PROTECTED_BRANCHES = new Set(["main", "master"])
+const VALID_QA_REWORK_STAGES = new Set(["full_qa", "full_implementation"])
+const VALID_QA_REWORK_DECIDERS = new Set(["MasterOrchestrator", "TechLeadAgent"])
+const VALID_QA_REWORK_OWNERS = new Set(["QAAgent", "FullstackAgent"])
+
+const VALID_ASSIGNMENT_AUTHORITIES = {
+  primary_owner: ["MasterOrchestrator", "TechLeadAgent"],
+  qa_owner: ["MasterOrchestrator", "TechLeadAgent"],
+}
+
+function fail(message) {
+  throw new Error(message)
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0
+}
+
+function validateTaskReference(task, contextLabel = "Parallel execution") {
+  if (!task || typeof task !== "object" || Array.isArray(task)) {
+    fail(`${contextLabel} requires task objects`)
+  }
+
+  if (!isNonEmptyString(task.task_id)) {
+    fail(`${contextLabel} requires each task to have a non-empty task_id`)
+  }
+
+  return task
+}
+
+function validateTaskReferenceList(tasks) {
+  if (!Array.isArray(tasks)) {
+    fail("Parallel assignment validation requires a tasks array")
+  }
+
+  return tasks.map((task) => validateTaskReference(task, "Parallel assignment validation"))
+}
+
+function validatePerTaskOwnerField(tasks, ownerField) {
+  for (const task of validateTaskReferenceList(tasks)) {
+    const owner = task[ownerField]
+    if (owner === null || owner === undefined) {
+      continue
+    }
+
+    if (!isNonEmptyString(owner)) {
+      fail(`Parallel ${ownerField} for task '${task.task_id}' must be a non-empty string when set`)
+    }
+  }
+}
+
+function validateParallelAssignments(tasks) {
+  validatePerTaskOwnerField(tasks, "primary_owner")
+  validatePerTaskOwnerField(tasks, "qa_owner")
+  return tasks
+}
+
+function validateReassignmentAuthority({ task, ownerField, requestedBy, nextOwner }) {
+  validateTaskReference(task, "Reassignment validation")
+
+  if (!Object.prototype.hasOwnProperty.call(VALID_ASSIGNMENT_AUTHORITIES, ownerField)) {
+    fail(`Unknown assignment field '${ownerField}'`)
+  }
+
+  if (!isNonEmptyString(requestedBy)) {
+    fail("Reassignment validation requires requestedBy")
+  }
+
+  if (!isNonEmptyString(nextOwner)) {
+    fail(`Reassignment validation requires a non-empty next owner for '${ownerField}'`)
+  }
+
+  const currentOwner = task[ownerField]
+  const allowedAuthorities = VALID_ASSIGNMENT_AUTHORITIES[ownerField]
+  const isInitialAssignment = !isNonEmptyString(currentOwner)
+
+  if (isInitialAssignment) {
+    if (!allowedAuthorities.includes(requestedBy)) {
+      fail(`Only ${allowedAuthorities.join(" or ")} can assign ${ownerField}`)
+    }
+
+    return {
+      ownerField,
+      requestedBy,
+      nextOwner,
+      reassignment: false,
+    }
+  }
+
+  if (currentOwner === nextOwner) {
+    return {
+      ownerField,
+      requestedBy,
+      nextOwner,
+      reassignment: false,
+    }
+  }
+
+  if (!allowedAuthorities.includes(requestedBy)) {
+    fail(`Only ${allowedAuthorities.join(" or ")} can reassign ${ownerField}`)
+  }
+
+  return {
+    ownerField,
+    requestedBy,
+    nextOwner,
+    reassignment: true,
+  }
+}
+
+function validateTaskScopedFinding(finding, task) {
+  if (!finding || typeof finding !== "object" || Array.isArray(finding)) {
+    fail("A task-scoped finding must be an object")
+  }
+
+  validateTaskReference(task, "Task-scoped finding validation")
+
+  const requiredFields = [
+    "issue_id",
+    "task_id",
+    "title",
+    "summary",
+    "type",
+    "severity",
+    "rooted_in",
+    "recommended_owner",
+    "evidence",
+  ]
+
+  for (const field of requiredFields) {
+    if (!isNonEmptyString(finding[field])) {
+      fail(`Task-scoped finding requires '${field}'`)
+    }
+  }
+
+  if (finding.task_id !== task.task_id) {
+    fail(`A task-scoped finding for '${task.task_id}' must reference the same task_id`)
+  }
+
+  if (!Array.isArray(finding.artifact_refs) || finding.artifact_refs.length === 0 || !finding.artifact_refs.every(isNonEmptyString)) {
+    fail("Task-scoped finding requires non-empty artifact_refs")
+  }
+
+  if (!Array.isArray(finding.affects_tasks) || finding.affects_tasks.length !== 1 || finding.affects_tasks[0] !== task.task_id) {
+    fail(`Task-scoped finding affects_tasks must be isolated to exactly one task: '${task.task_id}'`)
+  }
+
+  return finding
+}
+
+function validateFailureIsolation(finding, task) {
+  validateTaskScopedFinding(finding, task)
+
+  if (finding.blocks_parallel_work === true) {
+    fail("Task-scoped local rework cannot proceed when the finding blocks parallel work")
+  }
+
+  if (finding.affects_tasks.length !== 1) {
+    fail("Failure isolation requires a finding isolated to exactly one task")
+  }
+
+  if (finding.severity === "critical") {
+    fail("critical failures require orchestrator escalation")
+  }
+
+  return finding
+}
+
+function validateQaFailRerouteDecision(rerouteDecision) {
+  if (!rerouteDecision || typeof rerouteDecision !== "object" || Array.isArray(rerouteDecision)) {
+    fail("QA fail local rework routing requires a rerouteDecision")
+  }
+
+  if (!VALID_QA_REWORK_STAGES.has(rerouteDecision.stage)) {
+    fail(`QA fail local rework reroute field 'stage' must be 'full_qa' or 'full_implementation'; received '${String(rerouteDecision.stage)}'`)
+  }
+
+  if (!VALID_QA_REWORK_OWNERS.has(rerouteDecision.owner)) {
+    fail(`QA fail local rework reroute field 'owner' must be 'QAAgent' or 'FullstackAgent'; received '${String(rerouteDecision.owner)}'`)
+  }
+
+  if (!VALID_QA_REWORK_DECIDERS.has(rerouteDecision.decided_by)) {
+    fail(`QA fail local rework reroute field 'decided_by' must be 'MasterOrchestrator' or 'TechLeadAgent'; received '${String(rerouteDecision.decided_by)}'`)
+  }
+
+  if (!isNonEmptyString(rerouteDecision.reason)) {
+    fail("QA fail local rework reroute field 'reason' must be a non-empty string")
+  }
+
+  return rerouteDecision
+}
+
+function decideQaFailLocalRework({ mode, task, finding, rerouteDecision }) {
+  if (mode !== "full") {
+    fail("QA fail local rework routing is only allowed in full mode")
+  }
+
+  validateTaskReference(task, "QA fail local rework routing")
+
+  if (task.status !== "qa_in_progress") {
+    fail("QA fail local rework routing requires task status 'qa_in_progress'")
+  }
+
+  validateFailureIsolation(finding, task)
+
+  if (finding.type !== "bug" || finding.rooted_in !== "implementation" || finding.recommended_owner !== "FullstackAgent") {
+    fail("QA design or requirements findings must not stay in local rework")
+  }
+
+  const route = validateQaFailRerouteDecision(rerouteDecision)
+
+  return {
+    allowed: true,
+    route,
+  }
+}
+
+function validateWorktreeMetadata(metadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    fail("Worktree metadata must be an object")
+  }
+
+  const { task_id: taskId, branch, worktree_path: worktreePath } = metadata
+
+  if (!isNonEmptyString(taskId)) {
+    fail("Worktree metadata requires task_id")
+  }
+
+  if (!isNonEmptyString(branch)) {
+    fail("Worktree metadata requires branch")
+  }
+
+  if (!isNonEmptyString(worktreePath)) {
+    fail("Worktree metadata requires worktree_path")
+  }
+
+  if (PROTECTED_BRANCHES.has(branch)) {
+    fail("Parallel worktree branch must not target main or master")
+  }
+
+  if (!branch.includes(taskId)) {
+    fail(`Parallel worktree branch must include task id '${taskId}'`)
+  }
+
+  if (!worktreePath.startsWith(ALLOWED_WORKTREE_PREFIX)) {
+    fail(`Parallel worktree_path must start with '${ALLOWED_WORKTREE_PREFIX}'`)
+  }
+
+  return metadata
+}
+
+module.exports = {
+  VALID_ASSIGNMENT_AUTHORITIES,
+  decideQaFailLocalRework,
+  validateFailureIsolation,
+  validateParallelAssignments,
+  validateReassignmentAuthority,
+  validateTaskScopedFinding,
+  validateWorktreeMetadata,
+}