From f04aaee94c0fd4d056b91a568777290416f4f8fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Thu, 21 May 2026 11:12:58 -0700 Subject: [PATCH 1/6] chore: remove showcase from root validation scripts --- package.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index cda5d7f..ec1c08e 100644 --- a/package.json +++ b/package.json @@ -3,10 +3,10 @@ "private": true, "scripts": { "postinstall": "npm run bootstrap", - "bootstrap": "npm --prefix dashboard/app install && npm --prefix showcase/app install", - "build": "npm --prefix dashboard/app run build && npm --prefix showcase/app run build", - "typecheck": "npm --prefix dashboard/app run typecheck && npm --prefix showcase/app run typecheck", - "validate": "npm --prefix showcase/app run validate", + "bootstrap": "npm --prefix dashboard/app install", + "build": "npm --prefix dashboard/app run build", + "typecheck": "npm --prefix dashboard/app run typecheck", + "validate": "npm --prefix dashboard/app run smoke:release-health", "test": "pytest", "test:core": "pytest tests/test_core_foundation_ts.py -q", "test:replay": "pytest tests/test_paper_replay_bench.py tests/test_agent_trace_replay.py tests/test_replay_continuity.py -q", From adc09f31d145f08aa3218ca6013e4b2c7fb29a39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Thu, 21 May 2026 11:13:17 -0700 Subject: [PATCH 2/6] ci: remove showcase validation pipeline --- .github/workflows/ci.yml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1b2d4ab..3871403 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -24,10 +24,8 @@ jobs: - name: Install Python dependencies run: python -m pip install -e ".[test]" - - name: Install Node dependencies - run: | - npm --prefix dashboard/app ci - npm --prefix showcase/app ci + - name: Install dashboard dependencies + run: npm --prefix dashboard/app ci - name: Canonical Check run: npm run check From 89a260ee70002d846bd6a06a60c37ee448e398f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Thu, 21 May 2026 11:13:39 -0700 Subject: [PATCH 3/6] ci: decouple showcase from agent checks --- .github/workflows/agent-checks.yml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/.github/workflows/agent-checks.yml b/.github/workflows/agent-checks.yml index f5ff4f5..4b42662 100644 --- a/.github/workflows/agent-checks.yml +++ b/.github/workflows/agent-checks.yml @@ -62,10 +62,8 @@ jobs: with: node-version: '22' - - name: Install dependencies - run: | - npm --prefix dashboard/app ci - npm --prefix showcase/app ci + - name: Install dashboard dependencies + run: npm --prefix dashboard/app ci - name: Typecheck run: npm run typecheck From 1c15a1e47ad0ad59446a556a6a1e9f17133d7f22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Thu, 21 May 2026 11:14:49 -0700 Subject: [PATCH 4/6] docs: document dashboard-only validation flow --- docs/validation.md | 47 ++++++++++++++++++---------------------------- 1 file changed, 18 insertions(+), 29 deletions(-) diff --git a/docs/validation.md b/docs/validation.md index 9f6b2cb..4a71b57 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -1,8 +1,8 @@ # Validation Guide -This repository intentionally has multiple validation surfaces. You can use the -root npm wrapper commands for broad reviewer-friendly validation, or use direct -app commands when you only need to validate one app. +This repository intentionally has multiple validation surfaces. Use the root npm +wrapper commands for broad reviewer-friendly validation, or use direct dashboard +commands when only the dashboard application is affected. ## Repository layout @@ -10,7 +10,6 @@ app commands when you only need to validate one app. Comptextv7/ ├── package.json # Root command wrapper only; no root dependencies ├── dashboard/app/ # Vite + TypeScript dashboard application -├── showcase/app/ # Vite + TypeScript showcase application ├── tests/ # Python regression, replay, and foundation tests ├── scripts/ # Python validation and repository utility scripts ├── artifacts/ # Committed deterministic replay artifacts @@ -19,11 +18,15 @@ Comptextv7/ The repository root contains a minimal `package.json` wrapper for reviewer convenience. It does not define workspaces, dependencies, or a root Node app. -Dashboard and showcase remain the real Node applications, with their dependency -management in `dashboard/app` and `showcase/app`. +The dashboard remains the only Node application in this repository, with its +dependency management in `dashboard/app`. -Root npm scripts use `npm --prefix` to delegate to the app directories and use -`pytest` for Python validation. No root `node_modules` directory or root npm +The embedded showcase was removed from Comptextv7 and is maintained separately +in `ProfRandom92/comptext-v7-monaco-showcase`. Historical Comptextv7 showcase +files are preserved on the `archive/showcase-before-extraction` branch. + +Root npm scripts use `npm --prefix` to delegate to the dashboard directory and +use `pytest` for Python validation. No root `node_modules` directory or root npm dependencies are required for the wrapper itself. ## Root wrapper commands @@ -42,11 +45,11 @@ npm run check The root wrapper delegates as follows: - `npm run layout` runs `python scripts/check_repo_layout.py`. -- `npm run typecheck` runs dashboard and showcase typechecks with +- `npm run typecheck` runs the dashboard typecheck with `npm --prefix`. +- `npm run validate` runs the dashboard release-health smoke test with `npm --prefix`. -- `npm run validate` runs showcase static validation with `npm --prefix`. -- `npm run build` runs dashboard and showcase builds with `npm --prefix`. -- `npm test` runs `pytest -q`. +- `npm run build` runs the dashboard build with `npm --prefix`. +- `npm test` runs `pytest`. - `npm run check` chains layout, typecheck, validate, build, and Python tests. ## Dashboard app validation @@ -58,25 +61,11 @@ changes: cd dashboard/app npm run typecheck npm run build +npm run smoke:release-health ``` -Use these commands for core dashboard TypeScript changes, including the -`dashboard/app/src/core/foundation/` modules. - -## Showcase app validation - -Run showcase validation directly from `showcase/app` for targeted showcase -changes: - -```bash -cd showcase/app -npm run typecheck -npm run validate -npm run build -``` - -Use these commands for showcase TypeScript, static validation, and Vite build -checks. +Use these commands for dashboard TypeScript changes, release-health UI changes, +and `dashboard/app/src/core/foundation/` modules. ## Python validation from the repository root From d714f757b19b13283182dbe63ec533576ec7bc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Thu, 21 May 2026 11:15:27 -0700 Subject: [PATCH 5/6] docs: remove embedded showcase workflow references --- docs/AGENT_WORKFLOW.md | 159 +++++++---------------------------------- 1 file changed, 25 insertions(+), 134 deletions(-) diff --git a/docs/AGENT_WORKFLOW.md b/docs/AGENT_WORKFLOW.md index fc60fd6..783cfb1 100644 --- a/docs/AGENT_WORKFLOW.md +++ b/docs/AGENT_WORKFLOW.md @@ -40,86 +40,46 @@ git checkout -b agent/benchmark-integration-docs If a local clone does not have a `main` branch or remote, note that limitation in the final response and still ensure work happens on the requested feature branch. +## Repository structure note + +Comptextv7 no longer embeds the Monaco showcase application. The showcase is +maintained separately in `ProfRandom92/comptext-v7-monaco-showcase`. + +The historical embedded showcase state remains preserved on the +`archive/showcase-before-extraction` branch for recovery or forensic review. ## Safe workflow helper scripts -Use the new deterministic helper scripts before making or reviewing agent-authored +Use the deterministic helper scripts before making or reviewing agent-authored changes: -1. Run `python scripts/repo_intake.py` as the first safe discovery step. It - records repository structure, project files, tests, workflows, and likely - API/dashboard/report areas in `docs/reports/repo-intake-report.md` without - reading sensitive payloads or requiring network access. +1. Run `python scripts/repo_intake.py` as the first safe discovery step. 2. Use the commands in [`docs/validation.md`](validation.md) as the local - validation step. Use root wrapper commands for broad validation, or - app-specific commands from `dashboard/app` and `showcase/app` for targeted - validation. + validation step. 3. Run `python scripts/generate_contract_fixtures.py` when API/dashboard/export - contracts are touched. It regenerates - `contracts/examples/api-dashboard.example.json` and writes - `docs/reports/contract-fixture-generation-report.md` using deterministic - synthetic values only. -4. Run `python scripts/validate_api_exports.py` to validate the generated - API/dashboard/export fixture against `contracts/api-dashboard.schema.json`. It - writes `docs/reports/api-export-validation-report.md` and requires no live - server. -5. Run `python scripts/generate_project_health_report.py` before release-readiness - review or cross-repo promotion review. It writes - `docs/reports/project-health-report.md` as a deterministic snapshot of agent - workflow readiness, contract/API validation surfaces, existing reports, and - promotion checklist status without reading raw payload contents. -6. Run `python scripts/generate_dashboard_health_summary.py` after the local - reports are current. It writes `docs/reports/dashboard-health-summary.md` and - `docs/reports/dashboard-health-summary.json` as compact dashboard-facing - release-readiness artifacts from file-existence and simple metadata checks. -7. Let `.github/workflows/agent-checks.yml` provide the PR CI guardrail by - compiling the helper scripts, regenerating intake evidence, generating - contract fixtures, validating API/export payload shapes, generating the - project health report, generating the dashboard health summary, and running - the same safe checks on Python 3.11. + contracts are touched. +4. Run `python scripts/validate_api_exports.py` to validate generated export + fixtures against `contracts/api-dashboard.schema.json`. +5. Run `python scripts/generate_project_health_report.py` before + release-readiness review or cross-repo promotion review. +6. Run `python scripts/generate_dashboard_health_summary.py` after local reports + are current. +7. Let `.github/workflows/agent-checks.yml` provide the CI guardrail for helper + script compilation, report generation, validation, and dashboard smoke tests. These checks complement benchmark, regression, sanitization, and forensic replay reports from `ProfRandom92/Comptext-Daimler-Experiment-`. They do not replace -benchmark review and do not introduce runtime coupling between repositories. Use -only sanitized summaries or synthetic examples when connecting those reports to -Comptextv7 PR evidence. Future dashboard/UI work should consume -`docs/reports/dashboard-health-summary.json` as a static status source for -release-readiness cards, missing-artifact lists, and safety notes instead of -requiring a live server, network access, or real Daimler data. +benchmark review and do not introduce runtime coupling between repositories. ## Cross-repo promotion gate Use `docs/CROSS_REPO_RELEASE_CHECKLIST.md` after experiment validation and before -creating a Comptextv7 implementation PR. The checklist is the practical release -gate for deciding whether an experiment result is safe to promote through this -flow: - -```text -experiment result -> review -> Comptextv7 issue/PR -> validation -> release -``` - -Agents should apply the checklist when a benchmark, regression, sanitization, or -forensic replay finding from `ProfRandom92/Comptext-Daimler-Experiment-` might -change Comptextv7 runtime behavior, API/dashboard contracts, exports, validation -logic, or release documentation. If the checklist produces a no-go decision, -create or update an issue with sanitized evidence instead of opening an -implementation PR. - -The checklist fits between the experiment repository's validation evidence and -Comptextv7 implementation work: first confirm the experiment artifacts and -contract validation, then make the go/no-go decision, and only then open a small, -reversible Comptextv7 PR with the required local validation results. +creating a Comptextv7 implementation PR. ## How to consume experiment repo reports -Agents may use these sanitized report types as review inputs: - -| Input | How to use it in Comptextv7 | -| --- | --- | -| Benchmark report | Compare p50, p95, p99, RPS, error rate, and payload size for affected dashboard/API routes. | -| Regression summary | Decide whether a PR needs remediation, a smaller scope, or explicit reviewer acceptance. | -| Sanitization report | Confirm no secrets, tokens, cookies, real Daimler/customer payloads, raw production logs, or proprietary documents are included. | -| Forensic replay notes | Create follow-up fixes for determinism, semantic retention, sparse anomalies, export shape, or dashboard evidence display. | +Agents may use sanitized benchmark, regression, sanitization, and forensic +reports as review evidence for dashboard/API/runtime changes. Agents should summarize findings in PR bodies or documentation. They should not copy raw experiment payloads, raw logs, proprietary documents, or sensitive @@ -146,8 +106,7 @@ Never commit: - Real Daimler payloads or customer data. - Raw production logs. - Proprietary documents or unreleased vendor material. -- Unsanitized VIN/FIN, account, employee, plant, vehicle, or workshop - identifiers. +- Unsanitized identifiers. - Large opaque binary artifacts from benchmark tools. Prefer: @@ -155,73 +114,5 @@ Prefer: - Synthetic examples. - Sanitized summaries. - Small Markdown/JSON/CSV contracts. -- Explicit `synthetic: true` flags in examples, including - `contracts/examples/api-dashboard.example.json`. +- Explicit `synthetic: true` flags in examples. - Redacted finding IDs and endpoint names. - -## Review checklist - -Before opening a Comptextv7 PR, agents should verify: - -- [ ] Branch is a feature branch and PR targets `main`. -- [ ] The change does not introduce runtime coupling to the experiment - repository unless explicitly approved. -- [ ] New examples are synthetic. -- [ ] No secrets, cookies, tokens, real Daimler data, customer data, raw logs, or - proprietary documents are committed. -- [ ] Benchmark-sensitive routes are called out when affected. -- [ ] p50, p95, p99, RPS, error rate, and payload size are reviewed when - performance-sensitive code changes. -- [ ] Regression summaries are reviewed before merging dashboard/API or export - changes. -- [ ] Forensic replay notes are converted into actionable fixes or follow-up - issues. -- [ ] Tests or validation steps are documented, or the PR states why no code - execution was required. -- [ ] Release-readiness changes run `python scripts/generate_dashboard_health_summary.py` - and update `docs/reports/dashboard-health-summary.md` plus - `docs/reports/dashboard-health-summary.json` when generated. -- [ ] API/dashboard/export changes run `python scripts/generate_contract_fixtures.py` - and `python scripts/validate_api_exports.py`, with reports checked in under - `docs/reports/contract-fixture-generation-report.md` and - `docs/reports/api-export-validation-report.md` when generated. - -## Synthetic PR evidence example - -```markdown -## Benchmark evidence - -- source_repo: ProfRandom92/Comptext-Daimler-Experiment- -- target_repo: ProfRandom92/Comptextv7 -- report_type: regression_summary -- synthetic: true -- affected_surface: /export.json -- p95_ms_delta: +4 -- p99_ms_delta: +9 -- rps_delta: -1.2 -- error_rate_delta: 0.0 -- payload_size_bytes_delta: +128 -- status: review -- notes: Synthetic example only; no real Daimler data included. -``` - -## Deciding repository ownership - -Use this rule of thumb: - -- If the change affects Comptextv7 users, dashboard/API surfaces, runtime - behavior, validation gates, documentation, or exported report contracts, it - belongs in Comptextv7. -- If the change affects benchmark workload generation, experiment-only scripts, - experiment report production, or exploratory forensic scenarios, it belongs in - `ProfRandom92/Comptext-Daimler-Experiment-`. -- If both repositories are affected, split the work into two PRs and keep the - handoff contract small and sanitized. - -## Next recommended PRs - -1. Add a versioned JSON Schema for synthetic benchmark summaries. -2. Add a versioned JSON Schema for regression and sanitization summaries. -3. Add optional local import of sanitized summary files, disabled by default. -4. Add dashboard trend cards for p50/p95/p99 and payload-size deltas. -5. Add PR checklist entries for benchmark-sensitive route review. From ef86fa09a8824ec81c9e7cdfa92ffcad0fe21c9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6lnberger?= <159939812+ProfRandom92@users.noreply.github.com> Date: Thu, 21 May 2026 11:21:24 -0700 Subject: [PATCH 6/6] docs: restore complete agent workflow guidance --- docs/AGENT_WORKFLOW.md | 180 +++++++++++++++++++++++++++++++++++------ 1 file changed, 154 insertions(+), 26 deletions(-) diff --git a/docs/AGENT_WORKFLOW.md b/docs/AGENT_WORKFLOW.md index 783cfb1..a70e6cd 100644 --- a/docs/AGENT_WORKFLOW.md +++ b/docs/AGENT_WORKFLOW.md @@ -11,6 +11,14 @@ The default integration approach is documentation-first, lightweight, and safe. Agents should use synthetic examples only unless a human explicitly provides a sanitized artifact for review. +## Repository structure note + +Comptextv7 no longer embeds the Monaco showcase application. The showcase is +maintained separately in `ProfRandom92/comptext-v7-monaco-showcase`. + +The historical embedded showcase state remains preserved on the +`archive/showcase-before-extraction` branch for recovery or forensic review. + ## Agent roles | Agent work type | Belongs in Comptextv7 | Belongs in Comptext-Daimler-Experiment- | @@ -20,6 +28,7 @@ sanitized artifact for review. | Report contract documentation | Yes. | Yes, when documenting producer-side details. | | Sanitization policy | Yes for consumer/review expectations. | Yes for producer-side sanitization implementation. | | Forensic replay findings | Yes when they require runtime, parser, dashboard, export, or validation fixes. | Yes when they require experiment scenario changes. | +| Monaco showcase/UI demo work | No. It belongs in `ProfRandom92/comptext-v7-monaco-showcase`. | No, unless only experiment evidence changes. | ## Safe branch workflow @@ -40,46 +49,85 @@ git checkout -b agent/benchmark-integration-docs If a local clone does not have a `main` branch or remote, note that limitation in the final response and still ensure work happens on the requested feature branch. -## Repository structure note - -Comptextv7 no longer embeds the Monaco showcase application. The showcase is -maintained separately in `ProfRandom92/comptext-v7-monaco-showcase`. - -The historical embedded showcase state remains preserved on the -`archive/showcase-before-extraction` branch for recovery or forensic review. - ## Safe workflow helper scripts Use the deterministic helper scripts before making or reviewing agent-authored changes: -1. Run `python scripts/repo_intake.py` as the first safe discovery step. +1. Run `python scripts/repo_intake.py` as the first safe discovery step. It + records repository structure, project files, tests, workflows, and likely + API/dashboard/report areas in `docs/reports/repo-intake-report.md` without + reading sensitive payloads or requiring network access. 2. Use the commands in [`docs/validation.md`](validation.md) as the local - validation step. + validation step. Use root wrapper commands for broad validation, or direct + commands from `dashboard/app` for targeted dashboard validation. 3. Run `python scripts/generate_contract_fixtures.py` when API/dashboard/export - contracts are touched. -4. Run `python scripts/validate_api_exports.py` to validate generated export - fixtures against `contracts/api-dashboard.schema.json`. -5. Run `python scripts/generate_project_health_report.py` before - release-readiness review or cross-repo promotion review. -6. Run `python scripts/generate_dashboard_health_summary.py` after local reports - are current. -7. Let `.github/workflows/agent-checks.yml` provide the CI guardrail for helper - script compilation, report generation, validation, and dashboard smoke tests. + contracts are touched. It regenerates + `contracts/examples/api-dashboard.example.json` and writes + `docs/reports/contract-fixture-generation-report.md` using deterministic + synthetic values only. +4. Run `python scripts/validate_api_exports.py` to validate the generated + API/dashboard/export fixture against `contracts/api-dashboard.schema.json`. It + writes `docs/reports/api-export-validation-report.md` and requires no live + server. +5. Run `python scripts/generate_project_health_report.py` before release-readiness + review or cross-repo promotion review. It writes + `docs/reports/project-health-report.md` as a deterministic snapshot of agent + workflow readiness, contract/API validation surfaces, existing reports, and + promotion checklist status without reading raw payload contents. +6. Run `python scripts/generate_dashboard_health_summary.py` after the local + reports are current. It writes `docs/reports/dashboard-health-summary.md` and + `docs/reports/dashboard-health-summary.json` as compact dashboard-facing + release-readiness artifacts from file-existence and simple metadata checks. +7. Let `.github/workflows/agent-checks.yml` provide the PR CI guardrail by + compiling the helper scripts, regenerating intake evidence, generating + contract fixtures, validating API/export payload shapes, generating the + project health report, generating the dashboard health summary, running the + same safe Python checks, and running dashboard validation on Python 3.11 and + Node.js 22. These checks complement benchmark, regression, sanitization, and forensic replay reports from `ProfRandom92/Comptext-Daimler-Experiment-`. They do not replace -benchmark review and do not introduce runtime coupling between repositories. +benchmark review and do not introduce runtime coupling between repositories. Use +only sanitized summaries or synthetic examples when connecting those reports to +Comptextv7 PR evidence. Dashboard/UI work should consume +`docs/reports/dashboard-health-summary.json` as a static status source for +release-readiness cards, missing-artifact lists, and safety notes instead of +requiring a live server, network access, or real Daimler data. ## Cross-repo promotion gate Use `docs/CROSS_REPO_RELEASE_CHECKLIST.md` after experiment validation and before -creating a Comptextv7 implementation PR. +creating a Comptextv7 implementation PR. The checklist is the practical release +gate for deciding whether an experiment result is safe to promote through this +flow: + +```text +experiment result -> review -> Comptextv7 issue/PR -> validation -> release +``` + +Agents should apply the checklist when a benchmark, regression, sanitization, or +forensic replay finding from `ProfRandom92/Comptext-Daimler-Experiment-` might +change Comptextv7 runtime behavior, API/dashboard contracts, exports, validation +logic, or release documentation. If the checklist produces a no-go decision, +create or update an issue with sanitized evidence instead of opening an +implementation PR. + +The checklist fits between the experiment repository's validation evidence and +Comptextv7 implementation work: first confirm the experiment artifacts and +contract validation, then make the go/no-go decision, and only then open a small, +reversible Comptextv7 PR with the required local validation results. ## How to consume experiment repo reports -Agents may use sanitized benchmark, regression, sanitization, and forensic -reports as review evidence for dashboard/API/runtime changes. +Agents may use these sanitized report types as review inputs: + +| Input | How to use it in Comptextv7 | +| --- | --- | +| Benchmark report | Compare p50, p95, p99, RPS, error rate, and payload size for affected dashboard/API routes. | +| Regression summary | Decide whether a PR needs remediation, a smaller scope, or explicit reviewer acceptance. | +| Sanitization report | Confirm no secrets, tokens, cookies, real Daimler/customer payloads, raw production logs, or proprietary documents are included. | +| Forensic replay notes | Create follow-up fixes for determinism, semantic retention, sparse anomalies, export shape, or dashboard evidence display. | Agents should summarize findings in PR bodies or documentation. They should not copy raw experiment payloads, raw logs, proprietary documents, or sensitive @@ -94,9 +142,11 @@ Prefer one narrow purpose per PR: - API/export schema-version addition. - Validation or replay fix tied to a specific forensic finding. - Follow-up issue creation for larger automation. +- Showcase-only demo updates in `ProfRandom92/comptext-v7-monaco-showcase`, not in Comptextv7. Avoid mixing benchmark integration docs with unrelated runtime refactors, -dependency upgrades, dashboard redesigns, or fixture changes. +dependency upgrades, dashboard redesigns, fixture changes, or showcase migration +work. ## Security constraints @@ -106,7 +156,7 @@ Never commit: - Real Daimler payloads or customer data. - Raw production logs. - Proprietary documents or unreleased vendor material. -- Unsanitized identifiers. +- Unsanitized VIN/FIN, account, employee, plant, vehicle, or workshop identifiers. - Large opaque binary artifacts from benchmark tools. Prefer: @@ -114,5 +164,83 @@ Prefer: - Synthetic examples. - Sanitized summaries. - Small Markdown/JSON/CSV contracts. -- Explicit `synthetic: true` flags in examples. +- Explicit `synthetic: true` flags in examples, including + `contracts/examples/api-dashboard.example.json`. - Redacted finding IDs and endpoint names. + +## Review checklist + +Before opening or updating a Comptextv7 PR, agents should verify: + +- [ ] Branch is a feature branch and PR targets `main`. +- [ ] The change does not introduce runtime coupling to the experiment + repository unless explicitly approved. +- [ ] New examples are synthetic. +- [ ] No secrets, cookies, tokens, real Daimler data, customer data, raw logs, or + proprietary documents are committed. +- [ ] Unsanitized VIN/FIN, account, employee, plant, vehicle, or workshop + identifiers are not committed. +- [ ] Benchmark-sensitive routes are called out when affected. +- [ ] p50, p95, p99, RPS, error rate, and payload size are reviewed when + performance-sensitive code changes. +- [ ] Regression summaries are reviewed before merging dashboard/API or export + changes. +- [ ] Forensic replay notes are converted into actionable fixes or follow-up + issues. +- [ ] Tests or validation steps are documented, or the PR states why no code + execution was required. +- [ ] Release-readiness changes run `python scripts/generate_dashboard_health_summary.py` + and update `docs/reports/dashboard-health-summary.md` plus + `docs/reports/dashboard-health-summary.json` when generated. +- [ ] API/dashboard/export changes run `python scripts/generate_contract_fixtures.py` + and `python scripts/validate_api_exports.py`, with reports checked in under + `docs/reports/contract-fixture-generation-report.md` and + `docs/reports/api-export-validation-report.md` when generated. +- [ ] Monaco showcase-only work is routed to + `ProfRandom92/comptext-v7-monaco-showcase` instead of Comptextv7. + +## Synthetic PR evidence example + +```markdown +## Benchmark evidence + +- source_repo: ProfRandom92/Comptext-Daimler-Experiment- +- target_repo: ProfRandom92/Comptextv7 +- report_type: regression_summary +- synthetic: true +- affected_surface: /export.json +- p95_ms_delta: +4 +- p99_ms_delta: +9 +- rps_delta: -1.2 +- error_rate_delta: 0.0 +- payload_size_bytes_delta: +128 +- status: review +- notes: Synthetic example only; no real Daimler data included. +``` + +## Deciding repository ownership + +Use this rule of thumb: + +- If the change affects Comptextv7 users, dashboard/API surfaces, runtime + behavior, validation gates, documentation, exported report contracts, or + release evidence, it belongs in Comptextv7. +- If the change affects benchmark workload generation, experiment-only scripts, + experiment report production, or exploratory forensic scenarios, it belongs in + `ProfRandom92/Comptext-Daimler-Experiment-`. +- If the change affects Monaco showcase UI, demo composition, Monaco editor + behavior, standalone showcase assets, or showcase deployment, it belongs in + `ProfRandom92/comptext-v7-monaco-showcase`. +- If multiple repositories are affected, split the work into small PRs and keep + the handoff contract sanitized, documented, and reversible. + +## Next recommended PRs + +After this cleanup, prefer follow-up PRs in this order: + +1. Remove the now-decoupled embedded showcase files from Comptextv7 once the full + file list can be handled safely. +2. Improve dashboard release-health UX using the existing static + `docs/reports/dashboard-health-summary.json` contract. +3. Keep dependency updates manual, scoped, and validated. Do not reintroduce + Dependabot automation.