refactor: remove deprecated exports and update docs

Remove deprecated wrappers (mergeClaudeMd, hasExistingBmadDir,
CHECK_REGISTRY, validateArtifacts, RalphStatus type alias) and update
tests to use their replacements. Update CONTRIBUTING.md tree structure
and fix stale npm script references. Add package.json keywords.

Author: LarsCowe

CONTRIBUTING.md

@@ -34,7 +34,10 @@ bmalph/
 │   │   ├── upgrade.ts      # bmalph upgrade
 │   │   ├── doctor.ts       # bmalph doctor
 │   │   ├── check-updates.ts # bmalph check-updates
-│   │   └── status.ts       # bmalph status
+│   │   ├── status.ts       # bmalph status
+│   │   ├── implement.ts    # bmalph implement
+│   │   ├── reset.ts        # bmalph reset
+│   │   └── watch.ts        # bmalph watch
 │   ├── platform/           # Platform abstraction layer
 │   │   ├── types.ts        # PlatformId, PlatformTier, CommandDelivery types
 │   │   ├── registry.ts     # Platform registry (get, list, validate)
@@ -52,11 +55,20 @@ bmalph/
 │   │   ├── story-parsing.ts # Parse BMAD stories
 │   │   ├── fix-plan.ts     # Generate @fix_plan.md
 │   │   ├── artifacts.ts    # Locate BMAD artifacts
+│   │   ├── artifact-scan.ts # Artifact scanning
 │   │   ├── context.ts      # Generate PROJECT_CONTEXT.md
+│   │   ├── preflight.ts    # Pre-flight validation checks
 │   │   ├── tech-stack.ts   # Detect tech stack
 │   │   ├── specs-*.ts      # Spec generation modules
 │   │   ├── types.ts        # Shared transition types
 │   │   └── index.ts        # Module barrel export
+│   ├── watch/              # Live dashboard module
+│   │   ├── dashboard.ts    # Dashboard orchestrator
+│   │   ├── file-watcher.ts # File system polling
+│   │   ├── renderer.ts     # Terminal UI rendering
+│   │   ├── state-reader.ts # Ralph state parsing
+│   │   └── types.ts        # Watch types
+│   ├── reset.ts            # Reset plan-build + execute logic
 │   └── utils/              # Shared utilities
 │       ├── config.ts       # Config file operations
 │       ├── state.ts        # State management
@@ -149,9 +161,9 @@ npm test
 
 ### What Gets Bundled
 
-| Source                  | Destination | Contents                            |
-| ----------------------- | ----------- | ----------------------------------- |
-| BMAD-METHOD/bmad-agent/ | bmad/       | Agents, workflows, personas, config |
+| Source           | Destination | Contents                            |
+| ---------------- | ----------- | ----------------------------------- |
+| BMAD-METHOD/src/ | bmad/       | Agents, workflows, personas, config |
 
 ## Commit Guidelines
 
@@ -196,15 +208,15 @@ npm run lint
 npm run format
 
 # Full check (lint + build + test)
-npm run check
+npm run ci
 ```
 
 ## Pull Request Process
 
 1. Create feature branch from `main`
 2. Write tests first (TDD)
 3. Implement feature
-4. Ensure all tests pass: `npm run check`
+4. Ensure all tests pass: `npm run ci`
 5. Create PR with clear description (version bumps are automated)
 
 ## Questions?

package.json

@@ -1,7 +1,7 @@
 {
   "name": "bmalph",
   "version": "2.4.0",
-  "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
+  "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop",
   "type": "module",
   "bin": {
     "bmalph": "./bin/bmalph.js"
@@ -32,7 +32,11 @@
     "ai",
     "development",
     "framework",
-    "agents"
+    "agents",
+    "bmad",
+    "ralph",
+    "autonomous",
+    "coding-assistant"
   ],
   "author": "Lars Cowe",
   "license": "MIT",

src/commands/doctor.ts

@@ -1,6 +1,5 @@
 import chalk from "chalk";
 import { readFile, stat } from "fs/promises";
-import { exists } from "../utils/file-system.js";
 import { join } from "path";
 import { readJsonFile } from "../utils/json.js";
 import { readConfig } from "../utils/config.js";
@@ -540,53 +539,3 @@ export function buildCheckRegistry(platform: Platform): CheckDefinition[] {
 
   return [...CORE_CHECKS, ...platformChecks, ...TRAILING_CHECKS];
 }
-
-/**
- * Static registry for backward compatibility with existing tests.
- * Uses claude-code platform checks (slash-command + claude-md).
- *
- * Note: The check ids here ("slash-command", "claude-md") intentionally differ
- * from the live buildCheckRegistry path which uses platform-provided ids
- * ("instructions-file"). This is for test backward compatibility only.
- *
- * @deprecated Use `buildCheckRegistry(platform)` for platform-aware checks.
- */
-export const CHECK_REGISTRY: CheckDefinition[] = (() => {
-  // Inline claude-code platform checks to avoid async import at module level
-  const slashCommandCheck: CheckDefinition = {
-    id: "slash-command",
-    run: async (projectDir: string) => {
-      if (await exists(join(projectDir, ".claude/commands/bmalph.md"))) {
-        return { label: ".claude/commands/bmalph.md present", passed: true };
-      }
-      return {
-        label: ".claude/commands/bmalph.md present",
-        passed: false,
-        detail: "not found",
-        hint: "Run: bmalph init",
-      };
-    },
-  };
-
-  const claudeMdCheck: CheckDefinition = {
-    id: "claude-md",
-    run: async (projectDir: string) => {
-      const label = "CLAUDE.md contains BMAD snippet";
-      const hint = "Run: bmalph init";
-      try {
-        const content = await readFile(join(projectDir, "CLAUDE.md"), "utf-8");
-        if (content.includes("BMAD-METHOD Integration")) {
-          return { label, passed: true };
-        }
-        return { label, passed: false, detail: "missing BMAD-METHOD Integration section", hint };
-      } catch (err) {
-        if (isEnoent(err)) {
-          return { label, passed: false, detail: "CLAUDE.md not found", hint };
-        }
-        return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
-      }
-    },
-  };
-
-  return [...CORE_CHECKS, slashCommandCheck, claudeMdCheck, ...TRAILING_CHECKS];
-})();

src/commands/init.ts

@@ -5,13 +5,14 @@ import {
   installProject,
   mergeInstructionsFile,
   isInitialized,
-  hasExistingBmadDir,
   previewInstall,
   getBundledVersions,
 } from "../installer.js";
 import { formatDryRunSummary, type DryRunAction } from "../utils/dryrun.js";
 import { validateProjectName } from "../utils/validate.js";
 import { withErrorHandling } from "../utils/errors.js";
+import { exists } from "../utils/file-system.js";
+import { join } from "path";
 import { isPlatformId, getPlatform } from "../platform/registry.js";
 import { detectPlatform } from "../platform/detect.js";
 import type { Platform, PlatformId } from "../platform/types.js";
@@ -90,7 +91,7 @@ async function runInit(options: InitOptions): Promise<void> {
     return;
   }
 
-  if (await hasExistingBmadDir(projectDir)) {
+  if (await exists(join(projectDir, "_bmad"))) {
     console.log(chalk.cyan("Existing BMAD installation detected."));
     console.log("Framework files in _bmad/ will be replaced with the managed version.");
     console.log("Planning artifacts in _bmad-output/ will not be modified.\n");

src/installer.ts

@@ -528,22 +528,10 @@ export async function mergeInstructionsFile(
   await atomicWriteFile(instructionsPath, existing + snippet);
 }
 
-/**
- * @deprecated Use `mergeInstructionsFile(projectDir)` instead.
- * Kept for backward compatibility during migration.
- */
-export async function mergeClaudeMd(projectDir: string): Promise<void> {
-  return mergeInstructionsFile(projectDir);
-}
-
 export async function isInitialized(projectDir: string): Promise<boolean> {
   return exists(join(projectDir, CONFIG_FILE));
 }
 
-export async function hasExistingBmadDir(projectDir: string): Promise<boolean> {
-  return exists(join(projectDir, "_bmad"));
-}
-
 export async function previewInstall(
   projectDir: string,
   platform?: Platform

src/transition/artifacts.ts

@@ -1,4 +1,3 @@
-import { readFile } from "fs/promises";
 import { join } from "path";
 import { debug } from "../utils/logger.js";
 import { exists } from "../utils/file-system.js";
@@ -21,33 +20,3 @@ export async function findArtifactsDir(projectDir: string): Promise<string | nul
   debug(`No artifacts found. Checked: ${candidates.join(", ")}`);
   return null;
 }
-
-/** @deprecated Use `runPreflight` from `./preflight.js` instead. Kept for backward compatibility. */
-export async function validateArtifacts(files: string[], artifactsDir: string): Promise<string[]> {
-  const warnings: string[] = [];
-
-  const hasPrd = files.some((f) => /prd/i.test(f));
-  if (!hasPrd) {
-    warnings.push("No PRD document found in planning artifacts");
-  }
-
-  const hasArchitecture = files.some((f) => /architect/i.test(f));
-  if (!hasArchitecture) {
-    warnings.push("No architecture document found in planning artifacts");
-  }
-
-  // Check readiness report for NO-GO
-  const readinessFile = files.find((f) => /readiness/i.test(f));
-  if (readinessFile) {
-    try {
-      const content = await readFile(join(artifactsDir, readinessFile), "utf-8");
-      if (/NO[-\s]?GO/i.test(content)) {
-        warnings.push("Readiness report indicates NO-GO status");
-      }
-    } catch {
-      warnings.push("Could not read readiness report — NO-GO status unverified");
-    }
-  }
-
-  return warnings;
-}

src/transition/index.ts

@@ -27,7 +27,7 @@ export {
 export { detectTechStack, customizeAgentMd } from "./tech-stack.js";
 
 // Artifacts
-export { findArtifactsDir, validateArtifacts } from "./artifacts.js";
+export { findArtifactsDir } from "./artifacts.js";
 
 // Context
 export {

src/utils/state.ts

@@ -197,9 +197,6 @@ export function getPhaseInfo(phase: number): PhaseInfo {
   return info[phase] ?? { name: "Unknown", agent: "Unknown", commands: [] };
 }
 
-/** @deprecated Use RalphLoopStatus from validate.ts instead */
-export type RalphStatus = RalphLoopStatus;
-
 const DEFAULT_RALPH_STATUS: RalphLoopStatus = {
   loopCount: 0,
   status: "not_started",