chore!: remove ClariDoc harness
.run/의 세 런을 조사한 결과 claridoc run 파이프라인이 한 번도 완주하지 않았다. quality-gate.json 0건, stages/ 및 rounds/ 부재. 실사용 범위는 validate/collect/outline까지였고 글쓰기와 검수는 스킬이 담당했다. 파이썬 패키지, CLI, 스키마, 테스트, 예제, 조사 자료, 빌드·배포 산출물, 하네스 규약 문서를 제거한다. 남는 것은 Agent Skill 세 개, .run/의 문서 세 편, CLAUDE.md, README.md, LICENSE, 제거 결정 문서다. examples/golden의 구버전 초안 두 편(n+1liner.md 1416줄, claridoc-rewrite/document.md 1626줄)과 루트 document.md(.run 판과 md5 동일한 사본)도 함께 지운다. .run/에 더 진행된 판이 있다. 복구: git checkout pre-harness-removal -- <경로> 근거: docs/decisions/2026-08-07-remove-claridoc-harness.md Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
co-authored by
Claude Opus 5
Claude Opus 5
parent
7dae5a9359
commit
ef1f76146e
@@ -1,630 +0,0 @@
|
||||
# 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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```python
|
||||
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**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
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**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```python
|
||||
@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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
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**
|
||||
|
||||
```bash
|
||||
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**
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python3 -m unittest discover -s tests -v
|
||||
```
|
||||
|
||||
Expected: all tests pass.
|
||||
|
||||
- [ ] **Step 2: Run non-destructive contract commands**
|
||||
|
||||
```bash
|
||||
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.
|
||||
@@ -1,292 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,46 +0,0 @@
|
||||
# Runtime Call / Source Dependency SVG Split Design
|
||||
|
||||
## Brief
|
||||
|
||||
Split the two panels in `runtime-call-source-dependency.svg` into two standalone SVG assets. Do not change reader-facing Markdown or remove the existing combined SVG.
|
||||
|
||||
## Local evidence
|
||||
|
||||
- The combined SVG is a `1400 × 660` canvas with an upper runtime-call panel and a lower source-dependency panel.
|
||||
- Identical assets exist in the generated run output and the golden fixture.
|
||||
- Both corresponding documents currently reference the combined SVG.
|
||||
- No maintained generator source for this asset exists in the repository; the metadata only names a historical `_work/regenerate-technical-assets.py` path.
|
||||
|
||||
## Output
|
||||
|
||||
Create these files in both asset directories:
|
||||
|
||||
- `runtime-call.svg`: the upper “실행 시점 관계” panel.
|
||||
- `source-dependency.svg`: the lower “계약 소유·소스 의존” panel.
|
||||
|
||||
Each file will be a complete, independently renderable SVG with:
|
||||
|
||||
- a tightly fitted canvas and `viewBox`;
|
||||
- its own accessible `<title>` and `<desc>`;
|
||||
- only the marker definitions it uses;
|
||||
- the same typography, colors, labels, nodes, and relationships as its source panel.
|
||||
|
||||
The existing `runtime-call-source-dependency.svg` remains unchanged for compatibility. Markdown references and alt text remain unchanged.
|
||||
|
||||
## Geometry
|
||||
|
||||
The panels will retain their original `1400`-unit width so horizontal proportions do not change. Vertical coordinates will be translated upward to remove the unused space belonging to the other panel. A small outer margin will be preserved around each panel.
|
||||
|
||||
The runtime-call asset will contain only `FeedController → GetFeedUseCase → SpringTransactionPort` and its solid-arrow labels. The source-dependency asset will contain only the interface, implementation, and dashed dependency relationships from the lower panel.
|
||||
|
||||
## Validation
|
||||
|
||||
- Parse all four new files as XML.
|
||||
- Confirm each SVG has the expected root dimensions, `viewBox`, title, description, and referenced marker definitions.
|
||||
- Confirm the runtime asset excludes lower-panel labels and the source-dependency asset excludes upper-panel labels.
|
||||
- Confirm the golden and run-output copies are byte-identical for each new asset.
|
||||
- Render or inspect both assets to catch clipping and layout regressions.
|
||||
|
||||
## Scope boundary
|
||||
|
||||
This change does not revise document prose, document image references, the existing combined asset, the technical-writing pipeline, or the asset-generation system.
|
||||
Reference in New Issue
Block a user