ci: NO-JIRA add doc cleanup tools, sync enforcer, and edit tracker hooks

[belumontoya]

🛠️ Type Of Change

• CI
• Other (chore)

📖 Jira Ticket

N/A

📖 Description

Adds documentation cleanup and sync tooling for the Dialtone monorepo — a CI workflow, two Claude Code hooks, two commands, one agent, and one skill. These tools keep packages/dialtone-docs/src/content/ in sync with source code changes automatically.

CI Workflow

• cleanup-plan-docs.yml — auto-deletes PLAN-*.md and docs/plans/ after a PR merges to staging

Hooks

• post-tool-use-tracker.sh (PostToolUse on Edit/Write) — silently logs every file edit to .claude/tsc-cache/<session>/, tracks affected packages and their NX build/test commands
• pre-push-pr-guard.sh (PreToolUse on Bash) — fires on git push or gh pr create, reads the edit log, maps source packages to dialtone-docs content files, denies push if docs are missing and triggers the doc-sync-enforcer. Clean sessions pass through without interruption.

Skills/Agents/Commands

• doc-sync-enforcer skill + /doc-sync-enforcer command — reads source code changes, maps them to packages/dialtone-docs/src/content/ files, updates the docs to reflect what changed
• doc-janitor agent + /doc-janitor command — sweeps stale artifacts (session files, backups, done plans) before merging

Config

• .claude/settings.json — wired both hooks, added Skill(doc-sync-enforcer) and Agent(doc-janitor) to permissions allow list
• .gitignore — added work artifact patterns (PLAN-*.md, SESSION_*.md, *.backup, etc.) and .claude/tsc-cache/
• pr-fill.md — added step to suggest /doc-janitor during PR creation (non-blocking)
• CLAUDE.md — added Doc Sync Tooling section with package→doc mapping and session cache docs

Flow

Edit code → tracker logs it silently
Push → guard reads log → maps packages to docs
  ├─ Docs missing? → DENY push → enforcer updates docs → retry
  └─ Docs present? → ALLOW push
PR create → same doc check (clean sessions pass through)

💡 Context

Dialtone is getting a new dialtone-docs package (PR #1051) with AI-discoverable documentation. This tooling ensures those docs stay in sync with source code changes automatically — the hooks detect gaps and the enforcer fixes them before code is pushed.

📝 Checklist

• I have ensured no private Dialpad links or info are in the code or pull request description (Dialtone is a public repo!).
• I have reviewed my changes.

🔮 Next Steps

• Merge PR feat(dialtone-docs): DDT-1622 add AI documentation package — content, validation, and templates #1051 (dialtone-docs package) first — this tooling references its content structure
• Test the hook chain end-to-end: edit a package file → push → hook triggers → enforcer runs → push succeeds
• Iterate on the source→doc mapping as more content files are added in future milestones

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fb8b532e9a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".

[belumontoya]

Ignacio Ropolo (@iropolo) here is the doc tools automation 😉

[belumontoya]

Claude (@claude) review this PR

[claude]

Claude finished belumontoya's task in 1m 53s —— View job

---

PR Review — ci/doc-cleanup-tools

• Gather context and understand the request
• Read changed files
• Analyze hooks and scripts
• Review CI workflow and settings
• Post review feedback

---

Good addition overall. The tooling is well-structured and the second commit already addressed the Codex P1/P2 concerns (revalidation after new edits, stash+push detection). A few things worth looking at:

---

pre-push-pr-guard.sh

[Medium] PR creation always denies — including clean sessions

Lines 164–171 unconditionally output permissionDecision: deny even when docs are up to date. This means every gh pr create triggers an interruption to ask about /doc-janitor, regardless of whether there's anything to clean up. For PRs where no code files were edited at all (e.g., pure doc or CI changes), the hook will still halt and inject itself.

Consider only issuing the deny+janitor prompt when there are actual files to clean (detected stale artifacts), or at minimum when source files were edited this session.

[Minor] Missing set -e / error handling for jq

post-tool-use-tracker.sh uses set -e at the top (line 2), but pre-push-pr-guard.sh does not. If the jq call on line 155/161/165/170/181/186 fails (e.g., malformed input), the script continues silently and exits 0, potentially blocking the push without a useful error message. pre-push-pr-guard.sh:155

[Minor] UUOC on line 74

# current
edited_files=$(cat "$log_file" | cut -d: -f2)
# simpler
edited_files=$(cut -d: -f2 < "$log_file")

---

settings.json

[Medium] Wrong permission type for doc-janitor

doc-janitor is defined as an agent (.claude/agents/doc-janitor.md) and would be invoked via Agent(doc-janitor), but settings.json allows Skill(doc-janitor). These are different tool types in Claude Code, so the allow-list entry may not actually grant the needed permission when Claude triggers it automatically. .claude/settings.json:5

// current
"Skill(doc-janitor)"

// likely intended
"Agent(doc-janitor)"

doc-sync-enforcer is correctly listed as Skill(doc-sync-enforcer) since it's in .claude/skills/.

---

cleanup-plan-docs.yml

[Low] CI only cleans two artifact patterns

The .gitignore now ignores SESSION_*.md, *.backup, *.bak, CONTEXT.md, etc., but the CI workflow only removes PLAN-*.md and docs/plans/. If any of those other patterns slip through (e.g., committed before the .gitignore was in place), they won't be auto-cleaned post-merge. This is likely intentional — the janitor handles those per-session — but worth noting if the CI cleanup scope was meant to be broader.

[Low] No workflow_dispatch trigger

There's no way to manually trigger the cleanup if it's needed out of band. A workflow_dispatch entry would be a low-cost escape hatch. .github/workflows/cleanup-plan-docs.yml

---

post-tool-use-tracker.sh

[Low] Minor race condition in commands.txt deduplication

Lines 176–178 write to commands.txt.tmp and then sort-unique to commands.txt. If two edit events fire in rapid succession (which can happen with multi-file operations), both processes could write to .tmp simultaneously and the second sort -u overwrites the first's output. A file-lock or atomic append pattern would be safer, though in practice this would be very hard to hit.

[Low] Log field separator fragility

The log format timestamp:filepath:repo uses : as separator (line 156). cut -d: -f2 in the guard hook would mangle paths containing colons. Unlikely in practice, but using a different separator (tab \t or |) would be more robust.

---

Summary

The most impactful fix before merging is the Skill(doc-janitor) → Agent(doc-janitor) correction in settings.json — if the permission is wrong, the automatic janitor trigger won't work. The PR-path always-deny behavior is worth discussing since it adds friction on every PR creation regardless of session state.