fix: post-merge follow-ups from PR #133 (aidd-churn)

[ianwhitedeveloper]

Context

Follow-up findings from the code review of feat: /aidd-churn (#133). Items are ordered by priority.

---

1. 🔴 Remove .npmrc — redundant with package.json overrides

.npmrc contains legacy-peer-deps=true globally, but package.json already has a scoped overrides block that correctly resolves the tsmetrics-core peer dep conflict. The task archive for PR #133 explicitly states the intent was to replace .npmrc with overrides, yet both shipped.

legacy-peer-deps=true at the project root suppresses peer dependency validation for the entire dependency tree — not just tsmetrics-core. This masks any future peer dep conflict silently.

Fix: Delete .npmrc. The overrides block in package.json is sufficient and scoped correctly.

---

2. 🟡 ai/skills/aidd-churn/README.md should be in references/ per the Agent Skills spec

The Agent Skills specification defines three optional directory types for skill-supporting files: scripts/, references/, and assets/. Files in references/ are loaded on demand by agents, keeping context usage efficient.

README.md currently sits at the skill root (ai/skills/aidd-churn/README.md) — not in a spec-recognized location. This also conflates two concerns: user-facing CLI documentation and skill reference material.

Every other skill in this project (aidd-fix, aidd-react, aidd-ecs, etc.) has only SKILL.md + index.md. aidd-churn is the first to include supplementary reference material, making the non-standard placement more noticeable.

Fix:

ai/skills/aidd-churn/
├── SKILL.md
├── references/
│   └── README.md
└── index.md

---

3. 🟡 SKILL.md file references should use markdown link syntax

Per the Agent Skills spec:

"When referencing other files in your skill, use relative paths from the skill root"

The SKILL.md references README.md twice using unlinked prose:

• Line 25: Read README.md (colocated) for metric definitions...
• Line 53 (inside a SudoLang comment): // See README.md for interpretation ranges...

Fix (after moving to references/):

Read [references/README.md](references/README.md) for metric definitions, score formula, and interpretation ranges.

---

4. 🟡 LoC counting is off-by-one for files with trailing newlines

In lib/file-metrics-collector.js:

const loc = src.split("\n").length;

Files ending with a trailing newline (almost all well-formed source files) produce an extra empty string from split("\n"), overcounting by 1. This is acknowledged in the test comment:

// loc=5: 4 lines + empty element after trailing newline

It's consistently inaccurate and won't affect ranking, but it's a correctness issue.

Fix:

const loc = src.split("\n").filter(Boolean).length;
// or: src.trimEnd().split("\n").length

---

5. 🟡 Track --ext option — planned in task archive but not shipped or descoped

The archived task requirements include:

"Given a --ext option, should allow the user to override the included extensions"

This requirement is in the archive but the CLI does not expose --ext, and it's not listed in the PR's "Known follow-up items." It was silently dropped without a tracking issue.

Action: Either open a follow-up task for --ext support or explicitly note it was descoped from requirements.

---

6. ℹ️ Document TypeScript as a runtime dependency and its install cost

typescript was moved from devDependencies to dependencies in PR #133 so that tsmetrics-core can use the TypeScript compiler API at runtime. This is intentional and correct, but it adds ~10MB to the install footprint for every consumer of aidd.

The main README.md does not mention this trade-off.

Fix: Add a brief note to the README (near the npx aidd churn usage section) that the churn subcommand requires TypeScript as a runtime dependency.

---

Related

• PR feat: /aidd-churn #133: feat: /aidd-churn
• Agent Skills specification