# Phase 3: Document & Script Generation

**Generate only the artifacts confirmed in the Harness Needs Assessment (Phase 0k + Phase 1d).
Use the templates in `templates/` as reference starting points, not rigid structures.**

## What to generate

Generate artifacts based on the confirmed harness shape from Phase 1d:

1. **Documents**: only the document roles marked `needed` or `recommended-unconfirmed`
2. **Scripts**: only the scripts the project actually requires
3. **Operational sub-skills**: only the operational prompts confirmed as needed
4. **Machine-readable contracts**:
   - always emit `docs/harness-manifest.json` for artifact + execution contract
   - always emit `docs/feedback-profile.json` for feedback surfaces + gaps + business-flow coverage

## Available templates (reference starting points)

| Role | Default file | Template |
|---|---|---|
| `agents_doc` | `AGENTS.md` | `templates/AGENTS.md.tmpl` |
| `project_spec_doc` | `docs/project_spec.md` | `templates/project_spec.md.tmpl` |
| `prompt_doc` | `docs/prompt.md` | `templates/prompt.md.tmpl` |
| `plan_doc` | `docs/plan.md` | `templates/plan.md.tmpl` |
| `implement_doc` | `docs/implement.md` | `templates/implement.md.tmpl` |
| `documentation_doc` | `docs/documentation.md` | `templates/documentation.md.tmpl` |
| `failure_taxonomy_doc` | `docs/failures/taxonomy.md` | `templates/taxonomy.md.tmpl` |
| `compaction_doc` | `docs/compaction-strategy.md` | `templates/compaction-strategy.md.tmpl` |
| `feedback_profile` | `docs/feedback-profile.json` | `templates/feedback-profile.json.tmpl` |

Templates are starting points. Adapt structure, add sections, or omit irrelevant
sections based on what was discovered and confirmed. Do not blindly fill every
template placeholder — if a section does not apply, omit it.

## Script suite

| File | Template | Generate when |
|---|---|---|
| `scripts/validate-docs.sh` | `templates/validate-docs.sh.tmpl` | Multiple docs generated AND Unix environment |
| `scripts/validate-docs.ps1` | `templates/validate-docs.ps1.tmpl` | Multiple docs generated AND Windows environment |
| `scripts/quality-gates.sh` | `templates/quality-gates.sh.tmpl` | Quality tools exist AND Unix environment |
| `scripts/quality-gates.ps1` | `templates/quality-gates.ps1.tmpl` | Quality tools exist AND Windows environment |

Generate cross-platform variants (.sh + .ps1) only when the team actually uses
multiple OS environments. If the project is single-platform, generate only the
primary variant and note the portable alternative is available if needed later.

**Execution contract** (applies to all generated artifacts):

- Choose one **primary shell** for the repo:
  - Windows/PowerShell-first repo → `.ps1`
  - Linux/macOS/bash-first repo → `.sh`
- Fill every generated document with the same:
  - `Primary shell`
  - `Primary quality gate command`
  - `Primary doc validation command`
- The generated result is invalid if one file says PowerShell and another still uses `bash scripts/...` as the default path

## Operational sub-skills (copied to `.agents/skills/`)

Install only the operational sub-skills confirmed as needed in the Harness Needs Assessment:

| Skill | Purpose | Always needed? |
|---|---|---|
| `iterate` | Execute one iteration cycle within current milestone | Yes |
| `quality-audit` | Full quality audit + tech debt scan + quality score | Only if quality tools exist |
| `milestone-promote` | Safely promote from one milestone to the next | Only if multiple milestones |

Do not emit separate `doc-gardening` or `review-ready` sub-skills by default.
Inline those responsibilities into:
- `iterate` for routine doc-drift correction during normal work
- `milestone-promote` for review-packet capture and milestone-end doc sync

## Greenfield vs Messy-existing: which path to take

Based on the Documentation Health Report from Phase 0b, choose a path:

**Path A — Greenfield** (no existing docs, or all docs are `stale`):
- Generate confirmed documents from templates
- Fill placeholders with Phase 0 + Phase 1 information

**Path B — Reorganize** (some docs are `salvageable` or `healthy`):
- **Keep** `healthy` docs as-is (do not overwrite)
- **Rewrite** `salvageable` docs: extract useful content, restructure using
  template as the target format, fill gaps with discovered/decided information
- **Replace** `stale` docs: archive the old version to `docs/archive/` with
  a date suffix, then generate fresh from template
- **Merge** `redundant` docs: consolidate into the canonical file, delete duplicates
- **Create** any docs from the suite that don't exist yet

When reorganizing, preserve the user's existing terminology, naming conventions,
and any project-specific sections that aren't in the template. The template is
a minimum structure, not a maximum.

## Constraint → Enforcement pipeline

For each constraint discovered in Phase 0 or decided in Phase 1, the agent
must try to encode it as close to enforcement as possible. Prose-only
constraints are the weakest form. See `docs/feedback-layer-model.md` §
"Constraint Encoding Model."

| Constraint type | Enforcement target | Example |
|---|---|---|
| Layer dependency direction | Linter import rules | eslint `no-restricted-imports`, Go `internal/`, Python `import-linter`, Java ArchUnit |
| Forbidden patterns | Lint rule or pre-commit hook | No `console.log` in production, no `any` in TypeScript strict mode |
| API shape contract | Schema validation or typecheck | Zod schema, OpenAPI spec, Pydantic model, TypeScript strict |
| Config shape | Startup validation | Fail-fast on missing env vars, JSON schema for config files |
| Business-flow correctness | Scenario or E2E test | Playwright test for critical user path, golden output test for CLI |
| Safe rollback | Script guard | `implement.md` and sub-skills forbid `git checkout -- .` and `git reset --hard` |

**Process during generation:**

1. For each hard constraint from Phase 1, check: can it be encoded as a lint
   rule, test, schema check, or script guard? If yes, generate that enforcement.
2. For each feedback surface gap from Phase 0e, check: did Phase 1 confirm this
   gap should be closed now? If yes, generate the mechanism (test, config, rule).
3. Record what was enforced vs what remains prose-only in
   `docs/feedback-profile.json` → `feedback_surfaces.*.mechanisms`, `*.commands`,
   `*.evidence_paths`, and `*.gaps`.
4. If a constraint cannot be mechanically enforced yet, write it into
   `AGENTS.md` hard constraints AND add a Needs Manifest item to track when
   enforcement becomes possible.

## Generation rules

1. Fill templates with information from Phase 0 (discovered) and Phase 1 (decided)
   If the scaffold renderer exists, prefer generating one values JSON that includes
   the confirmed `HARNESS_MANIFEST`, then run the renderer instead of hand-writing
   each file individually.
2. Read templates lazily:
   - Open only the template needed for the next file you are generating
   - Do NOT dump every template or sub-skill file before writing if the scaffold shape is already determined
3. For `salvageable` docs: diff the existing content against the template structure,
   show the user what will change before overwriting
4. All cross-references between documents must be consistent
5. `docs/harness-manifest.json` is the machine-readable source of truth for which
   docs, scripts, and sub-skills were intentionally generated
6. `docs/feedback-profile.json` is the machine-readable source of truth for which
   feedback surfaces exist, how strong they are, and what gaps remain
6. Verification commands must be real commands that work in this project
7. Do NOT include placeholder text like "TBD" — if unknown, omit the section
   and add it to the Needs Manifest
8. `AGENTS.md` must fit in < 150 lines — it's a navigation layer, not an encyclopedia
9. `docs/prompt.md` must describe only the current milestone, not the whole roadmap
10. The generated primary doc validation command must pass immediately after generation
11. The generated primary quality gate command must integrate all available quality tools
12. Architecture dependency rules must be encoded in linter config where the
    language supports it (e.g., eslint import rules, Go internal packages,
    Python import-linter, Java ArchUnit)
13. Sub-skills must not contain unreplaced template variables; they should reference the repo's execution contract and current docs instead of embedding project-specific placeholders
14. `docs/plan.md` must include an Operations Cadence table that records when `$quality-audit` and `$milestone-promote` last ran and when they are due next
15. `docs/implement.md` and installed sub-skills must forbid repository-wide rollback commands such as `git checkout -- .` and `git reset --hard`
16. Review-packet capture and doc-sync responsibilities should be encoded in the operating docs even if they are not separate sub-skills
17. Optional gates (type-check, architecture-check, E2E) must be included or omitted based on discovery; do not leave fake placeholder commands in generated scripts just to satisfy the template
18. `docs/harness-manifest.json` must reference `docs/feedback-profile.json`; do not duplicate detailed feedback-surface state inside the manifest
19. Optional template sections must end in one of two states only:
    - omitted entirely, or
    - materialized as real Markdown with concrete repo-specific content
    Do not inject project-specific text into HTML comment blocks and leave it commented out.
20. `AGENTS.md` references must point to concrete manifest-declared files. Never use wildcard paths such as `scripts/*.ps1`, `scripts/*.sh`, or `docs/*` in agent-facing guidance.
