From 6fee9584e5200b122c3761ac7660227eb8ff1656 Mon Sep 17 00:00:00 2001
From: Elijah Duffy <elijah@thatoneguy.ca>
Date: Sun, 25 Oct 2026 14:21:29 -0700
Subject: [PATCH 1/4] chore: adopt Corestack project standards

---
 .gitea/workflows/ci.yml         |  5 ++++
 .gitea/workflows/docs-check.yml | 15 +++++++++++
 .gitea/workflows/release.yml    |  3 +++
 .golangci.yml                   | 12 +++++++++
 AGENTS.md                       | 48 ++++++++++++++++++++++++++++++---
 docs/adr/README.md              | 29 ++++++++++++++++++++
 6 files changed, 109 insertions(+), 3 deletions(-)
 create mode 100644 .gitea/workflows/docs-check.yml
 create mode 100644 .golangci.yml
 create mode 100644 docs/adr/README.md

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index 73c5864..584467c 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -19,6 +19,11 @@ jobs:
       - run: go vet ./...
       - run: go test -race ./...
       - run: go run ./cmd/docs check
+      - name: Require issue URLs in TODO comments
+        run: |
+          find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
+      - name: Go lint
+        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...
       - uses: goreleaser/goreleaser-action@v7.3.0
         with:
           distribution: goreleaser
diff --git a/.gitea/workflows/docs-check.yml b/.gitea/workflows/docs-check.yml
new file mode 100644
index 0000000..d5b6dc1
--- /dev/null
+++ b/.gitea/workflows/docs-check.yml
@@ -0,0 +1,15 @@
+name: Documentation
+on: [push, pull_request]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-go@v7.0.0
+        with:
+          go-version-file: go.mod
+          cache: false
+      - run: go run go.auvem.com/corestack/cmd/docs@v0.1.0 check
+      - name: Require issue URLs in TODO comments
+        run: |
+          find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml
index 2cb5e95..221112b 100644
--- a/.gitea/workflows/release.yml
+++ b/.gitea/workflows/release.yml
@@ -15,6 +15,9 @@ jobs:
       - uses: actions/setup-go@v7.0.0
         with:
           go-version-file: go.mod
+      - name: Require issue URLs in TODO comments
+        run: |
+          find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
       - uses: goreleaser/goreleaser-action@v7.3.0
         with:
           distribution: goreleaser
diff --git a/.golangci.yml b/.golangci.yml
new file mode 100644
index 0000000..b89de23
--- /dev/null
+++ b/.golangci.yml
@@ -0,0 +1,12 @@
+version: "2"
+linters:
+  default: none
+  enable:
+    - revive
+  settings:
+    revive:
+      rules:
+        - name: exported
+        - name: package-comments
+  exclusions:
+    presets: []
diff --git a/AGENTS.md b/AGENTS.md
index ce6ee12..0f322e2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,9 +1,51 @@
 # AGENTS.md
 
-Go module `go.auvem.com/corestack`. Reading map:
+## Commands
+- Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below.
+- Generate: No code generation is configured; format with `gofmt -w .`.
+- Documentation: `go run go.auvem.com/corestack/cmd/docs@v0.1.0 check`; use the same pinned command with `new adr "Title"` or `new plan "Title"` to create records. Also run `go run ./cmd/docs check` to test the local implementation.
+
+## Scope and decisions
+- Before editing under a directory with its own AGENTS.md, read it. Scoped files: none; this root governs the single Go module.
+- Explicit user instructions win; nearer scoped rules override broader rules.
+- Distinguish confirmed requirements, proposed defaults and unresolved decisions; resolve material ambiguity before dependent work.
+- Proposed ADRs are context, not authority; read relevant accepted decisions before changing their scope.
+- Before final review and merge, reconcile affected records against the latest target branch plus the PR, following [/docs/adr/README.md](/docs/adr/README.md).
+- Documentation tier: ADRs only. Create a plan only when work needs durable execution context across areas, phases or sessions; then enable the plans tier.
+- In a sandbox, request required network/cache access before first codegen; on permission/cache errors retry once with that access. Never hand-edit generated output.
+- Shared databases and ports may belong to other worktrees/agents; read project rules before starting, stopping or resetting them.
+- Ask before lint/autofix changes that could alter runtime behavior.
+- Report commands actually run and their results; never claim an unrun check passed.
+- Name branches `<type>/<kebab>` without agent-name prefixes.
+
+## Comments
+- Document package/module purpose, ownership and boundaries, and every public/exported contract in native doc comments; document generated surfaces at their source.
+- Explain why at invariants, auth decisions, concurrency/ordering, destructive edges and deliberate deviations; no narration, changelog comments or commented-out code.
+- Use `invariant: <property>`, `authz: <who and enforcement>`, `shortcut: <limit>, <when to upgrade>` on relevant code; retain Go `Deprecated:` and Rust `// SAFETY:`.
+- Every TODO needs an issue URL; reviewers recheck tagged comments on touched code.
+
+## Project map
+
+Go module `go.auvem.com/corestack`.
 
-- Build and test: `go build ./...`, `go vet ./...`, `go test -race ./...`; format with `gofmt -w .`.
 - Docs format (the spec `docs check` implements): `docs/docs-format.md`.
-- Check records: `go run ./cmd/docs check`. Create one: `go run ./cmd/docs new adr|plan "Title"`.
 - Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them.
 - Dependencies are limited to `go.yaml.in/yaml/v3` and `github.com/yuin/goldmark`.
+
+## Go
+- Default backend language is Go; follow existing package boundaries.
+- Define interfaces at the consumer only when a second implementation or a test seam needs one.
+- Wrap contextual errors with `%w`; inspect causes with `errors.Is`/`errors.As`.
+- Do not add package-level mutable state or `init` side effects.
+- Put `context.Context` first in parameters; never store it in a struct.
+- Give every goroutine an owner and a shutdown path.
+- Run `gofmt`, `go vet ./...`, tests and the project's configured linter from the owning module.
+- Use `.golangci.yml` (revive exported/package-comments); the pinned linter command is listed above.
+
+## TODO check
+
+Run from the project root (also enforced in CI):
+
+```sh
+find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
+```
diff --git a/docs/adr/README.md b/docs/adr/README.md
new file mode 100644
index 0000000..39e4fd5
--- /dev/null
+++ b/docs/adr/README.md
@@ -0,0 +1,29 @@
+Baseline copied from corestack/standards at a36288e7cec933a32f4819a1308201027c9f57ec; this project owns and may adapt it.
+
+# Documentation policy
+
+The [corestack/go docs-format specification](https://gitea.auvem.com/corestack/go/src/branch/main/docs/docs-format.md) owns record format, templates, and validation. In scaffolded projects, generate records and run checks with the pinned documentation command in the root AGENTS.md; do not maintain local format templates.
+
+The copied policy is a project-owned baseline that the project may adapt; scaffold re-runs never refresh it unless the owner explicitly asks. The project owns its locked checker pin and upgrades: update the tag and ensure compliance; scaffold re-runs retain the existing pin unless the owner asks.
+
+## Choose the smallest useful tier
+
+| Tier | Use when | Scaffold output |
+| --- | --- | --- |
+| Neither | A single-purpose CLI, library, or script has no consequential architectural choice or durable execution context yet. | No record directories and no docs-check CI step; root instructions tell agents to ask the owner to run scaffold-project to enable records when a consequential choice arises. |
+| ADRs only | Consequential choices need durable rationale, but execution fits a short issue or PR. | Local policy in docs/adr/README.md, ADRs as warranted and docs-check CI. |
+| ADRs + plans | Work spans areas, phases, or sessions and needs durable execution context. | Local policy in docs/adr/README.md, a docs/plans/README.md pointer, ADRs as warranted, one file per plan, and docs-check CI. |
+
+Project size is a signal, not an exemption: a small security-sensitive library can warrant an ADR. Add the CI docs-check step exactly when the selected tier enables records. Change tiers when actual work warrants it; do not create empty record directories in anticipation.
+
+## Decisions and execution
+
+Write an ADR for a consequential choice among real alternatives: difficult to reverse, crossing areas, changing a boundary, data model or security posture, or establishing a convention. Routine details and choices already governed by an accepted ADR or practice guide do not need another record. Read relevant accepted decisions and verify their claims against code before dependent work. Proposed ADRs are context, not authority; only the owner accepts a decision.
+
+Write a plan when work spanning areas, phases or sessions needs durable execution context. Otherwise keep planning in a PR, issue or chat. Each plan has its own file; the directory is the index. Never create a central living plan or living PRD checklist that parallel worktrees continually edit. Closed plans are history, never standing instructions.
+
+Use `write-adr` and `review-adr` when available: they guide reasoning while deferring textual format to repository conventions. Seek independent review and owner acceptance before treating a proposal as binding. Neither a self-check nor an independent recommendation accepts an ADR. ADRs may share a PR with implementation; no separate ADR PR or extra sections are required by this policy.
+
+## Reconcile before final review and merge
+
+Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `docs check` using the pinned documentation command in the root AGENTS.md after reconciliation.
-- 
2.54.0


From c349790f6c4fe44ebd15f175e32fc619caf2c7b4 Mon Sep 17 00:00:00 2001
From: Elijah Duffy <elijah@thatoneguy.ca>
Date: Sun, 25 Oct 2026 14:24:57 -0700
Subject: [PATCH 2/4] ci: consolidate documentation checks and avoid duplicate
 branch runs

---
 .gitea/workflows/ci.yml         |  2 ++
 .gitea/workflows/docs-check.yml | 15 ---------------
 2 files changed, 2 insertions(+), 15 deletions(-)
 delete mode 100644 .gitea/workflows/docs-check.yml

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index 584467c..e2c9576 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -2,6 +2,7 @@ name: ci
 
 on:
   push:
+    branches: [main]
   pull_request:
 
 jobs:
@@ -19,6 +20,7 @@ jobs:
       - run: go vet ./...
       - run: go test -race ./...
       - run: go run ./cmd/docs check
+      - run: go run go.auvem.com/corestack/cmd/docs@v0.1.0 check
       - name: Require issue URLs in TODO comments
         run: |
           find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
diff --git a/.gitea/workflows/docs-check.yml b/.gitea/workflows/docs-check.yml
deleted file mode 100644
index d5b6dc1..0000000
--- a/.gitea/workflows/docs-check.yml
+++ /dev/null
@@ -1,15 +0,0 @@
-name: Documentation
-on: [push, pull_request]
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7.0.1
-      - uses: actions/setup-go@v7.0.0
-        with:
-          go-version-file: go.mod
-          cache: false
-      - run: go run go.auvem.com/corestack/cmd/docs@v0.1.0 check
-      - name: Require issue URLs in TODO comments
-        run: |
-          find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
-- 
2.54.0


From e9dcaaa22c4600901b3f1ba6b15e99ba80deb6d4 Mon Sep 17 00:00:00 2001
From: Elijah Duffy <elijah@thatoneguy.ca>
Date: Sun, 25 Oct 2026 14:29:30 -0700
Subject: [PATCH 3/4] ci: filter documentation and implementation workflows by
 changed paths

---
 .gitea/workflows/ci.yml         | 18 ++++++++++++++++--
 .gitea/workflows/docs-check.yml | 27 +++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 2 deletions(-)
 create mode 100644 .gitea/workflows/docs-check.yml

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index e2c9576..f82dffb 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -3,7 +3,23 @@ name: ci
 on:
   push:
     branches: [main]
+    paths:
+      - "cmd/**"
+      - "internal/**"
+      - "go.mod"
+      - "go.sum"
+      - ".golangci.yml"
+      - ".goreleaser.yaml"
+      - ".gitea/workflows/ci.yml"
   pull_request:
+    paths:
+      - "cmd/**"
+      - "internal/**"
+      - "go.mod"
+      - "go.sum"
+      - ".golangci.yml"
+      - ".goreleaser.yaml"
+      - ".gitea/workflows/ci.yml"
 
 jobs:
   check:
@@ -19,8 +35,6 @@ jobs:
         run: test -z "$(gofmt -l .)"
       - run: go vet ./...
       - run: go test -race ./...
-      - run: go run ./cmd/docs check
-      - run: go run go.auvem.com/corestack/cmd/docs@v0.1.0 check
       - name: Require issue URLs in TODO comments
         run: |
           find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
diff --git a/.gitea/workflows/docs-check.yml b/.gitea/workflows/docs-check.yml
new file mode 100644
index 0000000..461ce53
--- /dev/null
+++ b/.gitea/workflows/docs-check.yml
@@ -0,0 +1,27 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+    paths:
+      - "**/*.md"
+      - "!internal/docs/templates/**"
+      - ".gitea/workflows/docs-check.yml"
+  pull_request:
+    paths:
+      - "**/*.md"
+      - "!internal/docs/templates/**"
+      - ".gitea/workflows/docs-check.yml"
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-go@v7.0.0
+        with:
+          go-version-file: go.mod
+          cache: false
+      - run: go run ./cmd/docs check
+      - run: go run go.auvem.com/corestack/cmd/docs@v0.1.0 check
+      - name: Require issue URLs in TODO comments
+        run: |
+          find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
-- 
2.54.0


From 864749c61c8a69ebff41b9e5deb2db6d489ac744 Mon Sep 17 00:00:00 2001
From: Elijah Duffy <elijah@thatoneguy.ca>
Date: Sun, 25 Oct 2026 14:33:44 -0700
Subject: [PATCH 4/4] ci: always validate docs and safely ignore
 documentation-only changes

---
 .gitea/workflows/ci.yml         | 23 +++++++----------------
 .gitea/workflows/docs-check.yml | 12 ------------
 AGENTS.md                       |  2 +-
 3 files changed, 8 insertions(+), 29 deletions(-)

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index f82dffb..266a719 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -3,23 +3,14 @@ name: ci
 on:
   push:
     branches: [main]
-    paths:
-      - "cmd/**"
-      - "internal/**"
-      - "go.mod"
-      - "go.sum"
-      - ".golangci.yml"
-      - ".goreleaser.yaml"
-      - ".gitea/workflows/ci.yml"
+    paths-ignore:
+      # Keep embedded Markdown templates in CI; paths-ignore cannot undo a match.
+      - "*.md"
+      - "docs/**"
   pull_request:
-    paths:
-      - "cmd/**"
-      - "internal/**"
-      - "go.mod"
-      - "go.sum"
-      - ".golangci.yml"
-      - ".goreleaser.yaml"
-      - ".gitea/workflows/ci.yml"
+    paths-ignore:
+      - "*.md"
+      - "docs/**"
 
 jobs:
   check:
diff --git a/.gitea/workflows/docs-check.yml b/.gitea/workflows/docs-check.yml
index 461ce53..68ad004 100644
--- a/.gitea/workflows/docs-check.yml
+++ b/.gitea/workflows/docs-check.yml
@@ -2,15 +2,7 @@ name: Documentation
 on:
   push:
     branches: [main]
-    paths:
-      - "**/*.md"
-      - "!internal/docs/templates/**"
-      - ".gitea/workflows/docs-check.yml"
   pull_request:
-    paths:
-      - "**/*.md"
-      - "!internal/docs/templates/**"
-      - ".gitea/workflows/docs-check.yml"
 jobs:
   docs:
     runs-on: ubuntu-latest
@@ -21,7 +13,3 @@ jobs:
           go-version-file: go.mod
           cache: false
       - run: go run ./cmd/docs check
-      - run: go run go.auvem.com/corestack/cmd/docs@v0.1.0 check
-      - name: Require issue URLs in TODO comments
-        run: |
-          find . -type d \( -name .git -o -name node_modules -o -name vendor -o -name generated -o -name gen -o -name target -o -name dist -o -name build -o -name .svelte-kit -o -name .next \) -prune -o -type f \( -name '*.go' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.svelte' -o -name '*.rs' -o -name '*.sql' -o -name '*.sh' -o -name '*.proto' -o -name '*.graphql' -o -name '*.yml' -o -name '*.yaml' -o -name '*.toml' \) -exec awk 'match($0, "((^|[^:])[/][/]|[/][*]|(^|[[:space:]])(#|--)|^[[:space:]]*([*]|<!--))") { comment=substr($0, RSTART + RLENGTH); todo=index(comment, "TO" "DO"); if (todo && substr(comment, todo + 4) !~ "https?:[/][/]") { print FILENAME ":" FNR ":" $0; bad=1 } } END { exit bad }' {} + # shortcut: line-based scan can flag comment-like strings and misses multiline issue links, use a parser when these need accurate coverage
diff --git a/AGENTS.md b/AGENTS.md
index 0f322e2..3fd1e35 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,7 +3,7 @@
 ## Commands
 - Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below.
 - Generate: No code generation is configured; format with `gofmt -w .`.
-- Documentation: `go run go.auvem.com/corestack/cmd/docs@v0.1.0 check`; use the same pinned command with `new adr "Title"` or `new plan "Title"` to create records. Also run `go run ./cmd/docs check` to test the local implementation.
+- Documentation: `go run ./cmd/docs check`; create records with `go run ./cmd/docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.
 
 ## Scope and decisions
 - Before editing under a directory with its own AGENTS.md, read it. Scoped files: none; this root governs the single Go module.
-- 
2.54.0