interface:
  display_name: "OT Project Description Builder"
  short_description: "Build milestone-based OT project descriptions"
  default_prompt: "Use $ot-project-description-builder to develop an OT project description and a separate chat-only milestone handoff."

# OT Authority and Scope Rules

Use the current statute, current DoD policy, and the agreement file as controlling sources. This reference prevents a technical project description from becoming an unsupported authority determination.

## Authority map

### 10 U.S.C. 4021 Research OT

- Covers basic, applied, and advanced research projects.
- Under subsection (e)(2), Government funds should, to the extent the Secretary determines practicable, not exceed the total provided by other parties.
- Do not turn that direction into an automatic 50/50 rule or automatic 100-percent Government arrangement. Record the approved contribution arrangement and source.

### 10 U.S.C. 4022 Prototype OT

The statute includes proof of concept, model, process or business process, reverse engineering for obsolescence, pilot or novel commercial application, agile development, creation or demonstration of operational utility, and combinations of those activities. TRL is useful for some projects but is not a statutory prerequisite.

Require the user or Agreements Officer to identify one subsection (d)(1) condition:

| Path | Condition | Project-description treatment |
|---|---|---|
| A | At least one nontraditional defense contractor or nonprofit research institution participates to a significant extent | Record the participant and user-supplied significance basis. Do not make the finding. |
| B | All significant non-Government participants are small businesses or nontraditional defense contractors | Record the participant list and user-supplied statuses. Do not make the finding. |
| C | At least one-third of total project cost is paid from non-Federal sources | Record the approved ratio, cash or in-kind form, valuation, and source without dollar amounts. |
| D | The senior procurement executive determines in writing that exceptional circumstances justify the OT | Record the determination date or `PENDING`. Do not invent or characterize the determination. |

There is no Path D competition-commitment condition.

### 10 U.S.C. 4022(f) Follow-On Production

- A prototype transaction may provide for one or more follow-on production contracts or transactions.
- A noncompetitive follow-on requires the statutory competitive-selection and successful-completion conditions. Record user-supplied facts, but do not decide either condition.
- Do not require a production-ready TRL that the statute does not state.
- Do not promise a follow-on award or state that prototype completion creates an entitlement.
- Section 4022(d) does not apply to a follow-on under subsection (f). Use the negotiated contribution arrangement supplied for the production action.

## Participant status

Under 10 U.S.C. 3014, a nontraditional defense contractor is an entity that is not currently performing and has not performed, for at least the year preceding the solicitation, a DoD contract or subcontract subject to full Cost Accounting Standards coverage.

Do not substitute a contract-dollar threshold, consortium membership, commercial-item status, small-business status, or self-certification for the Agreements Officer's determination. A nonprofit research institution is separately recognized in 4022(d)(1)(A).

## Data rights

OT data rights are negotiated in the agreement. For each deliverable category, record:

- Background material and its owner
- Agreement-generated material
- Government use, disclosure, modification, and sublicensing rights
- Delivery format and marking
- License duration and purpose
- Any specifically incorporated framework or clause

FAR Part 27 or DFARS clauses may inform negotiations, but they are not controlling merely because the project supports DoD. Do not default to Government Purpose Rights, Unlimited Rights, or performer ownership.

## Project-description boundary

The project description may state the approved authority and contribution arrangement as agreement facts. It must not:

- Originate the authority, status, significant-participation, exceptional-circumstances, successful-completion, or follow-on determination
- Include cost or funding arithmetic
- State that a contribution path guarantees follow-on eligibility
- Treat TRL as mandatory when another maturity model fits better
- Claim that all FAR or DFARS provisions are categorically irrelevant; use only requirements incorporated by the agreement or controlling policy

## Primary sources

- 10 U.S.C. 3014, Nontraditional defense contractor
- 10 U.S.C. 4021, Research projects: transactions other than contracts and grants
- 10 U.S.C. 4022, Authority of the Department of Defense to carry out certain prototype projects
- DoD Other Transaction Guide, OUSD(A&S), July 2023, Version 2.0
- Guide to Research Other Transactions, OUSD(R&E), February 2026

# OT Project Description Specification

Use a supplied agency or consortium template as the design and section authority. Without one, use US Letter portrait, 1-inch margins, a restrained formal-business style, page numbers, real Word styles, and a dynamic Table of Contents when the document has more than eight main sections.

## First-page decision brief

Before front matter, use a compact decision brief with five labeled elements:
prototype objective, decision supported, pivotal milestones, major assumptions,
and program-team next action. Make this the page a busy Agreements Officer or
program manager can use without reading the whole artifact. Use a route-specific
title such as "Prototype Delivery Plan" or "Milestone Change Register," not a
generic report name. The brief must not include pricing or make a reserved
determination.

The cover eyebrow or kicker, the cover title block, and the running header MUST
all name the same product. A Project Description must never carry another
route's label (for example "Prototype Delivery Plan") on its cover while its
running header says "Project Description". Verify the three labels agree before
delivery.

## Front matter

- Project title
- `Other Transaction Project Description`
- Government organization and performer, or `To Be Determined`
- Agreement number placeholder
- Authority as user-confirmed
- Version and date
- Distribution or handling marking only when supplied

Do not include the milestone handoff, price, cost, funding, staffing, or routing information.

## Section order

Use this relative order. A supplied template may rename or renumber sections, but it must preserve their functions.

### 1. Agreement Overview

- Purpose and project type
- User-confirmed statutory authority
- Parties and agreement structure
- Authority, participant-status, contribution, or follow-on facts marked `PENDING` when unresolved

### 2. Technical Background and Current State

- Problem or operational need
- Existing capability and evidence
- Prior work and present maturity
- Why this project is needed, without making the legal vehicle-selection determination

### 3. Project Objectives

For each objective state the capability, threshold, environment, verification method, and related completion evidence. Use TRL only when supported.

### 4. Technical Approach by Phase

For each phase state objective, entry conditions, duration, intended outcomes, risks retired, dependencies, and phase-exit criterion. Preserve performer flexibility unless the Government intentionally prescribes a method.

### 5. Milestone Schedule

Use one table:

`Milestone ID | Phase | Description | Deliverables Due | Completion Criteria | Timing or Sequence | Payment Type`

- Use the approved IDs and sequence.
- `Payment Type` is Fixed, Cost-Type, Mixed, or `PENDING` only when supplied.
- Completion criteria must identify objective evidence and acceptance responsibility.
- Do not include payment amounts, estimated labor, rates, ceilings, funding, or contribution arithmetic.

### 6. Deliverables

Use:

`ID | Title | Format | Due Trigger | Acceptance Criteria | Rights Category`

Due Trigger references a milestone or event, not an invented date. Include only deliverables mapped to project objectives, governance, or transition.

### 7. Data Rights

Separate background from agreement-generated material and state the supplied license posture by deliverable category. State markings, delivery format, Government uses, and unresolved negotiations. Do not present FAR or DFARS clauses as controlling unless incorporated.

### 8. Period of Performance

State total period, phase durations, sequencing, external dependencies, and the effect of go or no-go decisions. Use dates only when supplied.

### 9. Government Responsibilities

State Government-furnished property, information, facilities, systems access, test resources, review roles, and availability dates. Use `None identified` only when confirmed.

### 10. Key Personnel

State only roles, minimum qualifications, responsibilities, and substitution process. Do not include staffing counts, FTE, labor hours, SOC codes, or rates.

### 11. Reporting and Oversight

State technical reviews, status and risk reporting, milestone-review process, issue escalation, records, and acceptance roles.

### 12. Contribution Arrangement, when applicable

State the user-approved authority context, ratio, cash or in-kind treatment, valuation method, tracking, and source. Do not include dollar amounts, Government obligations, funding profiles, or calculations. Do not say the arrangement guarantees a follow-on.

### 13. Production Follow-On Provisions, when applicable

State transition planning and the user-supplied predecessor, selection, and completion facts. Make all follow-on language conditional on the Agreements Officer's determination. Do not promise award, require an invented TRL, or state that 4022(d) applies to the follow-on.

### 14. Constraints and Assumptions

Use:

`ID | Assumption or Constraint | Basis | Owner | Closeout Trigger`

Every `[TBD]` elsewhere in the document must have a matching row that names the owner and a concrete closeout action such as agreement modification, milestone review, or written Agreements Officer confirmation.

## Language and construction

- Use `The performer shall demonstrate...`, `The prototype shall achieve...`, and `The Government will provide...` when those obligations are approved.
- Use `Agreements Officer`, not `Contracting Officer`, unless a source template intentionally uses another title.
- Avoid CLIN, QASP, AQL, option-year, task-order, and FAR-clause language.
- Use real Heading 1, 2, and 3 styles, real lists, explicit table widths and cell margins, repeating table headers, and no fixed row heights.
- Keep headings with following content and prevent rows from splitting when practical.
- Use a page-number field and set Word to update fields on open.
- A Contents section must contain a real, well-formed TOC field (each `fldChar`
  and `instrText` in its own run) or be omitted entirely. Never ship
  instructional or template residue such as "Table of Contents updates
  automatically in Word." as visible document text; if the cached field result
  cannot show real TOC entries, leave the field result empty for Word to
  populate on open.
- Do not place prompts, tests, skill names, file paths, internal workpapers, or tool instructions in the document.
- Use a restrained color accent, a short executive table, and a visual rhythm
  appropriate to the route. A revision foregrounds before/after effects; a
  project description foregrounds the execution path. Do not clone identical
  section sequences or cover treatment across route products.
- Put source notes and validation detail in a concise Evidence and Assumptions
  appendix when needed; keep the body focused on executable scope and decisions.

# Chat-Only Milestone Handoff

Emit this handoff only after the user approved the milestone structure and the `.docx` passed available validation. It is an internal Government workpaper in the conversation, never a file, document section, appendix, or attachment.

Use this heading and notice:

```text
=== MILESTONE HANDOFF TABLE: FOR OT COST ANALYSIS ===
Internal Government workpaper. Not part of the OT project description.
Do not paste this table into the agreement file.
```

Use these columns:

`Milestone ID | Phase | Objective | Est. Duration | Deliverables | Completion Evidence | Timing or Sequence | Payment Type | TRL In/Out | Notes`

Rules:

- Include every approved milestone and preserve its ID.
- `Est. Duration` means calendar time from phase start or prior milestone completion, not labor effort.
- Preserve user-supplied Payment Type. Use `PENDING` rather than guessing.
- Use TRL only when approved; otherwise enter `N/A` and describe maturity evidence in Notes.
- Put user overrides, derivation, dependencies, unresolved decisions, and completion-evidence ownership in Notes.
- Do not include price, proposed amount, labor rate, fee, funding, should-cost, or price-reasonableness language.

After the table provide:

```text
Authority: <4021 research | 4022 prototype | 4022(f) follow-on production>
Prototype Path: <A | B | C | D | N/A | PENDING>
Contribution Arrangement: <approved ratio and cash/in-kind treatment | PENDING>
Contribution Source: <document/date/user confirmation | PENDING>
Project Start: <YYYY-MM | PENDING>
Performance Locations: <approved locations | PENDING>
Total Period of Performance: <calendar duration>
```

End with:

`This approved scope handoff is ready for OT Cost Analysis. The cost skill should preserve these milestones and ask only for missing cost inputs.`

## Separation audit

The final `.docx` must not contain:

- The handoff heading or notice
- `OT Cost Analysis`, skill invocation, or routing prose
- Internal-workpaper language
- Pricing, proposed amounts, should-costs, fees, labor rates, funding, or Government budget data

The conversation may contain the handoff because it is explicitly outside the agreement artifact.

# Professional product standard

This file is the canonical source for the copy packaged with each 1102tools skill.
The packaged copies must remain identical to this file.

## Product judgment

Produce a finished professional work product, not a record of the process used
to create it. Write for the person who must understand, use, approve, or act on
the result.

Exercise editorial judgment. Include material that improves the reader's
understanding or decision. Omit material merely because it was collected,
available, or easy to generate. Every page, section, table, and visual must earn
its place.

Match the structure, length, voice, and visual treatment to the assignment.
Do not reuse a universal report outline. A short decision card, formal
contract-file document, analytical workbook, landscape, timeline, or longer
consulting report may all be correct products for different requests.

Lead with the useful output. Research mechanics, process narration,
methodology, limitations, and compliance controls are secondary unless the
reader's purpose makes one of them the product.

## Controlled freedom

Route rules define the substantive outcome and genuine formal boundaries. They
do not prescribe identical headings, page counts, layouts, or section order
unless a law, supplied template, calculation model, or downstream interface
requires it.

Choose the clearest form for each idea:

- prose for explanation and judgment;
- tables for real comparison or repeated fields;
- cards, profiles, matrices, timelines, charts, and callouts when they improve
  comprehension;
- appendices only for material the intended reader may reasonably need.

Do not put paragraph-length narrative in narrow table cells. Do not repeat the
same information as a callout, table, and prose section unless each form serves
a different reader need.

Use a restrained, coherent design with clear hierarchy, readable typography,
comfortable spacing, and accessible contrast. Treat examples as quality
references, not templates to copy.

## Paid-value standard

The primary artifact should contain the analysis, comparison, requirements,
model, or operating guidance the customer is paying to receive. Audit material
must remain subordinate.

Before delivery, remove:

- generic background the intended reader already knows;
- duplicated findings or actions;
- query logs, tool operations, sanitized parameters, and internal record
  mechanics;
- generic owners, gates, scenarios, or warnings invented to fill a template;
- boilerplate disclaimers repeated in multiple sections;
- empty sections and tables that merely announce missing content.

When evidence is insufficient for the promised product, say so plainly and
provide the useful narrower result or acquisition plan for the missing evidence.
Do not pad an evidence gap into a document that resembles a completed analysis.

## Reader-facing source citations

Internal evidence identifiers such as `E001` may remain in a private research
record for backward compatibility, but they never appear in a customer-facing
artifact.

Assign each distinct reader-visible source an identifier in order of first
appearance: `S1`, `S2`, `S3`, with no leading zeros. Reuse the same identifier
wherever that source supports another claim. Cite sources beside the supported
claim using forms such as `[S1]`, `[S1, S4]`, or `[S1-S3]`.

End a sourced report with a concise `Source Register`. Each entry uses the
corresponding identifier and provides enough information to verify the source:
publisher or organization, title or record identity, relevant date, and a
clickable public URL or supplied-document locator. Deduplicate sources. Do not
display internal source-class tokens or a query-by-query research log.

Native legal and acquisition citations such as `FAR 10.001`, a docket number,
PIID, UEI, or document section remain in their ordinary form. Add an `S` citation
when the artifact also needs a link to the supporting source; do not replace the
native citation with an opaque source number.

For workbooks, source notes and benchmark rows may use `S` identifiers that
resolve to a Sources or Raw Data register. Formula cells and internal validation
IDs are not reader-facing source citations.

## Proportionate boundaries

Accuracy, authority boundaries, unresolved decisions, and limitations remain
mandatory when material. Present them once, in the least intrusive form that
keeps the product honest. A concise note or callout is preferable to a recurring
legalistic section when the reader needs the answer more than a compliance
lecture.

Do not weaken a formal SOW/PWS, OT project description, acquisition-policy
status analysis, or auditable cost model for stylistic reasons. Formal and
mathematical requirements remain hard constraints. Apply taste to hierarchy,
selection, explanation, and delivery view, not to the removal of necessary
substance.

## Final editorial review

After technical validation and rendering, review the complete artifact as a
demanding customer:

- Is the useful result apparent immediately?
- Did the author select and synthesize rather than dump everything collected?
- Does each section materially advance the reader's work?
- Are sources integrated credibly without dominating the product?
- Are limitations accurate and proportionate?
- Does the artifact feel composed for this assignment rather than populated
  from a universal template?
- Is this work product an experienced professional could confidently sell?

Revise until the answer to every applicable question is yes. Structural
validation is a technical floor, not the release decision.

# Question Blocks

Ask only for missing facts. Use the host's structured question tool when available; otherwise use numbered questions with an `Other` or free-text path. Batch related items, but do not cross a required approval gate in the same response.

## Compact reusable context record

Capture these facts once and reuse them across the project description,
handoff, revision, and cost analysis: agency mission; prototype objective;
baseline; authority and path facts; participants; locations; data and security
boundaries; transition intent; and the decision owner for each pending item.
Do not ask a later route to restate this record unless a fact changes.

## Stage A: authority and acquisition frame

1. Which authority has the Agreements Officer identified: 10 U.S.C. 4021 research, 4022 prototype, or 4022(f) follow-on production?
2. For a prototype, which 4022(d)(1) path applies: A, B, C, or D? What is the source or determination status?
3. What participant-status and significant-participation facts has the Agreements Officer confirmed?
4. What contribution arrangement is approved, including ratio, cash or in-kind form, valuation, and source? Use `PENDING` when undecided.
5. Is the action direct or consortium-based? Is there a required template?
6. What source documents control the technical scope?

For a follow-on production action also ask for the predecessor prototype, selection facts, completion facts, and user-confirmed transition intent. Do not make the statutory findings.

## Stage B1: outcome and baseline

1. What problem or operational need must the project address?
2. What exists today, and what evidence supports that baseline?
3. What observable capability must exist at completion?
4. Which quantitative thresholds, environments, interfaces, or user conditions define success?
5. What major technical, operational, schedule, or integration risks must be retired?

If the user uses TRL, collect entry level, target level, supporting evidence, and the assessment owner. Otherwise use observable maturity statements.

## Stage B2: phases and milestones

For each phase or work segment collect:

- Objective and duration
- Entry conditions
- Required activity or outcome
- Deliverables
- Completion evidence and reviewer
- Go or no-go decision and off-ramp
- Dependencies and Government actions
- Payment Type supplied by the user, or `PENDING`

Each completion criterion must be specific, measurable, testable, and capable of an objective pass or fail decision. Avoid `satisfactory`, `as needed`, or `as determined by the Government` without a measurable test.

## Stage B3: agreement execution details

Collect only applicable items:

- Prototype units, software releases, datasets, models, interfaces, and test events
- Places of performance and Government test or demonstration environments
- Government-furnished property, information, systems access, and personnel
- Security, privacy, export-control, and controlled-information boundaries supplied by the user
- Data-rights posture by deliverable category
- Key roles and substitution process
- Review, reporting, risk, and issue cadence
- Transition intent and follow-on provisions
- Constraints, assumptions, unresolved thresholds, owners, and closeout triggers

## Scope-reduction choices

Show the consequence of each proposed reduction without estimating savings unless OT Cost Analysis supplies them. Useful levers include:

- Defer a phase or target capability
- Reduce prototype units or environments
- Narrow interfaces or user groups
- Combine reviews without weakening completion evidence
- Defer noncritical deliverables

For each option show what capability, evidence, risk retirement, schedule, or transition readiness is lost. Obtain approval for the revised milestone table before editing the document.

# Runtime Adaptation

Describe operations by capability. Do not hardcode host-generated tool names, sandbox paths, or delivery functions.

## Questions

- Use the host's structured multi-choice input when available.
- Otherwise present numbered options in chat and accept a number, label, or free-text answer.
- Keep Stage A authority confirmation and the Decision Summary as hard stops in every runtime.

## Source documents

- Use the host's document or PDF reader for supplied files.
- Extract explicit decisions, unresolved terms, milestone candidates, and pricing content that must be excluded.
- Preserve source provenance and distinguish performer assertions from Government-approved facts.

## DOCX generation

- Use the host's native document-authoring capability when available.
- Otherwise use a local standards-compliant DOCX library.
- Use an agency or consortium template when supplied. Do not silently replace it with a generic style.
- Save to a writable task-specific location; never expose internal file-system paths in the artifact.

## Validation and rendering

- Run the bundled validator with Python 3.10 or later and `python-docx`.
- Render with Microsoft Word or LibreOffice when available and identify the engine used.
- If LibreOffice is the only engine, do not claim Microsoft Word validation.
- If rendering is unavailable, do not claim visual QA. Report the missing layer before delivery.

## Delivery

- Present the `.docx` through the host's file-delivery capability.
- For a dynamic TOC, state: `Open the document in Word, press Ctrl+A (Cmd+A on Mac), then F9 (or Fn+F9) to update all fields and page numbers.`
- Emit the milestone handoff in chat only.
- Never create a second handoff file merely because the runtime supports multiple artifacts.

# OT Project Description Validation Gates

## Before generation

- The user confirmed 4021 research, 4022 prototype, or 4022(f) follow-on production.
- A prototype has a user-confirmed 4022(d)(1) path or is visibly `PENDING`.
- No participant status, significant participation, contribution ratio, fee, successful completion, or follow-on eligibility was inferred.
- The user approved the milestone table and each derived assumption.
- Payment Type is supplied or `PENDING`.
- Each milestone has deliverables and objective completion evidence.
- TRL is used only when supported.
- Data-rights treatment is supplied by deliverable category or marked pending.

## Artifact structure

- Required sections appear in the specified relative order.
- Real heading styles and a dynamic TOC are used when required.
- The cover eyebrow, title, and running header all name the same product.
- No instructional or template residue (for example a note that the table of contents updates automatically) appears as visible text; a Contents section carries a real TOC field or is omitted.
- The Milestone Schedule contains every approved milestone ID.
- Every phase-exit criterion appears in the related milestone completion criteria.
- The Deliverables table maps each artifact to a due trigger and acceptance criterion.
- Each `[TBD]` has an owner and closeout trigger in Constraints and Assumptions.
- Tables have explicit geometry, repeating headers, adequate padding, and no clipped rows.
- Page one states the prototype objective, decision supported, pivotal milestones, major assumptions, and program-team next action without pricing or reserved determinations.
- The body provides executable thresholds, completion evidence, go/no-go logic, and owned closeout triggers rather than repeating the first-page brief.

## Separation and legal accuracy

- No milestone handoff, skill name, prompt, internal path, or routing message appears in the `.docx`.
- No price, cost estimate, labor rate, fee, funding profile, Government budget, or price-reasonableness conclusion appears in the `.docx`.
- Research is cited to 4021, prototypes to 4022, and follow-on production to 4022(f).
- Path D is not described as a competition commitment.
- The document does not make a status, significance, authority, completion, or follow-on determination.
- Follow-on provisions do not promise award or import 4022(d) into the follow-on action.
- FAR or DFARS clauses are not presented as controlling unless incorporated by the agreement.

## Deterministic and visual checks

1. Run `scripts/validate_docx.py <document> --json`.
2. Render the document with a real office engine.
3. Inspect every page at readable zoom.
4. Fix and rerun both checks after any defect.
5. Verify that the delivered file is the validated file.
6. Reject a cover-heavy first page, blank-looking contents page, clipped milestone table, or generic route title even when structural validation passes.

## Chat-only handoff

- The table exactly identifies itself for OT Cost Analysis.
- It contains all approved milestones, durations, deliverables, completion evidence, timing, payment type, and pending decisions.
- Authority and contribution facts are presented as supplied inputs with provenance.
- It contains no invented price, rate, fee, contribution arithmetic, or determination.

#!/usr/bin/env python3
"""Validate an OT project-description DOCX for structure and separation."""

from __future__ import annotations

import argparse
import json
import re
import sys
import zipfile
from pathlib import Path

from docx import Document


CORE_SECTIONS = [
    "agreement overview",
    "technical background and current state",
    "project objectives",
    "technical approach by phase",
    "milestone schedule",
    "deliverables",
    "data rights",
    "period of performance",
    "government responsibilities",
    "key personnel",
    "reporting and oversight",
    "constraints and assumptions",
]

FORBIDDEN = {
    "milestone handoff": re.compile(r"MILESTONE\s+HANDOFF\s+TABLE", re.I),
    "skill-routing language": re.compile(
        r"\bOT\s+Cost\s+Analysis\s+skill\b|\bbuild\s+the\s+OT\s+cost\s+analysis\b|\$ot-cost-analysis",
        re.I,
    ),
    "internal workpaper notice": re.compile(r"Internal\s+Government\s+workpaper", re.I),
    "currency amount": re.compile(
        r"(?:\$\s*\d|\b\d[\d,]*(?:\.\d+)?\s*(?:dollars?|USD|million|billion)\b)",
        re.I,
    ),
    "pricing or funding content": re.compile(
        r"\bshould[- ]cost\b|\bfunding\s+profile\b|\bGovernment\s+budget\b|"
        r"\bprice[- ]reasonableness\b|\blabor\s+rate\b|\bhourly\s+rate\b|\bmilestone\s+amount\b",
        re.I,
    ),
    "FAR artifact language": re.compile(r"\bCLINs?\b|\bQASP\b|\bAQL\b|\boption\s+year\b", re.I),
    "wrong prototype authority": re.compile(
        r"(?:Prototype\s+OT|prototype\s+(?:project|authority))[^.\n]{0,120}"
        r"(?:under|pursuant\s+to|authorized\s+by|authority:?\s*)\s*10\s*U\.?S\.?C\.?\s*4021",
        re.I,
    ),
    "obsolete prototype-definition citation": re.compile(r"10\s*U\.?S\.?C\.?\s*4003", re.I),
    "false Path D condition": re.compile(
        r"(?:4022\s*\(d\)\s*\(1\)\s*\(D\)|Path\s+D)[^.\n]{0,140}"
        r"(?:competition\s+commitment|commit(?:ment|ted)\s+to\s+compet)",
        re.I,
    ),
    "local runtime path": re.compile(r"/(?:mnt|tmp|Users)/|[A-Za-z]:\\", re.I),
    "instructional template residue": re.compile(
        r"table\s+of\s+contents\s+(?:updates?|will\s+update|refreshes?)\s+automatically"
        r"|updates?\s+automatically\s+in\s+word"
        r"|right-click[^.\n]{0,60}update\s+field"
        r"|press\s+F9",
        re.I,
    ),
}

PRODUCT_LABELS = ("project description", "delivery plan", "change register")


def cover_product_labels(document: Document) -> set[str]:
    parts: list[str] = []
    for paragraph in document.paragraphs:
        if heading_level(paragraph) is not None:
            break
        if paragraph.text.strip():
            parts.append(paragraph.text)
    text = re.sub(r"\s+", " ", " ".join(parts)).lower()
    return {label for label in PRODUCT_LABELS if label in text}


def header_product_labels(document: Document) -> set[str]:
    parts = [
        paragraph.text
        for section in document.sections
        for paragraph in section.header.paragraphs
    ]
    text = re.sub(r"\s+", " ", " ".join(parts)).lower()
    return {label for label in PRODUCT_LABELS if label in text}


def normalize_heading(text: str) -> str:
    text = re.sub(r"^\s*(?:section\s+)?\d+(?:\.\d+)*[.):-]?\s*", "", text, flags=re.I)
    return re.sub(r"\s+", " ", text).strip().lower()


def heading_level(paragraph: object) -> int | None:
    style = getattr(paragraph, "style", None)
    name = getattr(style, "name", "") or ""
    match = re.fullmatch(r"Heading\s+([1-9])", name, re.I)
    return int(match.group(1)) if match else None


def document_text(document: Document) -> str:
    parts = [paragraph.text for paragraph in document.paragraphs]
    for table in document.tables:
        for row in table.rows:
            for cell in row.cells:
                parts.append(cell.text)
    return "\n".join(parts)


def has_toc_and_update(path: Path) -> tuple[bool, bool]:
    with zipfile.ZipFile(path) as archive:
        document_xml = archive.read("word/document.xml").decode("utf-8", errors="replace")
        settings_xml = archive.read("word/settings.xml").decode("utf-8", errors="replace")
    has_toc = bool(re.search(r"<w:instrText[^>]*>[^<]*\bTOC\b", document_xml, re.I))
    update = bool(re.search(r"<w:updateFields\b[^>]*", settings_xml, re.I))
    return has_toc, update


def table_index(document: Document, required_headers: set[str]) -> tuple[int, dict[str, int]] | None:
    for table_number, table in enumerate(document.tables):
        if not table.rows:
            continue
        headers = {
            re.sub(r"\s+", " ", cell.text).strip().lower(): index
            for index, cell in enumerate(table.rows[0].cells)
        }
        if required_headers.issubset(headers):
            return table_number, headers
    return None


def validate_milestones(document: Document, failures: list[str]) -> int:
    required = {
        "milestone id",
        "phase",
        "description",
        "deliverables due",
        "completion criteria",
        "timing or sequence",
        "payment type",
    }
    found = table_index(document, required)
    if found is None:
        failures.append("missing Milestone Schedule table with required headers")
        return 0
    table_number, headers = found
    table = document.tables[table_number]
    if len(table.rows) < 2:
        failures.append("Milestone Schedule has no milestone rows")
        return 0
    required_values = [
        "milestone id",
        "phase",
        "description",
        "deliverables due",
        "completion criteria",
        "payment type",
    ]
    for row_number, row in enumerate(table.rows[1:], start=2):
        for header in required_values:
            value = row.cells[headers[header]].text.strip()
            if not value:
                failures.append(f"Milestone Schedule row {row_number} has blank {header}")
    return len(table.rows) - 1


def validate_deliverables(document: Document, failures: list[str]) -> int:
    required = {"id", "title", "format", "due trigger", "acceptance criteria", "rights category"}
    found = table_index(document, required)
    if found is None:
        failures.append("missing Deliverables table with required headers")
        return 0
    table_number, headers = found
    table = document.tables[table_number]
    if len(table.rows) < 2:
        failures.append("Deliverables table has no deliverable rows")
        return 0
    for row_number, row in enumerate(table.rows[1:], start=2):
        for header in ("id", "title", "due trigger", "acceptance criteria", "rights category"):
            if not row.cells[headers[header]].text.strip():
                failures.append(f"Deliverables row {row_number} has blank {header}")
    return len(table.rows) - 1


def validate_tbd_closeout(document: Document, text: str, failures: list[str]) -> None:
    if "[TBD]" not in text:
        return
    required = {"assumption or constraint", "basis", "owner", "closeout trigger"}
    found = table_index(document, required)
    if found is None:
        failures.append("document contains [TBD] but has no Constraints closeout table")
        return
    table_number, headers = found
    table = document.tables[table_number]
    closeout_rows = 0
    for row_number, row in enumerate(table.rows[1:], start=2):
        assumption = row.cells[headers["assumption or constraint"]].text
        if "[TBD]" not in assumption:
            continue
        closeout_rows += 1
        if not row.cells[headers["owner"]].text.strip():
            failures.append(f"Constraints row {row_number} has [TBD] but no owner")
        if not row.cells[headers["closeout trigger"]].text.strip():
            failures.append(f"Constraints row {row_number} has [TBD] but no closeout trigger")
    if closeout_rows == 0:
        failures.append("document contains [TBD] without a matching Constraints closeout row")


def validate(path: Path) -> dict[str, object]:
    failures: list[str] = []
    try:
        if not zipfile.is_zipfile(path):
            return {"status": "fail", "failures": ["file is not a valid DOCX ZIP"]}
        with zipfile.ZipFile(path) as archive:
            names = set(archive.namelist())
            for required in ("[Content_Types].xml", "word/document.xml", "word/styles.xml"):
                if required not in names:
                    failures.append(f"missing DOCX part: {required}")
        document = Document(path)
    except (OSError, ValueError, zipfile.BadZipFile) as exc:
        return {"status": "fail", "failures": [f"cannot read DOCX: {exc}"]}

    text = document_text(document)
    for label, pattern in FORBIDDEN.items():
        if pattern.search(text):
            failures.append(f"document contains forbidden {label}")

    cover_labels = cover_product_labels(document)
    header_labels = header_product_labels(document)
    if cover_labels and header_labels and not (cover_labels & header_labels):
        failures.append(
            "cover names "
            + ", ".join(sorted(cover_labels))
            + " but the running header names "
            + ", ".join(sorted(header_labels))
            + "; the cover eyebrow, title, and running header must name the same product"
        )

    h1 = [
        normalize_heading(paragraph.text)
        for paragraph in document.paragraphs
        if heading_level(paragraph) == 1 and paragraph.text.strip()
    ]
    positions: list[int] = []
    for expected in CORE_SECTIONS:
        candidates = [index for index, value in enumerate(h1) if value == expected]
        if not candidates:
            failures.append(f"missing Heading 1 section: {expected}")
        else:
            positions.append(candidates[0])
    if positions and positions != sorted(positions):
        failures.append("core Heading 1 sections are out of order")

    contribution_positions = [i for i, value in enumerate(h1) if value == "contribution arrangement"]
    follow_on_positions = [i for i, value in enumerate(h1) if value == "production follow-on provisions"]
    constraints_positions = [i for i, value in enumerate(h1) if value == "constraints and assumptions"]
    if constraints_positions:
        end = constraints_positions[0]
        if contribution_positions and contribution_positions[0] > end:
            failures.append("Contribution Arrangement appears after Constraints and Assumptions")
        if follow_on_positions and follow_on_positions[0] > end:
            failures.append("Production Follow-On Provisions appears after Constraints and Assumptions")
        if contribution_positions and follow_on_positions and contribution_positions[0] > follow_on_positions[0]:
            failures.append("Production Follow-On Provisions appears before Contribution Arrangement")

    milestone_count = validate_milestones(document, failures)
    deliverable_count = validate_deliverables(document, failures)
    validate_tbd_closeout(document, text, failures)

    if len(h1) > 8:
        try:
            has_toc, update = has_toc_and_update(path)
        except (KeyError, OSError, zipfile.BadZipFile) as exc:
            failures.append(f"cannot audit TOC settings: {exc}")
        else:
            if not has_toc:
                failures.append("document with more than eight sections has no dynamic TOC field")
            if not update:
                failures.append("document does not set updateFields-on-open")

    return {
        "status": "pass" if not failures else "fail",
        "heading_1_count": len(h1),
        "table_count": len(document.tables),
        "milestone_count": milestone_count,
        "deliverable_count": deliverable_count,
        "failures": failures,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Validate an OT project-description DOCX.")
    parser.add_argument("document", type=Path)
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()
    if not args.document.is_file():
        print(f"ERROR: document not found: {args.document}", file=sys.stderr)
        return 2
    result = validate(args.document)
    if args.json:
        print(json.dumps(result, indent=2, sort_keys=True))
    elif result["status"] == "pass":
        print("OT project-description structure and separation passed.")
    else:
        print("VALIDATION FAILED")
        for failure in result["failures"]:
            print(f"- {failure}")
    return 0 if result["status"] == "pass" else 1


if __name__ == "__main__":
    raise SystemExit(main())