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,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