ai-coding-skills/docs/CLEANUP-BASELINE.md

Cleanup Baseline — ai-coding-skills (M1)

Captured: 2026-05-03 · Platform: macOS (arm64, Apple Silicon) · Node 22.14.0 · pnpm 10.18.1

This document records the as-is state of every quality check at the start of the refactor series. All pre-existing failures listed here have since been resolved. As of M5 pnpm run check exits 0 on a clean checkout. Any failure now represents a regression and must be fixed before merge.

---

Byte-equivalence assertion

Before any file was modified in M1, git status showed a clean working tree. After all S-101 through S-107 changes were applied, git status confirms:

• Zero modifications to any nested package.json under skills/ or pi-package/.
• Zero modifications to any file under skills/*/{codex,claude-code,cursor,opencode,pi}/ (the generated agent-variant directories).
• All changes are confined to new root-level config files, new scripts, updated root package.json (devDependencies + scripts), and new docs.

---

1. Pre-existing root scripts

pnpm run sync:pi

Synced pi package skill mirror into …/pi-package/skills.
EXIT: 0

pnpm run verify:pi

package metadata ok
pi resources verified
pi workflow skill docs verified
EXIT: 0

pnpm run verify:reviewers

reviewer support verified
EXIT: 0

pnpm run test:installer

TAP version 13
# tests 22
# pass 22
# fail 0
EXIT: 0

---

2. Nested package scripts

atlassian/shared/scripts — test

TAP version 13
# tests 23
# pass 23
# fail 0
EXIT: 0

atlassian/shared/scripts — typecheck

EXIT: 0

atlassian/codex/scripts — typecheck

EXIT: 0

atlassian/claude-code/scripts — typecheck

EXIT: 0

atlassian/cursor/scripts — typecheck

EXIT: 0

atlassian/opencode/scripts — typecheck

EXIT: 0

atlassian/pi/scripts — typecheck

EXIT: 0

web-automation/codex/scripts — typecheck

EXIT: 0

web-automation/codex/scripts — lint

EXIT: 0

web-automation/claude-code/scripts — typecheck

EXIT: 0

web-automation/cursor/scripts — typecheck

EXIT: 0

web-automation/opencode/scripts — typecheck

EXIT: 0

web-automation/pi/scripts — typecheck

EXIT: 0

---

3. reviewer-runtime tests

All three test scripts under skills/reviewer-runtime/tests/ passed:

claude-review-template-guard.sh  PASS
smoke-test.sh                    PASS
telegram-notify-test.sh          PASS
EXIT: 0 (each)

---

4. M1 quality tooling — baseline violations

4a. ESLint (pnpm run lint — ESLint stage)

Exit code: 1 — 2 pre-existing errors (no new errors from M1 additions).

Files with violations in the existing codebase:

File	Line	Rule	Message
scripts/lib/skill-manager-core.mjs	282	no-useless-assignment	Value assigned to entries is not used
scripts/manage-skills.mjs	270	no-unused-vars	client is assigned a value but never used

Action: Fix in a later milestone. Do not suppress with eslint-disable comments unless the code is intentionally dead.

4b. shellcheck (pnpm run lint — shellcheck stage)

Exit code: 1 — 7 files with pre-existing findings (no new violations from M1).

File	Finding
scripts/verify-pi-resources.sh	SC2016 (info, ×3): single-quoted backtick strings; SC2251 (info, ×1): ! outside condition
scripts/verify-pi-workflows.sh	SC2016 (info, ×2): single-quoted backtick strings; SC2251 (info, ×1): ! outside condition
skills/reviewer-runtime/pi/run-review.sh	SC2329 (info): unused handle_signal; SC2034 (warning, ×2): unused variables
skills/reviewer-runtime/run-review.sh	SC2329 (info): unused handle_signal; SC2034 (warning, ×2): unused variables
skills/reviewer-runtime/tests/claude-review-template-guard.sh	SC2016 (info, ×1): single-quoted expansion
skills/reviewer-runtime/tests/smoke-test.sh	SC2064 (warning, ×1): trap should use single quotes
skills/reviewer-runtime/tests/telegram-notify-test.sh	SC2064 (warning, ×1): trap should use single quotes

The following files pass shellcheck with EXIT 0:

• scripts/install-pi-package.sh
• scripts/manage-skills.sh
• scripts/sync-pi-package-skills.sh
• scripts/verify-reviewer-support.sh
• skills/reviewer-runtime/notify-telegram.sh
• skills/reviewer-runtime/pi/notify-telegram.sh
• skills/web-automation/scripts/sync-variants.sh

Action: Fix SC2064 trap issues and SC2034 warnings in a later milestone. SC2016 findings are intentional (single-quoted strings containing backticks are used as literal grep patterns to match markdown text).

4c. markdownlint (pnpm run verify:docs)

Exit code: 1 — 1160 errors across 62 files (no new violations from M1 additions).

markdownlint-cli2 v0.22.1 scanned README.md, docs/**/*.md, and canonical SKILL.md files (excluding node_modules and generated agent-variant directories).

Rule breakdown (selected):

Rule	Description
MD013	Line length > 120 chars (majority of errors)
MD012	Multiple consecutive blank lines
MD024	Duplicate headings
MD029	Ordered list item prefix
MD032	Blanks around lists
MD038	Spaces inside code span
MD040	Fenced code without language
MD058	Blanks around tables

Affected files include (non-exhaustive): docs/ATLASSIAN.md, docs/CREATE-PLAN.md, docs/DO-TASK.md, docs/IMPLEMENT-PLAN.md, docs/INSTALLER.md, docs/PI-COMMON-REVIEWER.md, docs/PI-RESEARCH.md, docs/PI-SUPERPOWERS.md, docs/PI.md, docs/README.md, docs/TELEGRAM-NOTIFICATIONS.md, docs/WEB-AUTOMATION.md, README.md, and all skills/*/*/SKILL.md variants.

Action: Bulk-fix in a dedicated doc-cleanup milestone. New docs added in M1 (docs/DEVELOPMENT.md, docs/CLEANUP-BASELINE.md) pass all enabled rules.

4d. markdown-link-check (offline, pnpm run verify:docs)

Exit code: 0 — no broken repo-relative or anchor links found.

53 markdown files scanned (offline mode: external http/https links ignored). All internal links are valid.

4e. pnpm run typecheck (workspace aggregate)

Exit code: 0.

Ran typecheck in workspace members:

• skills/atlassian/shared/scripts — PASS
• skills/web-automation/codex/scripts — PASS

4f. pnpm run test (workspace aggregate)

Exit code: 0.

Ran:

• pnpm run test:installer (22/22 tests)
• skills/atlassian/shared/scripts test (23/23 tests)

4g. pnpm run check aggregate (M1 transitional state)

FAIL  lint            (exit 1) — ESLint + shellcheck pre-existing violations (§4a, §4b)
PASS  typecheck
PASS  test
PASS  verify:pi
PASS  verify:reviewers
FAIL  verify:docs     (exit 1) — markdownlint pre-existing violations (§4c)
PASS  verify:generated (stub)

Overall exit: 1 — expected per transitional contract; all failures are pre-existing and documented in this file.

---

5. Platform notes

• Tested on macOS 15 (arm64). No GNU/Linux run available at M1 capture time.
• shellcheck 0.11.0 installed via brew install shellcheck.
• stat variant: BSD stat (macOS default). The scripts/ shell scripts do not call stat; this affects only M5 CI configuration.
• rg (ripgrep) is required by scripts/verify-pi-workflows.sh. It is present on the test machine; absent systems should install via brew install ripgrep / apt-get install ripgrep.

---

This file is generated once (M1) and updated only when a subsequent milestone changes the baseline status of a check.

---

Post-M3 state

Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1

M3 resolved all remaining pre-existing lint violations (2 ESLint errors and 7 shellcheck findings). verify:generated is now a real implementation (was a stub in M2).

pnpm run check aggregate (post-M3)

PASS  lint             (was FAIL in M1/M2; pre-existing violations fixed in M3)
PASS  typecheck
PASS  test
PASS  verify:pi
PASS  verify:reviewers
PASS  verify:docs
PASS  verify:generated (was stub in M2; real implementation in M3)

Overall exit: 0 — all checks green for the first time.

What changed in M3

• scripts/generate-skills.mjs added (generator for all 31 agent-variant roots).
• scripts/verify-generated.mjs added (drift detector).
• Canonical source directories created: skills/<skill>/_source/, skills/web-automation/shared/.
• All 31 generated roots now carry .generated-manifest.json and file-type-aware headers.
• package.json renames: all generated agent-variant packages renamed to @ai-coding-skills/<skill>-<agent> with "private": true.
• pnpm-workspace.yaml updated: M1 negative-glob exclusions replaced by positive includes for all uniquely-named generated variants.
• Pre-existing ESLint violations fixed: skill-manager-core.mjs:282 (no-useless-assignment) and manage-skills.mjs:270 (no-unused-vars).
• Pre-existing shellcheck findings fixed: SC2034 and SC2329 in reviewer-runtime/run-review.sh; SC2064 in test trap statements; SC2016 / SC2251 in verify scripts (suppress intentional patterns).
• pnpm run sync:pi now calls the generator instead of sync-pi-package-skills.sh.
• docs/DEVELOPMENT.md extended with generation workflow and metadata docs.
• CHANGELOG.md created with package-metadata change callout.

Full byte-equivalence diff (M3 vs pre-M3)

See CHANGELOG.md § "Byte-equivalence diff allow-list" for the complete documented diff between M3-generated output and the pre-M3 variants. The only permitted diffs are headers, .generated-manifest.json, name rename, and "private": true.

---

Post-M2 state

Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1

M2 resolved all verify:docs violations and the verify:pi portability issue (stat -f BSD-ism in scripts/verify-pi-resources.sh).

pnpm run check aggregate (post-M2)

FAIL  lint            (exit 1) — same 2 ESLint + 7 shellcheck pre-existing violations (§4a, §4b)
PASS  typecheck
PASS  test
PASS  verify:pi
PASS  verify:reviewers
PASS  verify:docs      (was FAIL in M1; now clean)
PASS  verify:generated (stub)

Overall exit: 1 — only lint still fails on pre-existing violations. verify:docs is now green (0 markdownlint errors, offline link-check clean, docs-flow verifier passes).

What changed in M2

• scripts/lib/portable.sh added with portable_stat_perms helper.
• scripts/verify-pi-resources.sh updated to use portable_stat_perms (replaces stat -f '%Lp' BSD-only call).
• scripts/lib/run-shellcheck.mjs updated to pass -x --source-path=SCRIPTDIR so shellcheck follows source directives correctly on both platforms.
• skills/.markdownlint.jsonc added to disable MD013 and MD024 for agent-facing SKILL.md files.
• All 1160 M1 markdownlint violations resolved (auto-fix + targeted edits).
• docs/README.md reorganized into ordered reading flow.
• README.md layout section updated to reflect actual repo tree.
• docs/REVIEWERS.md added as canonical reviewer CLI matrix.
• docs/TELEGRAM-NOTIFICATIONS.md extended with Pi section.
• docs/CREATE-PLAN.md, docs/IMPLEMENT-PLAN.md, docs/DO-TASK.md updated with REVIEWERS.md references and unique variant headings.
• OpenCode reviewer branches added to skills/create-plan/opencode/SKILL.md and skills/implement-plan/opencode/SKILL.md.
• scripts/verify-docs-flow.mjs implemented and wired into verify:docs.
• pnpm run verify:docs:online added for external link checks.

Ubuntu smoke note

No Docker/Ubuntu run was available at M2 capture time. The portability fix (portable_stat_perms) replaces the only identified BSD-ism. The Ubuntu Docker command is documented in DEVELOPMENT.md.

---

Post-M4 state

Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1

M4 extracted reusable abstractions, consolidated shared helpers, tightened types, and removed the legacy dead-code path. pnpm run check remains fully green.

pnpm run check aggregate (post-M4)

PASS  lint
PASS  typecheck
PASS  test
PASS  verify:pi
PASS  verify:reviewers
PASS  verify:docs
PASS  verify:generated

Overall exit: 0 — all checks green (no regressions from M3).

What changed in M4

• S-401 — scripts/lib/safe-replace-dir.mjs added: Node.js helper that validates a target is a strict descendant of a safety root before replacing it. Thin shell wrapper scripts/lib/safe-replace-dir.sh provided for sourcing in shell scripts. scripts/sync-pi-package-skills.sh updated to use safe_replace_dir from the shared helper (inline replace_dir removed).

• S-402 — removeTarget(op) extracted from executeOperation() in scripts/lib/skill-manager-core.mjs and exported. The helper handles skill, helper, and symlink removal with idempotent semantics. executeOperation now delegates to removeTarget for all remove branches.

• S-403 — skills/atlassian/shared/scripts/src/command-helpers.ts added with dryRunResponse<T>() and resolveFormat() helpers. confluence.ts, jira.ts, and raw.ts consume dryRunResponse (8 inline objects removed). cli.ts imports resolveFormat from command-helpers instead of defining it locally. All atlassian agent variants regenerated.

• S-404 — skills/web-automation/shared/lib/browser.ts created with getProfilePath, launchBrowser, and getPage. browse.ts imports and re-exports them. auth.ts, flow.ts, and scan-local-app.ts now import directly from lib/browser.js. Generator updated to include lib/ directory in scriptFiles for web-automation variants. tsconfig.json updated to include lib/**/*.ts.

• S-405 — scan-local-app.ts page: any parameters replaced with Page from playwright-core. Added GotoError discriminated type to narrow the page.goto().catch() union type safely.

• S-406 — scripts/sync-pi-package-skills.sh deleted (retired in M3, inline replace_dir migrated to shared helper as part of S-401). Comment in skill-manager-core.mjs referencing the deleted file updated. Generator's clearGeneratedRoot fixed to preserve node_modules at all depths (was only protected at root level, causing pnpm workspace packages inside scripts/ subdirs to lose their node_modules on regeneration).

• S-407 — Tests added:

  • scripts/tests/safe-replace-dir.test.mjs (6 tests for S-401 helper)
  • scripts/tests/skill-manager-core-remove.test.mjs (5 tests for S-402)
  • skills/atlassian/shared/scripts/tests/command-helpers.test.ts (7 tests for S-403 dryRunResponse and resolveFormat)

Test count (post-M4)

Suite	Tests
pnpm run test:installer (root scripts)	80
atlassian/shared/scripts	29
Total	109

---

Final state (post-M5) — CLOSED

Captured: 2026-05-03 · Platform: macOS 15 (arm64) · Node 22.14.0 · pnpm 10.18.1

M5 added CI configuration, finalised documentation, closed out this baseline report, and locked in a permanently green pnpm run check gate. No pre-existing failures remain open.

pnpm run check aggregate (post-M5 — macOS)

PASS  lint
PASS  typecheck
PASS  test
PASS  verify:pi
PASS  verify:reviewers
PASS  verify:docs
PASS  verify:generated

All checks passed.

Overall exit: 0 — all checks green (no regressions from M4).

What changed in M5

• S-501 — .github/workflows/check.yml added: matrix over ubuntu-latest and macos-latest; installs shellcheck (apt/brew), ripgrep (apt), pnpm, and Node.js 22; runs pnpm run check.
• S-501 — .github/workflows/check-online.yml added: weekly schedule + workflow_dispatch; runs verify:docs:online for full external link checking.
• S-502 — Root README.md gained a "Contributing / Development" section naming pnpm run check as the single quality gate and linking to docs/DEVELOPMENT.md.
• S-503 — docs/DEVELOPMENT.md finalised: added "Adding a new agent", "Adding a new skill", and "CI" sections; transitional contract replaced by the permanent M5 contract; baseline links updated.
• S-504 — This file (docs/CLEANUP-BASELINE.md) closed out with the "Final state" section.
• S-505 — Root package.json files list updated: docs/DEVELOPMENT.md and docs/REVIEWERS.md added.
• S-506 — CHANGELOG.md extended with the M5 consolidated entry.
• S-507 — Final pnpm run check run confirmed green (output above).

Baseline status summary

Every pre-existing failure recorded in this document is now resolved. No waivers are required.

Check	M1 status	Final status	Resolution
lint (ESLint)	FAIL — 2 errors	PASS	Fixed in M3 (S-302)
lint (shellcheck)	FAIL — 7 findings	PASS	Fixed in M3 (S-302)
typecheck	PASS	PASS	Never regressed
test	PASS	PASS	Never regressed
verify:pi	PASS	PASS	Portability hardened in M2
verify:reviewers	PASS	PASS	Never regressed
verify:docs (markdownlint)	FAIL — 1160 errors	PASS	Fixed in M2
verify:docs (link-check)	PASS	PASS	Never regressed
verify:generated	PASS (stub)	PASS	Real implementation in M3

Ubuntu smoke test

The CI workflow (.github/workflows/check.yml) runs the same pnpm run check command on ubuntu-latest. This replaces the Docker one-liner that was the only documented Ubuntu smoke test path in M1–M4.

For local reproduction on Linux:

# Requires Docker
docker run --rm \
  -v "$PWD:/w" \
  -w /w \
  node:22-bookworm \
  bash -lc 'apt-get update -q && apt-get install -y -q shellcheck ripgrep python3 \
            && corepack enable \
            && pnpm install --frozen-lockfile \
            && pnpm run check'

This baseline report is now closed. Future regressions must be caught by CI and fixed before merge; they should NOT reopen this document.