From 14d5c05180b7055773513ed54cd79431d5aa7d18 Mon Sep 17 00:00:00 2001 From: Milind Srivastava Date: Mon, 9 Nov 2026 20:42:33 -0500 Subject: [PATCH] chore(agents): remove all .agents/skills Delete the 19 repo-managed agent skills and drop their entries from .agents/projectasap-managed-files.txt. Co-Authored-By: Claude Opus 5.5 --- .agents/projectasap-managed-files.txt | 19 -- .../skills/asap-api-interface-design/SKILL.md | 17 -- .../asap-architecture-explainer/SKILL.md | 19 -- .agents/skills/asap-code-review/SKILL.md | 103 -------- .agents/skills/asap-correctness-fix/SKILL.md | 19 -- .../skills/asap-debugging-recovery/SKILL.md | 17 -- .../asap-deprecation-migration/SKILL.md | 18 -- .agents/skills/asap-design-review/SKILL.md | 30 --- .../assets/design-document-template.md | 58 ----- .agents/skills/asap-documentation/SKILL.md | 24 -- .agents/skills/asap-exploration/SKILL.md | 18 -- .../asap-implement-existing-design/SKILL.md | 17 -- .agents/skills/asap-issue-authoring/SKILL.md | 29 --- .agents/skills/asap-observability/SKILL.md | 17 -- .../asap-performance-investigation/SKILL.md | 18 -- .agents/skills/asap-pr-authoring/SKILL.md | 90 ------- .../references/key-code-interfaces-example.md | 220 ------------------ .agents/skills/asap-refactor/SKILL.md | 18 -- .../skills/asap-security-hardening/SKILL.md | 18 -- .../asap-source-driven-development/SKILL.md | 17 -- .agents/skills/asap-start-work/SKILL.md | 18 -- .../asap-test-driven-development/SKILL.md | 20 -- 22 files changed, 824 deletions(-) delete mode 100644 .agents/skills/asap-api-interface-design/SKILL.md delete mode 100644 .agents/skills/asap-architecture-explainer/SKILL.md delete mode 100644 .agents/skills/asap-code-review/SKILL.md delete mode 100644 .agents/skills/asap-correctness-fix/SKILL.md delete mode 100644 .agents/skills/asap-debugging-recovery/SKILL.md delete mode 100644 .agents/skills/asap-deprecation-migration/SKILL.md delete mode 100644 .agents/skills/asap-design-review/SKILL.md delete mode 100644 .agents/skills/asap-design-review/assets/design-document-template.md delete mode 100644 .agents/skills/asap-documentation/SKILL.md delete mode 100644 .agents/skills/asap-exploration/SKILL.md delete mode 100644 .agents/skills/asap-implement-existing-design/SKILL.md delete mode 100644 .agents/skills/asap-issue-authoring/SKILL.md delete mode 100644 .agents/skills/asap-observability/SKILL.md delete mode 100644 .agents/skills/asap-performance-investigation/SKILL.md delete mode 100644 .agents/skills/asap-pr-authoring/SKILL.md delete mode 100644 .agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md delete mode 100644 .agents/skills/asap-refactor/SKILL.md delete mode 100644 .agents/skills/asap-security-hardening/SKILL.md delete mode 100644 .agents/skills/asap-source-driven-development/SKILL.md delete mode 100644 .agents/skills/asap-start-work/SKILL.md delete mode 100644 .agents/skills/asap-test-driven-development/SKILL.md diff --git a/.agents/projectasap-managed-files.txt b/.agents/projectasap-managed-files.txt index 8e27cc589..9ccc773bf 100644 --- a/.agents/projectasap-managed-files.txt +++ b/.agents/projectasap-managed-files.txt @@ -1,23 +1,4 @@ AGENTS.md -.agents/skills/asap-correctness-fix -.agents/skills/asap-code-review -.agents/skills/asap-documentation -.agents/skills/asap-design-review -.agents/skills/asap-pr-authoring -.agents/skills/asap-issue-authoring -.agents/skills/asap-start-work -.agents/skills/asap-performance-investigation -.agents/skills/asap-implement-existing-design -.agents/skills/asap-refactor -.agents/skills/asap-exploration -.agents/skills/asap-architecture-explainer -.agents/skills/asap-api-interface-design -.agents/skills/asap-debugging-recovery -.agents/skills/asap-deprecation-migration -.agents/skills/asap-observability -.agents/skills/asap-security-hardening -.agents/skills/asap-source-driven-development -.agents/skills/asap-test-driven-development .github/PULL_REQUEST_TEMPLATE/projectasap.md .github/ISSUE_TEMPLATE/projectasap-correctness-bug.md .github/ISSUE_TEMPLATE/projectasap-performance.md diff --git a/.agents/skills/asap-api-interface-design/SKILL.md b/.agents/skills/asap-api-interface-design/SKILL.md deleted file mode 100644 index 036d61507..000000000 --- a/.agents/skills/asap-api-interface-design/SKILL.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: asap-api-interface-design -description: Design or review ProjectASAP public APIs and interfaces. Use when adding or changing externally consumed functions, data structures, protocols, schemas, or service boundaries. ---- - -# API and interface design - -Define consumers, inputs, outputs, invariants, errors, lifecycle, compatibility, -and versioning. Prefer one authoritative representation and minimize conversion -layers and public surface area. - -Demonstrate why a new interface is necessary and compare it with extending an -existing one. Make invalid states difficult to express where the language and -compatibility constraints permit it. - -Include representative usage and failure examples. Review migration cost, -observability, security boundaries, and how developers verify integrations. diff --git a/.agents/skills/asap-architecture-explainer/SKILL.md b/.agents/skills/asap-architecture-explainer/SKILL.md deleted file mode 100644 index 429ab1879..000000000 --- a/.agents/skills/asap-architecture-explainer/SKILL.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: asap-architecture-explainer -description: Create or update a ProjectASAP code-architecture explainer or HTML visualization. Use when a design or implementation benefits from a maintained visual map; not for routine small changes. ---- - -# Architecture explainer - -Identify the audience and the relationships or execution flow that prose cannot -show clearly. Base the explainer on the current code and authoritative design, -not inferred components. - -Use the smallest useful visual: a flow for execution, a tree for ownership, or a -table for exact mappings. An HTML explainer should be self-contained when -practical, accessible, readable without animation, and accompanied by concise -text that defines scope and terminology. - -After implementation, verify names, links, and flows against the final code. -Store the artifact only when the repository has an agreed documentation location -and the user has authorized the change. diff --git a/.agents/skills/asap-code-review/SKILL.md b/.agents/skills/asap-code-review/SKILL.md deleted file mode 100644 index 5d6091fcc..000000000 --- a/.agents/skills/asap-code-review/SKILL.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: asap-code-review -description: Review ProjectASAP changes for correctness, regressions, unnecessary complexity, and maintainability. Use when asked to review a diff, branch, commit, or pull request. ---- - -# Code review - -When practical, perform final review in a fresh session or use a reviewer that -did not implement the change. Give the reviewer the requirement, diff, and -necessary repository context without priming it with the author's conclusions. -State when review was not independent. - -Review the actual diff and enough surrounding code to validate its assumptions. -Prioritize findings that can cause incorrect behavior, regressions, security -issues, data loss, or operational failure. - -Check whether new conceptual layers, types, or interfaces solve a demonstrated -need. Flag duplicated definitions and avoid recommending architecture whose cost -exceeds the stated requirement. - -Required step: for the interfaces in the PR, self-ask "any ways to simplify -or make them more human-readable?", and give the author choices. For every -type, field, function, method, CLI flag or format the PR adds or changes, -check whether it could be simpler or easier for a human to read: - -- Names are understandable without their comments, and builder or method names - match the field names they set or read. -- Near-duplicate types or functions are merged (for example, two structs that - carry the same fields). -- Reserved or unused fields are removed. -- A struct holding indexes into another list holds the items themselves. -- Counts are integers, not `f64`. -- Display strings live outside planner structs. -- Planner-internal helpers are not methods on public types. -- One function replaces a general function plus a special case of it. - -Report these in a section **Interface simplifications (author's choice)**. Give -each option the current signature, the proposed signature, and the trade-off, -for example: - -- `equal_shares(target, metric, of, shares)` and `equal_share(target, metric, n)` - → one `per_input_target(target, metric, approximate_inputs)`. Trade-off: only - the legacy core uses `shares > 1`; merging needs that core gone first. -- `whole_result_guarantee(guarantee, output_values: Option)` → - `guarantee.over_whole_result(values_per_result: Option)`. Trade-off: a - method on a public type, but a count that cannot be fractional. -- `Pass2Candidate { .. }` and `Pass2Of { .. }`, which carry nearly the same fields - as ready-formatted strings, plus `SharedSummary { group: usize, members: - Vec }`, which indexes into two other lists → one - `Stage1Candidate.pass2: Option` holding the Pass 1 candidate - and the shared build nodes themselves (`shared_builds: - Vec>>`), with display text moved to the devtools. - Trade-off: one more rename across the Pass 2 rules, but readers no longer - follow indexes. - -The author picks; the reviewer does not decide. - -Required step: review the implementation's performance complexity -(efficiency) as well. For the new or changed code paths, check: - -- Time and space complexity: quadratic or exponential loops, subset - enumeration, recomputation inside loops (for example a reachability walk - per node), unnecessary clones of DAGs or roots, and eager enumeration that - could be lazy or capped. -- Allocations on hot paths. -- How the cost scales with the number of queries, candidates and series. - -Each efficiency finding states the complexity, a realistic input size at which -it hurts, and a concrete cheaper alternative. When the cheaper alternative has -a trade-off, give the author choices here too. - -For example: - -- `price` recomputes `query_reach(dag)`, a walk over the whole DAG, for every - MatAtQuery node: O(n · (n + e)) per candidate, times every candidate. At - Example 3's 972 candidates, if each DAG has about 50 nodes, that is about 2.5·10⁶ - node visits instead of 5·10⁴. Alternative: compute it once per candidate - before the loop and pass it in. -- Subset enumeration over one sharing group's members is 2^n. It is capped by - `MAX_GROUP_MEMBERS = 20` (about 10⁶ subsets). Choices: keep the cap and - report a group that hits it, or enumerate lazily and stop at - `--max-combinations`. - -Review output format, in this order: - -1. **Findings**: correctness, regressions and other defects, by severity. -2. **Interface simplifications (author's choice)**: the options above. -3. **Efficiency**: complexity, the input size where it hurts, the - alternative, and choices where there is a trade-off. - -Write "None" under a section with nothing to report. - -Check that tests exercise the changed behavior, including relevant unit and -end-to-end paths. For a bug fix, verify that a regression test would fail without -the production change. - -For materially affected quality attributes—maintainability, debuggability, -scalability, understandability, extensibility, performance, and operability—ask -for measurable evidence where practical. Do not invent numerical precision. - -Report findings first (section 1 above), ordered by severity, with precise -file and line references. State concrete impact and a viable correction. Keep summaries brief; -if no actionable findings remain, say so and identify any material testing gap. diff --git a/.agents/skills/asap-correctness-fix/SKILL.md b/.agents/skills/asap-correctness-fix/SKILL.md deleted file mode 100644 index 053d0e669..000000000 --- a/.agents/skills/asap-correctness-fix/SKILL.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -name: asap-correctness-fix -description: Diagnose and fix correctness bugs in ProjectASAP code using regression-first testing. Use for wrong, inconsistent, or unexpectedly failing behavior; not for performance-only changes or new features. ---- - -# Correctness fixes - -Establish the incorrect observable behavior and identify the violated invariant. -Explain the root cause before changing production code when practical. - -Add the smallest regression test that expresses the expected behavior. Confirm -that it fails for the original implementation; do not weaken assertions or -change the test merely to make it pass. - -Implement the minimally complex fix. Avoid unrelated cleanup and new abstraction -unless the fix concretely requires it. - -Run the focused regression test, related unit tests, and the applicable -end-to-end test. Report the cause, fix, and verification concisely. diff --git a/.agents/skills/asap-debugging-recovery/SKILL.md b/.agents/skills/asap-debugging-recovery/SKILL.md deleted file mode 100644 index 31e454827..000000000 --- a/.agents/skills/asap-debugging-recovery/SKILL.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: asap-debugging-recovery -description: Diagnose ProjectASAP failures and design safe recovery. Use for unexplained errors, incidents, flaky behavior, or recovery-path work before a confirmed correctness fix exists. ---- - -# Debugging and recovery - -Capture the symptom, environment, timing, inputs, and last known good state. -Separate observations from hypotheses and seek the smallest reproduction. - -Instrument or inspect the boundary that distinguishes competing hypotheses. -Avoid broad speculative changes. Once the cause is established, preserve a -regression test or durable diagnostic signal. - -For recovery actions, define affected state, idempotency, retry limits, rollback, -and the stopping condition. Never perform destructive recovery or production -mutation without explicit authorization. Record what evidence confirms recovery. diff --git a/.agents/skills/asap-deprecation-migration/SKILL.md b/.agents/skills/asap-deprecation-migration/SKILL.md deleted file mode 100644 index 285cf67d4..000000000 --- a/.agents/skills/asap-deprecation-migration/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: asap-deprecation-migration -description: Plan or implement ProjectASAP API, data, configuration, or dependency deprecations and migrations. Use when compatibility and staged rollout matter. ---- - -# Deprecation and migration - -Inventory producers, consumers, persisted state, compatibility promises, and -rollback constraints. Define old and new behavior and a measurable completion -condition. - -Prefer staged, reversible migration: introduce compatibility, migrate consumers -and data, observe adoption, then remove the old path. Do not remove compatibility -based only on source search when runtime or external consumers may exist. - -Document operator and developer actions, telemetry, failure recovery, and the -point after which rollback is no longer safe. Test mixed-version behavior where -rolling deployment can create it. diff --git a/.agents/skills/asap-design-review/SKILL.md b/.agents/skills/asap-design-review/SKILL.md deleted file mode 100644 index 6ebaaab23..000000000 --- a/.agents/skills/asap-design-review/SKILL.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -name: asap-design-review -description: Develop or evaluate a ProjectASAP software design, especially new functionality requiring architectural decisions. Use for design documents, architecture proposals, and minimal-complexity reviews. ---- - -# Design review - -Define the user-visible problem, inputs, outputs, constraints, and minimum viable -outcome. Separate required behavior from possible future extensibility. - -For every new layer, abstraction, or public type, state the concrete pressure -that requires it and compare it with the simplest viable alternative. Look for -duplicated concepts across layers and assign one authoritative definition. - -Describe end-to-end behavior and define how it will be tested before detailing -implementation. Cover maintainability, debuggability, understandability, -operational observability, and extensibility to new capabilities and features when the design materially affects them. - -Define success metrics or observable proxies where practical, such as time to -diagnose, extend, or understand the system. State when a quality attribute cannot -be meaningfully measured. Define end-to-end acceptance behavior before -implementation, and distinguish independent test design from tests written after -seeing the implementation. - -Record consequential decisions and rejected alternatives. Add a diagram only -when it makes relationships or execution flow materially clearer than prose. -Surface unresolved decisions that require human product or architecture input. - -For a substantial design document, start from -[assets/design-document-template.md](assets/design-document-template.md). diff --git a/.agents/skills/asap-design-review/assets/design-document-template.md b/.agents/skills/asap-design-review/assets/design-document-template.md deleted file mode 100644 index bb5f985ce..000000000 --- a/.agents/skills/asap-design-review/assets/design-document-template.md +++ /dev/null @@ -1,58 +0,0 @@ -# Design: - -## Audience and context - -Identify whether this is for developers, designers/architects, or researchers. - -## Problem and why now - -What problem exists, for whom, and why is solving it necessary for the MVP? - -## Inputs, outputs, and end-to-end behavior - -Define observable inputs, outputs, current behavior, and intended behavior. - -## Goals and non-goals - -State the minimum successful outcome and deliberately excluded scope. - -## Heilmeier questions - -- What are you trying to do? State it without jargon. -- How is it done today, and what are the limits? -- What is new, and why will it succeed? -- Who cares? If successful, what difference will it make? -- What are the risks and costs? -- How long will it take? -- What are the midterm and final checks for success? - -## Proposed design - -Explain design-level interfaces and data flow. Exclude private implementation -details unless they constrain the design. - -## Minimal complexity - -For each new conceptual layer, abstraction, or public interface, explain why the -simpler alternative is insufficient. Identify the authoritative definition for -concepts that appear across layers. - -## Alternatives and decisions - -Record consequential decisions, rejected alternatives, and trade-offs. - -## Quality attributes and evidence - -Describe material effects on maintainability, debuggability, scalability, -understandability, extensibility, performance, security, and operability. Define -measurements or observable proxies where useful. - -## Acceptance and test design - -Define unit and end-to-end acceptance behavior before implementation. Identify -which tests or reviews will be designed independently. - -## Risks, rollout, and exit criteria - -State failure modes, compatibility concerns, rollback/exit criteria, and open -questions requiring human decisions. diff --git a/.agents/skills/asap-documentation/SKILL.md b/.agents/skills/asap-documentation/SKILL.md deleted file mode 100644 index b5625f4be..000000000 --- a/.agents/skills/asap-documentation/SKILL.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: asap-documentation -description: Write or revise ProjectASAP user, developer, or architecture documentation for a clearly defined audience. Use for documentation work and AI-generated prose cleanup. ---- - -# Documentation - -Identify the intended audience before drafting: - -- User documentation shows supported commands, inputs, outputs, and how to - verify results. Omit private code-level interfaces. -- Developer documentation starts with relevant code architecture, then defines - public inputs, outputs, functions, and data structures, followed by extension - and verification guidance. -- Design or research documentation explains the problem, goals, constraints, - alternatives, decisions, and observable outcomes without depending on a PR or - issue narrative. - -Match established repository terminology and writing style. Remove repetitive, -self-congratulatory, or process-oriented AI prose. Prefer concrete statements, -short sections, and examples that answer likely reader questions. - -Do not expose private interfaces in public developer guidance. Verify commands, -interfaces, and links where practical before presenting them as facts. diff --git a/.agents/skills/asap-exploration/SKILL.md b/.agents/skills/asap-exploration/SKILL.md deleted file mode 100644 index 38296f8f3..000000000 --- a/.agents/skills/asap-exploration/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: asap-exploration -description: Run a bounded ProjectASAP exploration or proof of concept. Use to answer an uncertain technical question before committing to production design. ---- - -# Exploration and proof of concept - -Write the question, hypothesis, success signal, time or scope boundary, and -expected artifact before experimenting. Prefer the cheapest experiment that can -discriminate between alternatives. - -Keep shortcuts and unsupported assumptions visible. Do not present POC code as -production-ready or introduce it into production paths without explicit -authorization and normal design, testing, security, and maintenance review. - -Conclude with evidence, limitations, rejected hypotheses, and a recommendation: -adopt, investigate further, or stop. Separate reusable findings from disposable -experimental code. diff --git a/.agents/skills/asap-implement-existing-design/SKILL.md b/.agents/skills/asap-implement-existing-design/SKILL.md deleted file mode 100644 index ab4d365f8..000000000 --- a/.agents/skills/asap-implement-existing-design/SKILL.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: asap-implement-existing-design -description: Implement ProjectASAP functionality from an approved existing design. Use when interfaces and intended behavior are already decided; route unresolved architecture back to design review. ---- - -# Implement an existing design - -Locate the authoritative design and restate its observable inputs, outputs, -invariants, and acceptance behavior. Do not silently redesign public interfaces. - -Implement the smallest vertical slice that satisfies the approved design. Keep -concept definitions authoritative across layers and avoid speculative extension -points. Add focused unit and end-to-end tests with short behavior descriptions. - -If implementation exposes a material design gap or contradiction, stop that -portion, document the decision needed, and request design review instead of -embedding an unreviewed architectural choice. diff --git a/.agents/skills/asap-issue-authoring/SKILL.md b/.agents/skills/asap-issue-authoring/SKILL.md deleted file mode 100644 index f26a41fe5..000000000 --- a/.agents/skills/asap-issue-authoring/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: asap-issue-authoring -description: Write ProjectASAP GitHub issues that a reader understands without prior context. Use when asked to open, draft or rewrite an issue, a tracking issue, or a follow-up. ---- - -# Issues - -Write the issue top-down so a reader new to the topic understands the problem -before the solution: - -1. **Problem, by example.** Start with one concrete, minimal example of the - problem: the input (a query, a workload, a command, a data shape), what - happens today, and what should happen instead. Use real syntax and real - numbers; show the current and the desired plan, output, or behavior side by - side when that is clearer. Prefer one small example over an abstract - description, and add a second only when it shows a different case. -2. **Why it happens / why it isn't done today.** The cause in the code or the - design, named precisely (types, functions, rules), and what already works - nearby. -3. **Proposal or goal.** What a fix or feature would change, at the level of - interfaces and behavior, with alternatives when the choice is open. -4. **Scope and acceptance.** What is in and out of scope, and the test that - would show it is done (for a bug, the regression test that fails today). -5. **Status and related work.** Decisions already made (with dates), why it is - deferred if it is, and links to related issues and PRs. - -Never invent behavior or numbers: derive the example from the code, a run, or -a measurement, and say which. Keep people and company names out. Use the -repository's issue templates when one fits, and keep their sections. diff --git a/.agents/skills/asap-observability/SKILL.md b/.agents/skills/asap-observability/SKILL.md deleted file mode 100644 index 8e7e29f5f..000000000 --- a/.agents/skills/asap-observability/SKILL.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: asap-observability -description: Design or review ProjectASAP logs, metrics, traces, and diagnostic signals. Use for instrumentation and operational-debuggability changes. ---- - -# Observability - -Start from operator questions and failure modes. Define which signal answers -each question, its labels or fields, units, ownership, and expected cardinality. - -Prefer stable semantic events over noisy implementation logs. Avoid secrets, -personal data, unbounded labels, duplicated signals, and instrumentation that -materially changes hot-path behavior without measurement. - -Show how to interpret and verify each new signal, including healthy and failure -examples. Cover dashboards or alerts only when an actionable response and owner -exist. diff --git a/.agents/skills/asap-performance-investigation/SKILL.md b/.agents/skills/asap-performance-investigation/SKILL.md deleted file mode 100644 index 6567ad735..000000000 --- a/.agents/skills/asap-performance-investigation/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: asap-performance-investigation -description: Investigate and improve ProjectASAP performance with reproducible before-and-after measurements. Use for latency, throughput, memory, CPU, or scalability work; not for unmeasured cleanup. ---- - -# Performance investigation - -Define the metric, workload, environment, baseline, and acceptable regression -budget before optimizing. Reproduce the bottleneck and profile the relevant path -rather than inferring it from code shape alone. - -Preserve correctness tests. Make the smallest change supported by evidence, then -repeat the same measurement enough times to expose variance. Report raw context, -before and after results, uncertainty, trade-offs, and any shifted bottleneck. - -Use language-specific complexity metrics, including `rust-code-analysis`, only -when the metric answers a stated question. Do not treat a score as a quality gate -without a repository-approved threshold. diff --git a/.agents/skills/asap-pr-authoring/SKILL.md b/.agents/skills/asap-pr-authoring/SKILL.md deleted file mode 100644 index 0b7f1e34e..000000000 --- a/.agents/skills/asap-pr-authoring/SKILL.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -name: asap-pr-authoring -description: Prepare concise ProjectASAP commits and pull-request descriptions. Use when asked to organize commits, draft a PR, or explain a completed change for review. ---- - -# Commits and pull requests - -Organize commits at incremental logical boundaries. Do not include unrelated -working-tree changes or rewrite existing history without explicit authorization. - -Write the pull-request description top-down: - -1. **Why**: the user, design, correctness, or MVP need. -2. **What**: the observable behavior and scope changed. -3. **How**: the core implementation or algorithm, without narrating every file. -4. **Key code interfaces added / modified**: the public interfaces the PR adds, - changes, or removes: types, functions, methods, traits, fields, enum - variants, module paths, CLI flags, and wire, file, or document formats. - Write "None" when no interface changes (for example, documentation or tests - only). Use this layout: - - Group by source file. Head each group with links to the files at a fixed - commit, i.e. a permalink to the PR head or the merge commit, not a branch. - - Under each group, put one fenced code block in the source language. It - holds the real declarations copied from the diff: type definitions with - their fields or variants, and function, method and trait signatures with - bodies elided (`;` or `/* ... */`). Mark each change with a trailing - comment (`// new`, `// was X`, `// removed`). - - Never collapse members into a comment such as `// ...` or - `/* A, B, C unchanged */`; readers take a collapsed list for a removed - one. When a type is shown, list each of its variants or fields with a - one-line `///` and a marker (`// unchanged`, `// new`, `// was X`, - `// removed`), and put a `///` on the type itself saying whether the type - stays or is removed. - - Explain every interface. Above each declaration, write a short `///` (or - the language's doc-comment form) saying what it is, what it is for, and - when a caller uses it. For an enum variant or an error, say when it is - produced and whether it reflects bad input, an unsatisfiable request, or an - internal bug. For a field, say what it holds and its default. Keep each - explanation to one or two lines. - - End with a **Usage** example that is end to end, not isolated calls. - Start from what the user writes (the workload entry or query with its - requirements and the data facts it needs, or the CLI or devtool - invocation). Walk through where the system reaches this PR's interfaces: - which stage or component calls them, and with what values. End at what the - user gets back (for a planner change: the selected plan, its sizes and - cost, and each candidate's accepted or rejected line). Every variable gets - a comment where it is defined saying what it holds and what it is used for - later in the flow; no bare `let x = f(...)` lines, and never a bare - internal call such as `size_params(...)` without the flow that reaches it. - Use real syntax and numbers, and check them by compiling and running the - example (a test, an example binary or a devtool run) at the linked commit. - See [references/key-code-interfaces-example.md](references/key-code-interfaces-example.md). -5. **Major algorithm changes**: for each algorithm the PR adds, replaces, or - changes in a way that alters its results or cost (search, selection, pruning, - sizing, accuracy composition, cost model, scheduling, execution kernels), - write a short subsection: - - **Problem**: what the old algorithm got wrong or could not do, with one - concrete input and its observed outcome. - - **Before / after**: the old and new algorithm as numbered steps or short - pseudocode, naming the functions that implement them. - - **Correctness**: the invariant, guarantee, or proof sketch that the new - algorithm keeps (for example, exactness against exhaustive search, an error - bound, or a cost that never exceeds the old one), and the tests that check - it. - - **Complexity**: time and memory before and after, in terms of the inputs - that drive them, plus a measured number on a real workload when there is - one. - - **Assumptions and limits**: when the algorithm does not apply or falls back, - and what it deliberately leaves out. - Write "None" when the PR changes no algorithm (for example, a rename, - documentation, tests, or plumbing only). Keep **How** as the overview and put - the algorithmic detail here. -6. **Before this PR**: the previous end-to-end behavior, limitation, failure - mode, architecture, or workflow. -7. **After this PR**: the new end-to-end behavior and what users, developers, or - operators can do differently. -8. **Verification**: focused tests and applicable end-to-end evidence. - -Include a compact before/after example, screenshot, or diagram when it provides -real evidence or makes behavior easier to understand. For significant design -changes, summarize architectural decisions and alternatives. - -Use the evidence form appropriate to the change: screenshots for visual output, -execution examples for behavior, measurements for performance, or diagrams for -architecture. Explicitly mark an evidence type as not applicable instead of -fabricating it. - -State limitations and follow-up work explicitly. Never fabricate screenshots, -test results, measurements, or human approval. Creating or publishing a commit or -PR still requires user authorization. diff --git a/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md b/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md deleted file mode 100644 index fdb14c7a8..000000000 --- a/.agents/skills/asap-pr-authoring/references/key-code-interfaces-example.md +++ /dev/null @@ -1,220 +0,0 @@ -# Example: Key code interfaces section - -An excerpt from ASAPPlanner #715 (HLL sized from (ε, δ)) in the expected layout: -links per file group at a fixed commit, real declarations with every member -listed and marked, a `///` on every interface, and an end-to-end usage example -whose every variable is commented and whose numbers come from running it. - -## Key code interfaces added / modified - -[`crates/types/src/post_asap/sketch.rs`](https://github.com/ProjectASAP/ASAPPlanner/blob/1b5d9577705c7664e711eef9a83ba4f2def0c1da/crates/types/src/post_asap/sketch.rs) - -```rust -/// Concrete parameters of one sketch instance; equality compares the built shape. -/// The type stays; this PR adds a field to `Hll` and `Kmv`. -pub enum SketchParams { - /// A UnivMon universal sketch (frequency moments, entropy, distinct count). - UnivMon { // unchanged - /// Top-k heap entries per layer. - heap_size: u32, // unchanged - /// Rows of each layer's Count Sketch. - sketch_rows: u32, // unchanged - /// Columns of each layer's Count Sketch. - sketch_cols: u32, // unchanged - /// Number of sampling layers. - layers: u8, // unchanged - /// The δ the heap was sized for when it answers a distinct count; None = no distinct guarantee. - distinct_failure_probability: Option, // unchanged - }, - /// A KLL quantile sketch. - Kll { // unchanged - /// Compactor capacity. - k: u32, // unchanged - /// The δ `k` was sized for when below 0.01; None = the empirical 99% calibration. - failure_probability: Option, // unchanged - }, - /// A Count-Min sketch. - Cms { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - }, - /// A HyperLogLog distinct-count sketch. - Hll { // unchanged variant; gains relative_error - /// `m = 2^precision` registers. - precision: u8, // unchanged - /// The relative error `precision` was sized for: its guarantee's error bound, - /// at which its failure probability is evaluated. - #[serde(default, skip_serializing_if = "Option::is_none")] - relative_error: Option, // new: the ε precision was sized for; None = RSE 1.04/√m; ignored by equality - }, - /// A DDSketch relative-error quantile sketch. - DDSketch { // unchanged - /// Relative accuracy of each bucket. - alpha: f64, // unchanged - }, - /// A Count-Min sketch with a top-k heap. - CmsWithHeap { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - /// Heap entries. - heap_size: u32, // unchanged - }, - /// A KMV (k minimum values) distinct-count sketch. - Kmv { // unchanged variant; gains relative_error - /// The number of smallest hashes kept. - k: u32, // unchanged - /// The relative error `k` was sized for: its guarantee's error bound, at which - /// its failure probability is evaluated. - #[serde(default, skip_serializing_if = "Option::is_none")] - relative_error: Option, // new: the ε k was sized for; None = RSE 1/√(k-2); ignored by equality - }, - /// A Theta distinct-count sketch. - Theta { // unchanged - /// Nominal entries. - k: u32, // unchanged - }, - /// A Count Sketch. - CountSketch { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - }, - /// A Count Sketch with a top-k heap. - CountSketchWithHeap { // unchanged - /// Counters per row. - width: u32, // unchanged - /// Rows. - depth: u32, // unchanged - /// Heap entries. - heap_size: u32, // unchanged - }, -} -``` - -[`crates/asap-aware-mapping/src/accuracy/estimators/hll.rs`](https://github.com/ProjectASAP/ASAPPlanner/blob/1b5d9577705c7664e711eef9a83ba4f2def0c1da/crates/asap-aware-mapping/src/accuracy/estimators/hll.rs) - -```rust -/// Pass 1's classic HLL precision for relative error `eps` at failure probability -/// `delta`, without data; plan selection later enlarges it for the source's bound. -pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8; // was hll_precision(eps) -/// Classic HLL's distinct-count guarantee over `source`'s own rows, with δ left -/// symbolic in the source's distinct bound; `None` for a precision outside the contract. -pub(crate) fn classic_guarantee( - precision: u8, - relative_error: Option, // new parameter - source: &str, -) -> Option; -/// The failure probability given the source's distinct bound; 1 (no certificate) -/// outside the contract's range. Plan selection calls it to bind the symbol. -pub(crate) fn classic_failure_probability( - precision: u8, - relative_error: f64, // new parameter - max_distinct: u64, -) -> f64; -``` - -Usage, end to end: one SQL distinct count with ε = 0.05 and δ = 0.01, planned -through `run_planning_stages` at the merge commit. It starts from what the user -writes, names the stage that calls each interface above with its values, and -ends at what the user gets back. - -```rust -// 1. What the user writes: one dashboard panel, the number of distinct source IPs -// in the last minute, refreshed every 10 s, within ε = 0.05 relative error -// with failure probability δ = 0.01. -let panel = RepeatingEntry { - query: Query("SELECT COUNT(DISTINCT src_ip) FROM flows WHERE ts >= now() - INTERVAL '1 minute'".into()), - demand: RepeatedDemand::FixedInterval(RepetitionInterval(10_000)), - requirements: QueryRequirements { - // The target every candidate plan's guarantee is checked against in Stage 3. - accuracy: AccuracyRequirement::Explicit(RequestedAccuracy { - scope: AccuracyScope::WholeResult, - ..RequestedAccuracy::epsilon_delta(0.05, 0.01) - }), - response_latency: LatencyRequirement::Unspecified, - }, - predictability: Predictability::Predictable { known_at: None }, - time_selection: TimeSelection { - scope: QueryTimeScope::RealTime, - lookback: Some(DurationMs(60_000)), - as_of: None, - }, -}; -// 2. What the deployment declares about the data: at most 1,000 distinct items in -// one evaluation of any distinct count over `flows` (the SQL table name is the -// source key). Stage 1 never reads it; Stage 3 uses it to turn HLL's symbolic δ -// into a number. -let data = DataWorkload { - arrival: DataArrival::ContinuouslyIngesting, - ingestion_rate: declared(Rate(1_000_000.0 / 15.0)), - max_distinct_per_evaluation: declared(BTreeMap::from([("flows".into(), 1_000)])), - ..Default::default() -}; -// The planner input: the query workload plus the data facts. -let workload = PlanningWorkload { - query_workload: QueryWorkload { - language: QueryLanguage::SQL(SqlDialect::DataFusionSQL), - query_batch: None, - repeating_queries: Some(vec![panel]), - }, - data_workload: Some(data), -}; -// The `flows(ts, src_ip)` schema the SQL frontend resolves the query against. -let catalog = asap_frontend_sql::SqlCatalog::new().with_table( - "flows", - Schema::with_time_index( - vec![ - Field::plain("ts", DataType::Timestamp, false), - Field::plain("src_ip", DataType::Utf8, false), - ], - 0, - vec![], - ), -); - -// 3. Stage 0 (query-language frontends): `roots` holds one plan root per workload entry, -// here a distinct count (`aggregate:cardinality`) over a scan of `flows`; Stage 1 reads it. -let roots = lower_sql_roots(&workload, &catalog)?; - -// 4. Stages 1-3 in one call. `run` holds every stage's candidates and the selection, -// which steps 5 and 6 read. -let run = run_planning_stages(&workload, roots, None).expect("Pass 1 enumerates"); -// Stage 1 / Pass 1 offers L1 exact, L2 HLL, L3 KMV and L4 UnivMon for the count. -// For L2 it calls `size_params(Hll, &intent, 0.05, 0.01)`: the smallest m with -// m ≥ 1/(2ε²δ) whose tail certifies δ at ε for every bound up to ⌈1/ε⌉ = 20, -// i.e. `Hll { precision: 15, relative_error: Some(0.05) }`. -// It then calls `hll::classic_guarantee(15, Some(0.05), "flows")`: error bound -// 0.05 (relative), and δ left as the symbol -// `classic_hll_failure_probability[p=15,eps=0.05](max_distinct[flows])`, -// because the distinct count it depends on is a data fact Stage 1 does not read. -// L3 needs no bound: `Kmv { k: 4323 }` certifies δ = 0.009996 for any count. -// -// 5. Stage 3 (plan selection) binds the symbol: it parses (15, 0.05, "flows"), reads -// the bound 1,000 from `max_distinct_per_evaluation`, and calls -// `hll::classic_failure_probability(15, 0.05, 1_000)` = 0.0058 ≤ 0.01, so P2 (HLL) -// meets the target without enlargement (`precision_for` keeps 15; precision 15 -// certifies bounds up to 1,176, precision 18 up to 9,636). -// `selection`: Stage 3's result (selected id, costs, rejections); Err only when no candidate is valid. -let selection = run.stage3_plan_selection?; - -// 6. What the user gets back. -// `selected`: the cheapest valid plan. The analytical cost model prices the -// exact plan P1 at 1.7600001 cost/s and HLL (P2) and KMV (P3) at 1.7600003 (the -// same scan and build, plus an estimate node), so exact is selected; HLL is valid -// but costlier. -assert_eq!(selection.selected, "P1"); -// `costs`: one entry per valid candidate (P1-P4; UnivMon P4 costs 2.96). -assert_eq!(selection.costs.len(), 4); -// `rejected`: P2's line is `valid: true, reason: "costlier: 1.760 vs 1.760 -// cost_per_second"`. With a bound of 10,000 instead, P2 is `valid: false`, -// "failure probability Some(1.0), which misses target ..." (beyond 9,636 even at -// precision 18); with no bound, "failure probability None". -// `hll`: the HLL candidate's line in the selection report, read to show why it was not chosen. -let hll = selection.rejected.iter().find(|r| r.id == "P2").unwrap(); -assert!(hll.valid && hll.reason.starts_with("costlier")); -``` diff --git a/.agents/skills/asap-refactor/SKILL.md b/.agents/skills/asap-refactor/SKILL.md deleted file mode 100644 index c101b1f41..000000000 --- a/.agents/skills/asap-refactor/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: asap-refactor -description: Refactor ProjectASAP code while preserving observable behavior and reducing demonstrated complexity. Use for structural cleanup without intended feature changes. ---- - -# Refactor - -State the concrete maintenance, duplication, comprehension, or extension problem -and the behavior that must remain unchanged. Establish relevant tests before -structural changes. - -Prefer removal, consolidation, and one authoritative conceptual definition over -new layers. Keep the diff focused and separate behavior changes when practical. -Use complexity metrics only as supporting evidence, not as a substitute for -review. - -Verify unit and end-to-end behavior after the change. Report before and after -structure, what became simpler, and any compatibility or migration effect. diff --git a/.agents/skills/asap-security-hardening/SKILL.md b/.agents/skills/asap-security-hardening/SKILL.md deleted file mode 100644 index d3b763460..000000000 --- a/.agents/skills/asap-security-hardening/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: asap-security-hardening -description: Review or improve ProjectASAP security boundaries and misuse resistance. Use for authentication, authorization, secrets, untrusted input, dependency, or threat-model work. ---- - -# Security hardening - -Define assets, trust boundaries, attacker capabilities, entry points, and likely -failure impact. Prioritize reachable risks over generic checklists. - -Apply least privilege, explicit authorization, safe parsing, secret hygiene, and -secure failure defaults. Preserve compatibility only when it does not retain the -vulnerability. Avoid exposing exploit details beyond what remediation and review -require. - -Add tests for the security invariant and negative cases. Document residual risk, -deployment considerations, and any credential rotation or operational action -that requires human authorization. diff --git a/.agents/skills/asap-source-driven-development/SKILL.md b/.agents/skills/asap-source-driven-development/SKILL.md deleted file mode 100644 index 5ac831297..000000000 --- a/.agents/skills/asap-source-driven-development/SKILL.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: asap-source-driven-development -description: Implement ProjectASAP work that depends on an external specification, paper, upstream source, or authoritative documentation. Use when fidelity and provenance matter. ---- - -# Source-driven development - -Identify the authoritative source and exact version. Separate requirements -stated by the source from local interpretation and verify unstable technical -facts against primary documentation. - -Map source concepts to local interfaces without copying unnecessary structure. -Record ambiguous or intentionally divergent behavior and the reason for it. - -Build conformance examples or tests for the relevant requirements. Respect -licenses and quotation limits; link or cite sources instead of embedding large -copied passages. diff --git a/.agents/skills/asap-start-work/SKILL.md b/.agents/skills/asap-start-work/SKILL.md deleted file mode 100644 index bc1588665..000000000 --- a/.agents/skills/asap-start-work/SKILL.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: asap-start-work -description: Prepare an isolated ProjectASAP Git worktree before implementation. Use when starting repository changes; skip only when the user specifies another workspace strategy. ---- - -# Start work - -Inspect repository status without modifying the current working tree. Preserve -all existing and untracked user changes. - -Unless the user specifies otherwise, fetch `origin`, verify `origin/main`, and -create a dedicated worktree and task branch from that remote commit. Choose a -worktree path and branch name scoped to the task, check for collisions first, and -report both to the user. - -Do not delete, overwrite, prune, or reuse an occupied worktree without explicit -authorization. If network access or `origin/main` is unavailable, report the -condition and use another base only with user direction. diff --git a/.agents/skills/asap-test-driven-development/SKILL.md b/.agents/skills/asap-test-driven-development/SKILL.md deleted file mode 100644 index 9ce27d2b3..000000000 --- a/.agents/skills/asap-test-driven-development/SKILL.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: asap-test-driven-development -description: Define ProjectASAP acceptance behavior and tests before implementation. Use for new behavior where test-first development or independent test design is requested or required. ---- - -# Test-driven development - -Derive observable behavior from the requirement or approved design before -examining a proposed implementation when practical. Cover representative success, -boundary, and failure behavior at the lowest useful layer plus the applicable -end-to-end path. - -Give each test a one- or two-line behavioral purpose. Confirm a new test fails -for the expected reason before implementing the behavior, then make the smallest -production change that passes it without weakening assertions. - -Prefer independent test design for consequential work. State who or what designed -the tests and never label them independent when the implementation author also -defined them. Run focused and relevant regression suites and report actual -results.