# Webdev Agent OS v6 — Project Command and Continuous Improvement Engine ## Purpose Project Command turns Webdev Agent OS from a collection of powerful project tools into a persistent web-development operating department. It maintains an authoritative registry of websites and web applications, connects quality evidence to releases, detects deterioration, schedules fresh inspections, generates next actions, and produces portfolio-level reports. The command layer does not replace Project Intake, Generator, Inspector, Repair Loop, Audit, Release Gate, or Web Intelligence. It coordinates them across time and across projects. ## Operating loop **Register → Baseline → Release → Re-inspect → Compare → Alert → Improve → Verify → Learn** Every active project should have: - A responsible owner - A business outcome and primary success event - A deployable source location - A production or staging URL - An inspection cadence - Quality history - Release history and rollback information - Open alerts and next actions - Relevant Web Intelligence records ## Health states Project health is derived from the most recent quality snapshot, prior trend, finding severity, inspection freshness, and open alerts. | State | Meaning | |---|---| | Healthy | Score is at least 85, no critical defects, inspection is current, and no material alert remains open. | | Watch | Score is below 85, high-severity findings remain, an inspection is due, or a lower-level alert is open. | | At risk | Score is below 75, quality dropped at least five points, the inspection is materially overdue, or high-severity defects accumulated. | | Blocked | A blocker or critical defect exists, or the measured quality score is below 50. | | Unmeasured | No quality baseline exists. | | Archived | The project is retained for history but removed from active operating metrics. | Health is an operating signal, not an authorization to release. Production approval still belongs to the Release Gate and accountable owner. ## Deterioration detection Recording a new inspection compares it with the previous snapshot. The engine creates alerts when it detects: - Blocker or critical findings - Broken routes - A quality-score decline of five points or more - Five or more additional findings Recommended actions are generated from the same evidence. Examples include baseline inspection, overdue re-inspection, regression investigation, blocker repair, high-severity remediation, quality-recovery campaigns, post-release verification, owner assignment, source linkage, measurement definition, and intelligence capture. Completed actions remain in project history. The same deterministic action is not recreated after completion unless the underlying situation materially changes and a new action identity is warranted. ## Data model The persistent store is `config/portfolio-store.json`. A non-destructive example baseline is included at `config/portfolio-seed.json`. Primary records: - **Project** — identity, owner, status, architecture, URL, source, outcome, cadence, tags - **Quality snapshot** — score, classification, severity counts, route evidence, report location - **Release** — version, environment, owner, audit score, commit, notes, rollback path - **Alert** — type, severity, metric, difference, status, evidence summary - **Action** — priority, due date, status, source, completion date - **Campaign** — objective, target score, owner, dates, participating projects - **Activity** — append-only portfolio events for reporting and future analytics The formal schema is `config/portfolio-store.schema.json`. ## Control Center The **Project Command** workspace provides: - Portfolio metrics and attention counts - Search and health filtering - Project health selection - Quality trend visualization - Inspection freshness and release status - Deterioration alerts - Prioritized next actions with completion controls - Project ownership and outcome contract - Release-history recording - Project registration and updates - Improvement-campaign creation - Imported inspection recording - Live inspection launch for projects with a URL - JSON export and client-facing health reports The included seed records are examples. Replace or update them with real project information before treating the dashboard as an operational source of truth. ## Command line Portfolio statistics: ```bash npm run portfolio:stats ``` List projects: ```bash node scripts/portfolio-cli.js list --status at-risk ``` Show a project: ```bash node scripts/portfolio-cli.js show trip-inspection-portal ``` Register a project from JSON: ```bash node scripts/portfolio-cli.js register project.json ``` Record an Inspector report: ```bash node scripts/portfolio-cli.js inspection trip-inspection-portal reports/site/report.json ``` Record a release: ```bash node scripts/portfolio-cli.js release trip-inspection-portal release.json ``` Generate the portfolio report: ```bash npm run portfolio:report ``` The report produces HTML, JSON, and Markdown in `reports/portfolio-command/`. ## Scheduled re-inspection Preview the due queue without launching Chromium: ```bash npm run portfolio:due npm run portfolio:run-due -- --dry-run ``` Run every due active project that has a URL: ```bash npm run portfolio:run-due ``` Each run creates: ```text reports/scheduled-inspections// /report.html /report.json /report.md /backlog.json /screenshots/ portfolio-report/ scheduled-run.json ``` On Windows, use: ```text run-portfolio-inspections.bat ``` An optional installer creates a daily Windows Scheduled Task: ```powershell powershell -ExecutionPolicy Bypass -File scripts\install-portfolio-schedule.ps1 -DailyTime "02:00" ``` The installer changes the local Task Scheduler only when explicitly run. The package does not silently install or activate recurring work. ## HTTP API ### Read portfolio ```http GET /api/portfolio?q=roofing&status=at-risk GET /api/portfolio/stats GET /api/portfolio/due GET /api/portfolio/export GET /api/portfolio/projects/:projectId ``` ### Write portfolio ```http POST /api/portfolio/projects POST /api/portfolio/projects/:projectId/inspection POST /api/portfolio/projects/:projectId/release POST /api/portfolio/projects/:projectId/actions/:actionId POST /api/portfolio/campaigns ``` ### Launch an inspection ```http POST /api/portfolio/projects/:projectId/inspect GET /api/portfolio/inspect/:jobId ``` ### Generate report ```http POST /api/portfolio/report ``` ## Client-facing reporting The portfolio report intentionally excludes local source paths and internal patch details. It emphasizes: - Portfolio quality position - Project health - Inspection freshness - Release status - Ownership - Priority actions - Improvement campaigns It can be shared as an evidence summary, but it should not expose confidential project identifiers, vulnerabilities, customer data, or internal infrastructure without review. ## Continuous learning Project Command establishes the evidence timeline needed by Web Intelligence: - A release defines what changed and when. - The next inspection measures whether quality improved or deteriorated. - Business analytics can determine whether the primary success event improved. - Successful components and patterns can receive positive intelligence feedback. - Failed changes can lower confidence or become lessons and repair patterns. The engine keeps project history and intelligence evidence separate so confidence is not inflated automatically. A responsible operator should connect outcomes to the specific intelligence records that influenced the release. ## Safety and limitations - URLs and source directories must be added deliberately. - Scheduled inspection does not deploy, repair, or release code. - Automated health rules cannot understand every business risk. - A good score does not prove authorization, privacy compliance, content accuracy, or conversion performance. - Inspection cadence should reflect project risk; critical operational systems may need more frequent checks. - External monitoring, uptime checks, analytics, source control, CI/CD, backups, and incident management remain complementary systems. - Store files should be backed up and protected from unauthorized modification.