Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions .github/workflows/agent-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 2 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
61 changes: 40 additions & 21 deletions docs/AGENT_WORKFLOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -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- |
Expand All @@ -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

Expand All @@ -40,20 +49,18 @@ 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.


## 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.
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. 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. It regenerates
`contracts/examples/api-dashboard.example.json` and writes
Expand All @@ -75,14 +82,15 @@ changes:
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.
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. Use
only sanitized summaries or synthetic examples when connecting those reports to
Comptextv7 PR evidence. Future dashboard/UI work should consume
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.
Expand Down Expand Up @@ -134,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

Expand All @@ -146,8 +156,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 VIN/FIN, account, employee, plant, vehicle, or workshop identifiers.
- Large opaque binary artifacts from benchmark tools.

Prefer:
Expand All @@ -161,14 +170,16 @@ Prefer:

## Review checklist

Before opening a Comptextv7 PR, agents should verify:
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.
Expand All @@ -185,6 +196,8 @@ Before opening a Comptextv7 PR, agents should verify:
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

Expand All @@ -210,18 +223,24 @@ Before opening a Comptextv7 PR, agents should verify:
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.
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 both repositories are affected, split the work into two PRs and keep the
handoff contract small and sanitized.
- 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

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.
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.
47 changes: 18 additions & 29 deletions docs/validation.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
# 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

```text
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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
8 changes: 4 additions & 4 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Loading