From 10aed95f9da77a607c35610b2477115f67696676 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Fri, 13 Feb 2026 20:29:36 -0500 Subject: [PATCH] [ci] bootstrap standalone torch package metadata and root-relative docs --- torch/.gitignore | 5 + torch/README.md | 119 ++++++---------- torch/examples/bitvid/META_PROMPTS.md | 28 ++-- torch/examples/bitvid/daily-scheduler.md | 6 +- torch/examples/bitvid/scheduler-flow.md | 10 +- torch/examples/bitvid/weekly-scheduler.md | 6 +- torch/package-lock.json | 162 ++++++++++++++++++++++ torch/package.json | 18 +++ 8 files changed, 249 insertions(+), 105 deletions(-) create mode 100644 torch/.gitignore create mode 100644 torch/package-lock.json create mode 100644 torch/package.json diff --git a/torch/.gitignore b/torch/.gitignore new file mode 100644 index 00000000..30458046 --- /dev/null +++ b/torch/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +.DS_Store +npm-debug.log* +yarn-error.log* +pnpm-debug.log* diff --git a/torch/README.md b/torch/README.md index 6e5ef16a..a8f6436a 100644 --- a/torch/README.md +++ b/torch/README.md @@ -1,78 +1,56 @@ -# TORCH Extract (Portable Folder) +# TORCH (Standalone) -This folder is a repo-ready extraction of TORCH so you can move it into a standalone project. +TORCH is a portable Nostr-based task locking toolkit for multi-agent coordination. + +## First-run quickstart + +From the repository root: + +```bash +npm install +npm run lock:check:daily +AGENT_PLATFORM=codex npm run lock:lock -- --agent docs-agent --cadence daily +npm run lock:list +``` + +Optional dashboard: + +```bash +npm run dashboard:serve +# then open http://localhost:4173/dashboard/ +``` ## Included - `src/nostr-lock.mjs` — Generic lock/check/list CLI - `src/docs/TORCH.md` — Protocol summary and usage - `src/prompts/` — Generic scheduler prompts and flow -- `examples/bitvid/` — Bitvid-specific scheduler overlay examples +- `examples/bitvid/` — Bitvid-style scheduler overlay examples adapted for standalone TORCH paths +- `dashboard/index.html` — Static lock dashboard -## Migration map (bitvid ➜ torch extract) +## CLI dependencies -Use this mapping when extracting TORCH from bitvid into this portable folder. +Declared in `package.json` and pinned: -| bitvid source path | torch destination path | -| --- | --- | -| `scripts/agent/nostr-lock.mjs` | `torch/src/nostr-lock.mjs` | -| `docs/agents/TORCH.md` | `torch/src/docs/TORCH.md` | -| `docs/agents/prompts/*` | `torch/src/prompts/*` and `torch/examples/bitvid/*` | -| `views/dev/agent-dashboard.html` | `torch/dashboard/index.html` | +- `nostr-tools@2.19.4` +- `ws@8.19.0` -### Leave source intact (copy-only, non-destructive) +## NPM script helpers -Use this checklist to ensure extraction does **not** mutate or remove any bitvid source files: +- `npm run lock:check:daily` +- `npm run lock:check:weekly` +- `npm run lock:list` +- `npm run lock:lock -- --agent --cadence ` +- `npm run dashboard:serve` -- [ ] Copy files from bitvid source paths into `torch/...`; do not move/rename originals. -- [ ] Do not delete or rewrite files under `scripts/agent/`, `docs/agents/`, or `views/dev/` during extraction. -- [ ] Keep bitvid runtime paths valid (existing docs and scripts should continue to work in-place). -- [ ] When adapting portable files, edit only the copied torch targets (`torch/src/...`, `torch/examples/...`, `torch/dashboard/...`). -- [ ] Confirm `git status` in bitvid does not show source removals caused by extraction. +## Environment variables -### Verification checklist (namespace/tag parity) - -Confirm namespace/tag identifiers are consistent across CLI, docs, and dashboard wiring: - -- [ ] CLI defaults/constants in `torch/src/nostr-lock.mjs` match documented values in `torch/src/docs/TORCH.md`. -- [ ] Prompt documentation in `torch/src/prompts/*` and `torch/examples/bitvid/*` references the same namespace usage as the CLI (for example `NOSTR_LOCK_NAMESPACE`). -- [ ] Dashboard filters in `torch/dashboard/index.html` match the same lock tag namespace used by the CLI and docs. -- [ ] Event kind/tag examples stay aligned across all three surfaces (CLI output/examples, protocol docs, dashboard expectations). - -## Drop-in notes - -1. Copy this `torch/` directory into your destination repository. -2. Ensure dependencies are available: - - `nostr-tools` - - `ws` -3. Update rosters via env vars: - - `NOSTR_LOCK_DAILY_ROSTER` - - `NOSTR_LOCK_WEEKLY_ROSTER` -4. Optionally set a namespace per repo: - - `NOSTR_LOCK_NAMESPACE=my-project` - -## Using the bitvid example overlay in a new host project - -The files in `examples/bitvid/` are intentionally preserved as a concrete, real-world overlay: - -- `daily-scheduler.md` -- `weekly-scheduler.md` -- `scheduler-flow.md` -- `META_PROMPTS.md` - -They include the exact bitvid command paths and full roster mappings as examples. - -To adapt this for another host project: - -1. Copy `examples/bitvid/` into your project prompt area (or duplicate it as a new overlay directory like `examples//`). -2. Replace path references to your host project's structure (for example, change: - - `docs/agents/prompts/...` - - `docs/agents/task-logs/...` - - `node scripts/agent/nostr-lock.mjs ...` - to your project-specific locations). -3. Replace daily/weekly roster tables with your own agent names and prompt filenames. -4. Update `AGENT_PLATFORM=...` defaults in `META_PROMPTS.md` if your runtime uses a different platform value. -5. Keep `src/prompts/*` generic; store host-specific behavior in overlays so TORCH remains portable. +- `NOSTR_LOCK_NAMESPACE` +- `NOSTR_LOCK_RELAYS` +- `NOSTR_LOCK_TTL` +- `NOSTR_LOCK_DAILY_ROSTER` +- `NOSTR_LOCK_WEEKLY_ROSTER` +- `AGENT_PLATFORM` ## Example @@ -81,22 +59,3 @@ NOSTR_LOCK_NAMESPACE=my-project \ AGENT_PLATFORM=codex \ node src/nostr-lock.mjs lock --agent docs-agent --cadence daily ``` - -## Agent dashboard (static page) - -TORCH includes a standalone dashboard page at `dashboard/index.html` that listens for -`kind:30078` lock events tagged with `#torch-agent-lock`. - -Open it directly in a browser: - -```bash -xdg-open dashboard/index.html -``` - -Or serve the folder with a static HTTP server: - -```bash -python3 -m http.server 4173 -``` - -Then visit `http://localhost:4173/dashboard/`. diff --git a/torch/examples/bitvid/META_PROMPTS.md b/torch/examples/bitvid/META_PROMPTS.md index 99804435..f6d5e11d 100644 --- a/torch/examples/bitvid/META_PROMPTS.md +++ b/torch/examples/bitvid/META_PROMPTS.md @@ -11,28 +11,28 @@ Copy one block below into the agent session. ```text You are the bitvid daily agent scheduler. -Follow `docs/agents/prompts/scheduler-flow.md` exactly. +Follow `src/prompts/scheduler-flow.md` exactly. MUST 1: Set cadence config to: - cadence = daily -- log_dir = docs/agents/task-logs/daily/ +- log_dir = task-logs/daily/ - branch_prefix = agents/daily/ -- prompt_dir = docs/agents/prompts/daily/ +- prompt_dir = src/prompts/daily/ MUST 2: Run preflight to get the exclusion set: -node scripts/agent/nostr-lock.mjs check --cadence daily +node src/nostr-lock.mjs check --cadence daily Use the `locked` array from the JSON output as the exclusion set. MUST 3: Run these commands in this order: 1) cat AGENTS.md CLAUDE.md -2) ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1 +2) ls -1 task-logs/daily/ | sort | tail -n 1 3) Select next roster agent not in exclusion set 4) Claim via Nostr lock: - AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent --cadence daily + AGENT_PLATFORM=jules node src/nostr-lock.mjs lock --agent --cadence daily Exit 0 = lock acquired, proceed. Exit 3 = race lost, go back to step 2. -5) Execute selected prompt from docs/agents/prompts/daily/ +5) Execute selected prompt from src/prompts/daily/ 6) npm run lint 7) Create `_completed.md` or `_failed.md`, commit, push @@ -44,28 +44,28 @@ MUST 4: If all daily agents are excluded, stop and write `_failed.md` with this ```text You are the bitvid weekly agent scheduler. -Follow `docs/agents/prompts/scheduler-flow.md` exactly. +Follow `src/prompts/scheduler-flow.md` exactly. MUST 1: Set cadence config to: - cadence = weekly -- log_dir = docs/agents/task-logs/weekly/ +- log_dir = task-logs/weekly/ - branch_prefix = agents/weekly/ -- prompt_dir = docs/agents/prompts/weekly/ +- prompt_dir = src/prompts/weekly/ MUST 2: Run preflight to get the exclusion set: -node scripts/agent/nostr-lock.mjs check --cadence weekly +node src/nostr-lock.mjs check --cadence weekly Use the `locked` array from the JSON output as the exclusion set. MUST 3: Run these commands in this order: 1) cat AGENTS.md CLAUDE.md -2) ls -1 docs/agents/task-logs/weekly/ | sort | tail -n 1 +2) ls -1 task-logs/weekly/ | sort | tail -n 1 3) Select next roster agent not in exclusion set 4) Claim via Nostr lock: - AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent --cadence weekly + AGENT_PLATFORM=jules node src/nostr-lock.mjs lock --agent --cadence weekly Exit 0 = lock acquired, proceed. Exit 3 = race lost, go back to step 2. -5) Execute selected prompt from docs/agents/prompts/weekly/ +5) Execute selected prompt from src/prompts/weekly/ 6) npm run lint 7) Create `_completed.md` or `_failed.md`, commit, push diff --git a/torch/examples/bitvid/daily-scheduler.md b/torch/examples/bitvid/daily-scheduler.md index f1627d89..b4d42df4 100644 --- a/torch/examples/bitvid/daily-scheduler.md +++ b/torch/examples/bitvid/daily-scheduler.md @@ -2,14 +2,14 @@ This file is an extracted **bitvid-specific overlay** for TORCH scheduler prompts. -Use `docs/agents/prompts/scheduler-flow.md` as the authoritative scheduler procedure. +Use `src/prompts/scheduler-flow.md` as the authoritative scheduler procedure. ## Daily Cadence Configuration (Bitvid Example) - `cadence`: `daily` -- `log_dir`: `docs/agents/task-logs/daily/` +- `log_dir`: `task-logs/daily/` - `branch_prefix`: `agents/daily/` -- `prompt_dir`: `docs/agents/prompts/daily/` +- `prompt_dir`: `src/prompts/daily/` ## Daily Agent Roster (alphabetical order) diff --git a/torch/examples/bitvid/scheduler-flow.md b/torch/examples/bitvid/scheduler-flow.md index dae05892..09eeef05 100644 --- a/torch/examples/bitvid/scheduler-flow.md +++ b/torch/examples/bitvid/scheduler-flow.md @@ -2,7 +2,7 @@ This file is an extracted **bitvid-specific overlay** for TORCH scheduler flow. -Use this document for **all scheduler runs**. Task locking uses the **TORCH** protocol (see `docs/agents/TORCH.md`). +Use this document for **all scheduler runs**. Task locking uses the **TORCH** protocol (see `src/docs/TORCH.md`). ## Scheduler Override (Top-Line Rule) @@ -25,14 +25,14 @@ During scheduler execution, the scheduler-specific instructions in this document 1. **MUST** set cadence variables before any command: - `cadence` = `daily` or `weekly` - - `log_dir` = `docs/agents/task-logs//` + - `log_dir` = `task-logs//` - `branch_prefix` = `agents//` - - `prompt_dir` = `docs/agents/prompts//` + - `prompt_dir` = `src/prompts//` 2. **MUST** run the preflight check to build the exclusion set: ```bash - node scripts/agent/nostr-lock.mjs check --cadence + node src/nostr-lock.mjs check --cadence ``` This queries Nostr relays for active lock events and returns JSON with `locked` and `available` agent lists. Use the `locked` array as the exclusion set. @@ -55,7 +55,7 @@ During scheduler execution, the scheduler-specific instructions in this document ```bash AGENT_PLATFORM= \ - node scripts/agent/nostr-lock.mjs lock \ + node src/nostr-lock.mjs lock \ --agent \ --cadence ``` diff --git a/torch/examples/bitvid/weekly-scheduler.md b/torch/examples/bitvid/weekly-scheduler.md index e867e63f..20d89cb8 100644 --- a/torch/examples/bitvid/weekly-scheduler.md +++ b/torch/examples/bitvid/weekly-scheduler.md @@ -2,14 +2,14 @@ This file is an extracted **bitvid-specific overlay** for TORCH scheduler prompts. -Use `docs/agents/prompts/scheduler-flow.md` as the authoritative scheduler procedure. +Use `src/prompts/scheduler-flow.md` as the authoritative scheduler procedure. ## Weekly Cadence Configuration (Bitvid Example) - `cadence`: `weekly` -- `log_dir`: `docs/agents/task-logs/weekly/` +- `log_dir`: `task-logs/weekly/` - `branch_prefix`: `agents/weekly/` -- `prompt_dir`: `docs/agents/prompts/weekly/` +- `prompt_dir`: `src/prompts/weekly/` ## Weekly Agent Roster (alphabetical order) diff --git a/torch/package-lock.json b/torch/package-lock.json new file mode 100644 index 00000000..db387ac8 --- /dev/null +++ b/torch/package-lock.json @@ -0,0 +1,162 @@ +{ + "name": "torch-lock", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "torch-lock", + "version": "0.1.0", + "dependencies": { + "nostr-tools": "2.19.4", + "ws": "8.19.0" + } + }, + "node_modules/@noble/ciphers": { + "version": "0.5.3", + "resolved": "https://registry.npmjs.org/@noble/ciphers/-/ciphers-0.5.3.tgz", + "integrity": "sha512-B0+6IIHiqEs3BPMT0hcRmHvEj2QHOLu+uwt+tqDDeVd0oyVzh7BPrDcPjRnV1PV/5LaknXJJQvOuRGR0zQJz+w==", + "license": "MIT", + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@noble/curves": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-1.2.0.tgz", + "integrity": "sha512-oYclrNgRaM9SsBUBVbb8M6DTV7ZHRTKugureoYEncY5c65HOmRzvSiTE3y5CYaPYJA/GVkrhXEoF0M3Ya9PMnw==", + "license": "MIT", + "dependencies": { + "@noble/hashes": "1.3.2" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@noble/curves/node_modules/@noble/hashes": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.3.2.tgz", + "integrity": "sha512-MVC8EAQp7MvEcm30KWENFjgR+Mkmf+D189XJTkFIlwohU5hcBbn1ZkKq7KVTi2Hme3PMGF390DaL52beVrIihQ==", + "license": "MIT", + "engines": { + "node": ">= 16" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@noble/hashes": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.3.1.tgz", + "integrity": "sha512-EbqwksQwz9xDRGfDST86whPBgM65E0OH/pCgqW0GBVzO22bNE+NuIbeTb714+IfSjU3aRk47EUvXIb5bTsenKA==", + "license": "MIT", + "engines": { + "node": ">= 16" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@scure/base": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@scure/base/-/base-1.1.1.tgz", + "integrity": "sha512-ZxOhsSyxYwLJj3pLZCefNitxsj093tb2vq90mp2txoYeBqbcjDjqFhyM8eUjq/uFm6zJ+mUuqxlS2FkuSY1MTA==", + "funding": [ + { + "type": "individual", + "url": "https://paulmillr.com/funding/" + } + ], + "license": "MIT" + }, + "node_modules/@scure/bip32": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/@scure/bip32/-/bip32-1.3.1.tgz", + "integrity": "sha512-osvveYtyzdEVbt3OfwwXFr4P2iVBL5u1Q3q4ONBfDY/UpOuXmOlbgwc1xECEboY8wIays8Yt6onaWMUdUbfl0A==", + "license": "MIT", + "dependencies": { + "@noble/curves": "~1.1.0", + "@noble/hashes": "~1.3.1", + "@scure/base": "~1.1.0" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@scure/bip32/node_modules/@noble/curves": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@noble/curves/-/curves-1.1.0.tgz", + "integrity": "sha512-091oBExgENk/kGj3AZmtBDMpxQPDtxQABR2B9lb1JbVTs6ytdzZNwvhxQ4MWasRNEzlbEH8jCWFCwhF/Obj5AA==", + "license": "MIT", + "dependencies": { + "@noble/hashes": "1.3.1" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/@scure/bip39": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/@scure/bip39/-/bip39-1.2.1.tgz", + "integrity": "sha512-Z3/Fsz1yr904dduJD0NpiyRHhRYHdcnyh73FZWiV+/qhWi83wNJ3NWolYqCEN+ZWsUz2TWwajJggcRE9r1zUYg==", + "license": "MIT", + "dependencies": { + "@noble/hashes": "~1.3.0", + "@scure/base": "~1.1.0" + }, + "funding": { + "url": "https://paulmillr.com/funding/" + } + }, + "node_modules/nostr-tools": { + "version": "2.19.4", + "resolved": "https://registry.npmjs.org/nostr-tools/-/nostr-tools-2.19.4.tgz", + "integrity": "sha512-qVLfoTpZegNYRJo5j+Oi6RPu0AwLP6jcvzcB3ySMnIT5DrAGNXfs5HNBspB/2HiGfH3GY+v6yXkTtcKSBQZwSg==", + "license": "Unlicense", + "dependencies": { + "@noble/ciphers": "^0.5.1", + "@noble/curves": "1.2.0", + "@noble/hashes": "1.3.1", + "@scure/base": "1.1.1", + "@scure/bip32": "1.3.1", + "@scure/bip39": "1.2.1", + "nostr-wasm": "0.1.0" + }, + "peerDependencies": { + "typescript": ">=5.0.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/nostr-wasm": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/nostr-wasm/-/nostr-wasm-0.1.0.tgz", + "integrity": "sha512-78BTryCLcLYv96ONU8Ws3Q1JzjlAt+43pWQhIl86xZmWeegYCNLPml7yQ+gG3vR6V5h4XGj+TxO+SS5dsThQIA==", + "license": "MIT" + }, + "node_modules/ws": { + "version": "8.19.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz", + "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==", + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + } + } +} diff --git a/torch/package.json b/torch/package.json new file mode 100644 index 00000000..2f664684 --- /dev/null +++ b/torch/package.json @@ -0,0 +1,18 @@ +{ + "name": "torch-lock", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "TORCH standalone lock CLI and optional dashboard", + "scripts": { + "lock:check:daily": "node src/nostr-lock.mjs check --cadence daily", + "lock:check:weekly": "node src/nostr-lock.mjs check --cadence weekly", + "lock:list": "node src/nostr-lock.mjs list", + "lock:lock": "node src/nostr-lock.mjs lock", + "dashboard:serve": "python3 -m http.server 4173" + }, + "dependencies": { + "nostr-tools": "2.19.4", + "ws": "8.19.0" + } +}