Skip to content

Commit bf7d8e9

Browse files
SiegeSailorSiegeSailor
committed
chore: add in-review Copilot documents
1 parent 2612403 commit bf7d8e9

File tree

7 files changed

+290
-0
lines changed

7 files changed

+290
-0
lines changed

‎.github/in-review/agents/repo-maintainer.agent.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: Repo Maintainer
3+
description: General maintenance agent for algorithm, CLI, build, and test consistency in this repository.
4+
argument-hint: Describe the maintenance task and desired thoroughness (quick/medium/thorough)
5+
model: ["Auto (copilot)"]
6+
target: vscode
7+
user-invocable: true
8+
tools:
9+
[
10+
"search",
11+
"read",
12+
"execute/getTerminalOutput",
13+
"execute/testFailure",
14+
"vscode/memory",
15+
]
16+
agents: []
17+
---
18+
19+
You are a repository maintenance agent for Cryptography.
20+
21+
Goals:
22+
23+
- Keep algorithm behavior deterministic and test-covered.
24+
- Preserve build and release script discipline.
25+
- Keep source and generated output boundaries clear.
26+
27+
Operating rules:
28+
29+
- Prefer minimal, reversible edits.
30+
- Follow repository instructions under `.github/instructions/`.
31+
- Use prompt templates in `.github/prompts/` for repeated workflows.
32+
- Escalate risks early when changes may affect public API, wasm parity, or release scripts.

‎.github/in-review/agents/wasm-triage.agent.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: Wasm Triage
3+
description: Specialized agent for WebAssembly build failures, runtime load issues, and TS/WASM parity debugging.
4+
argument-hint: Provide algorithm name, failure symptoms, repro inputs, and environment details.
5+
model: ["Auto (copilot)"]
6+
target: vscode
7+
user-invocable: true
8+
tools:
9+
[
10+
"search",
11+
"read",
12+
"execute/getTerminalOutput",
13+
"execute/testFailure",
14+
"vscode/memory",
15+
]
16+
agents: []
17+
---
18+
19+
You are the wasm triage specialist for Cryptography.
20+
21+
Goals:
22+
23+
- Restore parity between TypeScript and wasm implementations.
24+
- Preserve strict vs non-strict wasm build semantics.
25+
- Maintain safe fallback behavior when wasm is unavailable.
26+
27+
Operating rules:
28+
29+
- Start from reproducible failing inputs.
30+
- Check compiler detection and build script behavior first.
31+
- Validate expected wasm exports and smoke checks.
32+
- Add targeted regression tests before concluding.
33+
- Avoid broad refactors during incident triage.

‎.github/in-review/insturctions/testing-release.instructions.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
description: Test, CI, and release guardrails
3+
applyTo: "package.json,.github/workflows/**/*.yml,source/**/*.test.ts,scripts/**/*.js"
4+
---
5+
6+
# Script policy
7+
8+
[NPM scripts](./package.json) are organized with [ESLint Package.json Conventions](https://eslint.org/docs/latest/contribute/package-json-conventions):
9+
10+
# Validation flows
11+
12+
- Unit tests: `npm run test`.
13+
- Local wasm confidence: `npm run build:wasm:strict && npm run build:wasm:check && npm run test -- --runInBand`.
14+
- CI validation: `npm run test:coverage -- --ci --runInBand --verbose && npm run build`.
15+
16+
- Required environment: Node `>= 25.2.1`; local wasm compilation also expects LLVM clang and lld as described in [CONTRIBUTING.md](../CONTRIBUTING.md).
17+
- Local iteration: `npm run test` and `npm run build`.
18+
- Wasm confidence flow: `npm run build:wasm:strict && npm run build:wasm:check && npm run test -- --runInBand`.
19+
- CI parity flow: `npm run test:coverage -- --ci --runInBand --verbose && npm run build`.
20+
21+
# CI and release expectations
22+
23+
- Preserve the semantic-release entry point: `release`.
24+
- Keep workflow commands aligned with script names in `package.json`.
25+
- If changing test/build behavior, verify both local and CI paths remain consistent.
26+
27+
# Risk checks before merge
28+
29+
- Confirm algorithm behavior changes include tests.
30+
- Confirm wasm-related changes keep fallback behavior intact.
31+
- Confirm no generated artifacts are being proposed for commit.

‎.github/in-review/insturctions/wasm.instructions.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
description: WebAssembly compile and runtime fallback rules
3+
applyTo: "source/algorithms/**/{index.ts,main.c},scripts/{compile-wasm.js,copy-wasm.js,verify-wasm.js},source/shared/wasm.ts"
4+
---
5+
6+
# WASM contract
7+
8+
- WASM is an optimization path, not the only execution path.
9+
- TypeScript implementations must remain valid fallback behavior.
10+
- Runtime must fail safely to TypeScript when wasm loading or ABI constraints fail.
11+
12+
# Build behavior
13+
14+
- Preserve compiler discovery order from `scripts/compile-wasm.js`:
15+
1. `WASM_CLANG`
16+
2. `/opt/homebrew/opt/llvm/bin/clang`
17+
3. `clang` in `PATH`
18+
- Keep non-strict flow warning-only when wasm toolchain is unavailable.
19+
- Keep strict flow (`WASM_STRICT=1`) fail-fast when wasm cannot compile.
20+
21+
# Verification behavior
22+
23+
- Keep expected export mapping in `scripts/verify-wasm.js` synchronized with algorithm folders.
24+
- Preserve smoke checks for core runtime confidence.
25+
- If adding algorithm wasm exports, add verification entries in the same change.
26+
27+
# Artifact hygiene
28+
29+
- Do not commit generated `.wasm` binaries.
30+
- Keep copy and verification scripts aligned with current algorithm set.

‎.github/in-review/skills/add-algorithm/SKILL.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
name: add-algorithm
3+
description: "Add or update a cryptography algorithm in this repo, including source/algorithms layout, deterministic tests, optional WebAssembly support, and source/entry-point export wiring. Use when scaffolding a new algorithm, extending an existing one, or deciding whether main.c and verify-wasm updates are required."
4+
argument-hint: "Algorithm name, API shape, examples, and whether wasm is required"
5+
---
6+
7+
# Add Algorithm
8+
9+
Use this skill to add a new algorithm or extend an existing one without breaking the repository's deterministic API, TypeScript fallback behavior, or package export surface.
10+
11+
## When To Use
12+
13+
- Add a brand-new algorithm under `source/algorithms/<name>/`.
14+
- Update an existing algorithm while preserving public behavior.
15+
- Decide whether a change needs wasm support now or should stay TypeScript-only.
16+
- Wire a new algorithm into `source/entry-point.ts`.
17+
18+
## Required Inputs
19+
20+
- Algorithm folder name in kebab-case.
21+
- Exported function name and signature.
22+
- Expected inputs, outputs, and at least one concrete example.
23+
- Whether wasm support is required, optional, or explicitly out of scope.
24+
- Any constraints on bigint behavior, determinism, or educational CLI usage.
25+
26+
## Success Criteria
27+
28+
- The algorithm lives under `source/algorithms/<name>/` with the expected repo folder shape.
29+
- `index.ts` remains the source of truth and default export.
30+
- `index.test.ts` covers deterministic nominal and edge-case behavior.
31+
- `source/entry-point.ts` exports the algorithm intentionally.
32+
- If wasm is added, TypeScript fallback still works safely and `scripts/verify-wasm.js` stays in sync.
33+
- No generated `.wasm` artifacts are committed.
34+
35+
## Procedure
36+
37+
1. Clarify scope before writing code.
38+
Confirm the algorithm name, function signature, expected examples, and whether the request is for library code only or also affects prompt-driven CLI flows.
39+
40+
2. Inspect nearby algorithm folders for a matching pattern.
41+
Reuse the existing shape: `index.ts` for implementation, `index.test.ts` for tests, and optional `main.c` for wasm.
42+
43+
3. Implement the TypeScript path first.
44+
Keep the algorithm deterministic, preserve stable parameter semantics, and use `@/` imports for shared utilities. Do not route internal imports through `@/entry-point`.
45+
46+
4. Add or update tests beside the implementation.
47+
Cover representative inputs, edge conditions, and any regression cases from the request. Prefer stronger assertions over weaker or broader snapshots.
48+
49+
5. Decide on wasm support explicitly.
50+
If wasm is not required or would complicate correctness, keep the implementation in TypeScript only.
51+
If wasm is required, add `main.c`, integrate it through the shared helpers in `source/shared/wasm.ts`, and keep the TypeScript path as a safe fallback when loading or ABI expectations fail.
52+
53+
6. Update repository integration points.
54+
Add the named export in `source/entry-point.ts`.
55+
If wasm was added, update the expected export mapping in `scripts/verify-wasm.js` in the same change.
56+
57+
7. Validate with the smallest correct command set.
58+
Run `npm run test` for all algorithm changes.
59+
If wasm behavior changed, run `npm run build:wasm:strict && npm run build:wasm:check && npm run test -- --runInBand`.
60+
Use `npm run build` when the change affects package exports or build integration.
61+
62+
8. Report the change clearly.
63+
Summarize what changed, why wasm was or was not included, how fallback behavior is preserved, and what commands were run.
64+
65+
## Decision Points
66+
67+
### When To Add `main.c`
68+
69+
- Add it when the request explicitly needs wasm acceleration now.
70+
- Add it when an existing algorithm already has a wasm path that must stay parity-checked.
71+
- Skip it when correctness, determinism, or delivery speed would be better served by a TypeScript-only implementation.
72+
73+
### When To Touch CLI Code
74+
75+
- Update CLI or prompt-layer code only if the user asks for interactive exposure or the algorithm must be reachable through existing command flows.
76+
- Otherwise keep the change limited to `source/algorithms/` and `source/entry-point.ts`.
77+
78+
## Guardrails
79+
80+
- Keep behavior deterministic for every public algorithm API.
81+
- Treat `build/` as generated output, not source.
82+
- Keep changes minimal and co-located in the algorithm folder whenever possible.
83+
- Do not change public API names unless explicitly requested.
84+
- Do not commit generated `.wasm` files.
85+
86+
## Output Expectations
87+
88+
- `source/algorithms/<name>/index.ts`
89+
- `source/algorithms/<name>/index.test.ts`
90+
- Optional `source/algorithms/<name>/main.c`
91+
- `source/entry-point.ts`
92+
- Optional `scripts/verify-wasm.js`
93+
94+
## Completion Checklist
95+
96+
- Function name, signature, and export are intentional.
97+
- Tests cover nominal behavior and edge cases.
98+
- Wasm decision is explicit and justified.
99+
- Fallback behavior remains valid if wasm is unavailable.
100+
- Verification commands were run and reported.

‎.github/in-review/skills/release-readiness/SKILL.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Release Readiness
2+
3+
Use this skill to perform a release-readiness review for test, build, exports, and packaging risk.
4+
5+
## When To Use
6+
7+
- Before merge to `main`
8+
- Before manual release verification
9+
- When validating CI parity and semantic-release safety
10+
11+
## Checklist
12+
13+
1. Confirm no generated artifacts are included unexpectedly (`build/`, `.wasm`).
14+
2. Validate package scripts still align with workflow expectations.
15+
3. Run and report:
16+
- `npm run test:coverage -- --ci --runInBand --verbose`
17+
- `npm run build`
18+
4. Confirm public exports in `source/entry-point.ts` are intentional.
19+
5. Confirm algorithm/test changes are deterministic and covered.
20+
6. Confirm wasm verification mappings are aligned with algorithm set.
21+
7. Flag potential semantic-release risks (script drift, commit intent ambiguity).
22+
23+
## Output Format
24+
25+
- Findings by severity: high, medium, low
26+
- Concrete file references for each finding
27+
- Pass/fail recommendation for merge to `main`

‎.github/in-review/skills/wasm-parity-triage/SKILL.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Wasm Parity Triage
2+
3+
Use this skill to diagnose and fix mismatches between TypeScript and WebAssembly behavior for an algorithm.
4+
5+
## When To Use
6+
7+
- Runtime mismatch between TypeScript and wasm results
8+
- Fallback behavior differences
9+
- Strict/non-strict wasm build discrepancies
10+
11+
## Required Inputs
12+
13+
- Algorithm name
14+
- Observed mismatch or failure
15+
- Repro inputs
16+
- Environment details (OS, compiler availability, strict vs non-strict build)
17+
18+
## Triage Checklist
19+
20+
1. Reproduce failure with focused inputs.
21+
2. Verify compiler detection and build-mode behavior in `scripts/compile-wasm.js`.
22+
3. Inspect algorithm `index.ts`, shared wasm helpers in `source/shared/wasm.ts`, and optional `main.c` for ABI and value-range differences.
23+
4. Validate expected export mapping and smoke checks in `scripts/verify-wasm.js`.
24+
5. Confirm TypeScript fallback remains safe and deterministic.
25+
26+
## Fix Expectations
27+
28+
- Prefer the smallest change that restores parity.
29+
- Add or strengthen tests in `index.test.ts` using failing repro inputs.
30+
- Keep strict/non-strict wasm build semantics unchanged.
31+
32+
## Verification
33+
34+
- Run targeted tests first.
35+
- Run `npm run test`.
36+
- Run `npm run build:wasm:strict && npm run build:wasm:check && npm run test -- --runInBand` for final confidence.
37+
- Summarize root cause, fix, and residual risk.

0 commit comments

Comments
 (0)