# [Epic] Pre-Publish Validation System

**Overview**: Build automated audit and validation system to ensure all customer-facing files are ready for publication, including IP protection verification, documentation checks, build status validation, and interactive checklists.

## Child Issues

### Issue 1: Core Audit Script & Reporting
**Type**: Enhancement  
**Overview**: Create comprehensive audit script that checks 20+ publication readiness criteria and generates detailed reports with pass/fail/warning status.

**Acceptance Criteria**
- [ ] Script checks build status (dist/ compiled, no stale artifacts)
- [ ] Validates version consistency (package.json, git tags, CHANGELOG)
- [ ] Audits IP protection (no .ts files in dist/, license headers on all files)
- [ ] Verifies file structure and correct folders
- [ ] Detects secrets/credentials in dist/ files
- [ ] Validates documentation (README customer-ready, no internal refs)
- [ ] Checks for placeholders (TODO, FIXME, {{PLACEHOLDER}})
- [ ] Tests installation script runs without errors
- [ ] Validates links in customer documentation
- [ ] Outputs formatted markdown report with timestamps
- [ ] Categorizes issues by severity (BLOCK/WARN/INFO)

**Technical Implementation**
- Create `scripts/pre-publish-audit.ts`
- Implement 20 distinct audit checks
- Generate markdown report with checkmarks/warnings
- Add timestamps and severity levels
- Export function `runAudit()` returning structured results
- Add npm script: `npm run pre-publish-audit`
- Follow existing error handling patterns

**Dependencies**: None  
**Classification**: 5  
**Size/Complexity**: M/M

---

### Issue 2: Audit Report Template & Documentation
**Type**: Enhancement  
**Overview**: Create reusable markdown template for audit reports and document all 20 checks with examples of pass/fail output.

**Acceptance Criteria**
- [ ] Template includes all 20 check categories
- [ ] Shows example PASS, WARN, and FAIL outputs
- [ ] Documents what each check validates
- [ ] Includes severity ratings and actionable fixes
- [ ] Contains quick-fix command suggestions
- [ ] Stored in `templates/roadcrew/audit-report.template.md`
- [ ] Customer-ready documentation in `docs/PUBLISHING.md`

**Technical Implementation**
- Create audit report template markdown
- Document each of the 20 checks
- Include real examples from actual audit runs
- Add severity definitions (BLOCK/WARN/INFO)
- Create table mapping checks to fix commands
- Update PUBLISHING.md with audit report section

**Dependencies**: Depends on Issue 1  
**Classification**: 2  
**Size/Complexity**: S/S

---

### Issue 3: Interactive Validation Command
**Type**: Enhancement  
**Overview**: Create interactive validation command that runs audit, presents results, and prompts user before proceeding to publish.

**Acceptance Criteria**
- [ ] Command `validate-for-publish` runs full audit
- [ ] Displays audit report with color-coded results
- [ ] Shows summary of issues found
- [ ] Prompts: "Review audit report. Ready to publish?"
- [ ] If BLOCK issues exist, prevents proceeding
- [ ] If WARN issues exist, asks for confirmation
- [ ] Displays quick-fix commands for each issue
- [ ] Option to auto-fix simple issues (timestamps, placeholders)
- [ ] Added to package.json scripts

**Technical Implementation**
- Create `scripts/validate-for-publish.ts`
- Use existing audit script from Issue 1
- Implement interactive prompts using inquirer
- Add color output (green/yellow/red)
- Implement auto-fix for:
  - Datetime stamps on files
  - Simple placeholder replacements
  - File permission corrections
- Add npm script: `npm run validate-for-publish`

**Dependencies**: Depends on Issue 1  
**Classification**: 4  
**Size/Complexity**: M/M

---

### Issue 4: Command Documentation Validation
**Type**: Enhancement  
**Overview**: Validate all command files have accurate documentation that matches current implementation, proper headers, and no outdated descriptions.

**Acceptance Criteria**
- [ ] Audit checks command file YAML headers are present
- [ ] Verifies all commands in `.cursor/commands/` have descriptions
- [ ] Detects commands with TODO or placeholder text
- [ ] Cross-references command descriptions with functionality
- [ ] Flags outdated or inaccurate descriptions
- [ ] Validates command naming conventions
- [ ] Checks for broken internal links in command docs
- [ ] Reports which commands need documentation updates

**Technical Implementation**
- Add to audit script (Issue 1):
  - Parse all .md files in commands/
  - Extract YAML headers and descriptions
  - Check for placeholder/TODO markers
  - Validate against actual implementation
- Create mapping of command names to descriptions
- Generate detailed report of outdated docs
- Add audit check: "Command Documentation Validation"

**Dependencies**: Depends on Issue 1  
**Classification**: 3  
**Size/Complexity**: M/S

---

### Issue 5: License & IP Protection Audit
**Type**: Enhancement  
**Overview**: Comprehensive audit to verify all customer files have license headers, source code is compiled, and no proprietary information is exposed.

**Acceptance Criteria**
- [ ] Scans all dist/ files for TypeScript (.ts) source
- [ ] Verifies license headers on all distributed files
- [ ] Detects hardcoded API keys or credentials
- [ ] Flags internal paths (scripts/, context/, docs/)
- [ ] Checks for environment variable references
- [ ] Validates file permissions (executable where needed)
- [ ] Reports any files missing license headers
- [ ] Generates IP protection compliance report

**Technical Implementation**
- Add to audit script (Issue 1):
  - Scan dist/ for .ts extensions
  - Parse file headers for license comments
  - Regex patterns for common credential formats
  - Check for internal path references
  - Validate file modes (chmod)
- Create list of approved license patterns
- Generate compliance report
- Add audit checks:
  - "TypeScript Source Files in dist/"
  - "License Header Validation"
  - "Secrets & Credentials Scan"
  - "File Permissions Validation"

**Dependencies**: Depends on Issue 1  
**Classification**: 4  
**Size/Complexity**: M/M

---

### Issue 6: Customer Documentation Audit
**Type**: Enhancement  
**Overview**: Validate all customer-facing documentation is present, complete, and customer-ready (no internal references).

**Acceptance Criteria**
- [ ] README.md exists and is customer-ready
- [ ] CHANGELOG.md exists and documents recent changes
- [ ] COMMANDS.md lists all commands with descriptions
- [ ] Installation instructions are clear and complete
- [ ] No references to internal directories/scripts
- [ ] No development/contributor-only content
- [ ] All links are valid and not broken
- [ ] Documentation is properly formatted and readable
- [ ] Generates report of missing or incomplete documentation

**Technical Implementation**
- Add to audit script (Issue 1):
  - Check existence and size of key doc files
  - Scan for internal references (scripts/, context/, etc.)
  - Validate links with regex/URL checking
  - Check formatting is valid markdown
  - Count commands vs. documentation entries
- Create list of required customer-facing docs
- Generate documentation audit report
- Add audit checks:
  - "README.md Completeness"
  - "CHANGELOG.md Up-to-Date"
  - "COMMANDS.md Accuracy"
  - "Internal Reference Scan"
  - "Documentation Link Validation"

**Dependencies**: Depends on Issue 1  
**Classification**: 3  
**Size/Complexity**: M/S

---

### Issue 7: Build & Dependency Validation
**Type**: Enhancement  
**Overview**: Verify build is current, dependencies are locked, and no stale artifacts exist in distribution.

**Acceptance Criteria**
- [ ] dist/ directory exists and contains compiled files
- [ ] No stale/old artifacts (>1 week old)
- [ ] package-lock.json is up to date and committed
- [ ] All required utilities in dist/scripts/utils/
- [ ] Build timestamps are recent (within last build)
- [ ] No merge conflicts or uncommitted changes
- [ ] Git status is clean for distribution files
- [ ] Reports build timestamp and age

**Technical Implementation**
- Add to audit script (Issue 1):
  - Check dist/ directory exists
  - Get file modification times
  - Compare against last git commit
  - Verify package-lock.json exists
  - Run `git status` and check for conflicts
  - Compare timestamps against package.json
- Create list of required dist files
- Generate build status report
- Add audit checks:
  - "Distribution Directory Status"
  - "Build Age & Freshness"
  - "Dependency Lock Status"
  - "Git Stale Artifact Detection"

**Dependencies**: Depends on Issue 1  
**Classification**: 3  
**Size/Complexity**: M/S

---

### Issue 8: Pre-Publish Checklist Template
**Type**: Enhancement  
**Overview**: Create interactive markdown checklist for humans to review before publishing, with links to audit reports and manual verification steps.

**Acceptance Criteria**
- [ ] Checklist includes all 20 audit items
- [ ] Human-readable format with explanations
- [ ] Links to audit script output
- [ ] Manual verification steps for critical items
- [ ] Sign-off section for team approval
- [ ] Severity/priority indicators
- [ ] Stored in `templates/roadcrew/pre-publish-checklist.md`
- [ ] Integrated into publishing documentation

**Technical Implementation**
- Create markdown template with:
  - [ ] Checkboxes for each audit item
  - Description of what's verified
  - Link to related audit check
  - Manual verification steps where needed
  - Sign-off fields (date, person, ticket #)
- Include example completed checklist
- Add instructions to publishing docs
- Make printable/saveable format

**Dependencies**: Depends on Issue 2  
**Classification**: 2  
**Size/Complexity**: S/S

---

### Issue 9: Integration into Publish Workflow
**Type**: Enhancement  
**Overview**: Update publish-distribution script to require passing audit before allowing publication to customers.

**Acceptance Criteria**
- [ ] `publish-distribution.ts` calls audit before syncing
- [ ] Blocks publication if BLOCK issues found
- [ ] Warns if WARN issues found
- [ ] Shows audit report before prompting to continue
- [ ] Creates `npm run publish` wrapper command
- [ ] Provides clear instructions if audit fails
- [ ] Maintains existing `--push` flag behavior
- [ ] Includes dry-run option to preview without publishing

**Technical Implementation**
- Modify `scripts/publish-distribution.ts`:
  - Call runAudit() before main publish loop
  - Check severity levels
  - Display report to console
  - Prompt for confirmation
  - Prevent push if issues
- Create wrapper: `npm run publish`
- Add flags: `--skip-audit` (for emergency only)
- Update help text and documentation
- Add logging of publication events

**Dependencies**: Depends on Issues 1, 3  
**Classification**: 4  
**Size/Complexity**: M/M

---

### Issue 10: Documentation Updates
**Type**: Enhancement  
**Overview**: Update customer-facing and internal documentation to explain pre-publish validation process.

**Acceptance Criteria**
- [ ] `docs/PUBLISHING.md` includes pre-publish audit section
- [ ] README explains validation requirement
- [ ] Instructions for running audit manually
- [ ] Examples of common audit failures and fixes
- [ ] Customer guide: "What to expect during updates"
- [ ] Internal wiki/docs updated with process
- [ ] Release notes include audit checklist

**Technical Implementation**
- Update `docs/PUBLISHING.md`:
  - Add "Pre-Publication Validation" section
  - Include audit report example
  - Document how to run audit
  - List common issues and fixes
- Update main `README.md`:
  - Link to publishing guide
  - Mention validation process
- Create customer notice about quality checks
- Add to release process documentation

**Dependencies**: Depends on Issues 1, 2, 8  
**Classification**: 2  
**Size/Complexity**: S/S

---

## Dependencies

- **Blocks:** Release Publishing workflow (cannot publish until all validation checks complete)
- **Related Specs:** 
  - `memory-bank/requirements/specs/pre-publish-validation-spec.md`
  - `docs/PUBLISHING.md`

## Definition of Done

- [ ] All 10 child issues completed and merged to dev
- [ ] Audit script integrated into publish workflow
- [ ] Pre-publish validation required before customer publication
- [ ] Documentation updated and customer-ready
- [ ] Manual checklist available for team review
- [ ] First production publication passes full audit