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. The transitional pnpm run check contract allows the aggregate check to exit non-zero only on issues listed here. Any failure not covered by this document represents a regression introduced by a later milestone.

---

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.