corestack/go
2
0 Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: add docs checker for ADRs and implementation plans #1

Merged
end merged 13 commits from feat/docs-checker into main 2026-10-23 15:56:04 -07:00
Conversation 0 Commits 13 Files Changed 27
+2464
end commented 2026-10-23 15:07:37 -07:00
Owner
Copy link
Copy source

Summary

Adds the first corestack component: cmd/docs, a CLI that creates and checks ADRs and implementation plans against a public spec.

  • Spec — docs/docs-format.md: timestamp IDs (YYYYMMDDTHHMMSSmmmZ-slug.md), YAML frontmatter keys and enums, ADR decision status separate from implementation status, supersession rules, plan statuses, MADR 4 body layout with a mandatory ### Consequences, and repo-root/durable reference rules.
  • CLI — docs new adr|plan "Title" writes embedded templates. docs check [--root DIR] reports path:line: message, sorted, and exits 0 (ok), 1 (problems) or 2 (usage).
  • Repo skeleton — go.mod (go.auvem.com/corestack), BSD-3-Clause LICENSE, README (no support guarantees; breaking changes before 1.0), minimal AGENTS.md and a CLAUDE.md pointer.
  • CI/release — .gitea/workflows/ci.yml runs gofmt, vet, go test -race, docs check and goreleaser check plus a snapshot. release.yml runs on v* tags and publishes darwin/linux × amd64/arm64 archives and checksums to Gitea releases.
  • First ADR — created with docs new adr: adopt a checked format for ADRs and implementation plans.

Install, once merged: go install go.auvem.com/corestack/cmd/docs@latest

Merge readiness

  • Review: independent architecture review (2 passes) and code review (3 passes). No actionable findings remain.
  • Local validation on 694c430: gofmt, vet, go test -race, docs check, go install and a goreleaser v2.19.0 snapshot with 4 archives all pass. A panic sweep over 395 real-world Markdown files was clean.
  • CI: see the checks on this PR.
  • Blocking: owner acceptance of the ADR. It is proposed / in-progress. On acceptance it flips to accepted / implemented with implemented_by set to this PR before merge.

Format decisions

All format decisions raised during delivery are resolved and recorded in the spec and ADR:

  • IDs use UTC milliseconds.
  • MADR 4 layout, with ### Consequences required under Decision Outcome.
  • implementation status is separate from decision status.
  • Plans: ## Outcome is optional.
  • Each reference key accepts only certain kinds of target; ADR tracking may point at a local plan.
  • Hidden files are ignored.
  • No directory config and no legacy mode. Migration policy lives in the standards repo.
  • Plan review companions (*-review.md) are dropped.
  • Releases are published by tag.

Unverified until first use: whether the Gitea-provided GITEA_TOKEN can write releases. Recommend proving it with a throwaway prerelease tag such as v0.0.0-rc.1 before v0.1.0.

Accepted limitations:

  • Slugs are ASCII-only.
  • Errors after a structural YAML error (e.g. duplicate key) surface on the next run.
  • Line numbers are approximate in files that use lone-CR line endings, which the spec doesn't allow anyway.

🤖 Generated with Claude Code

Delivery efficiency report (feature-efficiency/v1) 
schema: feature-efficiency/v1
rubric: scope-complexity/v1
feature: corestack/go docs checker (PR #1)
run_id: run_40bd8c4dcb9d
candidate_commit: 694c430
reported_at: 2026-10-23T22:10Z
skill_revision: 43bdc3c
outcome: ready_pending_owner_adr_acceptance
ci: success (runs 2309 push, 2310 pull_request)
sizing:
  basis: initial
  scope: 3        # create + check for two record types, spec, CI/release
  complexity: 2   # cross-file rules, modest branching, established Go precedent
  size_index: 6
  revisions: []   # owner decisions refined rules; required work unchanged
configuration:
  coordinator: {tool: claude-code, model: claude-opus-5-5, effort: null}
  implementer: {tool: claude-code, model: claude-sonnet-5-5, effort: medium, dispatches: 7}
  reviewer: {tool: claude-code, model: claude-opus-5-5, effort: medium, dispatches: 5}
  failed_attempts: 1  # same-terminal reuse refused (agent_unconfigured); fresh terminal used
review_passes:
  standard: {initial: 2, fix_verification: 3}   # architecture 1+1, code 1+2
  sensitive: {initial: 0, fix_verification: 0}
findings:
  product: 34
  test_harness: 2
  environment_resource: 2
  unknown: 0
  open: 0   # 1 skipped by disposition (spec-not-required), 1 nit accepted
corrective_human_interventions: 0
full_validation_attempts: 1  # local final suite on 694c430, passed first time
diff: {go: 1216, tests: 704, docs_md: 416, other: 127}
elapsed_minutes: ~75   # run create 20:55Z to CI green ~22:09Z
usage: null   # no supported usage source available
## Summary Adds the first corestack component: `cmd/docs`, a CLI that creates and checks ADRs and implementation plans against a public spec. - **Spec** — [`docs/docs-format.md`](/docs/docs-format.md): timestamp IDs (`YYYYMMDDTHHMMSSmmmZ-slug.md`), YAML frontmatter keys and enums, ADR decision status separate from `implementation` status, supersession rules, plan statuses, MADR 4 body layout with a mandatory `### Consequences`, and repo-root/durable reference rules. - **CLI** — `docs new adr|plan "Title"` writes embedded templates. `docs check [--root DIR]` reports `path:line: message`, sorted, and exits 0 (ok), 1 (problems) or 2 (usage). - **Repo skeleton** — `go.mod` (`go.auvem.com/corestack`), BSD-3-Clause LICENSE, README (no support guarantees; breaking changes before 1.0), minimal AGENTS.md and a CLAUDE.md pointer. - **CI/release** — `.gitea/workflows/ci.yml` runs gofmt, vet, `go test -race`, `docs check` and `goreleaser check` plus a snapshot. `release.yml` runs on `v*` tags and publishes darwin/linux × amd64/arm64 archives and checksums to Gitea releases. - **First ADR** — created with `docs new adr`: [adopt a checked format for ADRs and implementation plans](/docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md). Install, once merged: `go install go.auvem.com/corestack/cmd/docs@latest` ## Merge readiness - **Review:** independent architecture review (2 passes) and code review (3 passes). No actionable findings remain. - **Local validation on 694c430:** gofmt, vet, `go test -race`, `docs check`, `go install` and a goreleaser v2.19.0 snapshot with 4 archives all pass. A panic sweep over 395 real-world Markdown files was clean. - **CI:** see the checks on this PR. - **Blocking: owner acceptance of the ADR.** It is `proposed` / `in-progress`. On acceptance it flips to `accepted` / `implemented` with `implemented_by` set to this PR before merge. ## Format decisions All format decisions raised during delivery are resolved and recorded in the spec and ADR: - IDs use UTC milliseconds. - MADR 4 layout, with `### Consequences` required under Decision Outcome. - `implementation` status is separate from decision status. - Plans: `## Outcome` is optional. - Each reference key accepts only certain kinds of target; ADR `tracking` may point at a local plan. - Hidden files are ignored. - No directory config and no legacy mode. Migration policy lives in the standards repo. - Plan review companions (`*-review.md`) are dropped. - Releases are published by tag. **Unverified until first use:** whether the Gitea-provided `GITEA_TOKEN` can write releases. Recommend proving it with a throwaway prerelease tag such as `v0.0.0-rc.1` before `v0.1.0`. **Accepted limitations:** - Slugs are ASCII-only. - Errors after a structural YAML error (e.g. duplicate key) surface on the next run. - Line numbers are approximate in files that use lone-CR line endings, which the spec doesn't allow anyway. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <details> <summary>Delivery efficiency report (feature-efficiency/v1)</summary> ```yaml schema: feature-efficiency/v1 rubric: scope-complexity/v1 feature: corestack/go docs checker (PR #1) run_id: run_40bd8c4dcb9d candidate_commit: 694c430 reported_at: 2026-10-23T22:10Z skill_revision: 43bdc3c outcome: ready_pending_owner_adr_acceptance ci: success (runs 2309 push, 2310 pull_request) sizing: basis: initial scope: 3 # create + check for two record types, spec, CI/release complexity: 2 # cross-file rules, modest branching, established Go precedent size_index: 6 revisions: [] # owner decisions refined rules; required work unchanged configuration: coordinator: {tool: claude-code, model: claude-opus-5-5, effort: null} implementer: {tool: claude-code, model: claude-sonnet-5-5, effort: medium, dispatches: 7} reviewer: {tool: claude-code, model: claude-opus-5-5, effort: medium, dispatches: 5} failed_attempts: 1 # same-terminal reuse refused (agent_unconfigured); fresh terminal used review_passes: standard: {initial: 2, fix_verification: 3} # architecture 1+1, code 1+2 sensitive: {initial: 0, fix_verification: 0} findings: product: 34 test_harness: 2 environment_resource: 2 unknown: 0 open: 0 # 1 skipped by disposition (spec-not-required), 1 nit accepted corrective_human_interventions: 0 full_validation_attempts: 1 # local final suite on 694c430, passed first time diff: {go: 1216, tests: 704, docs_md: 416, other: 127} elapsed_minutes: ~75 # run create 20:55Z to CI green ~22:09Z usage: null # no supported usage source available ``` </details>
end added 12 commits 2026-10-23 15:07:38 -07:00
docs: add docs format specification b4fab41135 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
docs: revise format spec after review 4cdc29bf3f 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
docs: apply architecture review pass 2 fixes f8a76a9ab0 
Clarify null scalars, marker handling in frontmatter, the Decision Outcome
prose rule, section extent wording and link rule scope.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
chore: add module, license and repository guides b0428256bd 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
feat: add docs checker and record templates 750b7449b0 
docs new creates ADRs and plans from embedded templates; docs check reports
path:line: message problems per docs/docs-format.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
ci: add Gitea workflows and goreleaser config e5c203d465 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
docs: record decision to adopt a checked docs format e33e8df6c6 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
ci: keep goreleaser to a single token in the release job ddebde0b2e 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
docs: correct two statements in the format ADR 789931d90f 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
fix: address docs checker review findings d579e38ba5 
Check every link reference definition, decode destinations per CommonMark,
report correct lines for empty headings, autolinks and nested definitions,
reject symlinked record directories and wrong-case path components, and
refuse titles that cannot pass. Only top-level headings count (spec section 6).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
docs: specify docs directory and path-case rules 9eec1d1016 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
fix: harden docs checker heading lines, definitions and docs symlinks
ci / check (push) Successful in 59s
Details
ci / check (pull_request) Successful in 58s
Details
694c43051e 
- N1: never call Lines() on inline nodes; locate empty ATX headings after the
  end of all preceding blocks (no panic, correct line after `***`)
- N2: take reference definition lines from ast.LinkReferenceDefinition and
  drop refCtx/defRe
- N3: reject docs/adr and docs/plans that resolve outside the repository

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
end added 1 commit 2026-10-23 15:55:33 -07:00
docs: accept docs format ADR
ci / check (push) Successful in 18s
Details
ci / check (pull_request) Successful in 17s
Details
e2ddd76536 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
end merged commit cc482d9a9b into main 2026-10-23 15:56:04 -07:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
end (Elijah Duffy) selias (Sebastian Elias)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: corestack/go#1