dsh-aris-panel 0.1.0

package/skills/skills-codex/comm-lit-review/references/source-policy.md

@@ -0,0 +1,99 @@
+# Source Policy
+
+## Default priority
+
+1. `IEEE Xplore`
+2. `ScienceDirect`
+3. `ACM Digital Library`
+4. Domain-appropriate primary venues and broader web only when the first three are insufficient
+5. Preprints only when necessary
+
+## Database intent
+
+- `IEEE Xplore`: best default for wireless, communications, PHY/MAC, networking, signal processing, NTN, and protocol work.
+- `ScienceDirect`: useful for communications journals, Computer Networks, Ad Hoc Networks, Physical Communication, and systems papers published through Elsevier venues.
+- `ACM Digital Library`: important second-line source for networking systems, transport protocols, mobile systems, and Internet measurement once the first two tiers are exhausted.
+
+## When to widen beyond IEEE, ScienceDirect, and ACM
+
+Widen only if one of these is true:
+
+- the topic is heavily systems-oriented and canonical papers live in ACM or USENIX venues
+- the recent frontier has not yet appeared in the three preferred databases
+- the user explicitly asks for a broader sweep
+
+When widening, prefer:
+
+- `dl.acm.org`
+- official conference pages
+- publisher DOI pages
+- authors' public PDFs that correspond to already-identified formal papers
+- carefully targeted web search rather than open-ended browsing
+
+## Search layering
+
+Always layer the search in two dimensions:
+
+1. **database layer**
+   - IEEE
+   - ScienceDirect
+   - ACM
+   - broader web
+2. **venue layer within each database**
+   - top journals and top conferences
+   - mainstream strong venues
+   - all other relevant formal venues
+
+Do not jump straight to broad web search if the topic can still be served by a higher database or venue tier.
+
+## Venue policy
+
+Follow [venue-tiering.md](venue-tiering.md).
+
+The default behavior is:
+
+- look for Tier A papers first
+- expand to Tier B if the set is too small
+- expand to Tier C if the topic is niche or the user wants broader coverage
+
+If the user explicitly asks for `top venues only`, `top journals only`, or `top conferences only`, treat Tier A as a hard filter rather than a ranking hint.
+
+## Publication policy
+
+- Prefer peer-reviewed journals and major conferences.
+- Label workshop papers as `workshop`.
+- Label arXiv-only or author-hosted versions as `preprint`.
+- If both a preprint and formal version exist, cite the formal version first.
+
+## Time-window policy
+
+If the user does not specify a year range:
+
+- include a short foundational set
+- include a recent set
+- separate them explicitly in the synthesis
+
+Recommended default split:
+
+- `foundational`: before 2022
+- `recent`: 2022 to present
+
+## Search-query guidance
+
+Build queries from:
+
+- system name: `LEO`, `NTN`, `Wi-Fi 7`, `NR sidelink`
+- technical problem: `rate adaptation`, `congestion control`, `beam hopping`
+- layer name: `PHY`, `MAC`, `transport`, `cross-layer`
+- method family if relevant: `RL`, `learning-based`, `optimization`, `prediction`
+
+Avoid overly broad queries such as:
+
+- `wireless AI`
+- `satellite network paper`
+
+Prefer tighter queries such as:
+
+- `LEO satellite congestion control IEEE`
+- `NTN rate adaptation IEEE Xplore`
+- `Wi-Fi rate adaptation ScienceDirect`

package/skills/skills-codex/comm-lit-review/references/venue-tiering.md

@@ -0,0 +1,112 @@
+# Venue Tiering
+
+Use this file to rank communications-domain literature before broadening the search.
+
+The goal is not to claim a universal ranking. The goal is to give the skill a stable, practical search order:
+
+1. top communications and networking venues
+2. strong mainstream venues
+3. the rest of the relevant formal literature
+
+By default, these tiers are search priorities rather than strict eligibility rules. Only treat Tier A as a hard boundary if the user explicitly requests top-only search.
+
+## Tier A: top journals and top conferences
+
+Start here unless the user asks for a broad sweep immediately.
+
+### Journals
+
+- `IEEE Journal on Selected Areas in Communications (JSAC)`
+- `IEEE/ACM Transactions on Networking (ToN)`
+- `IEEE Transactions on Wireless Communications (TWC)`
+- `IEEE Transactions on Communications (TCOM)`
+- `IEEE Transactions on Mobile Computing (TMC)` when the topic is mobile or wireless systems
+- `IEEE Transactions on Network and Service Management (TNSM)` when the topic is network control or management
+
+### Conferences
+
+- `ACM SIGCOMM`
+- `USENIX NSDI`
+- `ACM MobiCom`
+- `ACM CoNEXT`
+- `IEEE INFOCOM`
+
+## Tier B: mainstream strong venues
+
+Use these after Tier A, or earlier if the topic naturally lands here.
+
+### Journals
+
+- `IEEE Transactions on Vehicular Technology (TVT)`
+- `IEEE Wireless Communications Letters (WCL)`
+- `IEEE Communications Letters`
+- `Computer Networks`
+- `Computer Communications`
+- `Ad Hoc Networks`
+- `Physical Communication`
+
+### Conferences
+
+- `IEEE ICC`
+- `IEEE GLOBECOM`
+- `IEEE WCNC`
+- `IEEE PIMRC`
+- `ACM MobiHoc`
+- topic-specific satellite, wireless, or vehicular conferences with established proceedings
+
+## Tier C: broad relevant formal venues
+
+Use these when the higher tiers are sparse or when the user asks for exhaustive coverage.
+
+- other IEEE journals and transactions related to communications, networking, signal processing, and aerospace
+- other Elsevier journals relevant to the topic
+- other ACM conferences and workshops that are clearly on-topic
+- domain-specific venues in satellite, optical, vehicular, IoT, aerial, or edge communications
+
+## Escalation rule
+
+Within a given topic:
+
+- search Tier A first
+- if too few relevant papers appear, expand to Tier B
+- if still sparse, expand to Tier C
+- only after that use broader web search for gaps, forward citations, or hard-to-find formal papers
+
+## Topic-specific notes
+
+### Wireless PHY/MAC
+
+Give extra weight to:
+
+- `TWC`
+- `TCOM`
+- `JSAC`
+- `INFOCOM`
+- `MobiCom`
+- `ICC/GLOBECOM/WCNC` once the top tier is exhausted
+
+### Networking / transport
+
+Give extra weight to:
+
+- `SIGCOMM`
+- `NSDI`
+- `CoNEXT`
+- `ToN`
+- `INFOCOM`
+- `Computer Networks`
+
+### Satellite / NTN
+
+Give extra weight to:
+
+- `JSAC`
+- `TWC`
+- `TCOM`
+- `TVT`
+- `INFOCOM`
+- strong satellite or aerospace communications venues once top general venues are exhausted
+
+### Learning for communications
+
+If the center of gravity is still a communication system problem, keep the same venue ladder. Do not jump to generic ML venues unless the paper's actual home community is no longer communications.

package/skills/skills-codex/deepxiv/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: "deepxiv"
+description: "Search and progressively read open-access academic papers through DeepXiv. Use when the user wants layered paper access, section-level reading, trending papers, or DeepXiv-backed literature retrieval."
+---
+
+# DeepXiv Paper Search & Progressive Reading
+
+Search topic or paper ID: $ARGUMENTS
+
+## Role & Positioning
+
+DeepXiv is the progressive-reading literature source:
+
+| Skill | Source | Best for |
+|-------|--------|----------|
+| `/arxiv` | arXiv API | Batch search, PDF download, metadata |
+| **`/deepxiv`** | **DeepXiv SDK** | **Progressive section-level reading** |
+| `/semantic-scholar` | S2 API | Published venue metadata, citation counts |
+| `/alphaxiv` | alphaxiv.org | Instant LLM-optimized summary of one paper, with LaTeX source fallback |
+
+Use DeepXiv when you want to inspect papers incrementally instead of loading the full text immediately.
+
+## Constants
+
+- **DEEPXIV_FETCHER** — canonical name `deepxiv_fetch.py`, resolved per
+  [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2
+  (Codex-side chain: `$ARIS_REPO/tools/` → `tools/` → `~/.codex/skills/deepxiv/`).
+  Policy D1 — if unresolved (canonical chain exhausted), fall back to raw `deepxiv` CLI.
+- **MAX_RESULTS = 10** — Default number of search results.
+
+> Overrides (append to arguments):
+> - `/deepxiv "agent memory" - max: 5`
+> - `/deepxiv "2409.05591" - brief`
+> - `/deepxiv "2409.05591" - head`
+> - `/deepxiv "2409.05591" - section: Introduction`
+> - `/deepxiv "trending" - days: 14 - max: 10`
+> - `/deepxiv "karpathy" - web`
+> - `/deepxiv "258001" - sc`
+
+## Setup
+
+DeepXiv is optional:
+
+```bash
+pip install deepxiv-sdk
+```
+
+On first use, `deepxiv` auto-registers a free token and stores it in `~/.env`.
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for:
+
+- a paper topic, arXiv ID, or Semantic Scholar ID
+- `- max: N`
+- `- brief`
+- `- head`
+- `- section: NAME`
+- `- trending`
+- `- days: 7|14|30`
+- `- web`
+- `- sc`
+
+If the input looks like an arXiv ID and no explicit mode is provided, default to `brief`.
+
+### Step 2: Locate the Adapter
+
+Resolve `$DEEPXIV_FETCHER` via the canonical strict-safe Codex chain
+(see [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2):
+
+```bash
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+DEEPXIV_FETCHER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/deepxiv_fetch.py" ] && DEEPXIV_FETCHER="$ARIS_REPO/tools/deepxiv_fetch.py"
+[ -z "$DEEPXIV_FETCHER" ] && [ -f tools/deepxiv_fetch.py ] && DEEPXIV_FETCHER="tools/deepxiv_fetch.py"
+[ -z "$DEEPXIV_FETCHER" ] && [ -f ~/.codex/skills/deepxiv/deepxiv_fetch.py ] && DEEPXIV_FETCHER="$HOME/.codex/skills/deepxiv/deepxiv_fetch.py"
+
+# Smoke test (optional): resolved-but-non-functional adapter is not currently auto-demoted.
+if [ -n "$DEEPXIV_FETCHER" ]; then
+  echo "DeepXiv adapter resolved at: $DEEPXIV_FETCHER" >&2
+else
+  echo "DeepXiv adapter unresolved (canonical chain exhausted); raw deepxiv CLI fallback will be used." >&2
+fi
+```
+
+If the adapter is unresolved, fall back to raw `deepxiv` commands.
+
+### Step 3: Execute the Minimal Command
+
+```bash
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" search "QUERY" --max MAX_RESULTS
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" paper-brief ARXIV_ID
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" paper-head ARXIV_ID
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" paper-section ARXIV_ID "SECTION_NAME"
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" trending --days 7 --max MAX_RESULTS
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" wsearch "QUERY"
+[ -n "$DEEPXIV_FETCHER" ] && python3 "$DEEPXIV_FETCHER" sc "SEMANTIC_SCHOLAR_ID"
+```
+
+Fallbacks:
+
+```bash
+deepxiv search "QUERY" --limit MAX_RESULTS --format json
+deepxiv paper ARXIV_ID --brief --format json
+deepxiv paper ARXIV_ID --head --format json
+deepxiv paper ARXIV_ID --section "SECTION_NAME" --format json
+deepxiv trending --days 7 --limit MAX_RESULTS --output json
+deepxiv wsearch "QUERY" --output json
+deepxiv sc "SEMANTIC_SCHOLAR_ID" --output json
+```
+
+### Step 4: Present Results
+
+For search results, present a compact literature table. For paper reads, summarize the title, authors, date, TLDR, and the next recommended depth step.
+
+### Step 5: Escalate Depth Only When Needed
+
+Use the progression:
+
+1. `search`
+2. `paper-brief`
+3. `paper-head`
+4. `paper-section`
+
+Only read the full paper when the user explicitly needs it.
+
+### Step 6: Update Research Wiki (if active)
+
+If the project has an active research wiki and the user is building a literature set, add DeepXiv findings as source-backed entries with arXiv/Semantic Scholar IDs, retrieved sections, and the recommended next depth step.
+
+Follow [`shared-references/integration-contract.md`](../shared-references/integration-contract.md). If the wiki path or schema is unclear, ask before writing.
+
+## Key Rules
+
+- Prefer the adapter script over raw `deepxiv` commands when available.
+- If DeepXiv is missing, give the install command and suggest `/arxiv` or `/research-lit "topic" - sources: web`.
+- Use DeepXiv as an additive source, not a replacement for existing ARIS literature tooling.
+- If the result overlaps with a published venue paper from Semantic Scholar, keep the richer venue metadata in the final summary.

package/skills/skills-codex/dse-loop/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: "dse-loop"
+description: "Autonomous design space exploration loop for computer architecture and EDA. Runs a program, analyzes results, tunes parameters, and iterates until objective is met or timeout. Use when user says \\\"DSE\\\", \\\"design space exploration\\\", \\\"sweep parameters\\\", \\\"optimize\\\", \\\"find best config\\\", or wants iterative parameter tuning."
+---
+
+# DSE Loop: Autonomous Design Space Exploration
+
+Autonomously explore a design space: run → analyze → pick next parameters → repeat, until the objective is met or timeout is reached. Designed for computer architecture and EDA problems.
+
+## Context: $ARGUMENTS
+
+## Safety Rules — READ FIRST
+
+**NEVER do any of the following:**
+- `sudo` anything
+- `rm -rf`, `rm -r`, or any recursive deletion
+- `rm` any file you did not create in this session
+- Overwrite existing source files without reading them first
+- `git push`, `git reset --hard`, or any destructive git operation
+- Kill processes you did not start
+
+**If a step requires any of the above, STOP and report to the user.**
+
+## Constants (override via $ARGUMENTS)
+
+| Constant | Default | Description |
+|----------|---------|-------------|
+| `TIMEOUT` | 2h | Total wall-clock budget. Stop exploring after this. |
+| `MAX_ITERATIONS` | 50 | Hard cap on number of design points evaluated. |
+| `PATIENCE` | 10 | Stop early if no improvement for this many consecutive iterations. |
+| `OBJECTIVE` | minimize | `minimize` or `maximize` the target metric. |
+
+Override inline: `/dse-loop "task desc — timeout: 4h, max_iterations: 100, patience: 15"`
+
+## Typical Use Cases
+
+| Problem | Program | Parameters | Objective |
+|---------|---------|-----------|-----------|
+| Microarch DSE | gem5 simulation | cache size, assoc, pipeline width, ROB size, branch predictor | maximize IPC or minimize area×delay |
+| Synthesis tuning | yosys/DC script | optimization passes, target freq, effort level | minimize area at timing closure |
+| RTL parameterization | verilator sim | data width, FIFO depth, pipeline stages, buffer sizes | meet throughput target at min area |
+| Compiler flags | gcc/llvm build + benchmark | -O levels, unroll factor, vectorization, scheduling | minimize runtime or code size |
+| Placement/routing | openroad/innovus | utilization, aspect ratio, layer config | minimize wirelength / timing |
+| Formal verification | abc/sby | bound depth, engine, timeout per property | maximize coverage in time budget |
+| Memory subsystem | cacti / ramulator | bank count, row buffer policy, scheduling | optimize bandwidth/energy |
+
+## Workflow
+
+### Phase 0: Parse Task & Setup
+
+1. **Parse $ARGUMENTS** to extract:
+   - **Program**: what to run (command, script, or Makefile target)
+   - **Parameter space**: which knobs to tune and their ranges/options (may be incomplete — see step 2)
+   - **Objective metric**: what to optimize (and how to extract it from output)
+   - **Constraints**: hard limits that must not be violated (e.g., timing must close)
+   - **Timeout**: wall-clock budget
+   - **Success criteria**: when is the result "good enough" to stop early?
+
+2. **Infer missing parameter ranges** — If the user provides parameter names but NOT ranges/options, you MUST infer them before exploring:
+
+   a. **Read the source code** — search for the parameter names in the codebase:
+      - Look for argparse/click definitions, config files, Makefile variables, module parameters, `#define`, `parameter` (SystemVerilog), `localparam`, etc.
+      - Extract defaults, types, and any comments hinting at valid values
+
+   b. **Apply domain knowledge** to set reasonable ranges:
+      | Parameter type | Inference strategy |
+      |---------------|-------------------|
+      | Cache/memory sizes | Powers of 2, typically 1KB–16MB |
+      | Associativity | Powers of 2: 1, 2, 4, 8, 16 |
+      | Pipeline width / issue width | Small integers: 1, 2, 4, 8 |
+      | Buffer/queue/FIFO depth | Powers of 2: 4, 8, 16, 32, 64 |
+      | Clock period / frequency | Based on technology node; try ±50% from default |
+      | Bound depth (BMC/formal) | Geometric: 5, 10, 20, 50, 100 |
+      | Timeout values | Geometric: 10s, 30s, 60s, 120s, 300s |
+      | Boolean/enum flags | Enumerate all options found in source |
+      | Continuous (learning rate, threshold) | Log-scale sweep: 5 points spanning 2 orders of magnitude around default |
+      | Integer counts (threads, cores) | Linear: from 1 to hardware max |
+
+   c. **Start conservative** — begin with 3-5 values per parameter. Expand range later if the best result is at a boundary.
+
+   d. **Log inferred ranges** — write the inferred parameter space to `dse_results/inferred_params.md` so the user can review:
+      ```markdown
+      # Inferred Parameter Space
+
+      | Parameter | Source | Default | Inferred Range | Reasoning |
+      |-----------|--------|---------|---------------|-----------|
+      | CACHE_SIZE | config.py:42 | 32768 | [8192, 16384, 32768, 65536, 131072] | powers of 2, ±2x from default |
+      | ASSOC | config.py:43 | 4 | [1, 2, 4, 8] | standard associativities |
+      | BMC_DEPTH | run_bmc.py:15 | 10 | [5, 10, 20, 50] | geometric, common BMC depths |
+      ```
+
+   e. **Boundary expansion** — during the search, if the best result is at the min or max of a range, automatically extend that range by one step in that direction (but log the extension).
+
+3. **Read the project** to understand:
+   - How to run the program
+   - Where results are produced (stdout, log files, reports)
+   - How to parse the objective metric from output
+   - Current/baseline configuration (if any)
+
+4. **Create working directory**: `dse_results/` in project root
+   - `dse_results/dse_log.csv` — one row per design point
+   - `dse_results/DSE_REPORT.md` — final report
+   - `dse_results/DSE_STATE.json` — state for recovery
+   - `dse_results/inferred_params.md` — inferred parameter space (if ranges were not provided)
+   - `dse_results/configs/` — config files for each run
+   - `dse_results/outputs/` — raw output for each run
+
+5. **Write a parameter extraction script** (`dse_results/parse_result.py` or similar) that takes a run's output and returns the objective metric as a number. Test it on a baseline run first.
+
+6. **Run baseline** (iteration 0): run the program with default/current parameters. Record the baseline metric. This is the point to beat.
+
+### Phase 1: Initial Exploration
+
+**Goal**: Quickly survey the space to understand which parameters matter most.
+
+**Strategy**: Latin Hypercube Sampling or structured sweep of key parameters.
+
+1. Pick 5-10 diverse design points that span the parameter ranges
+2. Run them (in parallel if independent, via background processes or sequential)
+3. Record all results in `dse_log.csv`:
+   ```
+   iteration,param1,param2,...,metric,constraint_met,timestamp,notes
+   0,default,default,...,baseline_val,yes,2026-03-13T10:00:00,baseline
+   1,val1a,val2a,...,result1,yes,2026-03-13T10:05:00,initial sweep
+   ...
+   ```
+4. Analyze: which parameters have the most impact on the objective?
+5. Narrow the search to the most sensitive parameters
+
+### Phase 2: Directed Search
+
+**Goal**: Converge toward the optimum by making informed choices.
+
+**Strategy**: Adaptive — pick the approach that fits the problem:
+
+- **Few parameters (≤3)**: Fine-grained grid search around the best region from Phase 1
+- **Many parameters (>3)**: Coordinate descent — optimize one parameter at a time, holding others at current best
+- **Binary/categorical params**: Enumerate promising combinations
+- **Continuous params**: Binary search or golden section between best neighbors
+- **Multi-objective**: Track Pareto frontier, explore along the front
+
+For each iteration:
+
+1. **Select next design point** based on results so far:
+   - Look at the trend: which direction improves the metric?
+   - Avoid re-running configurations already evaluated
+   - Balance exploration (untested regions) vs exploitation (near current best)
+
+2. **Modify parameters**: edit config file, command-line args, or source constants
+
+3. **Run the program**: execute and capture output
+
+4. **Parse results**: extract the objective metric and check constraints
+
+5. **Log to `dse_log.csv`**: append the new row
+
+6. **Check stopping conditions**:
+   - Timeout reached? → stop
+   - Max iterations reached? → stop
+   - Patience exhausted (no improvement in N iterations)? → stop
+   - Success criteria met (metric is "good enough")? → stop
+   - Constraint violation pattern detected? → adjust search bounds
+
+7. **Update `DSE_STATE.json`**:
+   ```json
+   {
+     "iteration": 15,
+     "status": "in_progress",
+     "best_metric": 1.23,
+     "best_params": {"cache_size": 32768, "assoc": 4, "pipeline_width": 2},
+     "total_iterations": 15,
+     "start_time": "2026-03-13T10:00:00",
+     "timeout": "2h",
+     "patience_counter": 3
+   }
+   ```
+
+8. **Decide next step** → back to step 1
+
+### Phase 3: Refinement (if time allows)
+
+If the search converged and there's still time budget:
+
+1. **Local perturbation**: try ±1 step on each parameter from the best point
+2. **Sensitivity analysis**: which parameters can be relaxed without hurting the metric?
+3. **Constraint boundary**: if a constraint is nearly binding, explore near-feasible points
+
+### Phase 4: Report
+
+Write `dse_results/DSE_REPORT.md`:
+
+```markdown
+# Design Space Exploration Report
+
+**Task**: [description]
+**Date**: [start] → [end]
+**Total iterations**: N
+**Wall-clock time**: X hours Y minutes
+
+## Objective
+- **Metric**: [what was optimized]
+- **Direction**: minimize / maximize
+- **Baseline**: [value]
+- **Best found**: [value] ([improvement]% better than baseline)
+
+## Best Configuration
+| Parameter | Baseline | Best |
+|-----------|----------|------|
+| param1    | default  | best_val |
+| param2    | default  | best_val |
+| ...       | ...      | ... |
+
+## Search Trajectory
+| Iteration | param1 | param2 | ... | Metric | Notes |
+|-----------|--------|--------|-----|--------|-------|
+| 0 (baseline) | ... | ... | ... | ... | baseline |
+| 1 | ... | ... | ... | ... | initial sweep |
+| ... | ... | ... | ... | ... | ... |
+| N (best) | ... | ... | ... | ... | ★ best |
+
+## Parameter Sensitivity
+- **param1**: [high/medium/low impact] — [brief explanation]
+- **param2**: [high/medium/low impact] — [brief explanation]
+
+## Pareto Frontier (if multi-objective)
+[Table or description of non-dominated points]
+
+## Stopping Reason
+[timeout / max_iterations / patience / success_criteria_met]
+
+## Recommendations
+- [actionable insights from the exploration]
+- [which parameters matter most]
+- [suggested follow-up explorations]
+```
+
+Also generate a summary plot if matplotlib is available:
+- Convergence curve (metric vs iteration)
+- Parameter sensitivity bar chart
+- Pareto frontier scatter (if multi-objective)
+
+## State Recovery
+
+If the context window compacts mid-run, the loop recovers from `DSE_STATE.json` + `dse_log.csv`:
+
+1. Read `DSE_STATE.json` for current iteration, best params, patience counter
+2. Read `dse_log.csv` for full history
+3. Resume from next iteration
+
+## Key Rules
+
+- Work AUTONOMOUSLY — do not ask the user for permission at each iteration
+- **Every run must be logged** — even failed runs, constraint violations, errors. The log is the ground truth.
+- **Never re-run an identical configuration** — check `dse_log.csv` before each run
+- **Respect the timeout** — check elapsed time before starting a new iteration. If the next run is likely to exceed the timeout, stop and report.
+- **Parse metrics programmatically** — write a parsing script, don't eyeball logs
+- **Keep raw outputs** — save each run's full output in `dse_results/outputs/iter_N/`
+- **Constraint violations are not improvements** — a design point that violates constraints is never "best", regardless of the metric
+- If a run crashes, log the error, skip that point, and continue with the next
+- If the same crash repeats 3 times with different configs, the harness code itself is
+  the suspect — **discard and reimplement the run/parse script cleanly from the spec**
+  (a peer move to another patch; delete only the script, never `dse_log.csv` /
+  `dse_results/`; per [`external-cadence.md`](../shared-references/external-cadence.md), "Let a broken attempt restart, not
+  just patch"). **Before resuming the sweep, re-validate metric comparability**: re-parse
+  one COMPLETED iteration's raw output from `dse_results/outputs/iter_N/` with the new
+  parser and confirm it reproduces that row of `dse_log.csv`; on mismatch, fix the parser
+  or re-parse and flag all affected rows — never mix two parsing semantics in one log. If
+  a clean reimplement crashes the same way, stop and report — the spec or the environment
+  is then in question, which is what needs the human
+
+## Example Invocations
+
+```
+# Minimal — just name the parameters, let the agent figure out ranges
+/dse-loop "Run gem5 mcf benchmark. Tune: L1D_SIZE, L2_SIZE, ROB_ENTRIES. Objective: maximize IPC. Timeout: 3h"
+
+# Partial — some ranges given, some not
+/dse-loop "Run make synth. Tune: CLOCK_PERIOD [5ns, 4ns, 3ns, 2ns], FLATTEN, ABC_SCRIPT. Objective: minimize area at timing closure. Timeout: 1h"
+
+# Fully specified — explicit ranges for everything
+/dse-loop "Simulate processor with FIFO_DEPTH [4,8,16,32], ISSUE_WIDTH [1,2,4], PREFETCH [on,off]. Run: make sim. Objective: max throughput/area. Timeout: 2h"
+
+# Real-world: PDAG-SFA formal verification tuning
+/dse-loop "Run python run_bmc.py. Tune: BMC_DEPTH, ENGINE, TIMEOUT_PER_PROP. Objective: maximize properties proved. Timeout: 2h"
+```