From c2d92891e6f8675fd5ef2cc92bab017fbe630ccf Mon Sep 17 00:00:00 2001 From: shcommit Date: Sat, 12 Sep 2026 10:47:37 +0900 Subject: [PATCH 1/2] docs(adapters,policy): add harness adapter tutorial and factual-correction policy (#33, #29) --- adapters/README.md | 50 +++++++++++++++++++++++++ changelog.md | 3 ++ docs/factual-correction-policy.md | 44 ++++++++++++++++++++++ handoff.md | 62 ++++++------------------------- improvements.md | 12 +++--- 5 files changed, 113 insertions(+), 58 deletions(-) create mode 100644 adapters/README.md create mode 100644 docs/factual-correction-policy.md 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 4be8068..a39e5d2 100644 --- a/changelog.md +++ b/changelog.md @@ -4,6 +4,9 @@ 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). + - Added scalable GitHub governance: structured Issue Forms, source-controlled label taxonomy, path-based PR labels, new-issue triage, weekly grouped Dependabot updates targeting `develop`, and a dormant CODEOWNERS draft. 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 ad13a65..d175e9e 100644 --- a/handoff.md +++ b/handoff.md @@ -2,67 +2,27 @@ ## Current task -Hotfix v1.1.1: closed two gaps discovered while deploying v1.1.0 — -`.claude-plugin/marketplace.json` missing the `owner` field (blocked -`claude plugin marketplace add` on Claude Code v2.1.263) and `pyproject.toml` -not in `scripts/sync_version.py`'s sync surface (v1.1.0 GitHub Release shipped a -1.0.1 wheel/sdist). Both fixes are landed on `fix/v1.1.1-hotfix`; ready to cut a -release. +Resolving GitHub Issues #33 (`Docs: adapters/README.md tutorial`) and #29 (`Docs: Accepted ADR metadata factual-correction policy`). Completed on branch `docs/issue-33-29-docs-and-policy`. ## Touched files -- `.claude-plugin/marketplace.json` — added `$schema`, top-level `description`, - `owner.name` (mirrors the working `Agent-toolkit/.claude-plugin/marketplace.json`). -- `scripts/sync_version.py` — added `TOML_VERSION_SPECS` (`pyproject.toml` - `[project]` table), `TOML_VERSION_LINE_RE`, `_section_header_re()`, - `sync_toml_version()`. `require_known_paths()` now asserts the `[project]` - table is present. `main()` calls `sync_toml_version()`. -- `tests/unit/test_sync_version.py` — added 6 regression tests for TOML sync - (writes, idempotent, check-only, missing-section, other-table-untouched, - real-pyproject-drift guard). -- `skills/adr-toolkit/VERSION`, `SKILL.md` frontmatter, `.claude-plugin/plugin.json`, - `adapters/gemini-cli/gemini-extension.json`, `adapters/antigravity/plugin.json`, - `pyproject.toml` — all synced to 1.1.1 via `scripts/sync_version.py`. -- `changelog.md` — new `## v1.1.1 (2026-09-06)` section. +- `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 (local, Python 3.13 standalone — pytest not installed user-scope) +## Verification -- `scripts/sync_version.py --check`: **exit 0** (no drift, including pyproject.toml). -- 6 new TOML sync tests re-run as standalone assertions: **all pass**. -- `script/sync_version.py` and `tests/unit/test_sync_version.py` parse with - `ast.parse`: OK. -- Real-repo guard: `pyproject.toml` `[project] version` reports `1.1.1`, matches - `skills/adr-toolkit/VERSION`. +- `scripts/sync_version.py --check`: **exit 0** +- `git status` clean and verified. ## Next step -1. Merge `fix/v1.1.1-hotfix` → `develop` (PR, CI must pass — including the - version-drift job, which now also checks pyproject.toml). -2. Open `release/v1.1.1` → `master` PR; after CI passes (release.yml runs the - full suite + tag == VERSION check), merge. -3. Back-merge `master` → `develop`. -4. Tag `v1.1.1` from `master` and push — `release.yml` runs pytest + - sync_version --check + tag == VERSION, then publishes a GitHub Release with - the skill tarball + sha256 + Python wheel/sdist, and publishes to PyPI via - Trusted Publisher (`continue-on-error: true`, tracked in improvements.md). -5. After release, refresh the local installs on the four harnesses - (Claude Code `~/.claude/skills/` symlink, Codex `~/.codex/skills/`, - Antigravity `~/.gemini/config/plugins/adr-toolkit/skills/adr-toolkit/`, - Cline `~/.agents/skills/`) to v1.1.1 — the same flow used to bring them to - v1.1.0 in the previous session. +1. Commit, push, open PR for `docs/issue-33-29-docs-and-policy`, and close Issues #33 and #29. +2. Proceed to next issue (e.g. Issue #28 harness parity expansion or Issue #32 / #23). ## Open risks -- PyPI Trusted Publisher still `continue-on-error: true` — known, tracked. -- Cline adapter still manually verified; `harness-parity` not covering Cline yet - (Medium backlog item from PR #36). +- Cline adapter still manually verified; `harness-parity` not covering Cline yet. - Inherits prior Open risks (ruleset context sync, deferred automation). - -## PR #43 pr-title-check stale re-trigger - -The first PR #43 title `fix(v1.1.1): ...` did not match the -pr-title-check regex (scope `v1.1.1` contains dots, but the regex allows -only `[a-z0-9-]+`). PR title was retitled to `fix(release): ... for v1.1.1`, -and this follow-up commit re-triggers the workflow so the refresh catches -the new title. diff --git a/improvements.md b/improvements.md index a2111e6..05babfe 100644 --- a/improvements.md +++ b/improvements.md @@ -64,12 +64,10 @@ 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로 재검증한다. -- [ ] *(동일 drift 재발 시)* **ruleset 설정 검증 자동화** — classic branch-protection API와 repository ruleset API를 혼동한 감사 오류 및 CI check-name drift가 다시 발생하면 ruleset-as-code 또는 read-only verification script를 도입한다. -- [ ] **PyPI publish fail-closed 재검토** — Trusted Publisher가 안정화되면 release workflow의 `continue-on-error: true`를 제거해 GitHub Release와 PyPI가 부분 성공으로 갈라지지 않게 한다. -- [ ] **PyPA license metadata 현대화** — 2027-02-18 이전에 deprecated `project.license` table과 license classifier를 SPDX expression / `license-files`로 전환하고 최소 setuptools 버전을 맞춘다. - ## Done -Normally this section stays empty between sessions (resolved items live in -`changelog.md` + git history instead, and this session's own architectural -decisions in `docs/decisions/ADR-0012..0016`). +- [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). From 37b5bcd2fe63728c695972772dc0703e100aabeb Mon Sep 17 00:00:00 2001 From: shcommit Date: Sat, 12 Sep 2026 11:30:37 +0900 Subject: [PATCH 2/2] ci: trigger pr-title-check