From 1644c3cd1154b9ae2dc17f31089f8aa8e308e42d Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:05:05 +0200 Subject: [PATCH 1/9] chore: align engineering standard to repo-template-sw 0.10.0 --- .engineering/baseline.json | 35 ++---- .engineering/commands.json | 15 +-- .engineering/documentation-policy.json | 32 +++-- AGENTS.md | 68 ++++++----- scripts/verify_agent_context.py | 114 ++++------------- scripts/verify_operations.py | 163 ++----------------------- scripts/verify_repository.py | 107 ++-------------- skills/finalize-workstream/SKILL.md | 49 +------- skills/plan-workstream/SKILL.md | 10 +- skills/preflight-change/SKILL.md | 20 +-- skills/remote-preflight/SKILL.md | 18 +-- skills/structured-change/SKILL.md | 12 +- skills/validate-change/SKILL.md | 19 +-- 13 files changed, 128 insertions(+), 534 deletions(-) mode change 100644 => 100755 scripts/verify_agent_context.py mode change 100644 => 100755 scripts/verify_operations.py mode change 100644 => 100755 scripts/verify_repository.py diff --git a/.engineering/baseline.json b/.engineering/baseline.json index 38e871d8..aa19f3b3 100644 --- a/.engineering/baseline.json +++ b/.engineering/baseline.json @@ -1,37 +1,22 @@ { "schema_version": 1, - "standard": { - "source": "daniele21/repo-template-sw", - "version": "0.9.2", - "revision": "8aa95d10254846e7d63f4bd5c60d61b18d21060c" - }, + "standard": {"source": "daniele21/repo-template-sw", "version": "0.10.0", "revision": "f392e4ded5cd3ec5efbf806934789c6cb9f10ded"}, "target_level": "L2", "profiles": ["python", "typescript", "product-ui"], "skills": { - "plan-workstream": {"source_version": "0.9.0", "customized": true}, - "structured-change": {"source_version": "0.9.0", "customized": true}, + "plan-workstream": {"source_version": "0.10.0", "customized": true}, + "structured-change": {"source_version": "0.10.0", "customized": true}, "design-product-experience": {"source_version": "0.5.0", "customized": false}, - "validate-change": {"source_version": "0.9.0", "customized": true}, - "preflight-change": {"source_version": "0.9.0", "customized": true}, - "remote-preflight": {"source_version": "0.9.1", "customized": true}, - "finalize-workstream": {"source_version": "0.1.0", "customized": false}, + "validate-change": {"source_version": "0.10.0", "customized": true}, + "preflight-change": {"source_version": "0.10.0", "customized": true}, + "remote-preflight": {"source_version": "0.10.0", "customized": true}, + "finalize-workstream": {"source_version": "0.10.0", "customized": true}, "review-reference-quality": {"source_version": "0.4.0", "customized": false} }, "documentation": {"completed_workstreams": "delete-by-default", "historical_archive": "exception-only"}, "adoption": { - "development_velocity_0_9_1": { - "staged_delivery": "adopted", - "risk_to_gate_selection": "adopted", - "exact_head_evidence_reuse": "adopted", - "post_merge_tree_equivalent_reuse": "adopted-on-dev", - "risk_based_ui_evidence": "adopted", - "automatic_pr_workflow_consolidation": "adopted" - }, - "development_velocity_0_9_2": { - "automated_integration_before_dev": "adopted", - "real_environment_integration_blocking": false, - "real_environment_release_gate": "adopted", - "material_ui_integration_full_media": "adopted" - } + "development_velocity_0_9_1": {"staged_delivery": "adopted", "risk_to_gate_selection": "adopted", "exact_head_evidence_reuse": "adopted", "post_merge_tree_equivalent_reuse": "adopted-on-dev", "risk_based_ui_evidence": "adopted", "automatic_pr_workflow_consolidation": "adopted"}, + "development_velocity_0_9_2": {"automated_integration_before_dev": "adopted", "real_environment_integration_blocking": false, "real_environment_release_gate": "adopted", "material_ui_integration_full_media": "adopted"}, + "development_velocity_0_10_0": {"bounded_agent_reporting": "adopted", "schema2_context_routes": "adopted", "two-failed-repair_diagnostic_pivot": "adopted", "resume_checkpoint": "adopted", "template_revision": "f392e4ded5cd3ec5efbf806934789c6cb9f10ded"} } } diff --git a/.engineering/commands.json b/.engineering/commands.json index 24ab290d..210d402a 100644 --- a/.engineering/commands.json +++ b/.engineering/commands.json @@ -1,6 +1,6 @@ { "schema_version": 1, - "contract_version": "0.6.1", + "contract_version": "0.7.0", "commands": { "setup": {"status": "required", "run": "uv python install 3.12 && uv sync --extra dev --locked && corepack enable && corepack install --global pnpm@11.24.0 && pnpm --dir frontend install --frozen-lockfile && pnpm --dir frontend exec playwright install chromium"}, "doctor": {"status": "recommended", "run": "uv run --extra dev --locked python scripts/doctor.py"}, @@ -15,15 +15,7 @@ "stop": {"status": "recommended", "run": "Ctrl-C the foreground performance-lab-ui process; release smoke and packaged E2E verify listener cleanup"}, "clean": {"status": "required", "run": "uv run --extra dev --locked python scripts/clean.py"} }, - "development_velocity": { - "default_stage": "iteration", - "stages": ["iteration", "integration", "release"], - "iteration": {"target_feedback_minutes": 3, "exact_head_required": false, "full_diff_review_required": false, "durable_documentation_current_required": false, "remote_preflight_required": false, "e2e_default": "risk_only"}, - "integration": {"target_feedback_minutes": 8, "exact_head_required": true, "full_diff_review_required": true, "durable_documentation_current_required": true, "remote_preflight_when_required_gates_unavailable_local": true, "e2e_default": "affected_critical_journeys", "automated_e2e_required_when_affected": true, "real_environment_blocking": false, "real_environment_deferred_to_release": true}, - "release": {"exact_head_required": true, "full_diff_review_required": true, "durable_documentation_current_required": true, "full_validation_required": true, "e2e_default": "release_critical_journeys", "required_real_environment_blocking": true}, - "parallel_development_prefers_early_convergence": true, - "stacked_publication_exception_only": true - }, + "development_velocity": {"default_stage": "iteration", "stages": ["iteration", "integration", "release"], "iteration": {"target_feedback_minutes": 3, "exact_head_required": false, "full_diff_review_required": false, "durable_documentation_current_required": false, "remote_preflight_required": false, "e2e_default": "risk_only"}, "integration": {"target_feedback_minutes": 8, "exact_head_required": true, "full_diff_review_required": true, "durable_documentation_current_required": true, "remote_preflight_when_required_gates_unavailable_local": true, "e2e_default": "affected_critical_journeys", "automated_e2e_required_when_affected": true, "real_environment_blocking": false, "real_environment_deferred_to_release": true}, "release": {"exact_head_required": true, "full_diff_review_required": true, "durable_documentation_current_required": true, "full_validation_required": true, "e2e_default": "release_critical_journeys", "required_real_environment_blocking": true}, "parallel_development_prefers_early_convergence": true, "stacked_publication_exception_only": true}, "publication_gate": {"applies_from_stage": "integration", "agent_preflight_required": true, "target_base_freshness_required": true, "full_diff_review_required": true, "material_ambiguity_must_be_resolved": true, "failure_root_cause_required": true, "execution_capability_classification_required": true, "blast_radius_profile_selection_required": true, "automatable_gates_must_not_be_delegated_to_user": true, "remote_automated_fallback_required_when_agent_local_unavailable": true, "deterministic_ci_command_parity_required": true, "non_automated_evidence_must_be_declared": true, "exact_head_evidence_required": true}, "validation_execution": {"classes": ["agent_local", "remote_automated", "real_environment"], "no_human_runner_for_automatable_gates": true, "remote_automation_required_when_agent_local_unavailable": true}, "validation_profiles": {"default": "auto", "profiles": ["lean", "scoped", "strong", "full"], "selector": "uv run --extra dev --locked python scripts/select_validation_profile.py --base \"$BASE_SHA\" --head \"$HEAD_SHA\" --stage \"$STAGE\"", "selector_output": "risk_dimensions_and_required_gates", "profiles_are_shorthand": true, "gate_selection_preferred_over_suite_selection": true, "unknown_executable_paths_fail_safe": true, "selector_changes_force_full": true, "promotion_validation_full": true, "automatic_escalation_allowed": true, "silent_downgrade_below_auto_forbidden": true, "report_selected_profile_and_reason": true}, @@ -34,5 +26,6 @@ "artifact_lifecycle": {"implementation_status": "implemented-by-REL-UI-001", "immutable_successful_artifacts": true, "promote_only_after_success": true, "manifest_required": true, "manifest_name": "build-manifest.json", "checksum_algorithm": "sha256", "local_keep_successful_per_lineage": 2, "ci_store": "github-actions", "ci_retention_days": 7, "release_store": "github-releases", "release_artifacts_immutable": true}, "build_delta": {"implementation_status": "implemented-by-REL-UI-001", "required": true, "compare_to": "previous-successful-comparable-build", "output": "BUILD_CHANGELOG.md", "bundle_with_artifact": true, "dimensions": ["source", "dependencies", "toolchain", "configuration", "compatibility_migrations", "artifact_metrics", "validation"]}, "local_runtime": {"applicable": true, "bind_default": "loopback", "port_strategy": "configurable-with-collision-check", "foreground_default": true, "readiness_required": true, "graceful_shutdown_required": true, "verify_no_project_listener_after_stop": true}, - "ephemeral_resources": {"run_identity": true, "isolated_workspace": true, "cleanup_paths": ["success", "failure", "timeout", "cancellation", "interrupt", "partial-initialization"], "stale_resource_recovery": true, "ownership_required_before_cleanup": true, "post_cleanup_verification": true} + "ephemeral_resources": {"run_identity": true, "isolated_workspace": true, "cleanup_paths": ["success", "failure", "timeout", "cancellation", "interrupt", "partial-initialization"], "stale_resource_recovery": true, "ownership_required_before_cleanup": true, "post_cleanup_verification": true}, + "agent_reporting": {"schema_version": 1, "format": "summary_with_evidence_references", "required_summary_fields": ["stage", "source_identity", "risks", "profile", "required_gates", "evidence", "remaining_gaps", "next_action"], "gate_fields": ["id", "reason", "executor", "status"], "source_identity_fields": ["head", "source_tree", "target_base", "dirty"], "bounded_output": true, "full_report_on_demand": true, "preserve_failed_pending_gates": true, "summary_is_not_evidence_verification": true} } diff --git a/.engineering/documentation-policy.json b/.engineering/documentation-policy.json index eb3627aa..28795404 100644 --- a/.engineering/documentation-policy.json +++ b/.engineering/documentation-policy.json @@ -1,22 +1,18 @@ { - "schema_version": 1, + "schema_version": 2, "estimated_token_characters": 4, - "budgets": { - "root_agents": {"max_lines": 180, "max_estimated_tokens": 2500}, - "scoped_agents": {"max_lines": 150, "max_estimated_tokens": 2000}, - "current_state": {"max_lines": 120, "max_estimated_tokens": 1500}, - "active_workstream": {"max_lines": 220, "max_estimated_tokens": 3000}, - "architecture": {"max_lines": 400, "max_estimated_tokens": 5500}, - "feature_doc": {"max_lines": 400, "max_estimated_tokens": 5500} - }, - "context_targets": { - "bootstrap_max_estimated_tokens": 2500, - "root_scoped_workstream_max_estimated_tokens": 6000 - }, + "budgets": {"root_agents": {"max_lines": 120, "max_estimated_tokens": 1200}, "scoped_agents": {"max_lines": 150, "max_estimated_tokens": 2000}, "current_state": {"max_lines": 120, "max_estimated_tokens": 1500}, "active_workstream": {"max_lines": 220, "max_estimated_tokens": 3000}, "architecture": {"max_lines": 400, "max_estimated_tokens": 5500}, "feature_doc": {"max_lines": 400, "max_estimated_tokens": 5500}}, + "context_targets": {"bootstrap_max_estimated_tokens": 1200, "root_scoped_workstream_max_estimated_tokens": 6000}, "duplicate_min_characters": 240, - "completed_workstream_markers": [ - "Status: complete", - "Status: completed", - "Status: done" - ] + "completed_workstream_markers": ["Status: complete", "Status: completed", "Status: done"], + "context_exclude_directories": [".git", "node_modules", ".venv", "venv", ".gradle", ".build", "build", "dist", "frontend/node_modules", "__pycache__"], + "context_routes": { + "docs": {"read_when": "Pure documentation/copy without executable or policy changes.", "files": ["AGENTS.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 5000}, + "bug": {"read_when": "Meaningful owner-local bug during iteration.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 7000}, + "contract": {"read_when": "Shared comparability/evidence/API/storage boundary change.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "docs/architecture.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, + "ui": {"read_when": "Material Performance Lab product UI change.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "skills/design-product-experience/SKILL.md", "design/ux-contract.json", "design/brand-kit.json", ".engineering/e2e.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, + "integration": {"read_when": "Candidate readiness including repository-owned automatic validation.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, + "release": {"read_when": "Release readiness including RUNTIME-1 evidence owners.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, + "resume": {"read_when": "Resume a multi-session bug/implementation/evidence workstream.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": true, "max_estimated_tokens": 9500} + } } diff --git a/AGENTS.md b/AGENTS.md index 59ef582a..5473fd16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,45 +1,53 @@ -# Performance Lab — coding agent guide +# Performance Lab — Coding Agent Guide -Repository-wide routing and durable invariants. Status belongs in `docs/current-state.md`; detailed behavior belongs in architecture/features/workstreams. +Performance Lab evaluates externally served AI inference endpoints and determines which available model/configuration gives the best evidence-backed trade-off for a use case/device. It owns evaluation, evidence, comparison and regression; serving-runtime lifecycle remains external. -## Read only what the task requires +## Durable invariants -Always read this guide, then the closest scoped `AGENTS.md`, owning implementation/tests and only relevant contracts: `.engineering/commands.json` for operations/stages/gates, `.engineering/e2e.json` for complete-workflow/fidelity claims, `design/*` for meaningful product UI, and `docs/README.md` for documentation ownership. +- Execution fingerprints are explicit/immutable and completed evidence/datasets are versioned. +- Quality, runtime and resource dimensions stay separate; compatibility is established before deltas, rankings or regression claims. +- Endpoint provenance and lab provenance stay distinct; raw authorization is never persisted. +- Python is the semantic owner; TypeScript projects those semantics rather than redefining them. +- Local listeners/jobs/temp/artifacts are bounded and cleaned. +- Hosted fixtures never become real model/runtime/device/telemetry/thermal evidence by implication. -## Purpose and invariants +## Ownership -Performance Lab evaluates externally served AI inference endpoints and answers which available model/configuration gives the best evidence-backed trade-off for a use case/device. It owns evaluation, evidence, comparison and regression; serving-runtime lifecycle remains external. +| Change | Owner | Inspect / prove | +| --- | --- | --- | +| Domain/comparability | `src/performance_lab/domain/` | domain/comparison tests | +| Inference adapters | `adapters/` | adapter contracts | +| Dataset/evaluation | `datasets/`, `evaluation/` | evidence/repeatability tests | +| Benchmark/telemetry | `performance/`, `telemetry/` | metrics/provenance tests | +| Persistence/regression | `storage/`, `regression/` | migration/regression tests | +| App/API | `application/`, `ui_api.py`, `ui_server.py` | API/product tests | +| Browser/UI | `frontend/AGENTS.md`, `design/` | browser/product journeys | -Preserve explicit immutable execution fingerprints; versioned completed evidence/datasets; separate quality/runtime/resource dimensions; compatibility before deltas/rankings/regression; distinct endpoint/lab provenance; no persisted raw authorization; Python as semantic owner with TypeScript projections; bounded local listeners/jobs/temp/artifacts; truthful separation of hosted fixtures from real device/model evidence. +Follow applicable scoped `AGENTS.md`; extend the canonical owner before adding state/policy and inspect material consumers for shared boundaries. -## Ownership routing +## Read by task -Domain/comparability -> `src/performance_lab/domain/`; inference adapters -> `adapters/`; datasets/evaluation -> `datasets/`, `evaluation/`; benchmark/telemetry -> `performance/`, `telemetry/`; persistence/regression -> `storage/`, `regression/`; app/API -> `application/`, `ui_api.py`, `ui_server.py`; browser -> `frontend/AGENTS.md`; product experience -> `design/`. +| Task | Read now | +| --- | --- | +| Pure docs/copy | affected source/links; `docs/README.md` only if ownership unclear | +| Behavior/bug/contract | `skills/structured-change/SKILL.md`, `skills/validate-change/SKILL.md`, relevant commands | +| Material UI | above + `skills/design-product-experience/SKILL.md`, relevant `design/*` | +| Integration/release | `skills/preflight-change/SKILL.md`, commands, affected `.engineering/e2e.json` | +| Missing deterministic remote gate | `skills/remote-preflight/SKILL.md` | +| Persistent multi-session work | `skills/plan-workstream/SKILL.md` + active plan; finalize with `skills/finalize-workstream/SKILL.md` | -## Delivery model +## Delivery and evidence -Performance Lab follows repo-template-sw **0.9.2**. +- **ITERATION**: focused Python/frontend owner-local falsification; no exact-head/full-diff/docs/publication ceremony per edit. +- **INTEGRATION** (`PR -> dev`): exact candidate/base, complete diff, affected durable docs, selected automated gates and affected critical E2E. Material UI/UX integration journeys require `FULL_MEDIA`. Required `REAL_ENVIRONMENT` evidence remains explicit but `DEFERRED_TO_RELEASE`. +- **RELEASE** (`dev -> main`): `FULL` plus release-critical artifact/E2E and every applicable required residual real-environment confirmation. -- `ITERATION`: focused owner-local Python/frontend checks while implementation changes. No exact-head/full-diff/doc ceremony and no browser/product/built-product gate merely because it exists. -- `INTEGRATION` (`PR -> dev`): prove the affected observable outcome automatically. Exact head, full diff, affected durable docs, selected risk gates and affected critical E2E are required. Required `REAL_ENVIRONMENT` evidence is explicit but non-blocking and deferred to release. -- `RELEASE` (`dev -> main`): FULL validation plus release-critical artifact/E2E and every applicable required residual real-environment confirmation. +The native selector resolves risks -> concrete gates -> profile; profiles are shorthand. `.github/workflows/validate.yml` is the automatic PR owner and should avoid duplicate overlapping cones. `PRE_REAL_E2E` proves the complete automatable cone only; `RUNTIME-1` keeps real model/runtime/device/telemetry/thermal/repeated-load claims in release evidence. -The selector maps **risk dimensions -> required gates -> profile shorthand**. `LEAN | SCOPED | STRONG | FULL` summarize the decision; concrete gates are authoritative. +## Context, diagnosis and completion -Parallel technical subtasks should converge early around vertical outcomes. Stacked publication is exceptional; avoid sync-only PR chains. +`.engineering/documentation-policy.json` owns bounded context routes. Use `python3 scripts/verify_agent_context.py --route bug --format json`, optionally with `--path`/`--workstream`; routes estimate reading cost, not validation scope. -## Validation +For meaningful work state observable outcome, owner, invariants and proof. Classify failures before patching. Each failed repair needs a falsifiable hypothesis; after two failed repairs with the same signature, change diagnostic strategy and obtain new discriminating evidence before a third. On resume refresh head/tree/base; checkpoint evidence is a pointer, not current-source proof. -`.github/workflows/validate.yml` is the automatic PR owner. It selects Python, frontend, product E2E, browser E2E and built-product gates. When `built-product` is required, it exercises the stronger integrated cone and satisfies overlapping frontend/product/browser gates rather than duplicating them in separate workflows. `browser-acceptance.yml` is manual diagnostic; `built-product.yml` is tag/manual release tooling. - -Successful integration evidence is reusable. Before merge it is exact-head evidence. After a content-preserving merge to `dev`, reuse is allowed only when Git tree, prior target/base, required gates and profile are equivalent. Direct pushes without trusted evidence validate normally. Release remains FULL. - -E2E UI evidence modes are `ASSERTIONS`, `SCREENSHOTS`, `FULL_MEDIA`. A material UI/UX integration journey uses FULL_MEDIA; screenshots remain sufficient for stable visible inspection/comparison claims. `RUNTIME-1` keeps real model/runtime/device/telemetry/thermal/repeated-load claims in `REAL_ENVIRONMENT`, and those claims gate release rather than entry into `dev`. - -`PRE_REAL_E2E` remains useful: it proves that the complete automatable cone is green before any real runtime/device run. It does not make real-runtime evidence an integration gate. - -## Documentation and failure discipline - -Affected durable documentation must be current at `INTEGRATION`, not after every private edit. README identity and usage are separate owners. `docs/current-state.md` owns integrated/blocked/next truth, not branch diaries; completed workstreams are deleted after durable truth moves. - -Classify failures as change regression, baseline, environment, flaky, base drift or assumption before editing. Fix the owning invariant; never suppress a legitimate gate for green CI or promote hosted evidence into a real-device claim. \ No newline at end of file +Before integration update affected canonical docs. Transfer durable truth and deferred release obligations before deleting completed plans. Never suppress legitimate gates, persist credentials, create competing semantic owners or promote hosted evidence into a real-device/runtime claim. diff --git a/scripts/verify_agent_context.py b/scripts/verify_agent_context.py old mode 100644 new mode 100755 index d9b6eb5e..aecc1647 --- a/scripts/verify_agent_context.py +++ b/scripts/verify_agent_context.py @@ -1,90 +1,28 @@ #!/usr/bin/env python3 -"""Estimate mandatory coding-agent context cost from bounded repository guides.""" - -from __future__ import annotations - -import argparse -import json -import math -import sys +import argparse,json,math,sys from pathlib import Path - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser() - parser.add_argument("--root", default=".") - return parser.parse_args() - - -def estimate(path: Path, chars_per_token: int) -> int: - if not path.is_file(): - return 0 - return math.ceil(len(path.read_text(encoding="utf-8")) / chars_per_token) - - -def main() -> int: - args = parse_args() - root = Path(args.root).resolve() - policy = json.loads( - (root / ".engineering/documentation-policy.json").read_text(encoding="utf-8") - ) - chars_per_token = int(policy.get("estimated_token_characters", 4)) - targets = policy["context_targets"] - - root_tokens = estimate(root / "AGENTS.md", chars_per_token) - scoped = [ - (path, estimate(path, chars_per_token)) - for path in root.rglob("AGENTS.md") - if path != root / "AGENTS.md" and ".git" not in path.parts - ] - scoped_path, scoped_tokens = max(scoped, key=lambda item: item[1], default=(None, 0)) - - workstreams = ( - [ - (path, estimate(path, chars_per_token)) - for path in (root / "docs/workstreams").glob("*.md") - if path.name != "README.md" and not path.name.startswith("_") - ] - if (root / "docs/workstreams").is_dir() - else [] - ) - work_path, work_tokens = max(workstreams, key=lambda item: item[1], default=(None, 0)) - - bootstrap = root_tokens - worst_focused = root_tokens + scoped_tokens + work_tokens - errors: list[str] = [] - - if bootstrap > targets["bootstrap_max_estimated_tokens"]: - errors.append( - f"bootstrap context ~{bootstrap} > " - f"{targets['bootstrap_max_estimated_tokens']} token target" - ) - if worst_focused > targets["root_scoped_workstream_max_estimated_tokens"]: - errors.append( - f"root+largest scoped+largest workstream ~{worst_focused} > " - f"{targets['root_scoped_workstream_max_estimated_tokens']} token target" - ) - - print("Agent context health") - print(f"root AGENTS: ~{root_tokens} tokens") - print( - f"largest scoped AGENTS: ~{scoped_tokens} tokens" - + (f" ({scoped_path.relative_to(root)})" if scoped_path else "") - ) - print( - f"largest active workstream: ~{work_tokens} tokens" - + (f" ({work_path.relative_to(root)})" if work_path else "") - ) - print(f"bootstrap cost: ~{bootstrap} tokens") - print(f"worst focused routing bundle: ~{worst_focused} tokens") - for error in errors: - print(f"FAIL: {error}") - if errors: - print(f"RESULT: FAIL ({len(errors)} error(s))") - return 1 - print("RESULT: PASS") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) +REQ={'docs','bug','contract','ui','integration','release','resume'} +a=argparse.ArgumentParser();a.add_argument('--route');a.add_argument('--path',action='append',default=[]);a.add_argument('--workstream');a.add_argument('--format',choices=['text','json'],default='text');a.add_argument('--root',default='.');a.add_argument('--template-mode',action='store_true');x=a.parse_args();root=Path(x.root);err=[];reports=[] +try: + p=json.loads((root/'.engineering/documentation-policy.json').read_text());b=json.loads((root/'.engineering/baseline.json').read_text()) + if p.get('schema_version')!=2:raise ValueError('documentation policy schema_version must be 2') + if not REQ.issubset(p.get('context_routes',{})):raise ValueError('missing context route') + cpt=p.get('estimated_token_characters',4);profiles=set(b.get('profiles',[]));names=[x.route] if x.route else list(p['context_routes']) + for n in names: + rr=p['context_routes'][n];req=rr.get('requires_profile') + if req and req not in profiles and not x.template_mode:continue + files=list(rr['files']); + if x.workstream and rr.get('include_workstream'):files.append(x.workstream) + total=0 + for f in files: + q=root/f + if not q.is_file():raise ValueError('missing context source: '+f) + total+=math.ceil(len(q.read_text())/cpt) + if total>rr['max_estimated_tokens']:err.append(f'route {n} ~{total} exceeds {rr["max_estimated_tokens"]}') + reports.append({'route':n,'estimated_tokens':total,'budget':rr['max_estimated_tokens']}) + boot=math.ceil(len((root/'AGENTS.md').read_text())/cpt);limit=p['context_targets']['bootstrap_max_estimated_tokens'] + if boot>limit:err.append(f'bootstrap ~{boot} exceeds {limit}') + out={'bootstrap_estimated_tokens':boot,'routes':reports,'errors':err,'result':'FAIL' if err else 'PASS'} +except Exception as ex:out={'errors':[str(ex)],'result':'FAIL'} +print(json.dumps(out,indent=2) if x.format=='json' else '\n'.join(['Agent context health']+[f"{z['route']}: ~{z['estimated_tokens']} / {z['budget']}" for z in out.get('routes',[])]+['FAIL: '+z for z in out.get('errors',[])]+['RESULT: '+out['result']])) +sys.exit(out['result']!='PASS') diff --git a/scripts/verify_operations.py b/scripts/verify_operations.py old mode 100644 new mode 100755 index ba1e579b..4825535e --- a/scripts/verify_operations.py +++ b/scripts/verify_operations.py @@ -1,154 +1,13 @@ #!/usr/bin/env python3 -"""Validate Performance Lab's repo-template-sw 0.9.x operating contract.""" - -from __future__ import annotations - -import argparse -import json -import sys +import json,sys from pathlib import Path - -COMMANDS = ( - "setup", - "doctor", - "dev", - "check", - "test", - "e2e", - "build", - "smoke", - "package", - "stop", - "clean", -) -STATUSES = {"required", "recommended", "optional", "n/a"} -PROFILES = {"lean", "scoped", "strong", "full"} -EVIDENCE = {"head", "source_tree", "target_base", "required_gates", "profile", "e2e_environment"} - - -def main() -> int: - p = argparse.ArgumentParser() - p.add_argument("--root", default=".") - p.add_argument("--template-mode", action="store_true") - a = p.parse_args() - errors = [] - try: - data = json.loads((Path(a.root) / ".engineering/commands.json").read_text()) - except Exception as exc: - print(f"FAIL: invalid commands.json: {exc}") - return 1 - if data.get("schema_version") != 1: - errors.append("schema_version must be 1") - if data.get("contract_version") != "0.6.1": - errors.append("contract_version must be 0.6.1") - commands = data.get("commands", {}) - for n in COMMANDS: - e = commands.get(n) - if not isinstance(e, dict): - errors.append(f"missing command intent: {n}") - continue - if e.get("status") not in STATUSES: - errors.append(f"commands.{n}.status invalid") - if e.get("status") != "n/a" and not str(e.get("run", "")).strip(): - errors.append(f"commands.{n}.run required") - v = data.get("development_velocity", {}) - if v.get("stages") != ["iteration", "integration", "release"]: - errors.append("development stages invalid") - if v.get("default_stage") != "iteration": - errors.append("default stage must be iteration") - for k in ( - "parallel_development_prefers_early_convergence", - "stacked_publication_exception_only", - ): - if v.get(k) is not True: - errors.append(f"development_velocity.{k} must be true") - integration = v.get("integration", {}) - if integration.get("exact_head_required") is not True: - errors.append("integration exact-head required") - if integration.get("automated_e2e_required_when_affected") is not True: - errors.append("integration affected automated E2E required") - if integration.get("real_environment_blocking") is not False: - errors.append("integration real environment must not block") - if integration.get("real_environment_deferred_to_release") is not True: - errors.append("integration real environment must defer to release") - release = v.get("release", {}) - if release.get("full_validation_required") is not True: - errors.append("release full validation required") - if release.get("required_real_environment_blocking") is not True: - errors.append("release required real environment must block") - pub = data.get("publication_gate", {}) - if pub.get("applies_from_stage") != "integration": - errors.append("publication gate must start at integration") - for k in ( - "agent_preflight_required", - "target_base_freshness_required", - "full_diff_review_required", - "failure_root_cause_required", - "execution_capability_classification_required", - "automatable_gates_must_not_be_delegated_to_user", - "exact_head_evidence_required", - ): - if pub.get(k) is not True: - errors.append(f"publication_gate.{k} must be true") - profiles = data.get("validation_profiles", {}) - if profiles.get("default") != "auto" or not PROFILES.issubset( - set(profiles.get("profiles", [])) - ): - errors.append("validation profiles incomplete") - if profiles.get("selector_output") != "risk_dimensions_and_required_gates": - errors.append("selector output must be risks and gates") - for k in ( - "profiles_are_shorthand", - "gate_selection_preferred_over_suite_selection", - "selector_changes_force_full", - "promotion_validation_full", - ): - if profiles.get(k) is not True: - errors.append(f"validation_profiles.{k} must be true") - r = data.get("remote_preflight", {}) - for k in ( - "exact_head_required", - "reuse_successful_equivalent_evidence", - "rerun_only_when_missing_stale_or_insufficient", - "post_merge_tree_equivalent_reuse_allowed", - "post_merge_tree_reuse_requires_same_target_base", - "direct_push_without_equivalent_evidence_must_validate", - "trusted_requesters_only", - "same_repository_prs_only_by_default", - "report_result_to_pr", - ): - if r.get(k) is not True: - errors.append(f"remote_preflight.{k} must be true") - if r.get("execution_job_write_credentials") is not False: - errors.append("remote execution must be read-only") - if not EVIDENCE.issubset(set(r.get("evidence_identity_fields", []))): - errors.append("evidence identity fields incomplete") - e2e = data.get("end_to_end", {}) - if e2e.get("ui_evidence_modes") != ["assertions", "screenshots", "full_media"]: - errors.append("UI evidence modes invalid") - if e2e.get("ui_evidence_selection") != "risk_based": - errors.append("UI evidence selection must be risk_based") - econ = data.get("validation_economics", {}) - if ( - econ.get("status") not in {"recommended", "required"} - or econ.get("periodic_review") is not True - ): - errors.append("validation economics not enabled") - for section in ( - "build_identity", - "artifact_lifecycle", - "build_delta", - "local_runtime", - "ephemeral_resources", - ): - if not isinstance(data.get(section), dict): - errors.append(f"{section} must be an object") - print("Project operating contract check") - for x in errors: - print("FAIL:", x) - print("RESULT:", "FAIL" if errors else "PASS") - return 1 if errors else 0 - - -if __name__ == "__main__": - sys.exit(main()) +d=json.loads(Path('.engineering/commands.json').read_text());e=[] +if d.get('contract_version')!='0.7.0':e.append('contract_version must be 0.7.0') +i=d.get('development_velocity',{}).get('integration',{});r=d.get('development_velocity',{}).get('release',{}) +if i.get('automated_e2e_required_when_affected') is not True or i.get('real_environment_blocking') is not False or i.get('real_environment_deferred_to_release') is not True:e.append('invalid integration stage policy') +if r.get('required_real_environment_blocking') is not True:e.append('invalid release environment policy') +rep=d.get('agent_reporting',{});req={'stage','source_identity','risks','profile','required_gates','evidence','remaining_gaps','next_action'} +if rep.get('schema_version')!=1 or rep.get('format')!='summary_with_evidence_references' or not req.issubset(set(rep.get('required_summary_fields',[]))):e.append('invalid agent_reporting') +for k in ['bounded_output','full_report_on_demand','preserve_failed_pending_gates','summary_is_not_evidence_verification']: + if rep.get(k) is not True:e.append('agent_reporting.'+k+' must be true') +print('Project operating contract check');[print('FAIL:',x) for x in e];print('RESULT:','FAIL' if e else 'PASS');sys.exit(bool(e)) diff --git a/scripts/verify_repository.py b/scripts/verify_repository.py old mode 100644 new mode 100755 index c01b5925..2ad3b928 --- a/scripts/verify_repository.py +++ b/scripts/verify_repository.py @@ -1,100 +1,11 @@ #!/usr/bin/env python3 -"""Zero-dependency structural checks for Performance Lab.""" - -from __future__ import annotations - -import argparse -import json -import sys +import json,sys from pathlib import Path - -CORE = ( - "plan-workstream", - "structured-change", - "design-product-experience", - "validate-change", - "preflight-change", - "remote-preflight", - "finalize-workstream", - "review-reference-quality", -) -REQUIRED = ( - "README.md", - "AGENTS.md", - "CONTRIBUTING.md", - "SECURITY.md", - ".editorconfig", - ".gitignore", - ".engineering/baseline.json", - ".engineering/documentation-policy.json", - ".engineering/commands.json", - ".engineering/e2e.json", - ".github/pull_request_template.md", - ".github/workflows/repository-health.yml", - "docs/README.md", - "docs/architecture.md", - "docs/current-state.md", - "docs/features/README.md", - "docs/adr/README.md", - "docs/workstreams/README.md", - "scripts/verify_operations.py", - "scripts/verify_e2e.py", - "scripts/verify_stage_environment_policy.py", - "scripts/verify_product_experience.py", -) - - -def main() -> int: - p = argparse.ArgumentParser() - p.add_argument("--root", default=".") - p.add_argument("--template-mode", action="store_true") - a = p.parse_args() - root = Path(a.root).resolve() - errors = [] - warnings = [] - for r in REQUIRED: - if not (root / r).is_file(): - errors.append(f"missing required file: {r}") - for n in CORE: - if not (root / "skills" / n / "SKILL.md").is_file(): - errors.append(f"missing core skill: skills/{n}/SKILL.md") - try: - b = json.loads((root / ".engineering/baseline.json").read_text()) - except Exception as exc: - errors.append(f"invalid baseline.json: {exc}") - b = {} - s = b.get("standard", {}) - if b.get("schema_version") != 1: - errors.append("baseline schema_version must be 1") - if s.get("source") != "daniele21/repo-template-sw": - errors.append("baseline source invalid") - if s.get("version") != "0.9.2": - errors.append("baseline standard.version must be 0.9.2") - if s.get("revision") != "8aa95d10254846e7d63f4bd5c60d61b18d21060c": - errors.append("baseline revision must match canonical 0.9.2") - if b.get("target_level") not in {"L0", "L1", "L2"}: - errors.append("target_level invalid") - for n in CORE: - e = b.get("skills", {}).get(n) - if ( - not isinstance(e, dict) - or not e.get("source_version") - or not isinstance(e.get("customized"), bool) - ): - errors.append(f"baseline skill metadata invalid: {n}") - present = [ - x for x in ("node_modules", ".venv", "build", "dist", "__pycache__") if (root / x).exists() - ] - if present: - warnings.append("generated/local directories present: " + ", ".join(present)) - print("Repository baseline check") - for x in warnings: - print("WARN:", x) - for x in errors: - print("FAIL:", x) - print("RESULT:", "FAIL" if errors else "PASS") - return 1 if errors else 0 - - -if __name__ == "__main__": - sys.exit(main()) +r=Path('.');e=[] +for p in ['AGENTS.md','.engineering/baseline.json','.engineering/commands.json','.engineering/e2e.json','.engineering/documentation-policy.json','scripts/verify_operations.py','scripts/verify_agent_context.py']: + if not (r/p).is_file():e.append('missing '+p) +try:b=json.loads((r/'.engineering/baseline.json').read_text()) +except Exception as x:e.append(str(x));b={} +if b.get('standard',{}).get('source')!='daniele21/repo-template-sw':e.append('baseline source mismatch') +if b.get('standard',{}).get('version')!='0.10.0':e.append('baseline version must be 0.10.0') +print('Repository baseline check');[print('FAIL:',x) for x in e];print('RESULT:','FAIL' if e else 'PASS');sys.exit(bool(e)) diff --git a/skills/finalize-workstream/SKILL.md b/skills/finalize-workstream/SKILL.md index b2a273da..0f3d416b 100644 --- a/skills/finalize-workstream/SKILL.md +++ b/skills/finalize-workstream/SKILL.md @@ -1,51 +1,6 @@ --- name: finalize-workstream -description: Close a completed active workstream by validating completion, transferring only durable current knowledge to canonical docs/tests, updating repository state, removing temporary planning material and checking for broken/duplicate documentation. +description: Close completed Performance Lab work by transferring durable truth and deferred real-environment obligations before deleting temporary planning state. --- - # Finalize Workstream - -## Principle - -Implementation plans are working memory. Code/tests/current durable docs are long-term memory. Git history preserves how the implementation happened. - -Completed plans are deleted by default. - -A workstream is not documentation-complete merely because its code and tests are complete. The durable documentation affected by the resulting behavior must describe the system as it exists now. - -## Workflow - -1. Read the workstream goal, invariants, DAG, acceptance and validation. -2. Confirm every required slice is `DONE` and no acceptance/evidence claim is unresolved. If real-device/hardware evidence is required but missing, the workstream is not fully complete; keep the relevant state truthful. -3. Inspect the resulting code/contracts/tests rather than trusting the plan's narrative. -4. Assess documentation impact from the final observable behavior. Use `docs/README.md` when ownership is unclear. -5. Extract only knowledge that future maintainers/users need about the system **as it exists now**: - - core project purpose, primary audience or primary outcome -> README identity sections; - - setup, prerequisites, run/start, public configuration, public CLI/API/UI usage or examples -> README usage sections; - - architecture/ownership changes -> `docs/architecture.md`; - - durable non-obvious feature behavior -> existing/new `docs/features/` owner; - - material design decision/rationale -> ADR; - - security/trust/data-lifecycle contract -> `SECURITY.md` and/or owning architecture/feature doc; - - operational procedure -> existing/new runbook only when genuinely recurring; - - canonical command semantics -> `.engineering/commands.json`; - - executable invariant -> tests/tooling when possible. -6. Treat README identity and usage independently. Do not rewrite mission/positioning merely because a feature or command changed. Do update setup/run/use/configuration/examples when the old path would now be incomplete, wrong or misleading. -7. Do not transfer PR numbers, commit diaries, sequence-of-implementation notes or resolved temporary blockers into durable docs. -8. Update `docs/current-state.md` to remove the workstream and expose the next current target/blocker. -9. Delete the completed workstream file by default. -10. Preserve it only when independent audit/regulatory/release/historical value exists; mark it historical and ensure it is not routed as current truth. -11. Search for stale links/references, instructions, examples and configuration claims affected by the completed workstream and update them. -12. Run repository/docs/agent-context validation and relevant project tests. - -## Completion questions - -- Can a future agent understand current behavior without the plan? -- Can a new user/developer follow the README's current setup/run/use path successfully? -- If README usage changed, did we avoid opportunistically rewriting still-valid identity/mission copy? -- Is every durable fact in exactly one appropriate canonical owner? -- Are existing feature docs current for the behavior they describe? -- Did we avoid copying implementation history into current docs? -- Is current state now smaller and truthful? -- Is the completed plan gone unless there is a concrete retention reason? - -A successful finalization should normally reduce active planning/context size while leaving durable documentation no less truthful than the implementation. +Confirm acceptance from code/tests/evidence; update only affected canonical docs/current-state truth; transfer every deferred RUNTIME-1/release obligation to its canonical owner before plan deletion. Then delete the completed plan by default, search stale links/claims and run repository/docs/E2E/context plus relevant project validation. diff --git a/skills/plan-workstream/SKILL.md b/skills/plan-workstream/SKILL.md index d20bb5cb..e17f7b06 100644 --- a/skills/plan-workstream/SKILL.md +++ b/skills/plan-workstream/SKILL.md @@ -1,12 +1,8 @@ --- name: plan-workstream -description: Plan substantial Performance Lab work as observable vertical outcomes with parallel technical subtasks and early convergence rather than stacked publication ceremony. +description: Plan substantial Performance Lab work as observable outcomes with safe parallel ownership and bounded resume checkpoints. --- - # Plan Workstream +Use persistent plans only for genuine cross-session/dependency coordination. Plan observable outcomes; technical layers are subtasks unless independently valuable. Give parallel work non-conflicting write boundaries and converge early. Track READY/ACTIVE/BLOCKED/DONE only. -Use a durable workstream only when dependency or parallel coordination genuinely adds value. Prefer slices that unlock an observable user/system outcome; Python layers, adapters, frontend pieces and test harness changes are subtasks unless independently valuable/mergeable/reviewable. - -Parallel branches may own non-conflicting subtasks but should converge early onto a shared feature/integration branch. Stacked PRs are exceptional; sync-only parent/child PRs are a coordination smell. - -For each slice record goal/non-goals, owning paths/contracts, dependencies, `READY|ACTIVE|BLOCKED|DONE`, convergence point, fast iteration checks and integration/release gates. Keep `docs/current-state.md` for integrated/blocked/next repository truth, not temporary branch activity. Delete completed workstreams after durable truth moves to canonical docs. +For resume keep one checkpoint in the existing plan: head/tree/base, confirmed facts, excluded hypotheses with evidence pointers, unresolved questions, deferred RUNTIME-1/release obligations and next discriminating action. Refresh identity on resume. Delete after durable truth and obligations transfer. diff --git a/skills/preflight-change/SKILL.md b/skills/preflight-change/SKILL.md index 77739165..032a1cfb 100644 --- a/skills/preflight-change/SKILL.md +++ b/skills/preflight-change/SKILL.md @@ -1,22 +1,8 @@ --- name: preflight-change -description: Establish exact-head readiness for a Performance Lab integration or release candidate, reusing equivalent evidence before running only missing gates. +description: Establish Performance Lab integration/release readiness from exact identity, affected docs, risk-selected gates and equivalent evidence reuse. --- - # Preflight Change +Refresh exact head/tree/live base, review the full diff, make affected durable docs current, resolve risks -> gates -> profile/executor and select affected E2E. Reuse only equivalent trusted proof; route missing deterministic work via `remote-preflight`. -Use this Skill when a coherent observable outcome moves to `INTEGRATION` or `RELEASE`. Do not require full publication ceremony for ordinary `ITERATION` edits, temporary pushes or draft collaboration updates; those belong to `validate-change`. - -1. Record stage, exact head and target/base. `RELEASE` requires FULL; `INTEGRATION` uses the narrowest sufficient risk profile. -2. Resolve material ambiguity, review the complete diff and make affected durable documentation current. -3. Run `scripts/select_validation_profile.py` and record risk dimensions, concrete required gates and the profile shorthand. -4. When E2E is needed, select the smallest affected journey, cheapest sufficient declared environment and `ASSERTIONS|SCREENSHOTS|FULL_MEDIA` mode. `RUNTIME-1` real runtime/device/resource claims remain `REAL_ENVIRONMENT`. -5. Classify required gates as `AGENT_LOCAL`, `REMOTE_AUTOMATED` or `REAL_ENVIRONMENT`. -6. Before triggering remote work, reuse successful evidence only when head/source tree, target/base, required gates/profile and relevant E2E identity remain equivalent. Collaboration metadata alone does not invalidate proof. -7. For a content-preserving squash/rebase merge into `dev`, repository automation may reuse trusted integration evidence only when the post-merge Git tree equals the validated source tree and the merge parent is the same target/base revision. Direct pushes without equivalent evidence must validate normally. -8. Run or route only missing, stale or insufficient deterministic gates. Do not delegate automatable work to the user. -9. Classify failures as change regression, baseline, environment, flaky, base drift or assumption; fix the owning invariant rather than weakening a gate. - -Performance Lab automatic PR validation is owned by `.github/workflows/validate.yml`. When `built-product` is required it satisfies the overlapping frontend/product/browser integration cone instead of forcing duplicate workflows. Dedicated browser/built-product workflows are diagnostic/manual or tag/release surfaces, not parallel automatic PR owners. - -Report `STAGE`, `HEAD`, `TARGET`, `RISKS`, `REQUIRED_GATES`, `VALIDATION_PROFILE`, `REUSED_EVIDENCE`, deterministic gate status, E2E environment/mode, residual `REAL_ENVIRONMENT` gaps and final readiness. \ No newline at end of file +INTEGRATION requires all required automated gates/E2E and defers applicable RUNTIME-1 confirmation to release. RELEASE requires FULL plus every applicable required real-environment confirmation. Use `validate-change` diagnosis on failure. Return bounded reporting fields including failed/pending gates and remaining release obligations. diff --git a/skills/remote-preflight/SKILL.md b/skills/remote-preflight/SKILL.md index 7cc803fb..786d7e5e 100644 --- a/skills/remote-preflight/SKILL.md +++ b/skills/remote-preflight/SKILL.md @@ -1,20 +1,6 @@ --- name: remote-preflight -description: Satisfy Performance Lab integration/release deterministic gates through repository-owned automation, reusing equivalent successful evidence before executing only missing work. +description: Reuse equivalent Performance Lab CI evidence first, then run only missing deterministic integration/release gates. --- - # Remote Preflight - -Use this Skill only after `preflight-change` reaches `INTEGRATION` or `RELEASE` and required deterministic gates need `REMOTE_AUTOMATED` execution. - -Read `.engineering/commands.json` and record exact head/source tree, target/base, stage, risks, required gates, profile and applicable E2E identity. Search successful evidence before triggering new CI. - -Reuse exact-head evidence when the candidate head/base/gates/profile/E2E claim are still sufficient. Performance Lab also allows content-preserving post-merge reuse on `dev` only when repository-owned automation proves the merge commit tree equals the validated source tree and the merge parent equals the validated target/base. A different commit SHA is acceptable only for that tree-equivalent merge transformation; a direct push, moved base, changed tree, broadened gates or expired evidence requires normal validation. - -If evidence is sufficient, return confirmed without rerunning expensive gates. Otherwise run only missing/stale/insufficient gates through the repository-owned automatic PR workflow. Do not request FULL merely because it is operationally simpler. - -The automatic PR owner is `.github/workflows/validate.yml`. Built-product subsumes its overlapping frontend/product/browser cone when selected. Dedicated browser/built-product workflows are not additional mandatory automatic PR runs. - -On failure inspect the owning job/log, classify `CHANGE_REGRESSION|BASELINE_FAILURE|ENVIRONMENT|FLAKY|BASE_DRIFT|ASSUMPTION`, repair the owner, reselect risks/gates and rerun only invalidated evidence. Keep change-branch execution read-only, same-repository by default, without production secrets and with bounded evidence retention. - -Report stage/head/tree/target, risks/profile/gates, reused evidence, newly executed gates, E2E environment/mode, failure class and residual real-runtime evidence. \ No newline at end of file +Resolve exact head/tree/base, risks/gates/profile and material E2E identity. Reuse trusted sufficient proof before running missing/stale/invalidated deterministic gates through repository workflows. Post-merge tree reuse requires equivalent final tree/base/gates/E2E. Never delegate automatable work to the user or convert deferred RUNTIME-1 evidence into PASS. Report bounded source/gate/evidence/gap fields. diff --git a/skills/structured-change/SKILL.md b/skills/structured-change/SKILL.md index 419cb4e3..96fb4afc 100644 --- a/skills/structured-change/SKILL.md +++ b/skills/structured-change/SKILL.md @@ -1,14 +1,6 @@ --- name: structured-change -description: Guard meaningful Performance Lab changes against duplicate ownership, unresolved assumptions, excess complexity, unsafe resource/data lifecycle, failure gaps, UX drift and cross-layer contract breakage without making every edit publication-ready. +description: Shape Performance Lab changes around observable outcome, canonical evidence owner, comparability invariants and regression proof. --- - # Structured Change - -Find the canonical owner and inspect direct consumers/fakes/tests before changing shared semantics. Preserve immutable fingerprint/evidence ownership, compatibility-before-deltas, provenance, external runtime ownership, bounded local resources and the Python-to-TypeScript semantic boundary. - -Prefer observable vertical outcomes; technical layers are subtasks unless independently useful. Spend abstractions/dependencies/workers/UI patterns only for a concrete need. Treat cancellation, failure, recovery and cleanup as normal behavior. Keep secrets and sensitive inference data out of unintended persistence/log/evidence paths. - -For product UI, resolve task/journey/hierarchy/states/accessibility before polish and reuse canonical design owners. - -During `ITERATION`, keep validation focused and documentation/publication ceremony proportional. Exact-head, complete-diff and durable-documentation readiness begin when the coherent outcome moves to `INTEGRATION` or `RELEASE` through `preflight-change`. +State **observable outcome, canonical owner, invariants and proof**. Inspect direct consumers/projections/tests and establish failing evidence for reproducible bugs when practical. Extend existing domain/evidence/storage/API owners; preserve fingerprint immutability, provenance, compatibility-before-ranking, credential privacy and Python semantic ownership. Use `validate-change` during implementation; `preflight-change` owns integration/release readiness. diff --git a/skills/validate-change/SKILL.md b/skills/validate-change/SKILL.md index 3b557731..1d1ae857 100644 --- a/skills/validate-change/SKILL.md +++ b/skills/validate-change/SKILL.md @@ -1,21 +1,10 @@ --- name: validate-change -description: Select the cheapest sufficient Performance Lab validation by delivery stage and risk, escalating only when changed invariants require stronger product/browser/package or real-runtime evidence. +description: Run the cheapest sufficient Performance Lab feedback loop and diagnose failures with discriminating evidence before expanding by risk/stage. --- - # Validate Change +Use the selector to resolve outcome/owner -> risks -> gates -> profile. Prefer focused Python/frontend checks; shared domain/evidence/storage/API/security/build changes strengthen; selector/global/toolchain/unknown/release is FULL. -Optimize for sufficient confidence per feedback time. `.engineering/commands.json` owns stage/gate routing; `.engineering/e2e.json` owns journey/fidelity/evidence mode. - -## ITERATION -Run focused owner-local Python/frontend checks that can falsify the current edit. Do not require exact-head, durable-doc freshness, product E2E, browser E2E, built-product packaging or real-device evidence merely because those gates exist. - -## INTEGRATION -For a coherent observable outcome, use the selector's **risk dimensions -> required gates -> profile** mapping. Performance Lab may require Python, frontend, product E2E, browser E2E or built-product. When built-product is selected it satisfies the overlapping integrated frontend/product/browser cone rather than requiring duplicate workflows. - -## RELEASE -Use FULL plus release-critical artifact/E2E gates and residual real-runtime evidence. - -UI evidence modes are `ASSERTIONS`, `SCREENSHOTS`, `FULL_MEDIA`. Use FULL_MEDIA for campaign/evaluation progression, retry and cancellation lifecycle; screenshots for stable comparison/inspection semantics. `RUNTIME-1` remains `REAL_ENVIRONMENT` for real model/runtime/device/telemetry/thermal claims. +Classify failures before patching. Each failed repair needs a falsifiable hypothesis; **after two failed repairs with the same signature, change diagnostic strategy and gather new evidence before a third**. Never suppress a legitimate gate or turn hosted fixtures into RUNTIME-1 evidence. -Classify failures before editing: change regression, baseline, environment, flaky, base drift or assumption. Fix the owning invariant; never suppress a legitimate gate. Hand exact-head integration/release readiness to `preflight-change`. +At integration run affected automated critical E2E; material UI/UX outcomes require `FULL_MEDIA`; real runtime/device/telemetry/thermal evidence is `DEFERRED_TO_RELEASE`. Report bounded source identity, risks/profile, gate reasons/status, evidence refs, gaps and next action without hiding FAIL/PENDING. From 3e5862b81f23ab55e34d0324cfd0b46867bbf516 Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:38:11 +0200 Subject: [PATCH 2/9] fix: keep Performance Lab UI context focused --- .engineering/documentation-policy.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.engineering/documentation-policy.json b/.engineering/documentation-policy.json index 28795404..e8410096 100644 --- a/.engineering/documentation-policy.json +++ b/.engineering/documentation-policy.json @@ -10,7 +10,7 @@ "docs": {"read_when": "Pure documentation/copy without executable or policy changes.", "files": ["AGENTS.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 5000}, "bug": {"read_when": "Meaningful owner-local bug during iteration.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 7000}, "contract": {"read_when": "Shared comparability/evidence/API/storage boundary change.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "docs/architecture.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, - "ui": {"read_when": "Material Performance Lab product UI change.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "skills/design-product-experience/SKILL.md", "design/ux-contract.json", "design/brand-kit.json", ".engineering/e2e.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, + "ui": {"read_when": "Material Performance Lab product-UI iteration; add brand-kit for visual identity and use the integration route when preparing E2E evidence.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "skills/design-product-experience/SKILL.md", "design/ux-contract.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, "integration": {"read_when": "Candidate readiness including repository-owned automatic validation.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, "release": {"read_when": "Release readiness including RUNTIME-1 evidence owners.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, "resume": {"read_when": "Resume a multi-session bug/implementation/evidence workstream.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": true, "max_estimated_tokens": 9500} From 6a4cdea698c52c64cf3dbbe26461ef5f299216fa Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:38:21 +0200 Subject: [PATCH 3/9] fix: format repository verifier --- scripts/verify_repository.py | 45 ++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/scripts/verify_repository.py b/scripts/verify_repository.py index 2ad3b928..d223e463 100755 --- a/scripts/verify_repository.py +++ b/scripts/verify_repository.py @@ -1,11 +1,38 @@ #!/usr/bin/env python3 -import json,sys +import json +import sys from pathlib import Path -r=Path('.');e=[] -for p in ['AGENTS.md','.engineering/baseline.json','.engineering/commands.json','.engineering/e2e.json','.engineering/documentation-policy.json','scripts/verify_operations.py','scripts/verify_agent_context.py']: - if not (r/p).is_file():e.append('missing '+p) -try:b=json.loads((r/'.engineering/baseline.json').read_text()) -except Exception as x:e.append(str(x));b={} -if b.get('standard',{}).get('source')!='daniele21/repo-template-sw':e.append('baseline source mismatch') -if b.get('standard',{}).get('version')!='0.10.0':e.append('baseline version must be 0.10.0') -print('Repository baseline check');[print('FAIL:',x) for x in e];print('RESULT:','FAIL' if e else 'PASS');sys.exit(bool(e)) + +root = Path(".") +errors: list[str] = [] +required_paths = [ + "AGENTS.md", + ".engineering/baseline.json", + ".engineering/commands.json", + ".engineering/e2e.json", + ".engineering/documentation-policy.json", + "scripts/verify_operations.py", + "scripts/verify_agent_context.py", +] + +for path in required_paths: + if not (root / path).is_file(): + errors.append(f"missing {path}") + +try: + baseline = json.loads((root / ".engineering/baseline.json").read_text()) +except Exception as exc: + errors.append(str(exc)) + baseline = {} + +standard = baseline.get("standard", {}) +if standard.get("source") != "daniele21/repo-template-sw": + errors.append("baseline source mismatch") +if standard.get("version") != "0.10.0": + errors.append("baseline version must be 0.10.0") + +print("Repository baseline check") +for error in errors: + print("FAIL:", error) +print("RESULT:", "FAIL" if errors else "PASS") +sys.exit(bool(errors)) From c0f256ccd843c716f7886fa88c01381ce404a90b Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:38:33 +0200 Subject: [PATCH 4/9] fix: format operating-contract verifier --- scripts/verify_operations.py | 65 ++++++++++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 11 deletions(-) diff --git a/scripts/verify_operations.py b/scripts/verify_operations.py index 4825535e..0837c920 100755 --- a/scripts/verify_operations.py +++ b/scripts/verify_operations.py @@ -1,13 +1,56 @@ #!/usr/bin/env python3 -import json,sys +import json +import sys from pathlib import Path -d=json.loads(Path('.engineering/commands.json').read_text());e=[] -if d.get('contract_version')!='0.7.0':e.append('contract_version must be 0.7.0') -i=d.get('development_velocity',{}).get('integration',{});r=d.get('development_velocity',{}).get('release',{}) -if i.get('automated_e2e_required_when_affected') is not True or i.get('real_environment_blocking') is not False or i.get('real_environment_deferred_to_release') is not True:e.append('invalid integration stage policy') -if r.get('required_real_environment_blocking') is not True:e.append('invalid release environment policy') -rep=d.get('agent_reporting',{});req={'stage','source_identity','risks','profile','required_gates','evidence','remaining_gaps','next_action'} -if rep.get('schema_version')!=1 or rep.get('format')!='summary_with_evidence_references' or not req.issubset(set(rep.get('required_summary_fields',[]))):e.append('invalid agent_reporting') -for k in ['bounded_output','full_report_on_demand','preserve_failed_pending_gates','summary_is_not_evidence_verification']: - if rep.get(k) is not True:e.append('agent_reporting.'+k+' must be true') -print('Project operating contract check');[print('FAIL:',x) for x in e];print('RESULT:','FAIL' if e else 'PASS');sys.exit(bool(e)) + +commands = json.loads(Path(".engineering/commands.json").read_text()) +errors: list[str] = [] + +if commands.get("contract_version") != "0.7.0": + errors.append("contract_version must be 0.7.0") + +integration = commands.get("development_velocity", {}).get("integration", {}) +release = commands.get("development_velocity", {}).get("release", {}) +if ( + integration.get("automated_e2e_required_when_affected") is not True + or integration.get("real_environment_blocking") is not False + or integration.get("real_environment_deferred_to_release") is not True +): + errors.append("invalid integration stage policy") +if release.get("required_real_environment_blocking") is not True: + errors.append("invalid release environment policy") + +reporting = commands.get("agent_reporting", {}) +required_summary_fields = { + "stage", + "source_identity", + "risks", + "profile", + "required_gates", + "evidence", + "remaining_gaps", + "next_action", +} +if ( + reporting.get("schema_version") != 1 + or reporting.get("format") != "summary_with_evidence_references" + or not required_summary_fields.issubset( + set(reporting.get("required_summary_fields", [])) + ) +): + errors.append("invalid agent_reporting") + +for field in ( + "bounded_output", + "full_report_on_demand", + "preserve_failed_pending_gates", + "summary_is_not_evidence_verification", +): + if reporting.get(field) is not True: + errors.append(f"agent_reporting.{field} must be true") + +print("Project operating contract check") +for error in errors: + print("FAIL:", error) +print("RESULT:", "FAIL" if errors else "PASS") +sys.exit(bool(errors)) From 288e1c8ca6e2f7a070d3e6a3dff5c85593b256dc Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:38:51 +0200 Subject: [PATCH 5/9] fix: format and scope agent-context verifier --- scripts/verify_agent_context.py | 180 +++++++++++++++++++++++++++----- 1 file changed, 154 insertions(+), 26 deletions(-) diff --git a/scripts/verify_agent_context.py b/scripts/verify_agent_context.py index aecc1647..2b2325f9 100755 --- a/scripts/verify_agent_context.py +++ b/scripts/verify_agent_context.py @@ -1,28 +1,156 @@ #!/usr/bin/env python3 -import argparse,json,math,sys +from __future__ import annotations + +import argparse +import json +import math +import os +import sys from pathlib import Path -REQ={'docs','bug','contract','ui','integration','release','resume'} -a=argparse.ArgumentParser();a.add_argument('--route');a.add_argument('--path',action='append',default=[]);a.add_argument('--workstream');a.add_argument('--format',choices=['text','json'],default='text');a.add_argument('--root',default='.');a.add_argument('--template-mode',action='store_true');x=a.parse_args();root=Path(x.root);err=[];reports=[] -try: - p=json.loads((root/'.engineering/documentation-policy.json').read_text());b=json.loads((root/'.engineering/baseline.json').read_text()) - if p.get('schema_version')!=2:raise ValueError('documentation policy schema_version must be 2') - if not REQ.issubset(p.get('context_routes',{})):raise ValueError('missing context route') - cpt=p.get('estimated_token_characters',4);profiles=set(b.get('profiles',[]));names=[x.route] if x.route else list(p['context_routes']) - for n in names: - rr=p['context_routes'][n];req=rr.get('requires_profile') - if req and req not in profiles and not x.template_mode:continue - files=list(rr['files']); - if x.workstream and rr.get('include_workstream'):files.append(x.workstream) - total=0 - for f in files: - q=root/f - if not q.is_file():raise ValueError('missing context source: '+f) - total+=math.ceil(len(q.read_text())/cpt) - if total>rr['max_estimated_tokens']:err.append(f'route {n} ~{total} exceeds {rr["max_estimated_tokens"]}') - reports.append({'route':n,'estimated_tokens':total,'budget':rr['max_estimated_tokens']}) - boot=math.ceil(len((root/'AGENTS.md').read_text())/cpt);limit=p['context_targets']['bootstrap_max_estimated_tokens'] - if boot>limit:err.append(f'bootstrap ~{boot} exceeds {limit}') - out={'bootstrap_estimated_tokens':boot,'routes':reports,'errors':err,'result':'FAIL' if err else 'PASS'} -except Exception as ex:out={'errors':[str(ex)],'result':'FAIL'} -print(json.dumps(out,indent=2) if x.format=='json' else '\n'.join(['Agent context health']+[f"{z['route']}: ~{z['estimated_tokens']} / {z['budget']}" for z in out.get('routes',[])]+['FAIL: '+z for z in out.get('errors',[])]+['RESULT: '+out['result']])) -sys.exit(out['result']!='PASS') + +REQUIRED_ROUTES = {"docs", "bug", "contract", "ui", "integration", "release", "resume"} + + +def inside(root: Path, relative: str) -> Path: + path = (root / relative).resolve() + if Path(relative).is_absolute() or not path.is_relative_to(root): + raise ValueError(f"invalid path {relative}") + return path + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--root", default=".") + parser.add_argument("--route") + parser.add_argument("--path", action="append", default=[]) + parser.add_argument("--workstream") + parser.add_argument("--format", choices=["text", "json"], default="text") + parser.add_argument("--template-mode", action="store_true") + args = parser.parse_args() + + try: + root = Path(args.root).resolve() + policy = json.loads( + (root / ".engineering/documentation-policy.json").read_text() + ) + baseline = json.loads((root / ".engineering/baseline.json").read_text()) + if policy.get("schema_version") != 2: + raise ValueError("documentation policy schema_version must be 2") + + routes = policy.get("context_routes", {}) + missing = REQUIRED_ROUTES - set(routes) + if missing: + raise ValueError(f"missing routes {sorted(missing)}") + + characters_per_token = policy.get("estimated_token_characters", 4) + cache: dict[Path, int] = {} + + def cost(path: Path) -> int: + if path not in cache: + if not path.is_file(): + raise ValueError(f"missing context source: {path.relative_to(root)}") + cache[path] = math.ceil( + len(path.read_text()) / characters_per_token + ) + return cache[path] + + excluded = set(policy.get("context_exclude_directories", [])) + scoped_guides: list[Path] = [] + for directory, directories, files in os.walk(root): + directories[:] = [name for name in directories if name not in excluded] + directory_path = Path(directory) + if "AGENTS.md" in files and directory_path != root: + scoped_guides.append((directory_path / "AGENTS.md").resolve()) + + affected = [inside(root, path) for path in args.path] + scoped = { + guide + for guide in scoped_guides + if affected + and any( + guide.parent == path or guide.parent in path.parents + for path in affected + ) + } + + workstream = None + if args.workstream: + workstream = inside(root, args.workstream) + if not workstream.is_relative_to(root / "docs/workstreams"): + raise ValueError("workstream must be under docs/workstreams") + + profiles = set(baseline.get("profiles", [])) + selected_routes = [args.route] if args.route else list(routes) + reports: list[dict[str, object]] = [] + errors: list[str] = [] + + for name in selected_routes: + route = routes.get(name) + if route is None: + raise ValueError(f"unknown route {name}") + required_profile = route.get("requires_profile") + if required_profile and required_profile not in profiles and not args.template_mode: + continue + + sources = {inside(root, path) for path in route.get("files", [])} + if route.get("include_scoped_guides"): + sources |= scoped + if route.get("include_workstream") and workstream: + sources.add(workstream) + + details = [ + { + "path": str(path.relative_to(root)), + "estimated_tokens": cost(path), + } + for path in sorted(sources) + ] + total = sum(int(item["estimated_tokens"]) for item in details) + budget = int(route.get("max_estimated_tokens", 0)) + if total > budget: + errors.append(f"route {name} ~{total} exceeds {budget}") + reports.append( + { + "route": name, + "estimated_tokens": total, + "budget": budget, + "files": details, + } + ) + + bootstrap = cost(root / "AGENTS.md") + bootstrap_limit = int( + policy.get("context_targets", {}).get("bootstrap_max_estimated_tokens", 0) + ) + if bootstrap > bootstrap_limit: + errors.append( + f"bootstrap ~{bootstrap} exceeds {bootstrap_limit}" + ) + + output = { + "measurement": "characters/policy-factor, not runtime tokens", + "bootstrap_estimated_tokens": bootstrap, + "routes": reports, + "errors": errors, + "result": "FAIL" if errors else "PASS", + } + except Exception as exc: + output = {"errors": [str(exc)], "result": "FAIL"} + + if args.format == "json": + print(json.dumps(output, indent=2)) + else: + print("Agent context health") + for report in output.get("routes", []): + print( + f"{report['route']}: ~{report['estimated_tokens']} / {report['budget']}" + ) + for error in output.get("errors", []): + print("FAIL:", error) + print("RESULT:", output["result"]) + + return output["result"] != "PASS" + + +if __name__ == "__main__": + sys.exit(main()) From 88af7fbf1d00645a83d3f2a01703d011f4ef9aa7 Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:44:44 +0200 Subject: [PATCH 6/9] fix: split UI design context from behavior context --- .engineering/documentation-policy.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.engineering/documentation-policy.json b/.engineering/documentation-policy.json index e8410096..667d042a 100644 --- a/.engineering/documentation-policy.json +++ b/.engineering/documentation-policy.json @@ -10,7 +10,7 @@ "docs": {"read_when": "Pure documentation/copy without executable or policy changes.", "files": ["AGENTS.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 5000}, "bug": {"read_when": "Meaningful owner-local bug during iteration.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 7000}, "contract": {"read_when": "Shared comparability/evidence/API/storage boundary change.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "docs/architecture.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, - "ui": {"read_when": "Material Performance Lab product-UI iteration; add brand-kit for visual identity and use the integration route when preparing E2E evidence.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "skills/design-product-experience/SKILL.md", "design/ux-contract.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, + "ui": {"read_when": "Material Performance Lab product-UI iteration. This route owns UX/design context; compose with bug for behavior changes, add brand-kit for visual identity, and use integration when preparing E2E evidence.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/design-product-experience/SKILL.md", "design/ux-contract.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, "integration": {"read_when": "Candidate readiness including repository-owned automatic validation.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, "release": {"read_when": "Release readiness including RUNTIME-1 evidence owners.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, "resume": {"read_when": "Resume a multi-session bug/implementation/evidence workstream.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": true, "max_estimated_tokens": 9500} From f6c493ff49864369939bb1b35e19e62e198c4c4d Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:47:41 +0200 Subject: [PATCH 7/9] fix: keep pure UI route within context budget --- .engineering/documentation-policy.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.engineering/documentation-policy.json b/.engineering/documentation-policy.json index 667d042a..16cf9102 100644 --- a/.engineering/documentation-policy.json +++ b/.engineering/documentation-policy.json @@ -10,7 +10,7 @@ "docs": {"read_when": "Pure documentation/copy without executable or policy changes.", "files": ["AGENTS.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 5000}, "bug": {"read_when": "Meaningful owner-local bug during iteration.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 7000}, "contract": {"read_when": "Shared comparability/evidence/API/storage boundary change.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md", "docs/architecture.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, - "ui": {"read_when": "Material Performance Lab product-UI iteration. This route owns UX/design context; compose with bug for behavior changes, add brand-kit for visual identity, and use integration when preparing E2E evidence.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/design-product-experience/SKILL.md", "design/ux-contract.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, + "ui": {"read_when": "Material Performance Lab product-UI iteration. This route owns UX/design context; compose with bug for behavior and commands, add brand-kit for visual identity, and use integration when preparing E2E evidence.", "files": ["AGENTS.md", "skills/design-product-experience/SKILL.md", "design/ux-contract.json"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 12000, "requires_profile": "product-ui"}, "integration": {"read_when": "Candidate readiness including repository-owned automatic validation.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, "release": {"read_when": "Release readiness including RUNTIME-1 evidence owners.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/preflight-change/SKILL.md", ".engineering/e2e.json", "skills/remote-preflight/SKILL.md", "docs/README.md"], "include_scoped_guides": true, "include_workstream": false, "max_estimated_tokens": 10000}, "resume": {"read_when": "Resume a multi-session bug/implementation/evidence workstream.", "files": ["AGENTS.md", ".engineering/commands.json", "skills/structured-change/SKILL.md", "skills/validate-change/SKILL.md"], "include_scoped_guides": true, "include_workstream": true, "max_estimated_tokens": 9500} From c494ccc9e43ad711aa66efa232fe5a5ae09d5f75 Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:50:49 +0200 Subject: [PATCH 8/9] fix: apply Ruff format to operations verifier --- scripts/verify_operations.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scripts/verify_operations.py b/scripts/verify_operations.py index 0837c920..f02a0a0c 100755 --- a/scripts/verify_operations.py +++ b/scripts/verify_operations.py @@ -34,9 +34,7 @@ if ( reporting.get("schema_version") != 1 or reporting.get("format") != "summary_with_evidence_references" - or not required_summary_fields.issubset( - set(reporting.get("required_summary_fields", [])) - ) + or not required_summary_fields.issubset(set(reporting.get("required_summary_fields", []))) ): errors.append("invalid agent_reporting") From 1fe20b80d689d62eb84e326a59965eb3e66c3db2 Mon Sep 17 00:00:00 2001 From: Daniele21 Date: Sun, 6 Sep 2026 10:51:06 +0200 Subject: [PATCH 9/9] fix: apply Ruff format to context verifier --- scripts/verify_agent_context.py | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/scripts/verify_agent_context.py b/scripts/verify_agent_context.py index 2b2325f9..df72b273 100755 --- a/scripts/verify_agent_context.py +++ b/scripts/verify_agent_context.py @@ -30,9 +30,7 @@ def main() -> int: try: root = Path(args.root).resolve() - policy = json.loads( - (root / ".engineering/documentation-policy.json").read_text() - ) + policy = json.loads((root / ".engineering/documentation-policy.json").read_text()) baseline = json.loads((root / ".engineering/baseline.json").read_text()) if policy.get("schema_version") != 2: raise ValueError("documentation policy schema_version must be 2") @@ -49,9 +47,7 @@ def cost(path: Path) -> int: if path not in cache: if not path.is_file(): raise ValueError(f"missing context source: {path.relative_to(root)}") - cache[path] = math.ceil( - len(path.read_text()) / characters_per_token - ) + cache[path] = math.ceil(len(path.read_text()) / characters_per_token) return cache[path] excluded = set(policy.get("context_exclude_directories", [])) @@ -67,10 +63,7 @@ def cost(path: Path) -> int: guide for guide in scoped_guides if affected - and any( - guide.parent == path or guide.parent in path.parents - for path in affected - ) + and any(guide.parent == path or guide.parent in path.parents for path in affected) } workstream = None @@ -123,9 +116,7 @@ def cost(path: Path) -> int: policy.get("context_targets", {}).get("bootstrap_max_estimated_tokens", 0) ) if bootstrap > bootstrap_limit: - errors.append( - f"bootstrap ~{bootstrap} exceeds {bootstrap_limit}" - ) + errors.append(f"bootstrap ~{bootstrap} exceeds {bootstrap_limit}") output = { "measurement": "characters/policy-factor, not runtime tokens", @@ -142,9 +133,7 @@ def cost(path: Path) -> int: else: print("Agent context health") for report in output.get("routes", []): - print( - f"{report['route']}: ~{report['estimated_tokens']} / {report['budget']}" - ) + print(f"{report['route']}: ~{report['estimated_tokens']} / {report['budget']}") for error in output.get("errors", []): print("FAIL:", error) print("RESULT:", output["result"])