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`

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

### `pnpm run verify:pi`

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

### `pnpm run verify:reviewers`

```text
reviewer support verified
EXIT: 0
```

### `pnpm run test:installer`

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

---

## 2. Nested package scripts

### atlassian/shared/scripts — `test`

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

### atlassian/shared/scripts — `typecheck`

```text
EXIT: 0
```

### atlassian/codex/scripts — `typecheck`

```text
EXIT: 0
```

### atlassian/claude-code/scripts — `typecheck`

```text
EXIT: 0
```

### atlassian/cursor/scripts — `typecheck`

```text
EXIT: 0
```

### atlassian/opencode/scripts — `typecheck`

```text
EXIT: 0
```

### atlassian/pi/scripts — `typecheck`

```text
EXIT: 0
```

### web-automation/codex/scripts — `typecheck`

```text
EXIT: 0
```

### web-automation/codex/scripts — `lint`

```text
EXIT: 0
```

### web-automation/claude-code/scripts — `typecheck`

```text
EXIT: 0
```

### web-automation/cursor/scripts — `typecheck`

```text
EXIT: 0
```

### web-automation/opencode/scripts — `typecheck`

```text
EXIT: 0
```

### web-automation/pi/scripts — `typecheck`

```text
EXIT: 0
```

---

## 3. reviewer-runtime tests

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

```text
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)

```text
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)

```text
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)

```text
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](./DEVELOPMENT.md#cross-platform-shell-support-m2).

---

## 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)

```text
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** |