feat: living document freshness automation

[POWERFULMOVES]

Summary

• Living document freshness automation (docs-reconcile script, Make targets, skill command)
• Reconciled all P1 submodule findings as FIXED, closed 4 production-blocking P2 items
• Pinned exact CVE-patched versions in Dockerfiles (archon, deepresearch)
• Normalized AB-9 runner status across all dashboard references
• Added archival banner to BuildKit migration plan (implemented in PR fix(security): resolve 4 Dockerfile audit findings #838)
• Security fixes: Hi-RAG video_id validation, Chrome extension CodeQL alerts

Note: PMOVES-Archon submodule gitlink bump is intentional — it points to the Dockerfile fix commit (MCP_CONFIG_PATH rename + USER directive). This is a security fix, not scope creep.

Supersedes: #839 (closed), #840 (closed) — all commits from both PRs are included here.

CodeRabbit Resolution

All 7 findings from #839/#840 reviews addressed in fix(review) commit:

1. ✅ Dashboard "3 of 4" → "4 of 4" (all P2 items verified)
2. ✅ Runner status normalized to "0/4 offline" everywhere
3. ✅ Floating >= pins → exact == pins in Dockerfiles
4. ✅ Archon submodule bump explained (Dockerfile security fix)
5. ✅ P2 count "15 open" clarified as pre-triage snapshot
6. ✅ Ray/vLLM pinned exact in deepresearch Dockerfile
7. ✅ BuildKit migration plan marked as historical

Test plan

• grep -c "3 of 4" pmoves/docs/PRODUCTION_AUDIT_DASHBOARD.md → 0
• grep "1/4 self-hosted" pmoves/docs/PRODUCTION_AUDIT_DASHBOARD.md → no matches
• grep ">=0.8.0\|>=1.2.5\|>=2.52.0\|>=0.14.1" pmoves/services/*/Dockerfile → no matches
• Dockerfile validation CI passes for archon + deepresearch
• CodeRabbit re-review clean

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Rate limit exceeded

@POWERFULMOVES has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 23 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d587a6b1-ed73-4d6c-9b6f-f0d9261ee1d7

📥 Commits

Reviewing files that changed from the base of the PR and between e81f37d and e457473.

📒 Files selected for processing (13)

• .claude/CLAUDE.md
• .claude/commands/docs/reconcile.md
• docs/phase2-buildkit-secrets-migration-plan.md
• pmoves/Makefile
• pmoves/chrome-extension/options/options.js
• pmoves/chrome-extension/test/mock-server.js
• pmoves/docs/PRODUCTION_AUDIT_DASHBOARD.md
• pmoves/docs/security/P2_SUBMODULE_TRACKER.md
• pmoves/mk/preflight.mk
• pmoves/services/archon/Dockerfile
• pmoves/services/deepresearch/Dockerfile
• pmoves/services/pmoves-yt/yt.py
• pmoves/tools/docs_reconcile.py

📝 Walkthrough

Walkthrough

This pull request introduces a living document reconciliation framework consisting of new tooling, Make targets, and documentation standards. It also updates multiple Dockerfiles with environment variable renames and dependency additions, enhances Chrome extension rendering logic, improves git-based validation, and refreshes production audit dashboard and tracker metadata with reconciliation outcomes.

Changes

Cohort / File(s)	Summary
Living Document Framework .claude/CLAUDE.md, .claude/commands/docs/reconcile.md, pmoves/Makefile	Introduces Living Document Maintenance section documenting freshness rules and adds three new Make targets (docs-reconcile, docs-reconcile-check, docs-reconcile-json) for automated living document reconciliation. Updated Service Discovery Pattern to expose /metrics endpoint alongside /healthz.
Reconciliation Tool pmoves/tools/docs_reconcile.py	New Python tool implementing living document reconciliation with data models (DashboardMeta, TrackerItem, GitState, Finding, ReconcileReport), git state helpers, dashboard/tracker parsing, freshness and staleness checks, and CLI with --check, --update, and --json modes. Provides human-readable and JSON reporting with configurable thresholds.
Documentation & Metadata Updates pmoves/docs/PRODUCTION_AUDIT_DASHBOARD.md, pmoves/docs/security/P2_SUBMODULE_TRACKER.md, pmoves/mk/preflight.mk	Updated dashboard metadata (Last Updated, Commit) with reconciliation outcomes; expanded tracker findings enumeration across Phase C submodules (7 P1 items); reworked CI/QA visibility section; updated blocker narratives. Enhanced preflight static audit to run optional docs-reconcile-check step without failing build on failure.
Variable Renaming docs/phase2-buildkit-secrets-migration-plan.md, pmoves/services/archon/Dockerfile	Renamed build and runtime configuration variable from MCP_CREDENTIALS_PATH_* to MCP_CONFIG_PATH_* across Dockerfiles and documentation, standardizing nomenclature.
Dependency & Security Hardening pmoves/services/archon/Dockerfile, pmoves/services/deepresearch/Dockerfile, pmoves/images/firefly-iii/Dockerfile	Extended Archon Dockerfile with pip installations for crawl4ai and langchain-core with CVE override notes; added ray and vllm packages to DeepResearch; set firefly-iii container to run explicitly as www-data user for defense-in-depth hardening.
Chrome Extension & DOM Logic pmoves/chrome-extension/options/options.js, pmoves/chrome-extension/test/mock-server.js	Refactored diagnostics table rendering from HTML string concatenation to explicit DOM node creation (tr, td elements) with individual class and textContent assignment, removing escapeHtml dependency on detail field. Enhanced mock-server route handler lookup with Object.hasOwn checks for robustness.
Data Validation pmoves/services/pmoves-yt/yt.py	Added regex validation check (_SAFE_VID_RE) in yt_search to skip malformed or unsafe video IDs before processing, preventing downstream issues with invalid identifiers.
Submodule Updates PMOVES-Archon, PMOVES-llama-throughput-lab	Updated submodule commit references: Archon (178ebb9e → dd2f2ed1) and llama-throughput-lab (213a6822 → 823922fa).

Sequence Diagram

sequenceDiagram
    actor CLI as CLI (main)
    participant Repo as Repository
    participant Parser as Parser
    participant Checker as Freshness Checker
    participant Writer as Dashboard Writer
    participant Report as Report Generator

    CLI->>Repo: git branch, rev-list, log
    Repo-->>CLI: Git state (SHA, date, commits_behind)
    
    CLI->>Parser: parse_dashboard_metadata()
    Parser-->>CLI: DashboardMeta (commit, date, branch)
    
    CLI->>Parser: parse_tracker_items()
    Parser-->>CLI: List[TrackerItem]
    
    CLI->>Parser: get_submodule_status()
    Parser->>Repo: git config --file .gitmodules
    Repo-->>Parser: Submodule SHAs
    Parser-->>CLI: Dict[submodule, SHA]
    
    CLI->>Checker: check_freshness(meta, git_state)
    Checker-->>CLI: List[Finding] (stale_commit, stale_date)
    
    CLI->>Checker: check_tracker_staleness(items, submodules)
    Checker-->>CLI: List[Finding] (tracker issues)
    
    alt --update mode
        CLI->>Writer: reconcile_dashboard(git_state)
        Writer->>Repo: Write updated metadata
        Repo-->>Writer: Diff
        Writer-->>CLI: Diff or None
    end
    
    CLI->>Report: print_report(ReconcileReport)
    Report-->>CLI: Human-readable or JSON output
    CLI-->>CLI: Exit code (0=fresh, 1=stale, 2=error)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• #824: Overlapping updates to PRODUCTION_AUDIT_DASHBOARD.md and living-document metadata refreshes.
• #836: Concurrent documentation updates to Production Audit Dashboard and P2 Submodule Tracker files with reconciliation narrative changes.
• #711: Prior introduction of living-document maintenance concepts and dashboard metadata concerns that this PR implements tooling for.

Suggested labels

codex

Poem

🐰 A rabbit hops through documents of old,
Checking if their tales have grown too cold,
With docs_reconcile in paw so bright,
Living docs stay fresh and up-to-date right,
Automation keeps the dashboards in flight! ✨

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description covers the core functionality and test results but is missing the required Testing section with commands/output and some Review Coordination checkboxes.	Add a Testing section documenting the commands run and their output, and complete the Required Checks and Review Coordination checklists.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding automation for checking and updating living document freshness metadata.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/docs-reconcile-automation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Docker Hardening Validation

Hardening Validation Report

Validated: Mon Mar 9 20:36:44 UTC 2026

Services Checked

PMOVES.AI Docker Hardening Validation

[INFO] Checking: pmoves/docker-compose.hardened.yml

[INFO] Validating: hi-rag-gateway-v2
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: extract-worker
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: langextract
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: presign
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: render-webhook
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: retrieval-eval
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: pdf-ingest
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: jellyfin-bridge
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: invidious-companion-proxy
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: ffmpeg-whisper
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: media-video
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: media-audio
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: hi-rag-gateway-v2-gpu
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: hi-rag-gateway-gpu
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: deepresearch
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: supaserch
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: publisher-discord
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: mesh-agent
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: nats-echo-req
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: nats-echo-res
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: publisher
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: analysis-echo
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: graph-linker
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: comfy-watcher
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: grayjay-plugin-host
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: agent-zero
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: archon
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: channel-monitor
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: pmoves-yt
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: notebook-sync
[PASS] Non-root user: 65532:65532
[PASS] Read-only filesystem
[PASS] All capabilities dropped
[PASS] No-new-privileges enabled
[WARN] No resource limits

[INFO] Validating: supabase_service_role_key
[WARN] No user directive
[WARN] No read_only directive
[WARN] No cap_drop: ["ALL"]
[WARN] No no-new-privileges
[WARN] No resource limits

[INFO] Validating: supabase_jwt_secret
[WARN] No user directive
[WARN] No read_only directive
[WARN] No cap_drop: ["ALL"]
[WARN] No no-new-privileges
[WARN] No resource limits

======================================
Summary: 120 passed, 40 warnings, 0 errors