@hallucination-studio/harness-engine 1.0.0-beta.8.87407 → 1.0.0-beta.9.bb2cd30

package/skills/harness-repo-bootstrap/scripts/manage_harness.py

@@ -9,6 +9,8 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 MANAGED_MARKER = "<!-- harness-repo-bootstrap:managed -->"
+DEFAULT_KNOWLEDGE_PLACEHOLDER = "- [ ] Add durable facts here as they emerge -> <destination-doc>"
+DEFAULT_DEFECT_PLACEHOLDER = "None."
 PLAN_TEMPLATE = """# Execution Plan: {title}
 
 ## Goal
@@ -33,6 +35,40 @@ PLAN_TEMPLATE = """# Execution Plan: {title}
 
 - Describe how the work will be verified.
 
+## Quality Gate
+
+Status: pending
+Minimum score: 8.0
+Average score: pending
+Last scored: pending
+
+| Dimension | Score | Notes |
+| --- | ---: | --- |
+| Product correctness | pending | Confirm the requested behavior is complete. |
+| UX and operator clarity | pending | Confirm the user or operator experience is understandable. |
+| Architecture and maintainability | pending | Confirm the implementation is clean and easy to change. |
+| Reliability and observability | pending | Confirm the validation loop and failure handling are sufficient. |
+| Security and data handling | pending | Confirm secrets and sensitive data are handled safely. |
+
+## Defects To Resolve
+
+{defect_section}
+
+## Rework Required
+
+- Pending quality score.
+
+## Phase Continuity
+
+Mode: single-phase
+Workstream: none
+Current phase: none
+Next phase: none
+Continuation: none
+Next action: none
+Closure reason: This plan is not part of a longer workstream.
+Resume notes: none
+
 ## Durable Knowledge To Capture
 
 {knowledge_section}
@@ -52,6 +88,7 @@ Read this file first, then follow the linked docs.
 
 - Read `ARCHITECTURE.md` before changing boundaries, data flow, or integrations.
 - Read `docs/PLANS.md` before starting multi-step execution work.
+- Read `docs/exec-plans/workstreams.md` before resuming interrupted feature, refactor, reliability, or cleanup work.
 - Read `docs/exec-plans/active/` before resuming in-flight work, and create a plan there for new multi-step work.
 - Read `docs/QUALITY_SCORE.md` before evaluating tradeoffs or readiness.
 - Read `docs/RELIABILITY.md` for runtime validation and failure handling.
@@ -70,8 +107,11 @@ Read this file first, then follow the linked docs.
 
 - Keep durable decisions in repo docs, not only in chat.
 - Keep active plans in `docs/exec-plans/active/`.
+- Keep resumable feature, refactor, reliability, and cleanup work in `docs/exec-plans/workstreams.md`.
 - Move completed plans to `docs/exec-plans/completed/`.
 - Update plans during the work, not only at the end.
+- Score completed work with `quality-score` before closing an execution plan.
+- If `quality-score` fails, treat `## Rework Required` as the next implementation input and do not close the plan.
 - Encode durable facts learned during execution into permanent docs before closing the task.
 - Before handoff, run the local harness check: `python3 .codex/skills/harness-repo-bootstrap/scripts/manage_harness.py check --repo .`.
 - Keep generated artifacts in `docs/generated/`.
@@ -146,6 +186,7 @@ DOC_FILES = {
 
 - Put active execution plans in `docs/exec-plans/active/`.
 - Move completed plans to `docs/exec-plans/completed/`.
+- Track resumable multi-plan workstreams in `docs/exec-plans/workstreams.md`.
 - Record cross-cutting follow-up work in `docs/exec-plans/tech-debt-tracker.md`.
 
 ## Authoring Rules
@@ -154,6 +195,7 @@ DOC_FILES = {
 - Update plans during the work, not after the fact.
 - Link to specs, decisions, and validation artifacts when they exist.
 - Include a section for durable knowledge that must be written back into permanent docs.
+- Include phase continuity when a plan is part of a multi-phase feature, refactor, reliability, or cleanup effort.
 - Do not treat plans as the final home for product, architecture, or policy knowledge.
 """,
     "docs/PRODUCT_SENSE.md": """{marker}
@@ -236,6 +278,24 @@ DOC_FILES = {
 # Tech Debt Tracker
 
 Record follow-up work that should survive beyond a single execution plan.
+""",
+    "docs/exec-plans/workstreams.md": """{marker}
+# Workstreams
+
+Use this ledger to recover interrupted feature, refactor, reliability, security, frontend, and cleanup work.
+
+## Index
+
+| ID | Status | Current Plan | Last Completed Plan | Next Action | Last Updated |
+| --- | --- | --- | --- | --- | --- |
+
+## Operating Rules
+
+- Add a workstream when work spans multiple execution plans or may be resumed by another agent.
+- Keep `Current Plan` pointed at the active plan when one exists.
+- Keep `Last Completed Plan` pointed at the latest completed plan after `plan-close`.
+- Keep `Next Action` concrete enough that another agent can resume without chat history.
+- If a workstream is paused, record the restart condition in `Next Action`.
 """,
     "docs/exec-plans/active/README.md": """{marker}
 # Active Execution Plans
@@ -253,6 +313,8 @@ Minimum contents:
 - constraints
 - steps
 - validation
+- quality gate
+- phase continuity
 - durable knowledge to capture
 """,
     "docs/exec-plans/active/_template.md": """{marker}
@@ -279,6 +341,36 @@ List product, architecture, reliability, security, or delivery constraints.
 
 - Describe how the work will be verified.
 
+## Quality Gate
+
+Status: pending
+Minimum score: 8.0
+Average score: pending
+Last scored: pending
+
+| Dimension | Score | Notes |
+| --- | ---: | --- |
+| Product correctness | pending | Confirm the requested behavior is complete. |
+| UX and operator clarity | pending | Confirm the user or operator experience is understandable. |
+| Architecture and maintainability | pending | Confirm the implementation is clean and easy to change. |
+| Reliability and observability | pending | Confirm the validation loop and failure handling is sufficient. |
+| Security and data handling | pending | Confirm secrets and sensitive data are handled safely. |
+
+## Rework Required
+
+- Pending quality score.
+
+## Phase Continuity
+
+Mode: single-phase
+Workstream: none
+Current phase: none
+Next phase: none
+Continuation: none
+Next action: none
+Closure reason: This plan is not part of a longer workstream.
+Resume notes: none
+
 ## Durable Knowledge To Capture
 
 - List facts that must be written back into permanent docs before completion.
@@ -293,8 +385,10 @@ Summarize outcomes, follow-ups, and doc updates.
 Move finished plans here after:
 
 1. validation is complete
-2. permanent docs have been updated
-3. any remaining follow-ups are recorded in tech debt or new plans
+2. the quality gate has passed
+3. phase continuity has been recorded for multi-phase work
+4. permanent docs have been updated
+5. any remaining follow-ups are recorded in workstreams, tech debt, or new plans
 """,
     "docs/generated/db-schema.md": """{marker}
 # Generated DB Schema
@@ -399,6 +493,14 @@ QUESTION_CATALOG = [
     },
 ]
 
+QUALITY_DIMENSIONS = [
+    ("product_correctness", "Product correctness"),
+    ("ux_operator_clarity", "UX and operator clarity"),
+    ("architecture_maintainability", "Architecture and maintainability"),
+    ("reliability_observability", "Reliability and observability"),
+    ("security_data_handling", "Security and data handling"),
+]
+
 
 def detect_languages(files):
     ext_map = {}
@@ -597,11 +699,31 @@ def extract_knowledge_items(text):
     return items
 
 
+def extract_defect_items(text):
+    lines = text.splitlines()
+    section_index = find_section(lines, "## Defects To Resolve")
+    if section_index is None:
+        return []
+    items = []
+    for line in lines[section_index + 1 :]:
+        if line.startswith("## "):
+            break
+        stripped = line.strip()
+        if stripped.startswith("- ["):
+            items.append(stripped)
+    return items
+
+
 def knowledge_id_for(fact, destination):
     digest = hashlib.sha1(f"{clean_destination_text(destination)}\0{clean_fact_text(fact)}".encode()).hexdigest()
     return f"hk-{digest[:10]}"
 
 
+def defect_id_for(summary):
+    digest = hashlib.sha1(clean_fact_text(summary).encode()).hexdigest()
+    return f"bug-{digest[:10]}"
+
+
 def parse_knowledge_item(item):
     match = re.match(
         r"- \[(?P<status>[ xX])\]\s+"
@@ -623,6 +745,29 @@ def parse_knowledge_item(item):
     }
 
 
+def parse_defect_item(item):
+    match = re.match(
+        r"- \[(?P<status>[ xX])\]\s+"
+        r"(?:\[(?:id|bug):(?P<id>[A-Za-z0-9_.:-]+)\]\s+)?"
+        r"\[(?P<severity>P[0-3])\]\s+"
+        r"(?P<summary>.*?)"
+        r"(?:\s+\|\s+evidence:\s+(?P<evidence>.*?))?"
+        r"(?:\s+\|\s+fix:\s+(?P<fix>.+))?$",
+        item.strip(),
+    )
+    if not match:
+        return None
+    return {
+        "status": "closed" if match.group("status").lower() == "x" else "open",
+        "id": match.group("id"),
+        "severity": match.group("severity"),
+        "summary": clean_fact_text(match.group("summary")),
+        "evidence": clean_fact_text(match.group("evidence")) if match.group("evidence") else None,
+        "fix": clean_fact_text(match.group("fix")) if match.group("fix") else None,
+        "raw": item,
+    }
+
+
 def clean_fact_text(value):
     cleaned = value.strip()
     cleaned = cleaned.replace("`", "")
@@ -648,14 +793,482 @@ def replace_completion_notes(text, summary):
     return "\n".join(new_lines).rstrip() + "\n"
 
 
+def replace_section(text, heading, body):
+    lines = text.splitlines()
+    section_index = find_section(lines, f"## {heading}")
+    if section_index is None:
+        return text.rstrip() + f"\n\n## {heading}\n\n{body.rstrip()}\n"
+    end_index = len(lines)
+    for index in range(section_index + 1, len(lines)):
+        if lines[index].startswith("## "):
+            end_index = index
+            break
+    new_lines = lines[: section_index + 1] + ["", body.rstrip()] + lines[end_index:]
+    return "\n".join(new_lines).rstrip() + "\n"
+
+
+def quality_gate_for_plan(text):
+    lines = text.splitlines()
+    section_index = find_section(lines, "## Quality Gate")
+    if section_index is None:
+        return {"status": "missing", "minimum": None, "average": None, "scores": {}}
+    section_lines = []
+    for line in lines[section_index + 1 :]:
+        if line.startswith("## "):
+            break
+        section_lines.append(line)
+    section_text = "\n".join(section_lines)
+    status_match = re.search(r"^Status:\s*(?P<status>\w+)", section_text, flags=re.MULTILINE)
+    minimum_match = re.search(r"^Minimum score:\s*(?P<score>[0-9]+(?:\.[0-9]+)?)", section_text, flags=re.MULTILINE)
+    average_match = re.search(r"^Average score:\s*(?P<score>[0-9]+(?:\.[0-9]+)?)", section_text, flags=re.MULTILINE)
+    scores = {}
+    for _, label in QUALITY_DIMENSIONS:
+        row_match = re.search(
+            rf"^\|\s*{re.escape(label)}\s*\|\s*(?P<score>[0-9]+(?:\.[0-9]+)?)\s*\|",
+            section_text,
+            flags=re.MULTILINE,
+        )
+        if row_match:
+            scores[label] = float(row_match.group("score"))
+    return {
+        "status": status_match.group("status").lower() if status_match else "missing",
+        "minimum": float(minimum_match.group("score")) if minimum_match else None,
+        "average": float(average_match.group("score")) if average_match else None,
+        "scores": scores,
+    }
+
+
+def section_key_values(text, heading):
+    lines = text.splitlines()
+    section_index = find_section(lines, f"## {heading}")
+    if section_index is None:
+        return None
+    values = {}
+    for line in lines[section_index + 1 :]:
+        if line.startswith("## "):
+            break
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        normalized_key = key.strip().lower().replace(" ", "_")
+        values[normalized_key] = value.strip()
+    return values
+
+
+def phase_number_from_text(value):
+    match = re.search(r"\bphase[-_\s]*(?P<number>\d+)\b", value, flags=re.IGNORECASE)
+    if not match:
+        return None
+    return match.group("number")
+
+
+def plan_title(text):
+    for line in text.splitlines():
+        if line.startswith("# Execution Plan:"):
+            return line.split(":", 1)[1].strip()
+    return ""
+
+
+def default_workstream_id_from_plan(plan_path, text):
+    source = plan_path.stem
+    source = re.sub(r"^\d{4}-\d{2}-\d{2}-", "", source)
+    source = re.sub(r"phase[-_\s]*\d+", "", source, flags=re.IGNORECASE)
+    source = source.strip("-_ ")
+    if not source:
+        source = plan_title(text)
+        source = re.sub(r"phase[-_\s]*\d+", "", source, flags=re.IGNORECASE)
+    return slugify(source or "workstream")
+
+
+def phase_continuity_for_plan(plan_path, text):
+    values = section_key_values(text, "Phase Continuity")
+    detected_phase = phase_number_from_text(plan_path.stem) or phase_number_from_text(plan_title(text))
+    if values is None:
+        return {
+            "status": "missing",
+            "detected_phase": detected_phase,
+            "mode": None,
+            "workstream": None,
+            "current_phase": None,
+            "next_phase": None,
+            "continuation": None,
+            "next_action": None,
+            "closure_reason": None,
+            "resume_notes": None,
+        }
+    mode = values.get("mode", "").lower()
+    workstream = values.get("workstream")
+    current_phase = values.get("current_phase")
+    next_phase = values.get("next_phase")
+    continuation = values.get("continuation")
+    next_action = values.get("next_action")
+    closure_reason = values.get("closure_reason")
+    resume_notes = values.get("resume_notes")
+    return {
+        "status": "present",
+        "detected_phase": detected_phase,
+        "mode": mode,
+        "workstream": workstream,
+        "current_phase": current_phase,
+        "next_phase": next_phase,
+        "continuation": continuation,
+        "next_action": next_action,
+        "closure_reason": closure_reason,
+        "resume_notes": resume_notes,
+    }
+
+
+def is_empty_continuity_value(value):
+    if value is None:
+        return True
+    return value.strip().lower() in {"", "none", "pending", "unknown", "n/a", "-"}
+
+
+def phase_continuity_issues(repo, plan_path, plan_text):
+    continuity = phase_continuity_for_plan(plan_path, plan_text)
+    detected_phase = continuity["detected_phase"]
+    if continuity["status"] == "missing":
+        if detected_phase:
+            return [
+                {
+                    "severity": "error",
+                    "code": "missing-phase-continuity",
+                    "path": str(plan_path.relative_to(repo)),
+                    "message": "Phased plan is missing a Phase Continuity section.",
+                }
+            ]
+        return []
+    mode = continuity["mode"]
+    if mode in {"single-phase", "single", "none"} and not detected_phase:
+        return []
+    issues = []
+    relative_plan = str(plan_path.relative_to(repo))
+    if mode not in {"multi-phase", "phased", "paused", "completed", "stopped"} and detected_phase:
+        issues.append(
+            {
+                "severity": "error",
+                "code": "phase-mode-not-declared",
+                "path": relative_plan,
+                "message": "Plan name indicates a phase, but Phase Continuity does not declare multi-phase, paused, completed, or stopped mode.",
+            }
+        )
+    if is_empty_continuity_value(continuity["workstream"]):
+        issues.append(
+            {
+                "severity": "error",
+                "code": "missing-workstream",
+                "path": relative_plan,
+                "message": "Phased or multi-plan work must name a workstream in Phase Continuity.",
+            }
+        )
+    if is_empty_continuity_value(continuity["current_phase"]):
+        issues.append(
+            {
+                "severity": "error",
+                "code": "missing-current-phase",
+                "path": relative_plan,
+                "message": "Phased or multi-plan work must record the current phase.",
+            }
+        )
+    continuation = continuity["continuation"]
+    closure_reason = continuity["closure_reason"]
+    next_action = continuity["next_action"]
+    if mode in {"completed", "stopped"}:
+        if is_empty_continuity_value(closure_reason):
+            issues.append(
+                {
+                    "severity": "error",
+                    "code": "missing-phase-closure-reason",
+                    "path": relative_plan,
+                    "message": "Completed or stopped workstreams must explain why no next phase is needed.",
+                }
+            )
+        return issues
+    if is_empty_continuity_value(continuation):
+        issues.append(
+            {
+                "severity": "error",
+                "code": "missing-continuation",
+                "path": relative_plan,
+                "message": "Multi-phase work must point to a next active plan, workstreams ledger, tech debt item, or explicit closure.",
+            }
+        )
+    elif "workstreams.md" in continuation and not is_empty_continuity_value(continuity["workstream"]):
+        ledger = workstreams_path(repo)
+        if not ledger.exists() or continuity["workstream"] not in ledger.read_text():
+            issues.append(
+                {
+                    "severity": "error",
+                    "code": "missing-workstream-ledger-entry",
+                    "path": relative_plan,
+                    "message": "Phase Continuity points to workstreams.md, but the named workstream is not recorded there.",
+                }
+            )
+    if is_empty_continuity_value(next_action):
+        issues.append(
+            {
+                "severity": "error",
+                "code": "missing-next-action",
+                "path": relative_plan,
+                "message": "Multi-phase work must record a concrete next action for recovery.",
+            }
+        )
+    return issues
+
+
+def open_defects_for_plan(text):
+    open_items = []
+    for item in extract_defect_items(text):
+        parsed = parse_defect_item(item)
+        if parsed and parsed["status"] == "open":
+            open_items.append(parsed)
+    return open_items
+
+
+def render_quality_gate(scores, notes, minimum, open_defects=None):
+    open_defects = open_defects or []
+    average = sum(scores.values()) / len(scores)
+    low_dimensions = [
+        label for key, label in QUALITY_DIMENSIONS if scores[key] < minimum
+    ]
+    passed = average >= minimum and not low_dimensions and not open_defects
+    status = "pass" if passed else "fail"
+    lines = [
+        f"Status: {status}",
+        f"Minimum score: {minimum:.1f}",
+        f"Average score: {average:.1f}",
+        f"Last scored: {datetime.now(UTC).strftime('%Y-%m-%dT%H:%M:%SZ')}",
+        "",
+        "| Dimension | Score | Notes |",
+        "| --- | ---: | --- |",
+    ]
+    for key, label in QUALITY_DIMENSIONS:
+        note = notes.get(key) or "No note provided."
+        safe_note = note.replace("\n", " ").replace("|", "\\|").strip()
+        lines.append(f"| {label} | {scores[key]:.1f} | {safe_note} |")
+    return "\n".join(lines), passed, average, low_dimensions
+
+
+def render_rework_section(passed, average, minimum, low_dimensions, notes, open_defects=None):
+    open_defects = open_defects or []
+    if passed:
+        return "None. Quality gate passed."
+    lines = [
+        f"- Rework implementation until every quality dimension is at least {minimum:.1f}; current average is {average:.1f}.",
+    ]
+    for defect in open_defects:
+        evidence = f" Evidence: {defect['evidence']}." if defect.get("evidence") else ""
+        lines.append(
+            f"- Resolve {defect['id']} ({defect['severity']}): {defect['summary']}.{evidence}"
+        )
+    for key, label in QUALITY_DIMENSIONS:
+        if label in low_dimensions:
+            note = notes.get(key) or "No note provided."
+            lines.append(f"- Improve {label}: {note}")
+    return "\n".join(lines)
+
+
+def update_quality_gate(plan_path, scores, notes, minimum):
+    text = plan_path.read_text()
+    open_defects = open_defects_for_plan(text)
+    gate_text, passed, average, low_dimensions = render_quality_gate(scores, notes, minimum, open_defects)
+    updated = replace_section(text, "Quality Gate", gate_text)
+    updated = replace_section(
+        updated,
+        "Rework Required",
+        render_rework_section(passed, average, minimum, low_dimensions, notes, open_defects),
+    )
+    plan_path.write_text(updated)
+    return {
+        "status": "pass" if passed else "fail",
+        "minimum": minimum,
+        "average": round(average, 1),
+        "low_dimensions": low_dimensions,
+        "open_defects": [defect["id"] for defect in open_defects],
+    }
+
+
+def assert_quality_gate_passed(plan_text):
+    open_defects = open_defects_for_plan(plan_text)
+    if open_defects:
+        defects = "\n".join(
+            f"- {defect['id']} ({defect['severity']}): {defect['summary']}" for defect in open_defects
+        )
+        raise RuntimeError(
+            "Cannot close plan with unresolved defects:\n"
+            + defects
+            + "\nRun `defect-resolve`, re-run validation, and score again."
+        )
+    gate = quality_gate_for_plan(plan_text)
+    if gate["status"] != "pass":
+        raise RuntimeError(
+            "Cannot close plan until the quality gate passes. "
+            "Run `quality-score`, fix any `## Rework Required` items, then score again."
+        )
+    return gate
+
+
+def render_phase_continuity(mode, workstream, current_phase, next_phase, continuation, next_action, closure_reason, resume_notes):
+    return "\n".join(
+        [
+            f"Mode: {mode}",
+            f"Workstream: {workstream}",
+            f"Current phase: {current_phase}",
+            f"Next phase: {next_phase}",
+            f"Continuation: {continuation}",
+            f"Next action: {next_action}",
+            f"Closure reason: {closure_reason}",
+            f"Resume notes: {resume_notes}",
+        ]
+    )
+
+
+def update_phase_continuity(plan_path, mode, workstream, current_phase, next_phase, continuation, next_action, closure_reason, resume_notes):
+    text = plan_path.read_text()
+    detected_phase = phase_number_from_text(plan_path.stem) or phase_number_from_text(plan_title(text)) or "none"
+    resolved_workstream = workstream or default_workstream_id_from_plan(plan_path, text)
+    resolved_current_phase = current_phase or detected_phase
+    body = render_phase_continuity(
+        mode,
+        resolved_workstream,
+        resolved_current_phase,
+        next_phase,
+        continuation,
+        next_action,
+        closure_reason,
+        resume_notes,
+    )
+    plan_path.write_text(replace_section(text, "Phase Continuity", body))
+    return {
+        "status": "updated",
+        "mode": mode,
+        "workstream": resolved_workstream,
+        "current_phase": resolved_current_phase,
+        "next_phase": next_phase,
+        "continuation": continuation,
+        "next_action": next_action,
+    }
+
+
+def workstreams_path(repo):
+    return repo / "docs" / "exec-plans" / "workstreams.md"
+
+
+def workstream_table_insert_index(lines):
+    index_heading = find_section(lines, "## Index")
+    if index_heading is None:
+        return len(lines)
+    index = index_heading + 1
+    while index < len(lines) and lines[index].strip() == "":
+        index += 1
+    while index < len(lines) and not lines[index].startswith("| ID |"):
+        if lines[index].startswith("## "):
+            return index
+        index += 1
+    if index >= len(lines):
+        return index_heading + 1
+    index += 1
+    if index < len(lines) and lines[index].startswith("| ---"):
+        index += 1
+    while index < len(lines) and lines[index].startswith("|"):
+        index += 1
+    return index
+
+
+def append_workstream_entry(repo, workstream_id, status, current_plan, last_completed_plan, next_action, goal, resume_notes):
+    target = workstreams_path(repo)
+    ensure_parent(target)
+    if not target.exists():
+        target.write_text(DOC_FILES["docs/exec-plans/workstreams.md"].format(marker=MANAGED_MARKER))
+    text = target.read_text()
+    today = datetime.now(UTC).strftime("%Y-%m-%d")
+    row = (
+        f"| {workstream_id} | {status} | {current_plan or 'none'} | "
+        f"{last_completed_plan or 'none'} | {next_action or 'none'} | {today} |"
+    )
+    lines = text.splitlines()
+    replaced = False
+    updated_lines = []
+    for line in lines:
+        if line.startswith(f"| {workstream_id} |"):
+            updated_lines.append(row)
+            replaced = True
+        else:
+            updated_lines.append(line)
+    if not replaced:
+        insert_index = workstream_table_insert_index(updated_lines)
+        updated_lines.insert(insert_index, row)
+    detail = (
+        f"Status: {status}\n"
+        f"Goal: {goal or 'Record the durable goal for this workstream.'}\n"
+        f"Current plan: {current_plan or 'none'}\n"
+        f"Last completed plan: {last_completed_plan or 'none'}\n"
+        f"Next action: {next_action or 'none'}\n"
+        f"Resume notes: {resume_notes or 'Read the current or last completed plan before continuing.'}\n"
+        f"Last updated: {today}"
+    )
+    updated_text = "\n".join(updated_lines).rstrip() + "\n"
+    updated_text = replace_section(updated_text, workstream_id, detail)
+    target.write_text(updated_text)
+    return target
+
+
+def update_workstreams_after_plan_close(repo, active_relative_plan, completed_relative_plan):
+    target = workstreams_path(repo)
+    if not target.exists():
+        return
+    lines = target.read_text().splitlines()
+    updated = []
+    current_plan_was_closed = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("|") and not stripped.startswith("| ---") and not stripped.startswith("| ID |"):
+            cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+            if len(cells) == 6:
+                if cells[2] == active_relative_plan:
+                    cells[2] = "none"
+                    if cells[3] == "none":
+                        cells[3] = completed_relative_plan
+                if cells[3] == active_relative_plan:
+                    cells[3] = completed_relative_plan
+                updated.append("| " + " | ".join(cells) + " |")
+                continue
+        if line == f"Current plan: {active_relative_plan}":
+            updated.append("Current plan: none")
+            current_plan_was_closed = True
+            continue
+        if line == f"Last completed plan: {active_relative_plan}":
+            updated.append(f"Last completed plan: {completed_relative_plan}")
+            current_plan_was_closed = False
+            continue
+        if current_plan_was_closed and line == "Last completed plan: none":
+            updated.append(f"Last completed plan: {completed_relative_plan}")
+            current_plan_was_closed = False
+            continue
+        updated.append(line)
+        if line.startswith("## "):
+            current_plan_was_closed = False
+    target.write_text("\n".join(updated).rstrip() + "\n")
+
+
+def assert_phase_continuity_closed(repo, plan_path, plan_text):
+    issues = phase_continuity_issues(repo, plan_path, plan_text)
+    if issues:
+        messages = "\n".join(f"- {issue['code']}: {issue['message']}" for issue in issues)
+        raise RuntimeError(
+            "Cannot close plan until phase continuity is recorded:\n"
+            + messages
+            + "\nRun `phase-set` and update `workstreams.md` or `tech-debt-tracker.md` before closing."
+        )
+
+
 def append_knowledge_item(plan_path, fact, destination):
     text = plan_path.read_text()
     lines = text.splitlines()
     section_index = find_section(lines, "## Durable Knowledge To Capture")
     if section_index is None:
         raise ValueError("Plan is missing '## Durable Knowledge To Capture'")
-    placeholder = "- [ ] Add durable facts here as they emerge -> <destination-doc>"
-    filtered_lines = [line for line in lines if line.strip() != placeholder]
+    filtered_lines = [line for line in lines if line.strip() != DEFAULT_KNOWLEDGE_PLACEHOLDER]
     insert_index = section_index + 1
     while insert_index < len(filtered_lines) and not filtered_lines[insert_index].startswith("## "):
         insert_index += 1
@@ -666,11 +1279,126 @@ def append_knowledge_item(plan_path, fact, destination):
     return item, item_id
 
 
+def render_open_defect_rework(open_defects):
+    lines = ["- Resolve all open defects, then re-run validation and `quality-score`."]
+    for defect in open_defects:
+        evidence = f" Evidence: {defect['evidence']}." if defect.get("evidence") else ""
+        lines.append(f"- Resolve {defect['id']} ({defect['severity']}): {defect['summary']}.{evidence}")
+    return "\n".join(lines)
+
+
+def mark_quality_gate_blocked_by_defects(text):
+    open_defects = open_defects_for_plan(text)
+    if not open_defects:
+        return text
+    lines = text.splitlines()
+    section_index = find_section(lines, "## Quality Gate")
+    if section_index is None:
+        gate_text = "\n".join(
+            [
+                "Status: fail",
+                "Minimum score: 8.0",
+                "Average score: pending",
+                f"Last scored: {datetime.now(UTC).strftime('%Y-%m-%dT%H:%M:%SZ')}",
+                "",
+                "Blocked by unresolved defects. Run `defect-resolve`, re-run validation, then run `quality-score`.",
+            ]
+        )
+        text = replace_section(text, "Quality Gate", gate_text)
+    else:
+        end_index = len(lines)
+        for index in range(section_index + 1, len(lines)):
+            if lines[index].startswith("## "):
+                end_index = index
+                break
+        section_lines = lines[section_index + 1 : end_index]
+        has_status = False
+        updated_section = []
+        for line in section_lines:
+            if line.startswith("Status:"):
+                updated_section.append("Status: fail")
+                has_status = True
+            elif line.startswith("Last scored:"):
+                updated_section.append(f"Last scored: {datetime.now(UTC).strftime('%Y-%m-%dT%H:%M:%SZ')}")
+            else:
+                updated_section.append(line)
+        if not has_status:
+            updated_section.insert(0, "Status: fail")
+        lines = lines[: section_index + 1] + updated_section + lines[end_index:]
+        text = "\n".join(lines).rstrip() + "\n"
+    return replace_section(text, "Rework Required", render_open_defect_rework(open_defects))
+
+
+def append_defect_item(plan_path, severity, summary, evidence=None):
+    text = plan_path.read_text()
+    if find_section(text.splitlines(), "## Defects To Resolve") is None:
+        text = replace_section(text, "Defects To Resolve", DEFAULT_DEFECT_PLACEHOLDER)
+    lines = text.splitlines()
+    section_index = find_section(lines, "## Defects To Resolve")
+    if section_index is None:
+        raise ValueError("Plan is missing '## Defects To Resolve'")
+    filtered_lines = [line for line in lines if line.strip() != DEFAULT_DEFECT_PLACEHOLDER]
+    insert_index = section_index + 1
+    while insert_index < len(filtered_lines) and not filtered_lines[insert_index].startswith("## "):
+        insert_index += 1
+    item_id = defect_id_for(summary)
+    safe_summary = clean_fact_text(summary)
+    safe_evidence = clean_fact_text(evidence) if evidence else None
+    item = f"- [ ] [bug:{item_id}] [{severity}] {safe_summary}"
+    if safe_evidence:
+        item = f"{item} | evidence: {safe_evidence}"
+    updated_lines = filtered_lines[:insert_index] + [item] + filtered_lines[insert_index:]
+    plan_path.write_text(mark_quality_gate_blocked_by_defects("\n".join(updated_lines).rstrip() + "\n"))
+    return item, item_id
+
+
+def close_defect_line(line, fix_evidence):
+    updated = line.replace("- [ ]", "- [x]", 1)
+    if "| fix:" not in updated:
+        updated = f"{updated} | fix: {fix_evidence}"
+    return updated
+
+
+def mark_defect_resolved(plan_path, defect_id, fix_evidence):
+    if not defect_id:
+        raise ValueError("Provide --id to resolve a defect")
+    if not fix_evidence:
+        raise ValueError("Provide --fix-evidence or --fix-evidence-file to resolve a defect")
+    lines = plan_path.read_text().splitlines()
+    safe_fix = clean_fact_text(fix_evidence)
+    replaced = False
+    updated = []
+    for line in lines:
+        stripped = line.strip()
+        parsed = parse_defect_item(stripped)
+        if parsed and parsed["status"] == "open" and parsed["id"] == defect_id and not replaced:
+            updated.append(close_defect_line(line, safe_fix))
+            replaced = True
+        else:
+            updated.append(line)
+    if not replaced:
+        raise ValueError(f"Open defect not found for id: {defect_id}")
+    text = "\n".join(updated).rstrip() + "\n"
+    open_defects = open_defects_for_plan(text)
+    if open_defects:
+        text = replace_section(text, "Rework Required", render_open_defect_rework(open_defects))
+    else:
+        text = replace_section(
+            text,
+            "Rework Required",
+            "Defects resolved. Re-run validation and `quality-score` before closing.",
+        )
+    plan_path.write_text(text)
+
+
 def mark_knowledge_items_closed(text):
     lines = text.splitlines()
     updated = []
+    in_knowledge_section = False
     for line in lines:
-        if line.strip().startswith("- [ ]"):
+        if line.startswith("## "):
+            in_knowledge_section = line.strip().lower() == "## durable knowledge to capture"
+        if in_knowledge_section and line.strip().startswith("- [ ]") and line.strip() != DEFAULT_KNOWLEDGE_PLACEHOLDER:
             updated.append(line.replace("- [ ]", "- [x]", 1))
         else:
             updated.append(line)
@@ -802,6 +1530,24 @@ def completed_plan_dir(repo):
     return repo / "docs" / "exec-plans" / "completed"
 
 
+def plan_path_from_arg(repo, plan_arg):
+    raw_plan = Path(plan_arg)
+    if raw_plan.is_absolute():
+        plan_path = raw_plan.resolve()
+    else:
+        plan_path = (repo / raw_plan).resolve()
+
+    try:
+        relative_plan = str(plan_path.relative_to(repo.resolve()))
+    except ValueError as error:
+        raise ValueError(f"Plan must be inside repo: {plan_arg}") from error
+
+    if not plan_path.exists():
+        raise FileNotFoundError(f"Plan not found: {plan_path}")
+
+    return plan_path, relative_plan
+
+
 def create_plan(repo, slug, goal):
     plan_dir = active_plan_dir(repo)
     plan_dir.mkdir(parents=True, exist_ok=True)
@@ -813,6 +1559,7 @@ def create_plan(repo, slug, goal):
     content = PLAN_TEMPLATE.format(
         title=title.title(),
         goal=goal,
+        defect_section=DEFAULT_DEFECT_PLACEHOLDER,
         knowledge_section="- [ ] Add durable facts here as they emerge -> <destination-doc>",
     )
     plan_path.write_text(content)
@@ -820,11 +1567,16 @@ def create_plan(repo, slug, goal):
 
 
 def close_plan(repo, plan_relative_path, summary, force):
-    plan_path = repo / plan_relative_path
-    if not plan_path.exists():
-        raise FileNotFoundError(f"Plan not found: {plan_path}")
+    plan_path, active_relative_path = plan_path_from_arg(repo, plan_relative_path)
     text = plan_path.read_text()
-    open_items = [item for item in extract_knowledge_items(text) if item.startswith("- [ ]")]
+    if not force:
+        assert_quality_gate_passed(text)
+        assert_phase_continuity_closed(repo, plan_path, text)
+    open_items = [
+        item
+        for item in extract_knowledge_items(text)
+        if item.startswith("- [ ]") and item != DEFAULT_KNOWLEDGE_PLACEHOLDER
+    ]
     if open_items and not force:
         raise RuntimeError(
             "Cannot close plan with unresolved durable knowledge items:\n" + "\n".join(open_items)
@@ -835,6 +1587,8 @@ def close_plan(repo, plan_relative_path, summary, force):
     destination = completed_dir / plan_path.name
     destination.write_text(updated_text)
     plan_path.unlink()
+    completed_relative_path = str(destination.relative_to(repo))
+    update_workstreams_after_plan_close(repo, active_relative_path, completed_relative_path)
     return destination, open_items
 
 
@@ -846,6 +1600,7 @@ def check_harness(repo):
         "docs/QUALITY_SCORE.md",
         "docs/RELIABILITY.md",
         "docs/SECURITY.md",
+        "docs/exec-plans/workstreams.md",
         "docs/exec-plans/active/README.md",
         "docs/exec-plans/active/_template.md",
         "docs/exec-plans/completed/README.md",
@@ -869,7 +1624,40 @@ def check_harness(repo):
             if plan_path.name in {"README.md", "_template.md"}:
                 continue
             relative_plan = str(plan_path.relative_to(repo))
+            quality_gate = quality_gate_for_plan(plan_path.read_text())
+            if quality_gate["status"] == "missing":
+                issues.append(
+                    {
+                        "severity": "error",
+                        "code": "missing-quality-gate",
+                        "path": relative_plan,
+                        "message": "Active plan is missing a Quality Gate section.",
+                    }
+                )
+            elif quality_gate["status"] != "pass":
+                issues.append(
+                    {
+                        "severity": "error",
+                        "code": "quality-gate-not-passing",
+                        "path": relative_plan,
+                        "message": "Active plan quality gate has not passed; score the work and finish rework before handoff.",
+                    }
+                )
+            for defect in open_defects_for_plan(plan_path.read_text()):
+                issues.append(
+                    {
+                        "severity": "error",
+                        "code": "open-defect",
+                        "path": relative_plan,
+                        "id": defect["id"],
+                        "defect_severity": defect["severity"],
+                        "message": f"Active plan has an unresolved defect: {defect['summary']}",
+                    }
+                )
+            issues.extend(phase_continuity_issues(repo, plan_path, plan_path.read_text()))
             for item in extract_knowledge_items(plan_path.read_text()):
+                if item == DEFAULT_KNOWLEDGE_PLACEHOLDER:
+                    continue
                 parsed = parse_knowledge_item(item)
                 if not parsed:
                     issues.append(
@@ -905,6 +1693,34 @@ def check_harness(repo):
                         }
                     )
 
+    ledger = workstreams_path(repo)
+    if ledger.exists():
+        for index, line in enumerate(ledger.read_text().splitlines(), start=1):
+            stripped = line.strip()
+            if not stripped.startswith("|") or stripped.startswith("| ---") or stripped.startswith("| ID |"):
+                continue
+            cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+            if len(cells) != 6:
+                continue
+            workstream_id, _, current_plan, last_completed_plan, _, _ = cells
+            for label, plan_value in [
+                ("current plan", current_plan),
+                ("last completed plan", last_completed_plan),
+            ]:
+                if plan_value in {"", "none", "n/a", "-"}:
+                    continue
+                if not (repo / plan_value).exists():
+                    issues.append(
+                        {
+                            "severity": "error",
+                            "code": "missing-workstream-plan-reference",
+                            "path": str(ledger.relative_to(repo)),
+                            "line": index,
+                            "workstream": workstream_id,
+                            "message": f"Workstream {workstream_id} references missing {label}: {plan_value}",
+                        }
+                    )
+
     return {
         "repo": str(repo),
         "status": "pass" if not issues else "fail",
@@ -1004,11 +1820,21 @@ def load_json(path):
 def write_json(path, payload):
     output = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
     if path:
-        Path(path).write_text(output)
+        target = Path(path)
+        ensure_parent(target)
+        target.write_text(output)
     else:
         print(output, end="")
 
 
+def read_text_arg(value=None, file_path=None, label="value"):
+    if value and file_path:
+        raise ValueError(f"Use either --{label} or --{label}-file, not both")
+    if file_path:
+        return Path(file_path).read_text().strip()
+    return value
+
+
 def command_analyze(args):
     repo = Path(args.repo).resolve()
     analysis = analyze_repo(repo)
@@ -1044,14 +1870,43 @@ def command_plan_start(args):
 
 def command_knowledge_log(args):
     repo = Path(args.repo).resolve()
-    plan_path = repo / args.plan
-    if not plan_path.exists():
-        raise FileNotFoundError(f"Plan not found: {plan_path}")
-    item, item_id = append_knowledge_item(plan_path, args.fact, args.destination)
+    plan_path, _ = plan_path_from_arg(repo, args.plan)
+    fact = read_text_arg(args.fact, args.fact_file, "fact")
+    if not fact:
+        raise ValueError("Provide --fact or --fact-file")
+    item, item_id = append_knowledge_item(plan_path, fact, args.destination)
     result = {"repo": str(repo), "plan": str(plan_path), "id": item_id, "logged": item}
     write_json(args.output, result)
 
 
+def command_defect_log(args):
+    repo = Path(args.repo).resolve()
+    plan_path, _ = plan_path_from_arg(repo, args.plan)
+    summary = read_text_arg(args.summary, args.summary_file, "summary")
+    evidence = read_text_arg(args.evidence, args.evidence_file, "evidence")
+    if not summary:
+        raise ValueError("Provide --summary or --summary-file")
+    item, item_id = append_defect_item(plan_path, args.severity, summary, evidence=evidence)
+    result = {"repo": str(repo), "plan": str(plan_path), "id": item_id, "logged": item, "status": "fail"}
+    write_json(args.output, result)
+    raise SystemExit(1)
+
+
+def command_defect_resolve(args):
+    repo = Path(args.repo).resolve()
+    plan_path, _ = plan_path_from_arg(repo, args.plan)
+    fix_evidence = read_text_arg(args.fix_evidence, args.fix_evidence_file, "fix-evidence")
+    mark_defect_resolved(plan_path, args.id, fix_evidence)
+    result = {
+        "repo": str(repo),
+        "plan": str(plan_path),
+        "id": args.id,
+        "status": "resolved",
+        "fix_evidence": fix_evidence,
+    }
+    write_json(args.output, result)
+
+
 def command_plan_close(args):
     repo = Path(args.repo).resolve()
     destination, unresolved = close_plan(repo, args.plan, args.summary, args.force)
@@ -1064,26 +1919,91 @@ def command_plan_close(args):
     write_json(args.output, result)
 
 
+def score_arg(args, name):
+    value = getattr(args, name)
+    if value < 0 or value > 10:
+        raise ValueError(f"{name.replace('_', '-')} must be between 0 and 10")
+    return float(value)
+
+
+def command_quality_score(args):
+    repo = Path(args.repo).resolve()
+    plan_path, _ = plan_path_from_arg(repo, args.plan)
+    scores = {
+        "product_correctness": score_arg(args, "product_correctness"),
+        "ux_operator_clarity": score_arg(args, "ux_operator_clarity"),
+        "architecture_maintainability": score_arg(args, "architecture_maintainability"),
+        "reliability_observability": score_arg(args, "reliability_observability"),
+        "security_data_handling": score_arg(args, "security_data_handling"),
+    }
+    notes = {
+        "product_correctness": args.product_note,
+        "ux_operator_clarity": args.ux_note,
+        "architecture_maintainability": args.architecture_note,
+        "reliability_observability": args.reliability_note,
+        "security_data_handling": args.security_note,
+    }
+    result = update_quality_gate(plan_path, scores, notes, args.minimum)
+    result.update({"repo": str(repo), "plan": str(plan_path)})
+    write_json(args.output, result)
+    if result["status"] != "pass":
+        raise SystemExit(1)
+
+
+def command_phase_set(args):
+    repo = Path(args.repo).resolve()
+    plan_path, _ = plan_path_from_arg(repo, args.plan)
+    result = update_phase_continuity(
+        plan_path,
+        args.mode,
+        args.workstream,
+        args.current_phase,
+        args.next_phase,
+        args.continuation,
+        args.next_action,
+        args.closure_reason,
+        args.resume_notes,
+    )
+    result.update({"repo": str(repo), "plan": str(plan_path)})
+    write_json(args.output, result)
+
+
+def command_workstream_upsert(args):
+    repo = Path(args.repo).resolve()
+    target = append_workstream_entry(
+        repo,
+        args.id,
+        args.status,
+        args.current_plan,
+        args.last_completed_plan,
+        args.next_action,
+        args.goal,
+        args.resume_notes,
+    )
+    result = {"repo": str(repo), "workstreams": str(target), "id": args.id, "status": "updated"}
+    write_json(args.output, result)
+
+
 def command_knowledge_mark_written(args):
     repo = Path(args.repo).resolve()
-    plan_path = repo / args.plan
-    if not plan_path.exists():
-        raise FileNotFoundError(f"Plan not found: {plan_path}")
+    plan_path, _ = plan_path_from_arg(repo, args.plan)
+    fact = read_text_arg(args.fact, args.fact_file, "fact")
+    evidence = read_text_arg(args.evidence, args.evidence_file, "evidence")
     mark_single_knowledge_item_written(
         repo,
         plan_path,
-        args.fact,
+        fact,
         args.destination,
         append=args.append,
         knowledge_id=args.id,
-        evidence=args.evidence,
+        evidence=evidence,
     )
     result = {
         "repo": str(repo),
         "plan": str(plan_path),
-        "marked_written": args.id or args.fact,
+        "marked_written": args.id or fact,
         "destination": args.destination,
-        "evidence": args.evidence,
+        "evidence": evidence,
     }
     write_json(args.output, result)
 
@@ -1139,18 +2059,41 @@ def build_parser():
     knowledge_log = subparsers.add_parser("knowledge-log")
     knowledge_log.add_argument("--repo", required=True)
     knowledge_log.add_argument("--plan", required=True)
-    knowledge_log.add_argument("--fact", required=True)
+    knowledge_log.add_argument("--fact")
+    knowledge_log.add_argument("--fact-file")
     knowledge_log.add_argument("--destination", required=True)
     knowledge_log.add_argument("--output")
     knowledge_log.set_defaults(func=command_knowledge_log)
 
+    defect_log = subparsers.add_parser("defect-log")
+    defect_log.add_argument("--repo", required=True)
+    defect_log.add_argument("--plan", required=True)
+    defect_log.add_argument("--severity", choices=["P0", "P1", "P2", "P3"], required=True)
+    defect_log.add_argument("--summary")
+    defect_log.add_argument("--summary-file")
+    defect_log.add_argument("--evidence")
+    defect_log.add_argument("--evidence-file")
+    defect_log.add_argument("--output")
+    defect_log.set_defaults(func=command_defect_log)
+
+    defect_resolve = subparsers.add_parser("defect-resolve")
+    defect_resolve.add_argument("--repo", required=True)
+    defect_resolve.add_argument("--plan", required=True)
+    defect_resolve.add_argument("--id", required=True)
+    defect_resolve.add_argument("--fix-evidence")
+    defect_resolve.add_argument("--fix-evidence-file")
+    defect_resolve.add_argument("--output")
+    defect_resolve.set_defaults(func=command_defect_resolve)
+
     knowledge_mark_written = subparsers.add_parser("knowledge-mark-written")
     knowledge_mark_written.add_argument("--repo", required=True)
     knowledge_mark_written.add_argument("--plan", required=True)
     knowledge_mark_written.add_argument("--id")
     knowledge_mark_written.add_argument("--fact")
+    knowledge_mark_written.add_argument("--fact-file")
     knowledge_mark_written.add_argument("--destination")
     knowledge_mark_written.add_argument("--evidence")
+    knowledge_mark_written.add_argument("--evidence-file")
     knowledge_mark_written.add_argument("--append", action="store_true")
     knowledge_mark_written.add_argument("--output")
     knowledge_mark_written.set_defaults(func=command_knowledge_mark_written)
@@ -1163,6 +2106,57 @@ def build_parser():
     plan_close.add_argument("--output")
     plan_close.set_defaults(func=command_plan_close)
 
+    quality_score = subparsers.add_parser("quality-score")
+    quality_score.add_argument("--repo", required=True)
+    quality_score.add_argument("--plan", required=True)
+    quality_score.add_argument("--minimum", type=float, default=8.0)
+    quality_score.add_argument("--product-correctness", type=float, required=True)
+    quality_score.add_argument("--ux-operator-clarity", type=float, required=True)
+    quality_score.add_argument("--architecture-maintainability", type=float, required=True)
+    quality_score.add_argument("--reliability-observability", type=float, required=True)
+    quality_score.add_argument("--security-data-handling", type=float, required=True)
+    quality_score.add_argument("--product-note", default="")
+    quality_score.add_argument("--ux-note", default="")
+    quality_score.add_argument("--architecture-note", default="")
+    quality_score.add_argument("--reliability-note", default="")
+    quality_score.add_argument("--security-note", default="")
+    quality_score.add_argument("--output")
+    quality_score.set_defaults(func=command_quality_score)
+
+    phase_set = subparsers.add_parser("phase-set")
+    phase_set.add_argument("--repo", required=True)
+    phase_set.add_argument("--plan", required=True)
+    phase_set.add_argument(
+        "--mode",
+        choices=["single-phase", "multi-phase", "paused", "completed", "stopped"],
+        required=True,
+    )
+    phase_set.add_argument("--workstream")
+    phase_set.add_argument("--current-phase")
+    phase_set.add_argument("--next-phase", default="none")
+    phase_set.add_argument("--continuation", default="none")
+    phase_set.add_argument("--next-action", default="none")
+    phase_set.add_argument("--closure-reason", default="none")
+    phase_set.add_argument("--resume-notes", default="none")
+    phase_set.add_argument("--output")
+    phase_set.set_defaults(func=command_phase_set)
+
+    workstream_upsert = subparsers.add_parser("workstream-upsert")
+    workstream_upsert.add_argument("--repo", required=True)
+    workstream_upsert.add_argument("--id", required=True)
+    workstream_upsert.add_argument(
+        "--status",
+        choices=["active", "paused", "completed", "stopped"],
+        required=True,
+    )
+    workstream_upsert.add_argument("--current-plan", default="none")
+    workstream_upsert.add_argument("--last-completed-plan", default="none")
+    workstream_upsert.add_argument("--next-action", required=True)
+    workstream_upsert.add_argument("--goal", default="")
+    workstream_upsert.add_argument("--resume-notes", default="")
+    workstream_upsert.add_argument("--output")
+    workstream_upsert.set_defaults(func=command_workstream_upsert)
+
     check = subparsers.add_parser("check")
     check.add_argument("--repo", required=True)
     check.add_argument("--output")