Repo standardisation and DB layer simplification (#12)

# TLDR;

Standardises repo infrastructure (Makefile, CI workflows, docs
structure, agent config) and simplifies the DB layer by removing
unnecessary Result wrapping from internal functions.

# Details

**What Was Added:**
- New Claude skills: `code-dedup`, `spec-check`, `upgrade-packages`
- Agent instruction files for Cursor, Windsurf, Copilot, Cline (all
point to CLAUDE.md)
- `opencode.json` config
- `post-release` job in release workflow: auto-bumps `package.json`
version and triggers website deploy
- `deploy-pages.yml` replaces both `deploy-website.yml` (now
`workflow_dispatch`) and `deploy.yml` (deleted)
- Lock recovery spec section in `docs/specs/database.md`
- Parsing strategy spec `[DISC-PARSE-STRATEGY]` in discovery docs
- Mise task type added to README supported types table

**What Was Changed:**
- `Makefile` rewritten with cross-platform OS detection, help target,
public/private target split, `fmt-check` target, and standardised
interface
- `CLAUDE.md` / `Agents.md` consolidated and restructured with logging
standards, spec ID rules, and updated command table
- `.gitignore` expanded with universal patterns and secret exclusions
- `.prettierrc` renamed to `.prettierrc.json` with explicit settings
- DB layer (`db.ts`, `lifecycle.ts`): `initSchema`, `registerCommand`,
`ensureCommandExists`, `closeDatabase`, `addTagToCommand`,
`removeTagFromCommand`, `getAllTagNames`, `getCommandIdsByTag`,
`reorderTagCommands`, `getAllRows`, `upsertSummary` — all changed from
`Result<T,E>` returns to direct returns (throw on unrecoverable errors
only). New `getDbOrThrow()` convenience function replaces repeated
`getDb()` + `Result` unwrapping
- `CommandTreeProvider`, `QuickTasksProvider`, `TagConfig`,
`extension.ts`, `TaskRunner`, `summaryPipeline` — simplified by removing
`Result` unwrapping boilerplate, using `getDbOrThrow()`
- CI workflow: `make format` replaces `make fmt-check` for the format
step
- Coverage thresholds updated to reflect current coverage levels
- Docs moved from `docs/*.md` to `docs/specs/*.md` and `docs/plans/`
- `release.yml` adds marketplace publish step and `post-release` job
- VS Code workspace settings add title bar colour customisation
- Lint fix: renamed `dbPath` parameter to `targetDbPath` in
`dbLockRecovery.unit.test.ts` to resolve `no-shadow` error
- README updated: 22 tool types, Mise added, text filter references
removed

**What Was Deleted:**
- `.github/workflows/deploy.yml` (superseded by `release.yml`
post-release job)
- `.prettierrc` (replaced by `.prettierrc.json`)
- `Result` wrapping removed from all internal DB functions that cannot
meaningfully recover from errors
- `/* istanbul ignore */` comments removed from DB functions that are
now directly tested

# How do the tests prove the change works

- 84 unit tests pass (including `dbLockRecovery.unit.test.ts` lock
removal tests, model selection, task runner param formatting, tree
hierarchy, discovery, PowerShell parser)
- 143 E2E tests pass covering: tree view click behaviour, folder
hierarchy, make target line navigation, tag commands, junction table
tagging, command runner (shell/npm/make/python/launch/vscode tasks),
discovery (22 providers), configuration, quick tasks drag-and-drop,
markdown preview, filtering, file utils, DB operations
- 48 website Playwright tests pass (SEO, navigation, blog, docs, dark
mode, responsive)
- Coverage thresholds met (84.19% lines, 76.73% branches, 81.91%
functions)

---------

Co-authored-by: Jon Canning <jon.canning@gmail.com>

Author: MelbourneDeveloper

.claude/settings.local.json

@@ -18,7 +18,9 @@
       "Bash(npm run:*)",
       "Bash(npx cspell:*)",
       "Bash(gh pr:*)",
-      "Bash(gh run:*)"
+      "Bash(gh run:*)",
+      "Bash(npm test:*)",
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); t=d['total']; print\\(f\\\\\"Lines: {t['lines']['pct']}%\\\\nBranches: {t['branches']['pct']}%\\\\nFunctions: {t['functions']['pct']}%\\\\nStatements: {t['statements']['pct']}%\\\\\"\\)\")"
     ]
   },
   "autoMemoryEnabled": false

.claude/skills/ci-prep/SKILL.md

@@ -1,62 +1,106 @@
 ---
 name: ci-prep
-description: Prepare the codebase for CI. Reads the CI workflow, builds a checklist, then loops through format/lint/build/test/coverage until every single check passes. Use before submitting a PR or when the user wants to ensure CI will pass.
-argument-hint: "[optional focus area]"
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash
+description: Prepares the current branch for CI by running the exact same steps locally and fixing issues. If CI is already failing, fetches the GH Actions logs first to diagnose. Use before pushing, when CI is red, or when the user says "fix ci".
+argument-hint: "[--failing] [optional job name to focus on]"
 ---
+<!-- agent-pmo:5547fd2 -->
 
-# CI Prep — Get the Codebase PR-Ready
+# CI Prep
 
-You MUST NOT STOP until every check passes and coverage threshold is met.
+Prepare the current state for CI. If CI is already failing, fetch and analyze the logs first.
 
-## Step 1: Read the CI Pipeline and Build Your Checklist
+## Arguments
 
-Read the CI workflow file:
+- `--failing` — Indicates a GitHub Actions run is already failing. When present, you MUST execute **Step 1** before doing anything else.
+- Any other argument is treated as a job name to focus on (but all failures are still reported).
+
+If `--failing` is NOT passed, skip directly to **Step 2**.
+
+## Step 1 — Fetch failed CI logs (only when `--failing`)
+
+You MUST do this before any other work.
+
+```bash
+BRANCH=$(git branch --show-current)
+PR_JSON=$(gh pr list --head "$BRANCH" --state open --json number,title,url --limit 1)
+```
+
+If the JSON array is empty, **stop immediately**:
+> No open PR found for branch `$BRANCH`. Create a PR first.
+
+Otherwise fetch the logs:
 
 ```bash
-cat .github/workflows/ci.yml
+PR_NUMBER=$(echo "$PR_JSON" | jq -r '.[0].number')
+gh pr checks "$PR_NUMBER"
+RUN_ID=$(gh run list --branch "$BRANCH" --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run view "$RUN_ID"
+gh run view "$RUN_ID" --log-failed
 ```
 
-Parse EVERY step in the workflow. Extract the exact commands CI runs. Build yourself a numbered checklist of every check you need to pass. This is YOUR checklist — derived from the actual CI config, not from assumptions. The CI pipeline changes over time so you MUST read it fresh and build your list from what you find.
+Read **every line** of `--log-failed` output. For each failure note the exact file, line, and error message. If a job name argument was provided, prioritize that job but still report all failures.
 
-## Step 2: Coordinate with Other Agents
+## Step 2 — Analyze the CI workflow
 
-You are likely working alongside other agents who are editing files concurrently. Before making changes:
+1. Find the CI workflow file. Look in `.github/workflows/` for `ci.yml`.
+2. Read the workflow file completely. Parse every job and every step.
+3. Extract the ordered list of commands the CI actually runs (e.g., `make fmt-check`, `make lint`, `make spellcheck`, `make test EXCLUDE_CI=true`, `make build`, `make package`).
+4. Note any environment variables, matrix strategies, or conditional steps that affect execution.
 
-1. Check TMC status and messages for active agents and locked files
-2. Do NOT edit files that are locked by other agents
-3. Lock files before editing them yourself
-4. Communicate what you are doing via TMC broadcasts
-5. After each fix cycle, check TMC again — another agent may have broken something
+**Do NOT assume the steps.** Extract what the CI *actually does*.
 
-## Step 3: The Loop
+## Step 3 — Run each CI step locally, in order
 
-Run through your checklist from Step 1 in order. For each check:
+Work through failures in this priority order:
 
-1. Run the exact command from CI
-2. If it passes, move to the next check
-3. If it fails, FIX IT. Do NOT suppress warnings, ignore errors, remove assertions, or lower thresholds. Fix the actual code.
-4. Re-run that check to confirm the fix works
-5. Move to the next check
+1. **Formatting** — run `make fmt` first to clear noise
+2. **Compilation errors** — must compile before lint/test
+3. **Lint violations** — fix the code pattern
+4. **Runtime / test failures** — fix source code to satisfy the test
 
-When you reach the end of the checklist, GO BACK TO THE START AND RUN THE ENTIRE CHECKLIST AGAIN. Other agents are working concurrently and may have broken something you already fixed. A fix for one check may have broken an earlier check.
+For each command extracted from the CI workflow:
 
-**Keep looping through the full checklist until you get a COMPLETE CLEAN RUN with ZERO failures from start to finish.** One clean pass is not enough if you fixed anything during that pass — you need a clean pass where NOTHING needed fixing.
+1. Run the command exactly as CI would run it.
+2. If the step fails, **stop and fix the issues** before continuing to the next step.
+3. After fixing, re-run the same step to confirm it passes.
+4. Move to the next step only after the current one succeeds.
 
-Do NOT stop after one loop. Do NOT stop after two loops. Keep going until a full pass completes with every single check green on the first try.
+### Hard constraints
 
-## Step 4: Final Coordination
+- **NEVER modify test files** — fix the source code, not the tests
+- **NEVER add suppressions** (`// eslint-disable`, `// @ts-ignore`)
+- **NEVER use `any` in TypeScript** to silence type errors
+- **NEVER delete or ignore failing tests**
+- **NEVER remove assertions**
 
-1. Broadcast on TMC that CI prep is complete and all checks pass
-2. Release any locks you hold
-3. Report the final status to the user with the output of each passing check
+If stuck on the same failure after 5 attempts, ask the user for help.
+
+## Step 4 — Report
+
+- List every step that was run and its result (pass/fail/fixed).
+- If any step could not be fixed, report what failed and why.
+- Confirm whether the branch is ready to push.
+
+## Step 5 — Commit/Push (only when `--failing`)
+
+Once all CI steps pass locally:
+
+1. Commit, but DO NOT MARK THE COMMIT WITH YOU AS AN AUTHOR!!! Only the user authors the commit!
+2. Push
+3. Monitor until completion or failure
+4. Upon failure, go back to Step 1
 
 ## Rules
 
-- NEVER stop with failing checks. Loop until everything is green.
-- NEVER suppress lint warnings, skip tests, or lower coverage thresholds.
-- NEVER remove assertions to make tests pass.
-- Fix the CODE, not the checks.
-- If you are stuck on a failure after 3 attempts on the same issue, ask the user for help. Do NOT silently give up.
-- Always coordinate with other agents via TMC. Check for messages regularly.
-- Leave the codebase in a state that will pass CI on the first try.
+- **Always read the CI workflow first.** Never assume what commands CI runs.
+- Do not push if any step fails (unless `--failing` and all steps now pass)
+- Fix issues found in each step before moving to the next
+- Never skip steps or suppress errors
+- If the CI workflow has multiple jobs, run all of them (respecting dependency order)
+- Skip steps that are CI-infrastructure-only (checkout, setup-node, cache steps, artifact uploads) — focus on the actual build/test/lint commands
+
+## Success criteria
+
+- Every command that CI runs has been executed locally and passed
+- All fixes are applied to the working tree
+- The CI passes successfully (if you are correcting an existing failure)

.claude/skills/code-dedup/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: code-dedup
+description: Searches for duplicate code, duplicate tests, and dead code, then safely merges or removes them. Use when the user says "deduplicate", "find duplicates", "remove dead code", "DRY up", or "code dedup". Requires test coverage — refuses to touch untested code.
+---
+<!-- agent-pmo:5547fd2 -->
+
+# Code Dedup
+
+Carefully search for duplicate code, duplicate tests, and dead code across the repo. Merge duplicates and delete dead code — but only when test coverage proves the change is safe.
+
+## Prerequisites — hard gate
+
+Before touching ANY code, verify these conditions. If any fail, stop and report why.
+
+1. Run `make test` — all tests must pass. If tests fail, stop. Do not dedup a broken codebase.
+2. Run `make coverage-check` — coverage must meet the repo's threshold. If it doesn't, stop.
+3. Verify the project uses **static typing**. Check `tsconfig.json` has `"strict": true` — proceed.
+
+## Steps
+
+Copy this checklist and track progress:
+
+```
+Dedup Progress:
+- [ ] Step 1: Prerequisites passed (tests green, coverage met, typed)
+- [ ] Step 2: Dead code scan complete
+- [ ] Step 3: Duplicate code scan complete
+- [ ] Step 4: Duplicate test scan complete
+- [ ] Step 5: Changes applied
+- [ ] Step 6: Verification passed (tests green, coverage stable)
+```
+
+### Step 1 — Inventory test coverage
+
+Before deciding what to touch, understand what is tested.
+
+1. Run `make test` and `make coverage-check` to confirm green baseline
+2. Note the current coverage percentage — this is the floor. It must not drop.
+3. Identify which files/modules have coverage and which do not. Only files WITH coverage are candidates for dedup.
+
+### Step 2 — Scan for dead code
+
+Search for code that is never called, never imported, never referenced.
+
+1. Look for unused exports, unused functions, unused classes, unused variables
+2. Check for `noUnusedLocals`/`noUnusedParameters` in tsconfig, look for unexported functions with zero references
+3. For each candidate: **grep the entire codebase** for references (including tests, scripts, configs). Only mark as dead if truly zero references.
+4. List all dead code found with file paths and line numbers. Do NOT delete yet.
+
+### Step 3 — Scan for duplicate code
+
+Search for code blocks that do the same thing in multiple places.
+
+1. Look for functions/methods with identical or near-identical logic
+2. Look for copy-pasted blocks (same structure, maybe different variable names)
+3. Look for multiple implementations of the same algorithm or pattern
+4. Check across module boundaries — duplicates often hide in different packages
+5. For each duplicate pair: note both locations, what they do, and how they differ (if at all)
+6. List all duplicates found. Do NOT merge yet.
+
+### Step 4 — Scan for duplicate tests
+
+Search for tests that verify the same behavior.
+
+1. Look for test functions with identical assertions against the same code paths
+2. Look for test fixtures/helpers that are duplicated across test files
+3. Look for integration tests that fully cover what a unit test also covers (keep the integration test, mark the unit test as redundant)
+4. List all duplicate tests found. Do NOT delete yet.
+
+### Step 5 — Apply changes (one at a time)
+
+For each change, follow this cycle: **change → test → verify coverage → continue or revert**.
+
+#### 5a. Remove dead code
+- Delete dead code identified in Step 2
+- After each deletion: run `make test` and `make coverage-check`
+- If tests fail or coverage drops: **revert immediately** and investigate
+
+#### 5b. Merge duplicate code
+- For each duplicate pair: extract the shared logic into a single function/module
+- Update all call sites to use the shared version
+- After each merge: run `make test` and `make coverage-check`
+- If tests fail: **revert immediately**
+
+#### 5c. Remove duplicate tests
+- Delete the redundant test (keep the more thorough one)
+- After each deletion: run `make coverage-check`
+- If coverage drops: **revert immediately**
+
+### Step 6 — Final verification
+
+1. Run `make test` — all tests must still pass
+2. Run `make coverage-check` — coverage must be >= the baseline from Step 1
+3. Run `make lint` and `make fmt-check` — code must be clean
+4. Report: what was removed, what was merged, final coverage vs baseline
+
+## Rules
+
+- **No test coverage = do not touch.** If a file has no tests covering it, leave it alone entirely.
+- **Coverage must not drop.** The coverage floor from Step 1 is sacred.
+- **One change at a time.** Make one dedup change, run tests, verify coverage. Never batch.
+- **When in doubt, leave it.** If two code blocks look similar but you're not 100% sure they're functionally identical, leave both.
+- **Preserve public API surface.** Do not change function signatures, class names, or module exports that external code depends on.
+- **Three similar lines is fine.** Only dedup when the shared logic is substantial (>10 lines) or when there are 3+ copies.