Instruction file imported from lightspeedwp/ma-theme-extraction-test (.github/instructions/reporting.instructions.md). Copyright stays with the author.

Reporting Instructions for AI Agents & Copilot

This document defines how AI agents and Copilot should generate, structure, and manage reports in the block theme scaffold project.

Core Principles

1. Centralized Storage: All reports MUST be stored in .github/reports/ directory - never in repository root
2. Organized by Type: Reports organized into categorical subdirectories (coverage, analysis, performance, validation, agents)
3. Timestamped: All reports include ISO 8601 date in filename for versioning
4. Excluded from Distribution: Reports are in .distignore and .gitignore
5. Linked to Processes: Reports reference the process that generated them (build, lint, test, etc.)
6. Searchable: File naming allows easy discovery and archival

Report Directory Structure

.github/reports/
├── .gitkeep
├── README.md                          # Overview of reporting system
├── coverage/                          # Code coverage reports
│   ├── js/                           # JavaScript coverage
│   │   ├── 2025-12-07-coverage.html
│   │   ├── 2025-12-07-lcov-report/
│   │   └── 2025-12-07-coverage.json
│   └── php/                          # PHP coverage
│       ├── 2025-12-07-coverage.html
│       └── 2025-12-07-coverage.json
├── analysis/                          # Code analysis reports
│   ├── 2025-12-07-bundle-analysis.html
│   ├── 2025-12-07-lighthouse.json
│   ├── 2025-12-07-accessibility.json
│   └── 2025-12-07-security-audit.json
├── validation/                        # Validation & linting results
│   ├── 2025-12-07-eslint-report.json
│   ├── 2025-12-07-stylelint-report.json
│   ├── 2025-12-07-phpcs-report.json
│   └── 2025-12-07-validation-summary.json
├── performance/                       # Performance metrics
│   ├── 2025-12-07-lighthouse.json
│   ├── 2025-12-07-bundle-size.json
│   ├── 2025-12-07-core-web-vitals.json
│   └── 2025-12-07-performance-budget.json
├── projects/                          # Project progress tracking
│   └── active/                        # Per-active-project reports
│       └── my-project/                # Project slug
│           ├── 2025-12-07-daily-progress.md
│           └── 2025-12-09-weekly-summary.md
├── agents/                            # AI agent execution reports
│   ├── 2025-12-07-theme-generator.json
│   ├── 2025-12-07-build-agent.json
│   ├── 2025-12-07-code-review.json
│   └── 2025-12-07-agent-summary.md
├── comparison/                        # Before/after comparisons
│   ├── 2025-12-07-diff-report.json
│   ├── 2025-12-07-size-comparison.json
│   └── 2025-12-07-performance-diff.json
└── 📋 archived/                       # Old reports (rotated weekly/monthly)
    └── 2025-11-30-*.json              # Previous date reports

File Naming Convention

Format: YYYY-MM-DD-description.{ext}

Examples

✅ CORRECT NAMING:
- 2025-12-07-coverage.html
- 2025-12-07-eslint-report.json
- 2025-12-07-bundle-analysis.html
- 2025-12-07-agent-execution.md
- 2025-12-07-lighthouse.json

❌ INCORRECT NAMING:
- coverage.html                        (missing date)
- coverage-2025-12-07.html            (date at end)
- eslint_report.json                  (underscore instead of hyphen)
- report.json                          (no date, no description)
- eslint-report-2025-12-07.html       (date format wrong)

File Extensions by Type

Report Categories & Ownership

Coverage Reports (coverage/)

Purpose: Code coverage metrics from test runs Generated By: Jest, PHPUnit, Playwright When: After npm run test or npm run test:coverage Storage: .github/reports/coverage/{js|php}/YYYY-MM-DD-{metric}.{ext}

Files to Generate:

• YYYY-MM-DD-coverage.html - Interactive coverage viewer
• YYYY-MM-DD-coverage.json - Coverage data (for CI/parsing)
• YYYY-MM-DD-lcov-report/ - Detailed line coverage (optional)

Example:

# Jest generates
.github/reports/coverage/js/2025-12-07-coverage.html
.github/reports/coverage/js/2025-12-07-coverage.json

# PHPUnit generates
.github/reports/coverage/php/2025-12-07-coverage.html
.github/reports/coverage/php/2025-12-07-coverage.json

Analysis Reports (analysis/)

Purpose: Code analysis, bundle analysis, accessibility, security audits Generated By: Lighthouse CI, Webpack Bundle Analyzer, axe-core, npm audit When: As part of build, test, or performance checks Storage: .github/reports/analysis/YYYY-MM-DD-{analysis-type}.{ext}

Files to Generate:

• YYYY-MM-DD-bundle-analysis.html - Webpack bundle visualization
• YYYY-MM-DD-lighthouse.json - Lighthouse CI metrics
• YYYY-MM-DD-accessibility.json - Accessibility audit results
• YYYY-MM-DD-security-audit.json - npm audit or dependency check

Example:

.github/reports/analysis/2025-12-07-bundle-analysis.html
.github/reports/analysis/2025-12-07-lighthouse.json
.github/reports/analysis/2025-12-07-accessibility.json

Validation Reports (validation/)

Purpose: Linting, validation, and code quality check results Generated By: ESLint, Stylelint, PHPCS, package.json-lint When: After npm run lint or linting processes Storage: .github/reports/validation/YYYY-MM-DD-{tool}-report.json

Files to Generate:

• YYYY-MM-DD-eslint-report.json - ESLint results
• YYYY-MM-DD-stylelint-report.json - Stylelint results
• YYYY-MM-DD-phpcs-report.json - PHP CodeSniffer results
• YYYY-MM-DD-validation-summary.json - Combined validation summary

Example:

.github/reports/validation/2025-12-07-eslint-report.json
.github/reports/validation/2025-12-07-stylelint-report.json
.github/reports/validation/2025-12-07-phpcs-report.json
.github/reports/validation/2025-12-07-validation-summary.json

Performance Reports (performance/)

Purpose: Performance metrics, bundle size limits, Core Web Vitals Generated By: Lighthouse CI, size-limit, Webpack bundle analyzer When: During performance checks or CI/CD Storage: .github/reports/performance/YYYY-MM-DD-{metric}.json

Files to Generate:

• YYYY-MM-DD-lighthouse.json - Lighthouse metrics
• YYYY-MM-DD-bundle-size.json - Bundle size metrics
• YYYY-MM-DD-core-web-vitals.json - CWV data
• YYYY-MM-DD-performance-budget.json - Budget status

Example:

.github/reports/performance/2025-12-07-lighthouse.json
.github/reports/performance/2025-12-07-bundle-size.json
.github/reports/performance/2025-12-07-performance-budget.json

Agent Reports (agents/)

Purpose: AI agent execution summaries and results Generated By: AI agents, Copilot, automated scripts When: After agent executes (theme generation, code review, build automation) Storage: .github/reports/agents/YYYY-MM-DD-{agent-name}.{ext}

Files to Generate:

• YYYY-MM-DD-theme-generator.json - Theme generation results
• YYYY-MM-DD-build-agent.json - Build agent execution
• YYYY-MM-DD-code-review.json - Code review findings
• YYYY-MM-DD-agent-summary.md - Human-readable summary

Contents Should Include:

{
  "agent": "theme-generator",
  "timestamp": "2025-12-07T10:30:45.123Z",
  "status": "success|failure|warning",
  "summary": "What the agent did",
  "metrics": {
    "filesProcessed": 42,
    "duration": "2.5s",
    "errors": 0,
    "warnings": 3
  },
  "artifacts": ["list of created/modified files"],
  "logFile": "logs/agents/2025-12-07-agent-name.log"
}

Example:

.github/reports/agents/2025-12-07-theme-generator.json
.github/reports/agents/2025-12-07-theme-generator-summary.md
.github/reports/agents/2025-12-07-build-agent.json

Generate-Theme Agent Report Example:

{
  "agent": "generate-theme",
  "timestamp": "2025-12-10T10:30:45.123Z",
  "status": "success",
  "summary": "Generated theme 'my-awesome-theme' from scaffold",
  "metrics": {
    "filesProcessed": 87,
    "variablesReplaced": 52,
    "duration": "1.2s",
    "errors": 0,
    "warnings": 0
  },
  "artifacts": [
    "output-theme/",
    "output-theme/style.css",
    "output-theme/functions.php",
    "output-theme/theme.json"
  ],
  "config": {
    "theme_slug": "my-awesome-theme",
    "theme_name": "My Awesome Theme",
    "author": "Developer Name"
  },
  "logFile": "logs/agents/2025-12-10-generate-theme.log"
}

Project Progress Reports (projects/active/)

Purpose: Track multi-day or multi-week progress for active projects Generated By: Project owners, delivery agents, automation tied to .github/projects/active/ When: Daily updates and weekly rollups (week starts Monday) Storage: .github/reports/projects/active/{project-slug}/{YYYY-MM-DD}-{cadence}.md

Files to Generate:

• YYYY-MM-DD-daily-progress.md - Daily update per active project
• YYYY-MM-DD-weekly-summary.md - Weekly rollup per active project (use Monday date for the week)

Daily Update Format:

Date: 2025-12-07
Project: my-project
Work Completed:
- Task X.Y completed
- 4 tests added to file.test.js
- Coverage: 80% → 84% (+4%)
Blockers:
- None / describe blockers
Next Steps:
- Continue with Task X.Y+1
Links:
- Project doc: .github/projects/active/my-project.md
- Logs: logs/projects/2025-12-07-my-project.log

Weekly Summary Format:

Week of 2025-12-07
Project: my-project
Summary:
- Phase X completed
- Coverage: 82% → 86% (Δ+4%)
- Tests added: 12
Key Achievements:
- [...]
Challenges:
- [...]
Blockers:
- None / [...]
Next Steps:
- Continue with Task X.Y+1
Links:
- Daily logs: .github/reports/projects/active/my-project/
- Project doc: .github/projects/active/my-project.md

Implementation Notes:

• Create per-project subdirectories under .github/reports/projects/active/
• Derive project slug from .github/projects/active/ filenames
• Keep filenames ISO-dated and kebab-cased
• Include coverage deltas and test counts when available
• Link to related project docs and logs for traceability

Comparison Reports (comparison/)

Purpose: Before/after comparisons for performance, size, or metrics Generated By: CI/CD pipelines, performance analysis When: During multi-run analysis or PR validation Storage: .github/reports/comparison/YYYY-MM-DD-{comparison-type}.json

Files to Generate:

• YYYY-MM-DD-diff-report.json - Code diff analysis
• YYYY-MM-DD-size-comparison.json - Bundle size before/after
• YYYY-MM-DD-performance-diff.json - Performance metrics comparison

Example:

.github/reports/comparison/2025-12-07-bundle-size-diff.json
.github/reports/comparison/2025-12-07-performance-metrics-diff.json

Report Generation Rules for AI Agents

Rule 1: Always Use .github/reports/ Directory

MUST DO:

// ✅ Correct - Save to .github/reports/ directory
const reportPath = "./.github/reports/analysis/2025-12-07-bundle-analysis.html";
fs.writeFileSync(reportPath, htmlContent);

// ❌ Never do this - Root directory
const badPath = "./bundle-analysis.html";
fs.writeFileSync(badPath, htmlContent);

// ❌ Never do this - Unpredictable location
const alsoBad = `./${Date.now()}-report.json`;
fs.writeFileSync(alsoBad, JSON.stringify(data));

Rule 2: Always Include ISO Date in Filename

MUST DO:

// ✅ Correct - ISO 8601 date
const date = new Date().toISOString().split("T")[0]; // 2025-12-07
const filename = `.github/reports/coverage/js/${date}-coverage.json`;

// ❌ Never omit date
const badFilename = ".github/reports/coverage/js/coverage.json";

// ❌ Never use wrong date format
const wrongFormat = `.github/reports/coverage/js/${Date.now()}-coverage.json`;

Rule 3: Create Directory Structure If Needed

MUST DO:

// ✅ Correct - Create nested directories
const fs = require("fs");
const path = require("path");

function ensureDirectory(dirPath) {
  if (!fs.existsSync(dirPath)) {
    fs.mkdirSync(dirPath, { recursive: true });
  }
}

const reportDir = ".github/reports/coverage/js";
ensureDirectory(reportDir);
fs.writeFileSync(`${reportDir}/2025-12-07-coverage.json`, data);

Rule 4: Include Metadata in Reports

MUST DO:

// ✅ Correct - Include metadata
const report = {
  date: new Date().toISOString(),
  type: "coverage",
  tool: "jest",
  metrics: {
    statements: 92.5,
    branches: 88.3,
    functions: 90.1,
    lines: 93.2,
  },
  logFile: "logs/test/2025-12-07-jest.log",
};

fs.writeFileSync(".github/reports/coverage/js/2025-12-07-coverage.json", JSON.stringify(report, null, 2));

Rule 5: Reference Related Logs

MUST DO:

// ✅ Correct - Link to related log file
const report = {
  logFile: "logs/test/2025-12-07-jest.log", // Process that generated report
  timestamp: "2025-12-07T10:30:45.123Z",
  // ... rest of report
};

Rule 6: Don't Create Reports in tmp/

Rules:

• Use tmp/ only for temporary files during processing
• NEVER save final reports to tmp/ - move them to .github/reports/
• Clean up tmp/ files when done

MUST DO:

// ✅ Correct - Use tmp/ for intermediate files, .github/reports/ for results
const tempFile = "tmp/intermediate-data.json";
const reportFile = ".github/reports/analysis/2025-12-07-analysis.json";

// Process data
const data = processData();
fs.writeFileSync(tempFile, JSON.stringify(data));

// Generate report
const report = generateReport(data);
fs.writeFileSync(reportFile, JSON.stringify(report, null, 2));

// Clean up temporary files
fs.unlinkSync(tempFile);

// ❌ Never do this - Leaving reports in tmp/
const badPath = "tmp/2025-12-07-report.json";
fs.writeFileSync(badPath, JSON.stringify(report));

Integration with Logging

Reports should reference their generating processes through logs:

Report Should Contain:

{
  "date": "2025-12-07T10:30:45.123Z",
  "reportFile": ".github/reports/validation/2025-12-07-eslint-report.json",
  "logFile": "logs/lint/2025-12-07-eslint.log",
  "processName": "eslint",
  "category": "validation"
}

Logging Should Reference Reports:

logger.info("Generating report: .github/reports/validation/2025-12-07-eslint-report.json");
logger.debug(`Report saved with ${errorCount} issues`);

Report Retention & Archival

Automatic Cleanup

The .github/reports/archived/ directory stores older reports. Consider implementing:

# Archive reports older than 30 days (weekly rotation)
find .github/reports/ -type f -mtime +30 -exec mv {} .github/reports/archived/ \;

# Delete reports older than 90 days (quarterly cleanup)
find .github/reports/archived/ -type f -mtime +90 -delete

Manual Archival

# Move specific date's reports to archive
mv .github/reports/coverage/2025-11-30*.* .github/reports/archived/
mv .github/reports/analysis/2025-11-30*.* .github/reports/archived/
mv .github/reports/validation/2025-11-30*.* .github/reports/archived/

Distignore & Gitignore Rules

Ensure these exist in .distignore and .gitignore:

# Reports directory
.github/reports/
!.github/reports/README.md
!.github/reports/.gitkeep

# Temporary files
tmp/
.lint-temp/

# Logs directory
logs/
!logs/.gitkeep

Git Workflow

Reports should NOT be committed, but README can be:

# ✅ This is fine - documentation only
git add .github/reports/README.md

# ❌ Never commit actual reports
git add .github/reports/coverage/2025-12-07-coverage.html  # Don't do this!

Environment Variables

If reports need special handling, configure via environment:

# Control report output
export REPORT_DIR="reports"          # Where to save reports
export ARCHIVE_DIR=".github/reports/archived"  # Archive location
export REPORT_RETENTION_DAYS=30      # Auto-archive threshold
export LOG_LEVEL="debug"              # Logging detail level

Common Patterns

Pattern 1: Jest Coverage Report

const fs = require("fs");
const path = require("path");

function saveJestReport(coverageData) {
  const date = new Date().toISOString().split("T")[0];
  const reportDir = ".github/reports/coverage/js";

  // Ensure directory
  fs.mkdirSync(reportDir, { recursive: true });

  // Save report
  const report = {
    date: new Date().toISOString(),
    tool: "jest",
    type: "coverage",
    metrics: coverageData.coverageSummary,
    logFile: `logs/test/${date}-jest.log`,
  };

  fs.writeFileSync(path.join(reportDir, `${date}-coverage.json`), JSON.stringify(report, null, 2));
}

Pattern 2: ESLint Validation Report

const fs = require("fs");
const path = require("path");
const { ESLint } = require("eslint");

async function saveESLintReport(results) {
  const date = new Date().toISOString().split("T")[0];
  const reportDir = ".github/reports/validation";

  // Ensure directory
  fs.mkdirSync(reportDir, { recursive: true });

  // Generate report
  const report = {
    date: new Date().toISOString(),
    tool: "eslint",
    type: "validation",
    errorCount: results.reduce((sum, r) => sum + r.errorCount, 0),
    warningCount: results.reduce((sum, r) => sum + r.warningCount, 0),
    results: results,
    logFile: `logs/lint/${date}-eslint.log`,
  };

  fs.writeFileSync(path.join(reportDir, `${date}-eslint-report.json`), JSON.stringify(report, null, 2));
}

Pattern 3: Agent Execution Report

const fs = require("fs");
const path = require("path");

function saveAgentReport(agentName, status, metrics, artifacts) {
  const date = new Date().toISOString().split("T")[0];
  const reportDir = ".github/reports/agents";

  // Ensure directory
  fs.mkdirSync(reportDir, { recursive: true });

  // Generate report
  const report = {
    agent: agentName,
    timestamp: new Date().toISOString(),
    status: status,
    metrics: metrics,
    artifacts: artifacts,
    logFile: `logs/agents/${date}-${agentName}.log`,
  };

  fs.writeFileSync(path.join(reportDir, `${date}-${agentName}.json`), JSON.stringify(report, null, 2));

  return path.join(reportDir, `${date}-${agentName}.json`);
}

Verification Checklist

Before saving any report, verify:

• File is in .github/reports/ directory (not root)
• Filename includes ISO date (YYYY-MM-DD)
• Filename uses kebab-case, not underscores
• Directory structure exists (create if needed)
• Report includes metadata (date, tool, type)
• Report references related log file
• Temporary files cleaned up after processing
• Report format is valid (JSON or HTML, not random)

Updates to Other Instructions

This instructions file should be referenced in:

1. copilot-ai-agent.instructions.md - Add reference in file handling section
2. block-theme-development.instructions.md - Add reporting best practices
3. generate-theme.instructions.md - Agent report generation patterns
4. Any custom agent implementations

Summary

✅ All reports in .github/reports/ with date-based filenames ✅ Organized by category (coverage, analysis, validation, performance, agents) ✅ Always reference related logs ✅ Clean separation from source code ✅ Searchable and archivable ✅ Never scattered in root or tmp directories