From 720bd3ed630c311fe4157e46b418c8d71926b2bf Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Tue, 27 Jan 2026 13:46:29 +0100 Subject: [PATCH] chore: update OpenSpec commands and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Benoit --- .opencode/command/openspec-apply.md | 4 ++++ .opencode/command/openspec-archive.md | 5 ++++- .opencode/command/openspec-proposal.md | 12 ++++++++---- .opencode/opencode.jsonc | 4 ++-- ReforceXY/reward_space_analysis/README.md | 12 ++++++++---- ReforceXY/reward_space_analysis/tests/README.md | 17 ++++++++++------- openspec/AGENTS.md | 14 +++++++------- 7 files changed, 43 insertions(+), 25 deletions(-) diff --git a/.opencode/command/openspec-apply.md b/.opencode/command/openspec-apply.md index 2e25974..2686863 100644 --- a/.opencode/command/openspec-apply.md +++ b/.opencode/command/openspec-apply.md @@ -4,13 +4,16 @@ description: Implement an approved OpenSpec change and keep tasks in sync. --- + **Guardrails** + - Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. - Keep changes tightly scoped to the requested outcome. - Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. **Steps** Track these steps as TODOs and complete them one by one. + 1. Read `changes//proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria. 2. Work through tasks sequentially, keeping edits minimal and focused on the requested change. 3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished. @@ -18,5 +21,6 @@ Track these steps as TODOs and complete them one by one. 5. Reference `openspec list` or `openspec show ` when additional context is required. **Reference** + - Use `openspec show --json --deltas-only` if you need additional context from the proposal while implementing. diff --git a/.opencode/command/openspec-archive.md b/.opencode/command/openspec-archive.md index d172e44..5b564fb 100644 --- a/.opencode/command/openspec-archive.md +++ b/.opencode/command/openspec-archive.md @@ -1,6 +1,7 @@ --- description: Archive a deployed OpenSpec change and update specs. --- + $ARGUMENTS @@ -11,6 +12,7 @@ description: Archive a deployed OpenSpec change and update specs. - Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. **Steps** + 1. Determine the change ID to archive: - If this prompt already includes a specific change ID (for example inside a `` block populated by slash-command arguments), use that value after trimming whitespace. - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends. @@ -19,9 +21,10 @@ description: Archive a deployed OpenSpec change and update specs. 2. Validate the change ID by running `openspec list` (or `openspec show `) and stop if the change is missing, already archived, or otherwise not ready to archive. 3. Run `openspec archive --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work). 4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`. -5. Validate with `openspec validate --strict` and inspect with `openspec show ` if anything looks off. +5. Validate with `openspec validate --strict --no-interactive` and inspect with `openspec show ` if anything looks off. **Reference** + - Use `openspec list` to confirm change IDs before archiving. - Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off. diff --git a/.opencode/command/openspec-proposal.md b/.opencode/command/openspec-proposal.md index 47fabaa..8fc816a 100644 --- a/.opencode/command/openspec-proposal.md +++ b/.opencode/command/openspec-proposal.md @@ -3,13 +3,15 @@ agent: build description: Scaffold a new OpenSpec change and validate strictly. --- -The user has requested the following change proposal. Use the openspec instructions to create their change proposal. - -$ARGUMENTS +The user has requested the following change proposal. Use the openspec +instructions to create their change proposal. + $ARGUMENTS + **Guardrails** + - Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. - Keep changes tightly scoped to the requested outcome. - Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications. @@ -17,15 +19,17 @@ $ARGUMENTS - Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval. **Steps** + 1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification. 2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes//`. 3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing. 4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs. 5. Draft spec deltas in `changes//specs//spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant. 6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. -7. Validate with `openspec validate --strict` and resolve every issue before sharing the proposal. +7. Validate with `openspec validate --strict --no-interactive` and resolve every issue before sharing the proposal. **Reference** + - Use `openspec show --json --deltas-only` or `openspec show --type spec` to inspect details when validation fails. - Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones. - Explore the codebase with `rg `, `ls`, or direct file reads so proposals align with current implementation realities. diff --git a/.opencode/opencode.jsonc b/.opencode/opencode.jsonc index 2638a16..510ee9f 100644 --- a/.opencode/opencode.jsonc +++ b/.opencode/opencode.jsonc @@ -1,6 +1,6 @@ { "$schema": "https://opencode.ai/config.json", "permission": { - "external_directory": "allow" - } + "external_directory": "allow", + }, } diff --git a/ReforceXY/reward_space_analysis/README.md b/ReforceXY/reward_space_analysis/README.md index 82aa3b6..ce75865 100644 --- a/ReforceXY/reward_space_analysis/README.md +++ b/ReforceXY/reward_space_analysis/README.md @@ -201,7 +201,8 @@ be overridden via `--params`. - **`--strict_diagnostics`** (flag, default: false) – Fail-fast on degenerate statistical diagnostics (zero-width CIs, undefined distribution metrics) instead of graceful fallbacks. -- **`--exit_factor_threshold`** (float, default: 1000.0) – Emits a warning if the absolute value of the exit factor exceeds the threshold. +- **`--exit_factor_threshold`** (float, default: 1000.0) – Emits a warning if + the absolute value of the exit factor exceeds the threshold. - **`--pvalue_adjust`** (none|benjamini_hochberg, default: none) – Multiple testing p-value adjustment method. - **`--bootstrap_resamples`** (int, default: 10000) – Bootstrap iterations for @@ -233,7 +234,8 @@ be overridden via `--params`. The exit factor is computed as: -`exit_factor` = `base_factor` · `pnl_target_coefficient` · `efficiency_coefficient` · `time_attenuation_coefficient` +`exit_factor` = `base_factor` · `pnl_target_coefficient` · +`efficiency_coefficient` · `time_attenuation_coefficient` ##### PnL Target @@ -248,7 +250,8 @@ The exit factor is computed as: **Formula:** -Let `pnl_target = profit_aim · risk_reward_ratio`, `pnl_ratio = pnl / pnl_target`. +Let `pnl_target = profit_aim · risk_reward_ratio`, +`pnl_ratio = pnl / pnl_target`. - If `pnl_target ≤ 0`: `pnl_target_coefficient = 1.0` - If `pnl_ratio > 1.0`: @@ -290,7 +293,8 @@ Let `max_u = max_unrealized_profit`, `min_u = min_unrealized_profit`, `time_attenuation_coefficient = kernel_function(duration_ratio)` -where `kernel_function` depends on `exit_attenuation_mode`. See [Exit Attenuation Kernels](#exit-attenuation-kernels) for detailed formulas. +where `kernel_function` depends on `exit_attenuation_mode`. See +[Exit Attenuation Kernels](#exit-attenuation-kernels) for detailed formulas. #### Duration Penalties diff --git a/ReforceXY/reward_space_analysis/tests/README.md b/ReforceXY/reward_space_analysis/tests/README.md index 4998239..8f6494b 100644 --- a/ReforceXY/reward_space_analysis/tests/README.md +++ b/ReforceXY/reward_space_analysis/tests/README.md @@ -8,8 +8,7 @@ policies, maintenance workflows, and full coverage mapping. The suite enforces: - Reward component mathematics & transform correctness -- PBRS shaping mechanics (canonical exit semantics, near-zero - classification) +- PBRS shaping mechanics (canonical exit semantics, near-zero classification) - Robustness under extreme / invalid parameter settings - Statistical metrics integrity (bootstrap, constant distributions) - CLI parameter propagation & report formatting @@ -93,7 +92,9 @@ seed_all(SEEDS.FIXED_UNIT) ### Tolerance Selection -Choose appropriate numerical tolerances to prevent flaky tests. All tolerance constants are defined and documented in `tests/constants.py` with their rationale. +Choose appropriate numerical tolerances to prevent flaky tests. All tolerance +constants are defined and documented in `tests/constants.py` with their +rationale. **Common tolerances:** @@ -101,7 +102,8 @@ Choose appropriate numerical tolerances to prevent flaky tests. All tolerance co - `IDENTITY_RELAXED` (1e-09) - Multi-step operations with accumulated errors - `GENERIC_EQ` (1e-08) - General floating-point equality (default) -Always document non-default tolerance choices with inline comments explaining the error accumulation model. +Always document non-default tolerance choices with inline comments explaining +the error accumulation model. ### Test Documentation @@ -246,7 +248,8 @@ Table tracks approximate line ranges and source ownership: selection. 4. Follow the docstring template in `.docstring_template.md`. 5. Use constants from `tests/constants.py` - never use magic numbers. -6. Document tolerance choices with inline comments explaining error accumulation. +6. Document tolerance choices with inline comments explaining error + accumulation. 7. Optionally declare inline ownership: ```python # Owns invariant: @@ -320,8 +323,8 @@ before publishing analysis reliant on invariants. dataclasses with comprehensive documentation) - **`helpers/assertions.py`** - 20+ custom assertion functions for invariant validation -- **`test_base.py`** - Base class with common utilities (`make_ctx`, - `seed_all`, etc.) +- **`test_base.py`** - Base class with common utilities (`make_ctx`, `seed_all`, + etc.) --- diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md index 45ef8a6..8de8eb8 100644 --- a/openspec/AGENTS.md +++ b/openspec/AGENTS.md @@ -9,7 +9,7 @@ Instructions for AI coding assistants using OpenSpec for spec-driven development - Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`) - Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability - Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement -- Validate: `openspec validate [change-id] --strict` and fix issues +- Validate: `openspec validate [change-id] --strict --no-interactive` and fix issues - Request approval: Do not start implementation until proposal is approved ## Three-Stage Workflow @@ -50,7 +50,7 @@ Skip proposal for: 1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context. 2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`. 3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. -4. Run `openspec validate --strict` and resolve any issues before sharing the proposal. +4. Run `openspec validate --strict --no-interactive` and resolve any issues before sharing the proposal. ### Stage 2: Implementing Changes @@ -71,7 +71,7 @@ After deployment, create separate PR to: - Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/` - Update `specs/` if capabilities changed - Use `openspec archive --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly) -- Run `openspec validate --strict` to confirm the archived change passes checks +- Run `openspec validate --strict --no-interactive` to confirm the archived change passes checks ## Before Any Task @@ -121,7 +121,7 @@ openspec validate # Bulk validation mode # Debugging openspec show [change] --json --deltas-only -openspec validate [change] --strict +openspec validate [change] --strict --no-interactive ``` ### Command Flags @@ -354,7 +354,7 @@ Example for RENAMED: ```bash # Always use strict mode for comprehensive checks -openspec validate [change] --strict +openspec validate [change] --strict --no-interactive # Debug delta parsing openspec show [change] --json | jq '.deltas' @@ -391,7 +391,7 @@ Users MUST provide a second factor during login. EOF # 4) Validate -openspec validate $CHANGE --strict +openspec validate $CHANGE --strict --no-interactive ``` ## Multi-Capability Example @@ -515,7 +515,7 @@ Only add complexity with: ```bash openspec list # What's in progress? openspec show [item] # View details -openspec validate --strict # Is it correct? +openspec validate --strict --no-interactive # Is it correct? openspec archive [--yes|-y] # Mark complete (add --yes for automation) ``` -- 2.43.0