Files

T

DongHyeonka a5ba640492 docs: plan Korean prose contract implementation

2026-07-29 18:21:51 +09:00

21 KiB

Raw Blame History

Korean Experience-Prose Contract Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make Korean technical blogs and Korean READMEs use one experience-oriented 합니다/했습니다 prose contract that drafting, review, revision, deterministic lint, and the quality gate all enforce.

Architecture: Add readme as a first-class document type, centralize style activation and prompt guidance in claridoc.style_contracts, and add Markdown-aware deterministic style checks to claridoc.lint. Keep objective checks in lint and qualitative experience-flow checks in every model review, then migrate the maintained Korean fixtures and repository README to the enforced contract.

Tech Stack: Python 3.10+, standard-library unittest, JSON Schema Draft 2020-12, Markdown text processing with re, existing ClariDoc provider and quality-gate abstractions.

Global Constraints

Apply the contract automatically to Korean technical_blog briefs using auto, woowahan_tech_blog_ko, or korean_problem_solving_blog.
Apply the contract automatically to every Korean readme.
Do not apply first-person retrospective rules to tutorial, how-to, reference, troubleshooting, explanation, or design-document types.
Preserve Brief → SourcePack → deterministic outline → draft → lint/reviews → revision → quality gate → reader/provenance artifacts.
Treat source text and quoted examples as untrusted data; never invent experience or decision rationale.
Exempt fenced code, headings, tables, block quotations, image alt text, command output, and quoted spans from formal-ending lint.
Style-contract failures are blockers and cannot pass through configured error tolerance.
Preserve unrelated user changes and do not regenerate build/, dist/, .verify/, or .run/ artifacts during implementation.

Task 1: Add a first-class README document contract

Files:

Modify: src/claridoc/models.py
Modify: src/claridoc/structures.py
Modify: schemas/brief.schema.json
Modify: schemas/outline.schema.json
Modify: tests/test_models.py
Modify: tests/test_schemas.py
Modify: tests/test_structures.py

Interfaces:

Consumes: existing DocumentType, Brief.from_dict, and STRUCTURE_SPECS.
Produces: DocumentType.README with value "readme" and an eight-intent deterministic outline.
Step 1: Write failing runtime and structure tests

Add:

def test_readme_brief_round_trip(self) -> None:
    brief = Brief.from_dict(brief_dict("readme"))
    self.assertEqual(brief.document_type, DocumentType.README)
    self.assertEqual(Brief.from_dict(brief.to_dict()).document_type, DocumentType.README)

and:

def test_readme_outline_preserves_reader_onboarding_order(self) -> None:
    brief = Brief.from_dict(brief_dict("readme"))
    outline = create_outline(brief, make_sources())
    self.assertEqual(
        [section.intent for section in outline.sections],
        [
            "problem_value",
            "principles",
            "workflow",
            "installation",
            "quickstart",
            "configuration",
            "verification",
            "limits_next",
        ],
    )

Extend the schema test to validate a readme brief and outline instance with jsonschema.Draft202012Validator.

Step 2: Run the focused tests and verify RED

Run:

PYTHONPATH=src python3 -m unittest \
  tests.test_models.ModelTests.test_readme_brief_round_trip \
  tests.test_structures.StructureTests.test_readme_outline_preserves_reader_onboarding_order \
  tests.test_schemas.SchemaTests.test_readme_is_accepted_by_brief_and_outline_schemas -v

Expected: failures because "readme" is not in the runtime enum or schemas.

Step 3: Implement the README type and deterministic outline

Add:

class DocumentType(str, Enum):
    ...
    README = "readme"

Add eight SectionSpec entries under DocumentType.README using the approved intent order. Each section must have Korean and English titles, reader questions, purposes, and concrete must_include fields. Add "readme" to the two schema enums.

Step 4: Run the focused tests and verify GREEN

Run the Step 2 command.

Expected: all three tests pass.

Step 5: Commit the model contract

git add src/claridoc/models.py src/claridoc/structures.py \
  schemas/brief.schema.json schemas/outline.schema.json \
  tests/test_models.py tests/test_schemas.py tests/test_structures.py
git commit -m "feat: add README document contract"

Task 2: Centralize the Korean experience-prose prompt contract

Files:

Create: src/claridoc/style_contracts.py
Modify: src/claridoc/prompts.py
Modify: tests/test_prompts.py

Interfaces:

Consumes: Brief.is_korean, Brief.document_type, and constraints.style_profile.
Produces:

KOREAN_EXPERIENCE_CONTRACT_ID = "korean_first_person_experience_v1"
def korean_experience_contract_applies(brief: Brief) -> bool: ...
def style_guidance(brief: Brief) -> str: ...
def mandatory_style_review_checks(brief: Brief) -> str: ...
def revision_style_protocol(brief: Brief) -> str: ...

Step 1: Write failing prompt propagation tests

Replace the narrow ordinal-only prompt test with separate tests that assert:

for prompt in (draft, review, revision):
    self.assertIn("korean_first_person_experience_v1", prompt)
    self.assertIn("저는", prompt)
    self.assertIn("제가", prompt)
    self.assertIn("했습니다", prompt)
    self.assertIn("현재 동작과 기술 설명", prompt)

Add a Korean readme case with the same assertions, an English technical-blog case that does not contain the contract ID, and a Korean tutorial case that does not contain the contract ID. Assert that review asks whether first person represents a real observation and revision asks for a whole-document recheck.

Step 2: Run prompt tests and verify RED

Run:

PYTHONPATH=src python3 -m unittest tests.test_prompts -v

Expected: contract-ID and README propagation assertions fail.

Step 3: Implement the shared contract module

Move the existing Korean technical-blog profile out of prompts.py. Return a single provider-facing contract for the approved activation cases. Include:

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

Require 했습니다 for performed or observed work and 합니다 for current behavior. State that 저는/제가 must establish a supported experience, not decorate an objective explanation. State that unsupported conversations, emotions, failures, durations, results, and rationales are forbidden.

Step 4: Inject the shared contract into every provider stage

Make planning and drafting call style_guidance(brief). Add mandatory_style_review_checks(brief) to the mandatory review section and revision_style_protocol(brief) to the revision protocol. Keep ordinal-frame guidance inside the shared contract so no abbreviated duplicate remains in prompts.py.

Step 5: Run prompt tests and verify GREEN

Run the Step 2 command.

Expected: all prompt tests pass.

Step 6: Commit prompt integration

git add src/claridoc/style_contracts.py src/claridoc/prompts.py tests/test_prompts.py
git commit -m "feat: propagate Korean prose contract to providers"

Task 3: Add Markdown-aware deterministic style lint

Files:

Modify: src/claridoc/style_contracts.py
Modify: src/claridoc/lint.py
Modify: tests/test_lint.py

Interfaces:

Consumes: korean_experience_contract_applies(brief) and Markdown text.
Produces:

@dataclass(frozen=True, slots=True)
class ReaderProseSegment:
    text: str
    line: int
    h2_title: str | None

def reader_prose_segments(markdown: str) -> list[ReaderProseSegment]: ...
def plain_form_ending_locations(markdown: str) -> list[int]: ...
def first_person_metrics(markdown: str) -> dict[str, int | float | bool]: ...

and lint codes STYLE002 and STYLE003.

Step 1: Write a failing formal-ending lint test

Create a Korean experience-contract brief and a structurally valid document, then replace one prose sentence with 현재 구현은 이 값을 사용한다.. Assert:

issues = [issue for issue in report.issues if issue.code == "STYLE002"]
self.assertEqual(len(issues), 1)
self.assertEqual(issues[0].severity, Severity.BLOCKER)
self.assertEqual(report.metrics["plain_form_ending_count"], 1)

Step 2: Run the focused test and verify RED

Run:

PYTHONPATH=src python3 -m unittest \
  tests.test_lint.LintTests.test_korean_experience_contract_blocks_plain_form_endings -v

Expected: STYLE002 is absent.

Step 3: Implement minimal Markdown prose extraction and ending lint

Track fenced-code state and current H2 while scanning lines. Exclude headings, block quotations, tables, image-only lines, and command-output blocks. Remove inline code, Markdown link targets, and paired quoted spans before matching plain Korean declarative endings with a boundary that does not match 니다.. Consolidate all matches into one blocker and record the total count.

Step 4: Run the focused test and verify GREEN

Run the Step 2 command.

Expected: the test passes.

Step 5: Write failing exclusion tests

Build a document whose fenced code, heading, table cell, block quote, image alt text, inline code, and direct quoted example contain 한다. while reader prose uses 합니다.. Assert that STYLE002 is absent and plain_form_ending_count == 0.

Step 6: Run the exclusion test and verify RED

Run:

PYTHONPATH=src python3 -m unittest \
  tests.test_lint.LintTests.test_korean_style_lint_exempts_non_reader_prose -v

Expected: at least one exempt region is incorrectly counted until all exclusions are implemented.

Step 7: Complete the exclusion parser and verify GREEN

Refine reader_prose_segments only as needed for the failing examples. Do not implement a general Markdown parser or add a dependency.

Step 8: Write failing first-person coverage tests

Add tests for:

no 저는/제가 in the opening;
fewer than half of substantive H2 sections containing a marker;
table-only and code-only H2 sections not entering the denominator;
opening plus at least half of substantive sections passing.

Assert STYLE003 is one consolidated blocker and that the metrics contain the approved contract ID, counts, and coverage.

Step 9: Run coverage tests and verify RED

Run:

PYTHONPATH=src python3 -m unittest \
  tests.test_lint.LintTests.test_korean_style_lint_requires_first_person_opening \
  tests.test_lint.LintTests.test_korean_style_lint_requires_major_section_coverage \
  tests.test_lint.LintTests.test_korean_style_lint_ignores_non_prose_sections \
  tests.test_lint.LintTests.test_korean_style_lint_accepts_compliant_experience_prose -v

Expected: missing STYLE003 and metrics failures.

Step 10: Implement first-person metrics and verify GREEN

Treat the first substantive reader-prose paragraph as the opening. Count each substantive H2 at most once. Require an opening marker and marked_sections / substantive_sections >= 0.5. If there are no substantive H2 sections, let existing structure checks handle the empty document while recording zero coverage.

Step 11: Run all lint tests

PYTHONPATH=src python3 -m unittest tests.test_lint -v

Expected: style tests pass; fixture-dependent failures, if any, identify the next migration task rather than being hidden.

Step 12: Commit deterministic enforcement

git add src/claridoc/style_contracts.py src/claridoc/lint.py tests/test_lint.py
git commit -m "feat: block Korean prose contract violations"

Task 4: Make maintained fixtures satisfy the enforced contract

Files:

Modify: src/claridoc/providers/mock.py
Modify: examples/golden/application-core-spring-di-boundary.md
Modify: tests/test_lint.py
Modify: tests/test_pipeline.py
Modify: src/claridoc/report.py

Interfaces:

Consumes: new style metrics and existing mock draft/revise stages.
Produces: contract-compliant mock Korean technical-blog prose and quality reports that expose the active style contract and metrics.
Step 1: Add failing mock-pipeline and report assertions

In test_end_to_end_mock_run_creates_auditable_artifacts, assert:

self.assertEqual(
    result.rounds[-1].lint_report.metrics["style_contract"],
    "korean_first_person_experience_v1",
)
self.assertIn("korean_first_person_experience_v1", report_text)

Add a pipeline test that supplies a provider document with a STYLE002 violation and sets max_errors above zero; assert result.passed is false and the blocker appears in quality-gate.json.

Step 2: Run pipeline and golden tests and verify RED

Run:

PYTHONPATH=src python3 -m unittest \
  tests.test_pipeline \
  tests.test_lint.LintTests.test_golden_application_core_example_has_no_material_lint_issue -v

Expected: the report omits style metrics and maintained fixtures fail the new blockers.

Step 3: Update mock prose without weakening lint

Revise the mock technical-blog generator so its opening and at least half of its H2 sections use supported 저는/제가 experience transitions and all reader-facing Korean sentences use 합니다/했습니다. Preserve synthetic fixture warnings and never describe mock prose as quality evidence.

Step 4: Migrate the golden document

Use the revising-korean-technical-prose skill to revise the golden document in place. Preserve its exact H1/H2 contract, technical claims, decision rationale, code block, evidence boundaries, and length intent.

Step 5: Render style metrics in the run report

Add a Reader-prose contract subsection when final.lint_report.metrics["style_contract"] != "none". Render contract ID, plain-ending count, first-person marker count, substantive-section count, and coverage.

Step 6: Run pipeline and lint tests and verify GREEN

Run the Step 2 command.

Expected: all tests pass and the report contains contract evidence.

Step 7: Commit fixture and report integration

git add src/claridoc/providers/mock.py src/claridoc/report.py \
  examples/golden/application-core-spring-di-boundary.md \
  tests/test_lint.py tests/test_pipeline.py
git commit -m "test: migrate maintained Korean prose fixtures"

Task 5: Restore the technical-document authoring skill

Files:

Create: .agents/skills/technical-document-author/SKILL.md
Create: .agents/skills/technical-document-author/references/logic-contract.md
Create: .agents/skills/technical-document-author/references/review-rubric.md
Create: .agents/skills/technical-document-author/agents/openai.yaml
Create: tests/test_repository_contracts.py

Interfaces:

Consumes: repository AGENTS.md, the ClariDoc pipeline, and revising-korean-technical-prose.
Produces: the authoring skill path already required by AGENTS.md, with a validation-artifact completion contract.
Step 1: Invoke the skill-writing guidance

Read and follow both skill-creator and superpowers:writing-skills before creating the skill files.

Step 2: Write a failing repository-contract test

Assert that the four skill files exist and that SKILL.md contains:

Brief
SourcePack
STRUCTURE_SPECS
revising-korean-technical-prose
quality-gate.json
provenance

Also assert that the skill tells authors not to claim completion without lint, independent review, and quality-gate artifacts.

Step 3: Run the repository-contract test and verify RED

PYTHONPATH=src python3 -m unittest \
  tests.test_repository_contracts.RepositoryContractTests.test_technical_author_skill_is_complete -v

Expected: failure because the required skill path is absent.

Step 4: Create the authoring skill and references

The skill must route every document through the repository sequence, treat inputs as untrusted data, keep provenance out of reader prose, and invoke the Korean revision skill for Korean technical blogs and READMEs. The review rubric must separate deterministic findings from model judgment. The logic contract must preserve context, choice, reason, alternative, accepted cost, guardrail, verification, and evidence status.

Step 5: Run the repository-contract test and verify GREEN

Run the Step 3 command.

Expected: pass.

Step 6: Commit the restored skill

git add .agents/skills/technical-document-author tests/test_repository_contracts.py
git commit -m "feat: restore technical document author skill"

Task 6: Revise and document the repository README

Files:

Modify: README.md
Create: examples/briefs/claridoc-readme.json
Modify: tests/test_schemas.py
Modify: tests/test_cli.py

Interfaces:

Consumes: DocumentType.README, shared prompt contract, and CLI validate/outline behavior.
Produces: a schema-valid README brief, documented usage, and a repository README written in the enforced style.
Step 1: Write failing example and CLI tests

Add tests that load examples/briefs/claridoc-readme.json, validate it through Brief.from_dict, and run the CLI validate and outline commands. Assert that the outline reports type readme and the eight approved intents.

Step 2: Run the focused tests and verify RED

PYTHONPATH=src python3 -m unittest \
  tests.test_schemas.SchemaTests.test_examples_match_runtime_contracts \
  tests.test_cli.CliTests.test_readme_brief_validates_and_outlines -v

Expected: failure because the README brief does not yet exist.

Step 3: Add the README brief fixture

Create a Korean readme brief for ClariDoc with hidden citations, style_profile: "auto", the current project scope, and no invented operational claims.

Step 4: Run the focused tests and verify GREEN

Run the Step 2 command.

Expected: pass.

Step 5: Revise README in place

Use revising-korean-technical-prose and its sentence-pattern reference. Preserve commands, tables, links, diagrams, versions, source hierarchy, provider descriptions, and safety statements. Convert reader-facing Korean prose to 합니다/했습니다, add supported 저는/제가 experience transitions, and add a section describing:

automatic activation for Korean technical blogs and READMEs;
STYLE002 and STYLE003;
model-review responsibilities;
a readme brief example and validation command.
Step 6: Scan the README contract

Run a read-only scanner using reader_prose_segments and assert:

plain_form_ending_count = 0
opening_has_first_person = true
experience_section_coverage >= 0.5

Review the diff to confirm facts, code blocks, links, and information order remain intact.

Step 7: Commit README migration

git add README.md examples/briefs/claridoc-readme.json \
  tests/test_schemas.py tests/test_cli.py
git commit -m "docs: apply Korean prose contract to README"

Task 7: Run regression validation and review the implementation

Files:

Modify only files required by verified failures in the preceding tasks.

Interfaces:

Consumes: all implemented tasks.
Produces: test and review evidence with no regenerated user-owned build or distribution artifacts.
Step 1: Run the full unit and integration suite

PYTHONPATH=src python3 -m unittest discover -s tests -v

Expected: all tests pass.

Step 2: Run non-destructive contract commands

PYTHONPATH=src python3 -m claridoc validate \
  --brief examples/briefs/claridoc-readme.json \
  --sources examples/sources/retry-policy-sources.json

PYTHONPATH=src python3 -m claridoc outline \
  --brief examples/briefs/claridoc-readme.json \
  --sources examples/sources/retry-policy-sources.json \
  --output /tmp/claridoc-readme-outline.json

Expected: both commands succeed and the output uses document_type: readme.

Step 3: Inspect destructive verification scope

Do not run scripts/verify.sh because it removes and rebuilds .verify, build, dist, egg-info, and demo outputs that already contain user changes. Run its non-destructive validation portions through the unit suite, schema tests, CLI tests, JSON parsing, local-link scan, and an isolated wheel build in /tmp.

Step 4: Run independent code review

Use superpowers:requesting-code-review to inspect the final diff against the design and plan. Resolve every blocker and error through a new failing test before changing production code.

Step 5: Run verification-before-completion

Use superpowers:verification-before-completion, rerun the full test suite, README style scan, schema validation, and isolated package build, and record the exact results.

Step 6: Finish the development branch

Use superpowers:finishing-a-development-branch. Because the user explicitly requested uninterrupted inline implementation on the current branch, do not merge, push, or open a PR without a new explicit request.

21 KiB Raw Blame History

Korean Experience-Prose Contract Implementation Plan

Global Constraints

Task 1: Add a first-class README document contract

Task 2: Centralize the Korean experience-prose prompt contract

Task 3: Add Markdown-aware deterministic style lint

Task 4: Make maintained fixtures satisfy the enforced contract

Task 5: Restore the technical-document authoring skill

Task 6: Revise and document the repository README

Task 7: Run regression validation and review the implementation

21 KiB

Raw Blame History