# Korean Experience-Prose Contract Design

## Goal

ClariDoc must apply one enforceable Korean prose contract when it writes or
reviews a Korean technical blog or Korean README. The contract must preserve
facts and document structure while making the reader follow the author's
experience in consistent `합니다/했습니다` prose.

The change closes the gap between a skill file that describes the desired
style and a harness that currently neither passes that style to providers nor
checks it before returning `PASS`.

## Scope

The contract applies automatically to:

- a Korean `technical_blog` using `auto`, `woowahan_tech_blog_ko`, or
  `korean_problem_solving_blog`;
- every Korean `readme`.

It does not force first-person retrospective prose onto tutorials, how-to
guides, references, troubleshooting guides, explanations, or design documents.
Those document types keep their existing style behavior.

The current repository `README.md` is part of the migration. Its factual
content, commands, links, tables, and overall information order remain intact,
but its reader-facing Korean prose is revised to the same experience-oriented
`합니다/했습니다` style.

## Considered Approaches

### Prompt-only guidance

Copy the skill text into the drafting prompt. This has the smallest code
change, but it leaves no objective proof that the writer or reviser kept the
rules. It would preserve the current failure mode in which one correction
causes another part of the document to regress.

### Opt-in style profile only

Require README authors to select a special `style_profile`. This avoids adding
a document type, but a missing configuration value silently disables the
contract. It also makes README structure masquerade as another document type.

### Shared contract with a first-class README type

Add `readme` to the document model and define one shared prose contract used by
prompts, lint, reviews, revisions, reports, and tests. This is the selected
approach because it makes activation explicit and lets deterministic and model
judgment checks cover different parts of the same contract.

## Architecture

### First-class README document type

`DocumentType.README` is added to the model and JSON schemas. Its deterministic
outline contains these intents in order:

1. `problem_value`: the concrete problem and why the project exists;
2. `principles`: the project behavior and boundaries readers must understand;
3. `workflow`: the end-to-end operating flow;
4. `installation`: prerequisites and installation;
5. `quickstart`: the smallest useful execution path and expected result;
6. `configuration`: the main configuration choices and their effects;
7. `verification`: how to verify success and diagnose common failure;
8. `limits_next`: evidence limits, unsupported claims, and the next relevant
   action.

The planner may refine titles and evidence allocation, but it must preserve
these intents and their order just as it does for existing document types.

### Shared prose contract

A focused `claridoc.style_contracts` module owns activation and provider-facing
guidance. It exposes:

```python
def korean_experience_contract_applies(brief: Brief) -> bool: ...

def style_guidance(brief: Brief) -> str: ...
```

The returned guidance includes the same rules in every provider stage:

- open the document and major transitions from a concrete code, screen,
  request, or problem the author encountered;
- show the initial expectation, then the observed difference;
- explain an unfamiliar term where it first becomes necessary;
- show what the author checked, selected, or changed;
- close the thread with the result, accepted cost, or remaining problem;
- use `저는` or `제가` where it establishes the experience, without repeating
  it mechanically in every sentence;
- use `했습니다` for observed or performed work and `합니다` for current
  behavior and technical explanation;
- never invent an emotion, conversation, failure, duration, result, or
  technical rationale that the evidence does not support;
- preserve code, commands, identifiers, numbers, links, tables, diagrams,
  claims, evidence status, and outline order.

The guidance describes the canonical paragraph pattern as form, not as facts
to copy:

```text
concrete starting point
→ initial expectation
→ observed difference
→ immediate term explanation
→ author action or decision
→ result, cost, or remaining limit
```

`drafting_prompt`, `review_prompt`, and `revision_prompt` all call this shared
module. No stage keeps a separate abbreviated version.

### Deterministic checks

Deterministic lint checks only properties that can be recognized without
guessing the author's intent.

`STYLE002` reports a blocker when reader-facing prose mixes plain declarative
endings such as `한다.`, `있다.`, `아니다.`, or `~했다.` into a document whose
contract requires `합니다/했습니다`. Fenced code, headings, Markdown tables,
block quotations, image alt text, command output, and quoted spans are excluded.
The report consolidates matches and records their count and first locations.

`STYLE003` reports a blocker when the opening has no explicit `저는` or `제가`
marker, or when fewer than half of substantive H2 sections contain an explicit
first-person experience marker. A substantive section is an H2 section with at
least one reader-facing prose paragraph; code-only and table-only sections do
not count.

The lint report adds:

- `style_contract`: `korean_first_person_experience_v1` or `none`;
- `plain_form_ending_count`;
- `first_person_marker_count`;
- `experience_section_count`;
- `experience_section_coverage`.

Because both style issues are blockers, configured error tolerances cannot turn
them into a passing result.

Deterministic lint does not try to decide whether a paragraph contains a
genuine discovery, whether a term is unfamiliar, or whether the prose sounds
natural. Those require model judgment.

### Independent review and revision

Every reviewer role receives mandatory prose checks when the contract applies:

- the opening and major transitions follow an experience rather than listing
  settled facts;
- the paragraph presents an actual expectation or observation rather than
  inserting `저는` as decoration;
- unfamiliar terms are explained at first need;
- contrasts name the actual component and behavior that differ;
- the document does not manufacture personal history or project rationale;
- `합니다/했습니다` remains consistent outside exempt Markdown regions.

The revision prompt requires a whole-document contract audit after resolving
individual findings. This prevents a local rewrite from regressing another
section. Each revision round already runs lint and independent reviews again,
so the shared contract is re-evaluated before the quality gate can pass.

### Skill entry point

The dangling `.agents/skills/technical-document-author/SKILL.md` reference is
replaced with a real authoring skill. It preserves the repository sequence:

```text
Brief
→ SourcePack
→ deterministic outline
→ draft
→ lint and independent reviews
→ revision
→ quality gate
→ reader document and provenance artifacts
```

For Korean technical blogs and Korean READMEs, the authoring skill requires the
Korean prose contract and its sentence-pattern reference. It may not claim
completion without lint, review, and quality-gate artifacts. The existing
`revising-korean-technical-prose` skill remains the focused in-place revision
skill.

## Data Flow

```text
Brief(document_type, language, style_profile)
  → style-contract activation
  → planner keeps deterministic document structure
  → writer receives shared prose guidance
  → deterministic lint checks endings and first-person coverage
  → every reviewer checks experience quality and factual boundaries
  → reviser receives the same guidance plus all findings
  → lint and reviews run again
  → blockers prevent PASS
  → report records style metrics and findings
```

## README Migration

The repository `README.md` is revised in place with the
`revising-korean-technical-prose` skill:

- existing facts, code blocks, commands, paths, links, tables, and diagrams are
  preserved;
- Korean reader-facing prose uses `합니다/했습니다`;
- the opening and major transitions explain how the harness's failure modes
  were encountered and how the implemented workflow addresses them;
- no unverified personal event, advice, measurement, or project rationale is
  added;
- a section documents the activation scope, lint codes, review behavior, and
  `readme` brief usage.

The migration is checked separately from generated documents because the
repository README is not itself a pipeline output artifact.

## Error Handling

- Invalid `document_type: readme` handling disappears once the enum and schemas
  are updated; other unknown types remain validation errors.
- Style lint returns actionable locations and correction guidance rather than
  rewriting content.
- Empty or structure-only documents still fail existing structure and length
  checks; style metrics do not mask those failures.
- Quoted evidence and code are excluded from deterministic ending checks so
  original material is not altered to satisfy prose style.
- A model review cannot override a deterministic style blocker.

## Testing

Tests are added before production changes.

### Model and structure tests

- `readme` is accepted by `Brief` and outline schemas;
- `readme` receives eight unique required intents in the specified order;
- all existing document types retain their current outlines.

### Prompt tests

- Korean technical-blog and README draft, review, and revision prompts contain
  the same contract identifier and required rules;
- English and unrelated Korean document types do not receive the contract;
- the revision prompt requires a whole-document recheck.

### Lint tests

- mixed `한다/합니다` prose is a blocker;
- fenced code, headings, tables, block quotations, image alt text, and quoted
  examples do not cause false positives;
- missing opening first person is a blocker;
- insufficient substantive-section coverage is a blocker;
- a representative experience-oriented technical blog passes;
- a representative Korean README passes;
- unrelated document types retain existing lint behavior.

### Pipeline tests

- a style blocker prevents the quality gate from passing even when configured
  error tolerance is nonzero;
- revision rounds receive the blocker and rerun the contract checks;
- final artifacts record the style contract and findings.

### Repository validation

- targeted unit tests are run after each TDD cycle;
- `PYTHONPATH=src python3 -m unittest discover -s tests -v` is run;
- `bash scripts/verify.sh` is run if it can preserve the user's unrelated
  working-tree changes; otherwise its destructive build steps are inspected
  and an equivalent non-destructive validation set is reported explicitly;
- the revised `README.md` is scanned outside code and quoted regions for plain
  declarative endings and reviewed against the experience-flow checklist.

## Success Criteria

The implementation is complete only when:

- Korean technical blogs and Korean READMEs receive the contract in every model
  stage;
- omitting `합니다/했습니다` consistency or first-person experience coverage
  creates a deterministic blocker;
- qualitative experience flow is a mandatory independent-review concern;
- a revision cannot pass without rerunning the checks;
- `readme` is a supported contract-first document type;
- the missing technical-author skill entry point exists and requires validation
  artifacts;
- the repository README follows and documents the same contract;
- all targeted and full regression tests pass.