Skip to main content

Phase 7 Implementation Guide - Quality Gates, Feature Catalog, and Documentation Maturity

Phase: Phase 7 (Quality amplification and documentation maturity)
Estimated Duration: 18-26 hours (4-6 hours/week assuming 3-5 weeks)
Status: Complete
Last Updated: 2026-02-06

Purpose​

Phase 7 captures the work completed after Phase 6 governance to expand testing depth, formalize feature documentation, and tighten CI quality gates. This phase documents the changes across portfolio-app and portfolio-docs from the Phase 6 baseline commits and consolidates the outcomes into a reviewable summary.

What Phase 7 Delivers​

  • Testing depth expansion: New unit and integration coverage across app pages, components, data, and API endpoints.
  • Feature catalog documentation: A structured feature catalog with narrative coverage of core experience, content model, navigation, theming, SEO, security, testing, CI/CD, performance, and docs governance.
  • Documentation standards: Commentary standards, examples, and improved guidance for testing and verification.
  • Security and hardening updates: Security hardening implementation guidance, controls, and ADRs.
  • CI quality gates: Updated documentation and scripts that reflect stronger verification expectations.

Prerequisites​

Before starting Phase 7, ensure:

  • ✅ Phase 6 complete and verified
  • ✅ Portfolio docs baseline at commit 4a533309981eaa93099433cf5f4c4c5f79e8b85e
  • ✅ Portfolio app baseline at commit 9c34e42e6855c40f408d9eabeae59d628a0f2e7a

Verification checklist:

# From portfolio-app
pnpm verify

# From portfolio-docs
pnpm verify

Implementation Overview​

Sequential Steps (used for Phase 7)​

Phase 7 is best represented as sequential steps because the documentation additions and CI/testing updates build on one another and should be reviewed together.

APPROACH A: Sequential Steps Implementation​

STEP 1: Security hardening documentation and controls (5-7 hours)​

Goal: Capture security hardening work in docs, ADRs, and runbooks.

Scope:

  • ✅ In scope: security hardening implementation guidance, control documentation, ADRs
  • ❌ Out of scope: new product features in portfolio-app

Key changes:

  • Added ADRs for React2Shell hardening baseline and portfolio docs hardening baseline.
  • Added a security hardening implementation guide and expanded security controls coverage.
  • Updated risk register and security policies to align with the hardening scope.

Files to create/modify (portfolio-docs):

  • docs/10-architecture/adr/adr-0018-react2shell-hardening-baseline.md (new)
  • docs/10-architecture/adr/adr-0019-portfolio-docs-hardening-baseline.md (new)
  • docs/40-security/react2shell-hardening-implementation-guide.md (new)
  • docs/40-security/portfolio-docs-hardening-implementation-plan.md (new)
  • docs/40-security/security-policies.md (update)
  • docs/40-security/risk-register.md (update)

Success check:

  • Hardening ADRs published and linked from ADR index
  • Security hardening implementation guide published
  • Security controls documentation updated

STEP 2: Feature catalog and commentary standards (5-7 hours)​

Goal: Formalize the portfolio feature catalog and documentation commentary standard.

Scope:

  • ✅ In scope: portfolio feature catalog, commentary standard, commentary examples
  • ❌ Out of scope: roadmap changes or governance policy updates

Key changes:

  • Added a structured feature catalog under docs/00-portfolio/features/ with detailed coverage by feature domain.
  • Added a commentary standard and examples to align review writing with evidence expectations.

Files to create/modify (portfolio-docs):

  • docs/00-portfolio/features/index.md (new)
  • docs/00-portfolio/features/* (new catalogs for journey, content model, UX polish, theming, SEO, security, testing, CI/CD, performance, docs governance)
  • docs/20-engineering/commentary-standard.md (new)
  • docs/70-reference/commentary-examples.md (new)

Success check:

  • Feature catalog published and indexed
  • Commentary standard and examples published
  • Portfolio hubs updated to reference feature catalog

STEP 3: Testing guidance and CI quality gates (4-6 hours)​

Goal: Update testing guidance, verification scripts, and CI pipeline documentation.

Scope:

  • ✅ In scope: docs verification updates, CI gate documentation, testing guide improvements
  • ❌ Out of scope: product code changes in portfolio-app

Key changes:

  • Expanded CI documentation and testing guidance for verification steps.
  • Added optional audit reporting in docs verification scripts.
  • Updated testing references in portfolio project dossiers and runbooks.

Files to create/modify (portfolio-docs):

  • docs/30-devops-platform/ci-cd-pipeline-overview.md (update)
  • docs/70-reference/testing-guide.md (update)
  • scripts/verify-docs-local.sh (update)
  • docs/50-operations/runbooks/rbk-portfolio-ci-triage.md (update)
  • docs/60-projects/portfolio-app/05-testing.md (update)

Success check:

  • Documentation reflects current CI gates and verification steps
  • Optional audit reporting documented
  • Runbook guidance aligns with updated CI expectations

STEP 4: Portfolio-app testing expansion and coverage gating (4-6 hours)​

Goal: Expand app test coverage and clarify testing expectations.

Scope:

  • ✅ In scope: new tests across app pages, components, API routes, data, and libs
  • ❌ Out of scope: new UI features or layout changes

Key changes:

  • Added tests for pages, routes, components, and data utilities.
  • Strengthened test setup and coverage expectations.
  • Updated documentation for test structure and CI gates.

Files to create/modify (portfolio-app):

  • src/app/__tests__/* (new tests)
  • src/components/__tests__/* (new tests)
  • src/lib/__tests__/* (expanded coverage)
  • src/test/setup.ts (new setup)
  • vitest.config.ts (update)
  • package.json (update)

Success check:

  • Expanded test suite covers key routes, components, and utilities
  • Coverage and CI gate expectations documented
  • pnpm verify passes in portfolio-app

Implementation Checklist​

Pre-Implementation​

  • Phase 6 verified and on main branch
  • Baseline commits recorded for app and docs
  • Scope agreed for Phase 7 documentation and testing updates

Step 1 Checklist​

  • Publish security hardening ADRs
  • Publish hardening implementation guides
  • Update security policies and risk register

Step 2 Checklist​

  • Publish portfolio feature catalog
  • Publish commentary standard and examples
  • Update portfolio hubs and references

Step 3 Checklist​

  • Update CI and testing documentation
  • Enhance verification script guidance
  • Align runbooks with CI gates

Step 4 Checklist​

  • Expand portfolio-app test coverage
  • Update test setup and config
  • Verify pnpm verify passes

Post-Implementation​

  • All PRs merged to main
  • CI checks passing
  • Documentation and release notes updated
  • Phase 7 summary captured for reviewers

Timeline & Resource Estimate​

Step/StageTaskDurationStatusNotes
1Security hardening documentation5-7hComplete—
2Feature catalog + commentary standard5-7hComplete—
3Testing guidance + CI gates documentation4-6hComplete—
4Portfolio-app test coverage expansion4-6hComplete—
TotalPhase 7 Complete18-26hComplete—

Resource allocation:

  • Personnel: Docs and app owner(s): 4-6 hours/week
  • Dependencies: CI checks in both repos
  • Risk factors: Test suite growth impacting CI duration

Success Criteria​

Phase 7 is complete when:

  • ✅ Feature catalog and commentary standards are published
  • ✅ Security hardening guidance and ADRs are recorded
  • ✅ Testing guidance reflects updated CI and verification steps
  • ✅ Portfolio-app test coverage materially expanded
  • ✅ All tests pass locally: pnpm verify
  • ✅ All CI checks pass on main

Acceptance Criteria (Reviewability)​

A reviewer can validate Phase 7 completion through:

  • Viewing the feature catalog and commentary standard in docs
  • Reviewing ADRs for security hardening baselines
  • Confirming CI/testing documentation updates
  • Running pnpm verify in both repos to confirm gates pass