From 13f93ec6cf553b7546ddee7c825d5e1866618fad Mon Sep 17 00:00:00 2001 From: qingyingliu Date: Fri, 11 Sep 2026 22:10:20 -0700 Subject: [PATCH] Align agent context with evidence-driven structural work --- AGENTS.md | 23 +++++++++++++++++------ docs/architecture.md | 8 ++++---- tasks/README.md | 17 ++++++++++++----- tasks/T021-single-vm-frame-stack.md | 17 +++++++++++++---- tasks/TEMPLATE.md | 23 ++++++++++++++++++++++- 5 files changed, 68 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ca82706c..80a197c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -211,18 +211,29 @@ changed. ## Suggested Autonomous Loop -1. Pick one task from `tasks/`. For gap work, take quick wins from the - `find-qjsng-gaps.sh` recommendation queue while they exist; when the queue +1. Select work using the relevant context route. For gap work, take quick wins + from the `find-qjsng-gaps.sh` recommendation queue while they exist; when the queue is dominated by hard-hinted broad areas, switch to the next unchecked slice of the highest-priority campaign task in `tasks/README.md` instead - of re-running global probes. -2. Read the related crate, `docs/architecture.md`, and `docs/harness.md`. -3. Implement the smallest useful slice, with tests. + of re-running global probes. For performance work, read + `docs/performance-workflow.md`, then + `tasks/T022-performance-priority-controller.md`, and use the current exact + evidence queue and validated unit plan to select work. Historical task + order or an old "next" label does not establish current priority. +2. Read the related crate and relevant sections of `docs/architecture.md` and + `docs/harness.md`, plus the selected task's design and evidence references. +3. Implement a coherent, verifiable unit toward the task's acceptance criteria, + with tests. For structural changes, define the target architecture and + migration stages before coding; keep commits reviewable without restricting + the design to local patches. Performance migrations follow T022. 4. Run `./scripts/check-touched.sh --staged --explain` before committing; for runtime, parser, or lexer semantics, include the focused Test262 slices it selects or explain why no slice matched. 5. Run `./scripts/check.sh` before final handoff or push. -6. Summarize behavior, risks, verification, and the next useful task. +6. Update the task's current stage, verified revision and evidence, unresolved + issues, and next action so another session can resume. Link performance + plans and decisions instead of duplicating their metrics. Summarize + behavior, risks, verification, and the next useful task. When an LSP tool is available, prefer it over text search for semantic navigation: `findReferences`, `goToDefinition`, and call-hierarchy give diff --git a/docs/architecture.md b/docs/architecture.md index 428346a1..ec949359 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -25,8 +25,8 @@ This repository pins upstream references as git submodules: - `third_party/quickjs-ng`: mature QuickJS-derived engine used as a behavioral oracle and implementation reference. -- `third_party/test262`: official ECMAScript conformance tests used as input for - future subset runners. +- `third_party/test262`: official ECMAScript conformance input consumed by the + subset and baseline runners documented in `docs/harness.md`. These directories are intentionally outside the Cargo workspace. They should not be imported by library crates or edited as part of normal engine work. @@ -125,8 +125,8 @@ small. - Crate unit tests validate local behavior. - Workspace checks validate formatting, lints, and all tests. - QuickJS-NG comparison tests should be added for selected semantic questions. -- Test262 should be introduced through curated allowlists with explicit expected - failures. +- Test262 subset checks use curated allowlists with explicit expected failures; + baseline and gap scans provide broader evidence as documented in the harness. ## Growth Strategy diff --git a/tasks/README.md b/tasks/README.md index fc28ffd1..4aa49d3b 100644 --- a/tasks/README.md +++ b/tasks/README.md @@ -65,6 +65,11 @@ Campaign working rules: ## Performance +Entries below record campaign scope and historical outcomes, not execution +priority. Select new work through `docs/performance-workflow.md` and T022 using +current exact evidence, profiles, and a validated unit plan. Reopening a past +proposal requires the same process. + - `T018-broad-performance.md` — establish the 25-case, eight-family broad black-box benchmark, then drive candidate/QuickJS-NG overall wall ns/op to at most 0.50x without regressing any critical family above 1.00x or weakening @@ -84,11 +89,13 @@ Campaign working rules: costs two name-table hash lookups per store. Verified with the full test suite, Test262 subset, `compare-qjs.sh`, and exact gap scans across eval/module/global-code/with/for/Function; zero regressions. -- `T021-single-vm-frame-stack.md` — active structural performance unit. Move - ordinary synchronous bytecode calls onto one explicit VM frame stack, then - compact that same execution core into register/superinstructions. This is - the next T018 unit; do not create a second independent VM or expand the - direct-leaf eligibility predicate in the frame-stack commit. +- `T021-single-vm-frame-stack.md` — structural proposal with historical + experiments recorded in the task. Move ordinary synchronous bytecode calls + onto one explicit VM frame stack, then + compact that same execution core into register/superinstructions. Further + work requires current T022 selection and validation; do not create a second + independent VM or expand the direct-leaf eligibility predicate in the + frame-stack commit. - `T024-general-register-core.md` — **closed after falsification.** The retained dispatch-preamble split moved the external corpus by only about one percent, below its structural mechanism gate. Preserve its negative evidence; do not diff --git a/tasks/T021-single-vm-frame-stack.md b/tasks/T021-single-vm-frame-stack.md index fd3270ce..cb89eaa1 100644 --- a/tasks/T021-single-vm-frame-stack.md +++ b/tasks/T021-single-vm-frame-stack.md @@ -4,12 +4,21 @@ Remove recursive per-call VM construction from ordinary synchronous bytecode calls, then compact the same execution core into register-oriented or -superinstruction dispatch. This is the next structural T018 unit: it must -produce general external wins while preserving the current zero-gap Test262 -baseline. It is a foundation for the final every-case `<= 0.50x` QuickJS-NG +superinstruction dispatch. This structural T018 proposal must produce general +external wins while preserving the verified Test262 correctness baseline. +It is a foundation for the final every-case `<= 0.50x` QuickJS-NG contract, not permission to specialize benchmark identities or loop shapes. -## Current Evidence +## Selection and Evidence Scope + +The plans and experiment results below are historical records, not current +execution priority or permission to resume an experimental branch. Before new +work, follow `docs/performance-workflow.md` and T022: obtain current exact +evidence, profile the proposed shared cost, and validate a new unit plan. +Historical targets and continuation instructions below do not supersede that +plan or T022's migration and stop rules. + +## Historical Proposal Evidence Trusted-main Performance Preview run `29865188694` at `b8d0c2385128ad823a18488326a64299cffc3b2a` reports: diff --git a/tasks/TEMPLATE.md b/tasks/TEMPLATE.md index 1dfb9302..4f6f6019 100644 --- a/tasks/TEMPLATE.md +++ b/tasks/TEMPLATE.md @@ -2,7 +2,18 @@ ## Goal -Describe the smallest useful behavior change. +Describe the intended outcome and observable success criteria. Let the problem +determine the design scope; keep implementation units independently verifiable. + +## Design and Stages (structural changes only) + +- Target architecture and invariants: +- Design reference: +- Migration stages and their acceptance criteria: + +For performance work, follow `docs/performance-workflow.md` and T022. Link the +validated `tasks/performance-units/.json` plan and decision evidence; +do not duplicate their targets, budgets, or metrics here. ## Scope @@ -40,3 +51,13 @@ Add narrower commands here when useful. ## Notes Record assumptions, expected failures, and follow-up work. + +## Resume State + +- Current status and stage: +- Verified revision (SHA), checks, and evidence references: +- Unresolved issues: +- Next action: + +Update at a handoff or completed unit. Historical results apply only to their +recorded revisions; revalidate selection and evidence before starting new work.