diff --git a/adapters/README.md b/adapters/README.md new file mode 100644 index 0000000..64c3cf3 --- /dev/null +++ b/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/ +``` + +### 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//` or root configuration directory. +2. Ensure the manifest references `skills/adr-toolkit` as its skill target. +3. Write a clear `adapters//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//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__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. diff --git a/changelog.md b/changelog.md index a5508c1..b1ead37 100644 --- a/changelog.md +++ b/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). diff --git a/docs/factual-correction-policy.md b/docs/factual-correction-policy.md new file mode 100644 index 0000000..0801cbc --- /dev/null +++ b/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] ` +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. diff --git a/handoff.md b/handoff.md index 353a223..3af0095 100644 --- a/handoff.md +++ b/handoff.md @@ -2,14 +2,12 @@ ## 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. @@ -17,14 +15,12 @@ Resolving GitHub Issues #30 (`Build: PyPA license metadata 현대화`) and #26 ( ## 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 diff --git a/improvements.md b/improvements.md index c3ea0cb..8a0f201 100644 --- a/improvements.md +++ b/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).