docs: add harness adapter tutorial and factual correction policy

adapters/README.md

@@ -0,0 +1,50 @@
+# Harness Adapters
+
+This directory contains harness-specific adapters and integration documentation for connecting `adr-toolkit` to various AI coding assistants and CLI harnesses.
+
+---
+
+## Supported Harnesses
+
+| Harness Adapter | Directory | Type | Key Files |
+| :--- | :--- | :--- | :--- |
+| **Claude Code** | `adapters/claude/` | Manifest-based | `.claude-plugin/plugin.json`, `marketplace.json` |
+| **Codex CLI** | `adapters/codex/` | Manifest-based | `adapters/codex/marketplace.json` |
+| **Gemini CLI** | `adapters/gemini-cli/` | Manifest-based | `adapters/gemini-cli/gemini-extension.json` |
+| **Antigravity CLI** | `adapters/antigravity/` | Manifest-based | `adapters/antigravity/plugin.json` |
+| **Cline CLI / ClinePass** | `adapters/cline/` | Documentation (SKILL.md standard) | `adapters/cline/README.md` |
+| **Generic Agent** | `adapters/generic/` | Open Agent Skills Standard | `adapters/generic/README.md` |
+
+---
+
+## Tutorial: Adding a New Harness Adapter
+
+Follow these step-by-step instructions to create an adapter for a new AI coding assistant or CLI harness.
+
+### Step 1: Create the Adapter Directory
+Create a dedicated subdirectory under `adapters/`:
+```bash
+mkdir -p adapters/<harness-name>
+```
+
+### Step 2: Determine Adapter Type
+
+#### Type A: Manifest-Based Adapter
+If the harness supports native CLI plugin or extension registries via JSON manifests:
+1. Create the required JSON manifest in `adapters/<harness-name>/` or root configuration directory.
+2. Ensure the manifest references `skills/adr-toolkit` as its skill target.
+3. Write a clear `adapters/<harness-name>/README.md` explaining installation and CLI discovery commands.
+
+#### Type B: Open Agent Skills Standard (README-Only)
+If the harness natively supports the open `SKILL.md` standard (like Cline or Generic Agents):
+1. No separate manifest JSON is needed.
+2. Create `adapters/<harness-name>/README.md` detailing the standard installation command (e.g., skill add commands or symlinks).
+
+### Step 3: Register in Version Sync Tooling (If Applicable)
+If your adapter contains a JSON manifest with a hardcoded version string:
+- Register the manifest file path and JSON key pattern in `scripts/sync_version.py`.
+- Add a corresponding regression test in `tests/unit/test_<harness_name>_adapter.py`.
+
+### Step 4: Verification and CI Integration
+1. Run `python scripts/sync_version.py --check` to verify no version drift.
+2. Add end-to-end integration test steps to `.github/workflows/test.yml` under the `harness-parity` job if automated CLI testing is supported.

changelog.md

@@ -4,6 +4,8 @@ Lightweight human-readable summary of meaningful repository changes.
 
 ## Unreleased
 
+- Added step-by-step tutorial for adding new harness adapters in `adapters/README.md` (#33).
+- Added `docs/factual-correction-policy.md` defining in-place metadata correction vs. decision superseding policy for Accepted ADRs (#29).
 - Modernized PyPA license metadata in `pyproject.toml` to SPDX expression (`license = "MIT"`) and `license-files` (#30).
 - Automated GitHub ruleset required-check drift verification with `scripts/verify_rulesets.py`, unit tests, and CI `ruleset-drift` job (#26).
 - Switched PyPI publishing in `.github/workflows/release.yml` to fail-closed by removing `continue-on-error: true` (#22).

docs/factual-correction-policy.md

@@ -0,0 +1,44 @@
+# Accepted ADR Factual Correction Policy
+
+This document defines the governance policy for making minor metadata and factual corrections to **`ACCEPTED`** Architecture Decision Records (ADRs) without invalidating their decision lifecycle or requiring a formal superseding process.
+
+---
+
+## 1. Overview & Core Philosophy
+
+Architecture Decision Records (ADRs) are immutable historical logs of key architectural decisions. Once an ADR reaches the `ACCEPTED` state, its decision context, rationale, and consequences are considered settled.
+
+However, non-substantive factual errors (such as typos, broken links, date formatting errors, or broken path references) occasionally require maintenance. This policy establishes a clear boundary between **Allowed Factual Corrections** (in-place edits) and **Decision Changes** (which require `adr supersede`).
+
+---
+
+## 2. Permitted Modifications (In-Place Edits Allowed)
+
+The following minor changes may be made directly to an `ACCEPTED` ADR via a standard Pull Request:
+
+1. **Typographical & Grammatical Fixes**: Correcting spelling errors, punctuation, or formatting issues that do not alter the technical meaning.
+2. **Link & Path Updates**: Fixing broken URLs, updating repository file links, or updating relative documentation paths.
+3. **Frontmatter Metadata Corrections**:
+   - Fixing date format syntax errors (e.g. ISO 8601 formatting).
+   - Correcting misspelled author names or contributor tags.
+   - Updating non-semantic metadata fields (e.g. tags, categories).
+
+---
+
+## 3. Prohibited Modifications (Requires `adr supersede`)
+
+The following changes **CANNOT** be made in-place to an `ACCEPTED` ADR:
+
+1. **Modifying Technical Rationale or Context**: Altering the original trade-offs, problem statement, or decision context.
+2. **Changing the Decision Outcome**: Reversing, modifying, or expanding the scope of an architectural decision.
+3. **Altering Status Directly**: Changing `ACCEPTED` to `REJECTED` or `SUPERSEDED` by hand. Status transitions MUST use the `adr supersede` command to create a new successor ADR and maintain a verifiable audit trail.
+
+---
+
+## 4. Workflow & PR Conventions
+
+When submitting an in-place factual correction for an `ACCEPTED` ADR:
+
+1. **PR Title / Commit Prefix**: Use `docs(adr): [factual correction] <short description>`
+2. **PR Description**: Explicitly state that the edit is a non-substantive factual correction under this policy.
+3. **Review Requirement**: At least one standard maintainer review is required before merging.

handoff.md

@@ -2,29 +2,25 @@
 
 ## Current task
 
-Resolving GitHub Issues #30 (`Build: PyPA license metadata 현대화`) and #26 (`CI: ruleset required-check drift 자동 검증`). Branch `fix/issue-30-26-build-ci-hardening`.
+Resolving GitHub Issues #33 (`Docs: adapters/README.md tutorial`) and #29 (`Docs: Accepted ADR metadata factual-correction policy`). Branch `docs/issue-33-29-docs-and-policy`.
 
 ## Touched files
 
-- `pyproject.toml` — modernized license metadata to SPDX expression (`license = "MIT"`), added `license-files = ["LICENSE*"]`, and removed deprecated license classifier per PEP 639.
-- `scripts/verify_rulesets.py` — created script for ruleset required-check drift verification.
-- `tests/unit/test_ruleset_drift.py` — added regression test for ruleset drift verification.
-- `.github/workflows/test.yml` — added `ruleset-drift` CI job.
+- `adapters/README.md` — added overview table and step-by-step tutorial for adding new harness adapters.
+- `docs/factual-correction-policy.md` — defined permitted in-place metadata edits vs prohibited decision changes for Accepted ADRs.
 - `improvements.md` — moved resolved items to Done.
 - `changelog.md` — added notes under `## Unreleased`.
 - `handoff.md` — this file.
 
 ## Verification
 
 - `scripts/sync_version.py --check`: **exit 0**
-- `python -m build`: **exit 0**
-- `pytest tests/unit`: **537 passed**
-- `git status` / `git diff` clean and verified.
+- `git status` clean and verified.
 
 ## Next step
 
-1. Complete merge of `origin/develop` into `fix/issue-30-26-build-ci-hardening` and push.
-2. Verify PR #50 merge status on GitHub.
+1. Merge PR #51 into `develop`.
+2. Proceed to PR #52 and PR #53 merges.
 
 ## Open risks
 

improvements.md

@@ -64,8 +64,11 @@ Backlog derived from `docs/adr-toolkit-audit-report.md`, operational experiences
 - [ ] *(전제조건: qualified maintainer 2명 이상)* **CODEOWNERS 독립 승인 활성화** — 현재 1인 운영 상태에서 필수 code-owner review를 켜면 운영을 막거나 형식적 self-review만 만든다고 보고서 자체가 명시적으로 경고함. 인원 조건 충족 전엔 시작하지 않음. (enterprise-adoption.md §4, §9 "지금 구현하지 않을 것")
 - [ ] *(전제조건: 저장소 2개 이상)* **조직 단위 ruleset/reusable workflow/audit export/taxonomy** — 여러 저장소가 같은 운영 문제를 반복할 때 설계 시작. 지금은 저장소가 1개뿐이라 시작 조건 미충족. (enterprise-adoption.md §6, §8 항목 5)
 - [ ] *(다음 governance PR merge 직후)* **required-check context 동기화** — ruleset `22101891`에서 Python 3.9 context를 제거하고 Python 3.10 matrix, `lint`, `dependency-audit`를 required로 추가한 뒤 effective-rules API로 재검증한다.
+
 ## Done
 
+- [x] **'새 harness adapter 추가하기' 튜토리얼 작성** — `adapters/README.md` 가이드 및 규격 정리 완료 (#33).
+- [x] **Accepted ADR metadata factual-correction policy 설계** — `docs/factual-correction-policy.md` 정책 문서 정의 완료 (#29).
 - [x] **PyPA license metadata 현대화** — SPDX 표현식 (`license = "MIT"`) 및 `license-files = ["LICENSE*"]` 적용 완료 (#30).
 - [x] **ruleset 설정 검증 자동화** — `scripts/verify_rulesets.py` 및 CI `ruleset-drift` job과 단위 테스트 추가로 ruleset drift 자동 검증 도입 (#26).
 - [x] **PyPI publish fail-closed 재검토** — Trusted Publisher가 안정화되어 release workflow의 `continue-on-error: true`를 제거하고 fail-closed로 전환 완료 (#22).