canonical-doc-contract-plan-hardening

# Canonical doc-contract plan hardening

Use when drafting or revising a plan for a canonical documentation contract: repo mission, role map, glossary, or cross-doc wording reconciliation.

## Common reviewer failures this prevents

1. Validator contract is too vague
- Reviewers reject plans that say "add a validation script" without listing exact required phrases, forbidden phrases, section expectations, or file-specific rules.

2. Canonical artifact stored in the wrong namespace
- Do not put a normative long-lived contract under a reporting/history path unless that repo explicitly treats the path as authoritative.

3. Phrase-only validation is too weak
- Required/forbidden strings alone are insufficient. Add semantic role-claim checks and file-specific expectations.

4. Artifact status is muddy
- Split artifacts into:
  - existing evidence inputs
  - planned outputs
- Do not mix prior review artifacts with future deliverables in the same ambiguous list.

5. Cross-document terminology drift remains unresolved
- Explicitly distinguish concepts that share similar words. Example:
  - ecosystem control plane
  - workflow control plane inside that ecosystem

## Required hardening pattern

### 1. Put the canonical artifact in a normative location

Prefer a path under a durable standards/contracts namespace or another clearly authoritative docs path.
Avoid using report/history namespaces for the canonical artifact unless the repo already treats them as authoritative.

### 2. Add a "Canonical Terminology Contract" section to the plan

This section should include all of the following:
- exact required phrases for the canonical contract doc
- exact forbidden phrases
- required non-goal bullets
- required glossary terms when the deliverable claims to include a glossary
- file-specific expectations for each reconciled document
- explicit validator semantics:
  - case sensitivity
  - line-ending normalization
  - whitespace handling
  - whether checks are whole-line, substring, or regex-based
- exact plan-index rule if the plan updates a local index table, including full table schema when relevant

Also add explicit migration checks for legacy wording that must be removed, not merely supplemented. Example: if an existing doc says `GSD is the control plane`, add that exact legacy phrase to the forbidden list once the new distinction (`workspace-hub` as ecosystem control plane vs `GSD` as workflow control plane) is introduced.

### 3. Split lexical and semantic checks

Your TDD/validation plan should include both:

- lexical checks
  - phrase presence/absence
  - required section headers
  - required bullets
  - glossary terms when claimed in the deliverable

- semantic checks
  - no non-canonical repo gets assigned the canonical role
  - role statements in secondary docs do not contradict the main contract
  - generic standards docs stay generic and do not absorb repo-specific ownership prose
  - legacy role phrasing is removed where required, not merely coexisting beside the new phrasing
  - related standards/contracts cross-link to each other when the plan introduces two nearby authoritative docs

### 4. Lock constrained entrypoint files explicitly

If a root workflow-contract file is constrained by line count or by role, measure that in Resource Intelligence and make the plan explicit:
- unchanged in this packet
- or changed only under a deterministic rule

Also capture a deterministic baseline when immutability matters:
- current line count (for example via `wc -l`)
- current git blob SHA when possible (`git rev-parse HEAD:path/to/file`)

Use that baseline in the TDD plan so a later `file unchanged` test has a concrete source of truth rather than a vague before/after comparison.

Do not leave edits to a constrained file as an "optional if needed" judgment call.

### 5. Separate existing review evidence from future outputs

Artifact Map should usually have two subsections:

#### Existing evidence inputs
- this plan
- steering docs
- standards docs
- already generated review artifacts

#### Planned outputs
- canonical contract doc
- validation script
- reconciled target docs
- follow-up issue drafts

### 6. If manual validation would rot, draft the CI follow-up now

If the current issue is only for creating the contract plus validator, add a follow-up issue draft for CI enforcement so reviewers can see drift prevention is queued.

Be explicit about whether the follow-up draft is being created or updated. If a draft file already exists, treat it as a modify action, not create, and make the acceptance criterion require concrete contents:
- validator script path
- test file path
- exact test command
- intended CI hook/job

### 7. Review-wave hygiene for iterative plan hardening

When a plan goes through multiple adversarial-review waves:
- keep the review-artifact header in sync with the actual generated files
- keep the artifact map explicit about which waves already exist versus which outputs belong to eventual implementation
- do not leave the plan self-reporting `FAIL` once you have patched the cited blockers; change the summary to something like `pending final delta review` and immediately rerun review
- convert lingering open questions into explicit decisions or explicit deferred follow-up items before asking for approval
- if reviewers keep objecting to semantics rather than mechanism, add the exact regexes, section shapes, or file-specific predicates to the plan itself

### 8. Standards-vs-mission boundary rule

If a new canonical mission contract sits near an existing generic standard:
- keep the mission contract in a normative location
- keep the generic standard generic
- if cross-links are required, specify the exact relative markdown links and the relationship note expected in each file
- do not make a generic cross-repo standard carry repo-specific ownership tables just to satisfy a validator
- most importantly: do not leave the standard's edit status ambiguous. If tests/acceptance require a cross-link or wording change, mark the file as a mandatory generic-only modify everywhere in the plan. Do not call it optional in one section and required in another.

### 9. Validator semantics must be concrete, not inferred

When reviewers keep attacking validator ambiguity, add the exact semantics to the plan itself:
- how fenced code blocks are detected (for example, triple-backtick fences only)
- whether indented code blocks are exempt or not
- whether checks exclude fenced content consistently across required-phrase, forbidden-phrase, and semantic-regex rules
- whether matching is case-sensitive
- whether line endings are normalized
- whether Unicode is normalized (for example NFC)
- whether paragraph line-wraps are collapsed to spaces before matching
- whether a forbidden rule is substring-based or a whole-line regex

If a legacy phrase is being retired, prefer an explicit standalone regex over a vague substring ban.

### 10. Immutable file checks need a reproducible baseline

If the plan says a constrained file must remain unchanged, the test should not rely on a vague before/after claim.
Capture and use a deterministic baseline such as:
- `git rev-parse HEAD:path/to/file` for a blob SHA
- current line count via `wc -l`

Then make the test assert the working-tree blob still matches the recorded SHA when immutability is part of the contract.

### 11. Keep review-wave bookkeeping synchronized

In multi-wave hardening loops:
- if review artifacts are listed in plan metadata, keep the list synchronized with every actual review wave you cite in the summary
- if the Adversarial Review Summary mentions wave N, the artifact map and metadata should also reflect wave N
- if you patch blockers from the latest wave, change the summary status from outright FAIL to a pending-final-delta state only after you have actually made the patches and immediately rerun review
- do not let the plan's self-reported status lag behind the current draft

### 12. Align prose rules with tests verbatim

Common reviewer complaint: the prose says one thing and the test row says another.
Before re-review, cross-check all of these for exact agreement:
- Files to Change
- Artifact Map
- Canonical Terminology Contract
- TDD Test List
- Acceptance Criteria
- Adversarial Review Summary revision notes

Typical drift to catch:
- optional vs mandatory edits
- partial vs full plan-index schema
- create vs modify on already-existing follow-up drafts
- semantic checks applying to reconciled docs but not the canonical contract itself

## Template additions that help approval

Include concrete file-specific expectations like:
- a given top-level doc must contain the canonical role statement
- a strategy/brain doc must preserve its stronger structure while normalizing wording
- a generic standard may only receive generic terminology edits and must not gain repo-specific role tables

Include concrete non-goals like:
- repo does not own engineering computations
- repo does not own shared utility layer
- repo does not own GTM/public website
- repo does not resolve an open architecture decision tracked in another issue

## Example validation dimensions

For a mission/control-plane contract validator, check all of:
- required phrases in canonical contract
- forbidden phrases across reconciled docs
- required non-goal bullets in canonical contract
- file-specific role statements
- semantic no-contradiction checks for named repos
- generic standard remains generic
- local plan index row present with expected schema
- follow-up CI issue draft exists if validator is not yet enforced automatically

## Practical rule

If a reviewer says "the mechanism is specified but the substance is not," add more explicit content to the plan itself rather than only improving the future validator script.

## Outcome to aim for

A plan becomes approval-ready when:
- canonical location is correct
- content contract is explicit in the plan
- validator behavior is mechanically derived from that contract
- semantic contradictions are blocked, not just missing phrases
- artifact status is unambiguous
- any deferred enforcement work is captured in a follow-up issue draft