feat: move NightyTidy reports to audit-reports/ with 00_ prefix

Reports are now written to audit-reports/00_NIGHTYTIDY-REPORT_NN_*.md
instead of the project root. The 00_ prefix ensures reports sort to
the top of the audit-reports folder alongside other audit artifacts.

- buildReportNames() now returns { reportFile, reportDir }
- generateReport() creates audit-reports/ directory if needed
- Updated all callers (cli.js, orchestrator.js) to use full paths
- Updated 10 test files to expect new location/format

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: VibeWriter User

.claude/memory/report-generation.md

@@ -6,11 +6,11 @@ Assumes CLAUDE.md loaded. Report logic in `src/report.js`, action plan logic in
 
 | Function | Purpose |
 |----------|---------|
-| `generateReport(results, narration, metadata, { actionPlanText, reportFile })` | Writes NIGHTYTIDY-REPORT.md (with inline action plan) + updates CLAUDE.md |
+| `generateReport(results, narration, metadata, { actionPlanText, reportFile, reportDir })` | Writes report to `audit-reports/00_NIGHTYTIDY-REPORT_*.md` (with inline action plan) + updates CLAUDE.md |
 | `cleanNarration(text)` | Strips conversational preamble from AI-generated narration (applied internally by `generateReport`) |
 | `formatDuration(ms)` | Format milliseconds to human-readable string |
 | `getVersion()` | Returns version from package.json (lazy-cached, defaults to '0.1.0' on error) |
-| `buildReportNames(projectDir, startTime)` | Returns `{ reportFile }` with auto-incremented number + timestamp |
+| `buildReportNames(projectDir, startTime)` | Returns `{ reportFile, reportDir }` — reportFile has `00_` prefix, reportDir is `audit-reports/` subdirectory |
 
 ## Report Structure (single file — no separate ACTIONS file)
 

CLAUDE.md

@@ -47,7 +47,7 @@ src/
   dashboard-tui.js         # Standalone TUI progress display (spawned in separate terminal window)
   lock.js                  # Atomic lock file to prevent concurrent runs (async with TTY prompt)
   logger.js                # File + stdout logger with chalk coloring
-  report.js                # NIGHTYTIDY-REPORT.md generation + CLAUDE.md update
+  report.js                # Report generation (audit-reports/00_NIGHTYTIDY-REPORT_*.md) + CLAUDE.md update
   consolidation.js         # Post-run action plan — consolidates step recommendations for inline report embedding
   setup.js                 # --setup command: generates CLAUDE.md integration snippet for target projects
   sync.js                  # Google Doc prompt sync — fetches, parses, diffs, updates local prompt files
@@ -230,7 +230,7 @@ NightyTidy creates these files/artifacts in the project it runs against:
 | `nightytidy-run.log` | Full run log (timestamped) | No |
 | `nightytidy-progress.json` | Live progress state (read by TUI window) | No (deleted on stop) |
 | `nightytidy-dashboard.url` | Dashboard URL — Claude reads this and shares with user | No (deleted on stop) |
-| `NIGHTYTIDY-REPORT_NN_YYYY-MM-DD-HHMM.md` | Run summary with step results + inline action plan (numbered + timestamped) | Yes (on run branch) |
+| `audit-reports/00_NIGHTYTIDY-REPORT_NN_YYYY-MM-DD-HHMM.md` | Run summary with step results + inline action plan (numbered + timestamped) | Yes (on run branch) |
 | `CLAUDE.md` (appended section) | "NightyTidy — Last Run" with undo tag | Yes (on run branch) |
 | `nightytidy.lock` | Prevents concurrent runs (PID + timestamp) | No (auto-removed on exit; persistent in orchestrator mode) |
 | `nightytidy-gui.log` | GUI session log (startup, API requests, errors, shutdown) | No |
@@ -332,7 +332,7 @@ bin/nightytidy.js
 5. **Execution**: Run each step (improvement + doc update in same session via `--continue`), with fallback commits
 6. **Rate-limit handling**: If a step hits a rate limit, the run pauses with exponential backoff (2min → 2hr cap). API is probed periodically; on success the failed step is retried. SIGINT during pause stops the run and gets partial results. GUI mode shows a pause overlay with countdown, "Resume Now", and "Finish with Partial Results" buttons.
 7. **Abort handling**: SIGINT generates partial report; second SIGINT force-exits
-8. **Reporting**: Changelog → action plan → NIGHTYTIDY-REPORT.md (with inline action plan) → commit → merge back to original branch
+8. **Reporting**: Changelog → action plan → audit-reports/00_NIGHTYTIDY-REPORT_*.md (with inline action plan) → commit → merge back to original branch
 9. **Notifications**: Desktop notifications at start, on step failure, and on completion
 
 ### Orchestrator Mode (Claude Code)

README.md

@@ -229,7 +229,7 @@ Changes are always on the run branch — your original branch is safe.
 
 After all steps complete, NightyTidy generates:
 
-- **NIGHTYTIDY-REPORT.md** — AI-narrated run summary with per-step results, costs, token usage, duration, and a prioritized action plan
+- **`audit-reports/00_NIGHTYTIDY-REPORT_*.md`** — AI-narrated run summary with per-step results, costs, token usage, duration, and a prioritized action plan (the `00_` prefix ensures reports sort to the top of the audit-reports folder)
 - **CLAUDE.md update** — Appends a "Last Run" section with the run date and undo instructions
 - **Audit trail** — All 33 step prompts are copied to `audit-reports/refactor-prompts/` so you can see exactly what was asked
 
@@ -239,7 +239,7 @@ If the AI report fails verification (junk detection), NightyTidy falls back to a
 
 | File | Committed? | Purpose |
 |------|-----------|---------|
-| `NIGHTYTIDY-REPORT_NN_YYYY-MM-DD-HHMM.md` | Yes | Run summary with step results + action plan |
+| `audit-reports/00_NIGHTYTIDY-REPORT_NN_YYYY-MM-DD-HHMM.md` | Yes | Run summary with step results + action plan |
 | `CLAUDE.md` (appended section) | Yes | "NightyTidy — Last Run" with undo tag |
 | `audit-reports/refactor-prompts/*.md` | Yes | All 33 prompts for audit trail |
 | `nightytidy-before-*` git tag | Yes (tag) | Safety snapshot for rollback |

src/cli.js

@@ -195,7 +195,7 @@ function saveRunState(projectDir, ctx, snapshot) {
 
 async function handleAbortedRun(executionResults, { projectDir, runBranch, tagName, originalBranch }) {
   info('Run interrupted by user');
-  const { reportFile } = buildReportNames(projectDir, Date.now() - executionResults.totalDuration);
+  const { reportFile, reportDir } = buildReportNames(projectDir, Date.now() - executionResults.totalDuration);
   const totalInputTokens = executionResults.results.reduce((sum, r) => sum + (r.cost?.inputTokens || 0), 0) || null;
   const totalOutputTokens = executionResults.results.reduce((sum, r) => sum + (r.cost?.outputTokens || 0), 0) || null;
   generateReport(executionResults, null, {
@@ -207,11 +207,12 @@ async function handleAbortedRun(executionResults, { projectDir, runBranch, tagNa
     endTime: Date.now(),
     totalInputTokens,
     totalOutputTokens,
-  }, { reportFile });
+  }, { reportFile, reportDir });
 
   const gitInstance = getGitInstance();
+  const reportPath = path.join(reportDir, reportFile);
   try {
-    await gitInstance.add([reportFile]);
+    await gitInstance.add([reportPath]);
     await gitInstance.commit('NightyTidy: Add partial run report');
   } catch (err) { debug(`Could not commit partial report: ${err.message}`); }
 
@@ -718,7 +719,8 @@ async function finalizeRun(executionResults, projectDir, ctx) {
 
   // Build unique report filename (numbered + timestamped)
   const startTime = Date.now() - executionResults.totalDuration;
-  const { reportFile } = buildReportNames(projectDir, startTime);
+  const { reportFile, reportDir } = buildReportNames(projectDir, startTime);
+  const reportPath = path.join(reportDir, reportFile);
 
   const totalInputTokens = executionResults.results.reduce((sum, r) => sum + (r.cost?.inputTokens || 0), 0) || null;
   const totalOutputTokens = executionResults.results.reduce((sum, r) => sum + (r.cost?.outputTokens || 0), 0) || null;
@@ -738,7 +740,7 @@ async function finalizeRun(executionResults, projectDir, ctx) {
   info('Generating report...');
   ctx.spinner = ora({ text: 'Generating report...', color: 'cyan' }).start();
 
-  const reportPrompt = buildReportPrompt(executionResults, metadata, { reportFile });
+  const reportPrompt = buildReportPrompt(executionResults, metadata, { reportFile: reportPath });
   const reportResult = await runPrompt(SAFETY_PREAMBLE + reportPrompt, projectDir, {
     label: 'Report generation',
     timeout: ctx.timeoutMs,
@@ -747,7 +749,6 @@ async function finalizeRun(executionResults, projectDir, ctx) {
   ctx.spinner.stop();
 
   // Verify the report file was created correctly
-  const reportPath = path.join(projectDir, reportFile);
   let reportOk = false;
   try {
     if (existsSync(reportPath)) {
@@ -758,7 +759,7 @@ async function finalizeRun(executionResults, projectDir, ctx) {
 
   if (!reportOk) {
     warn('AI report generation failed — using template fallback');
-    generateReport(executionResults, null, metadata, { reportFile, skipClaudeMdUpdate: true });
+    generateReport(executionResults, null, metadata, { reportFile, reportDir, skipClaudeMdUpdate: true });
     console.log(chalk.dim('Report generated with fallback template.'));
   } else {
     console.log(chalk.green('Report generated successfully.'));
@@ -770,7 +771,7 @@ async function finalizeRun(executionResults, projectDir, ctx) {
   // Commit report + CLAUDE.md (if not already committed by Claude)
   const gitInstance = getGitInstance();
   try {
-    const filesToCommit = [reportFile, 'CLAUDE.md'];
+    const filesToCommit = [reportPath, 'CLAUDE.md'];
     await gitInstance.add(filesToCommit);
     await gitInstance.commit('NightyTidy: Add run report and update CLAUDE.md');
   } catch (err) {
@@ -781,7 +782,7 @@ async function finalizeRun(executionResults, projectDir, ctx) {
   const mergeResult = await mergeRunBranch(ctx.originalBranch, ctx.runBranch);
 
   // Completion notification + terminal summary
-  printCompletionSummary(executionResults, mergeResult, { runBranch: ctx.runBranch, tagName: ctx.tagName, reportFile });
+  printCompletionSummary(executionResults, mergeResult, { runBranch: ctx.runBranch, tagName: ctx.tagName, reportFile: reportPath });
 
   // Update dashboard to completed and schedule shutdown
   if (ctx.dashState) {

src/orchestrator.js

@@ -771,7 +771,8 @@ export async function finishRun(projectDir) {
     const stepsOutputTokens = executionResults.results.reduce((sum, r) => sum + (r.cost?.outputTokens || 0), 0) || null;
 
     // Build unique report filename (numbered + timestamped)
-    const { reportFile } = buildReportNames(projectDir, state.startTime);
+    const { reportFile, reportDir } = buildReportNames(projectDir, state.startTime);
+    const reportPath = path.join(reportDir, reportFile);
 
     // ── Single AI call for report generation ──
     const finishStart = Date.now();
@@ -800,7 +801,7 @@ export async function finishRun(projectDir) {
 
     // Generate report in a single fresh Claude session (like other steps)
     info('Generating report (narration + action plan)...');
-    const reportPrompt = buildReportPrompt(executionResults, metadata, { reportFile });
+    const reportPrompt = buildReportPrompt(executionResults, metadata, { reportFile: reportPath });
     const reportResult = await runPrompt(SAFETY_PREAMBLE + reportPrompt, projectDir, {
       label: 'Report generation',
       timeout: state.timeout || undefined,
@@ -811,7 +812,6 @@ export async function finishRun(projectDir) {
     const finishDuration = Date.now() - finishStart;
 
     // Verify the report file was created correctly
-    const reportPath = path.join(projectDir, reportFile);
     let reportOk = false;
     try {
       if (existsSync(reportPath)) {
@@ -823,7 +823,7 @@ export async function finishRun(projectDir) {
     // Fallback: generate report via JS template if AI failed
     if (!reportOk) {
       warn('AI report generation failed or produced invalid output — using template fallback');
-      generateReport(executionResults, null, metadata, { reportFile, skipClaudeMdUpdate: true });
+      generateReport(executionResults, null, metadata, { reportFile, reportDir, skipClaudeMdUpdate: true });
     }
 
     // Update progress: mark finish step as completed
@@ -844,7 +844,7 @@ export async function finishRun(projectDir) {
     // Commit report + CLAUDE.md (if not already committed by Claude)
     const gitInstance = getGitInstance();
     try {
-      const filesToCommit = [reportFile, 'CLAUDE.md'];
+      const filesToCommit = [reportPath, 'CLAUDE.md'];
       await gitInstance.add(filesToCommit);
       await gitInstance.commit('NightyTidy: Add run report and update CLAUDE.md');
     } catch (err) {
@@ -853,7 +853,7 @@ export async function finishRun(projectDir) {
 
     // Read report content for embedding in response (avoids fragile file-read API in GUI)
     let reportContent = null;
-    try { reportContent = readFileSync(path.join(projectDir, reportFile), 'utf-8'); } catch { /* merge will bring file back */ }
+    try { reportContent = readFileSync(reportPath, 'utf-8'); } catch { /* merge will bring file back */ }
 
     // Merge
     const mergeResult = await mergeRunBranch(state.originalBranch, state.runBranch);
@@ -890,7 +890,7 @@ export async function finishRun(projectDir) {
       finishDuration,
       merged: mergeResult.success,
       mergeConflict: mergeResult.conflict || false,
-      reportPath: reportFile,
+      reportPath,
       reportContent,
       tagName: state.tagName,
       runBranch: state.runBranch,

src/report.js

@@ -8,41 +8,45 @@
  * Error contract: Warns but NEVER throws. Report failure must not crash a run.
  */
 
-import { writeFileSync, readFileSync, existsSync, readdirSync } from 'fs';
+import { writeFileSync, readFileSync, existsSync, readdirSync, mkdirSync } from 'fs';
 import path from 'path';
 import { info, warn } from './logger.js';
 import { REPORT_PROMPT } from './prompts/loader.js';
 
-const REPORT_PREFIX = 'NIGHTYTIDY-REPORT';
+const REPORT_PREFIX = '00_NIGHTYTIDY-REPORT';
+const REPORT_SUBDIR = 'audit-reports';
 
 /**
  * Build a unique, numbered + timestamped filename for the report.
- * Scans the project directory for existing reports to auto-increment the number.
+ * Scans the audit-reports/ directory for existing reports to auto-increment the number.
  * @param {string} projectDir - Target project directory
  * @param {number} [startTime] - Run start time (ms epoch); defaults to now
- * @returns {{ reportFile: string }}
+ * @returns {{ reportFile: string, reportDir: string }}
  */
 export function buildReportNames(projectDir, startTime = Date.now()) {
   const d = new Date(startTime);
   const pad2 = n => String(n).padStart(2, '0');
   const timestamp = `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}`;
 
-  // Find next available number by scanning existing report files
+  const reportDir = path.join(projectDir, REPORT_SUBDIR);
+
+  // Find next available number by scanning existing report files in audit-reports/
   let maxNum = 0;
   try {
-    const files = readdirSync(projectDir);
-    const pattern = /^NIGHTYTIDY-REPORT_(\d+)_/;
+    const files = readdirSync(reportDir);
+    const pattern = /^00_NIGHTYTIDY-REPORT_(\d+)_/;
     for (const f of files) {
       const m = f.match(pattern);
       if (m) maxNum = Math.max(maxNum, parseInt(m[1], 10));
     }
-  } catch { /* directory unreadable — start at 1 */ }
+  } catch { /* directory unreadable or doesn't exist — start at 1 */ }
 
   const num = pad2(maxNum + 1);
   const suffix = `_${num}_${timestamp}`;
 
   return {
     reportFile: `${REPORT_PREFIX}${suffix}.md`,
+    reportDir,
   };
 }
 
@@ -68,6 +72,7 @@ export function buildReportNames(projectDir, startTime = Date.now()) {
  * @typedef {Object} ReportOptions
  * @property {string|null} [actionPlanText] - Inline action plan markdown (headings already downgraded)
  * @property {string} [reportFile] - Custom report filename
+ * @property {string} [reportDir] - Custom report directory (defaults to audit-reports/)
  */
 
 /** @type {string|undefined} */
@@ -449,7 +454,7 @@ export function verifyReportContent(content, metadata) {
  * @param {ReportOptions} [options] - Report options
  * @returns {string} The report filename (basename only, e.g. 'NIGHTYTIDY-REPORT_01_2026-03-10-1448.md')
  */
-export function generateReport(results, narration, metadata, { actionPlanText, reportFile, skipClaudeMdUpdate } = {}) {
+export function generateReport(results, narration, metadata, { actionPlanText, reportFile, reportDir, skipClaudeMdUpdate } = {}) {
   const date = formatDate(metadata.startTime);
 
   let report = `# NightyTidy Report \u2014 ${date}\n\n`;
@@ -474,8 +479,15 @@ export function generateReport(results, narration, metadata, { actionPlanText, r
 
   report += buildUndoSection(metadata);
 
-  const filename = reportFile || 'NIGHTYTIDY-REPORT.md';
-  const reportPath = path.join(metadata.projectDir, filename);
+  const filename = reportFile || '00_NIGHTYTIDY-REPORT.md';
+  const targetDir = reportDir || path.join(metadata.projectDir, REPORT_SUBDIR);
+
+  // Ensure the report directory exists
+  try {
+    mkdirSync(targetDir, { recursive: true });
+  } catch { /* directory already exists or can't be created — continue anyway */ }
+
+  const reportPath = path.join(targetDir, filename);
   writeFileSync(reportPath, report, 'utf8');
   info(`Report written to ${reportPath}`);
 

test/cli-extended.test.js

@@ -112,7 +112,7 @@ vi.mock('../src/report.js', () => ({
   generateReport: vi.fn(),
   formatDuration: vi.fn((ms) => `${Math.round(ms / 1000)}s`),
   getVersion: vi.fn(() => '0.1.0'),
-  buildReportNames: vi.fn(() => ({ reportFile: 'NIGHTYTIDY-REPORT_01_2026-01-01-0000.md' })),
+  buildReportNames: vi.fn(() => ({ reportFile: '00_NIGHTYTIDY-REPORT_01_2026-01-01-0000.md', reportDir: '/fake/project/audit-reports' })),
   buildReportPrompt: vi.fn(() => 'mock report prompt'),
   verifyReportContent: vi.fn(() => true),
   updateClaudeMd: vi.fn(),

test/cli-resume.test.js

@@ -117,7 +117,7 @@ vi.mock('../src/report.js', () => ({
   generateReport: vi.fn(),
   formatDuration: vi.fn((ms) => `${Math.round(ms / 1000)}s`),
   getVersion: vi.fn(() => '0.1.0'),
-  buildReportNames: vi.fn(() => ({ reportFile: 'NIGHTYTIDY-REPORT_01_2026-01-01-0000.md' })),
+  buildReportNames: vi.fn(() => ({ reportFile: '00_NIGHTYTIDY-REPORT_01_2026-01-01-0000.md', reportDir: '/fake/project/audit-reports' })),
   buildReportPrompt: vi.fn(() => 'mock report prompt'),
   verifyReportContent: vi.fn(() => true),
   updateClaudeMd: vi.fn(),

test/cli.test.js

@@ -112,7 +112,7 @@ vi.mock('../src/report.js', () => ({
   generateReport: vi.fn(),
   formatDuration: vi.fn((ms) => `${Math.round(ms / 1000)}s`),
   getVersion: vi.fn(() => '0.1.0'),
-  buildReportNames: vi.fn(() => ({ reportFile: 'NIGHTYTIDY-REPORT_01_2026-01-01-0000.md' })),
+  buildReportNames: vi.fn(() => ({ reportFile: '00_NIGHTYTIDY-REPORT_01_2026-01-01-0000.md', reportDir: '/fake/project/audit-reports' })),
   buildReportPrompt: vi.fn(() => 'mock report prompt'),
   verifyReportContent: vi.fn(() => true),
   updateClaudeMd: vi.fn(),

test/contracts.test.js

@@ -633,8 +633,9 @@ describe('contract: report.js — getVersion and side effects', () => {
     expect(version.length).toBeGreaterThan(0);
   });
 
-  it('generateReport writes NIGHTYTIDY-REPORT.md to disk', async () => {
+  it('generateReport writes report to audit-reports/ directory', async () => {
     const { generateReport } = await import('../src/report.js');
+    const { readdirSync } = await import('fs');
 
     const results = {
       results: [{ step: { number: 1, name: 'Lint' }, status: 'completed', output: 'ok', duration: 1000, attempts: 1, error: null }],
@@ -652,7 +653,11 @@ describe('contract: report.js — getVersion and side effects', () => {
 
     generateReport(results, null, metadata);
 
-    expect(existsSync(path.join(tempDir, 'NIGHTYTIDY-REPORT.md'))).toBe(true);
+    const auditDir = path.join(tempDir, 'audit-reports');
+    expect(existsSync(auditDir)).toBe(true);
+    const files = readdirSync(auditDir);
+    const reportFile = files.find(f => f.startsWith('00_NIGHTYTIDY-REPORT'));
+    expect(reportFile).toBeDefined();
   });
 
   it('generateReport also writes/updates CLAUDE.md', async () => {
@@ -937,7 +942,7 @@ describe('contract: orchestrator.js — never throws, returns result objects', (
     vi.doMock('../src/report.js', () => ({
       generateReport: vi.fn(),
       formatDuration: vi.fn(() => '0m'),
-      buildReportNames: vi.fn(() => ({ reportFile: 'NIGHTYTIDY-REPORT_01_2026-01-01-0000.md' })),
+      buildReportNames: vi.fn(() => ({ reportFile: '00_NIGHTYTIDY-REPORT_01_2026-01-01-0000.md', reportDir: '/fake/project/audit-reports' })),
       buildReportPrompt: vi.fn(() => 'mock report prompt'),
       verifyReportContent: vi.fn(() => true),
       updateClaudeMd: vi.fn(),