update

src/decisions/DECISIONS_2026-02-20T05-00-00Z.md

@@ -0,0 +1,50 @@
+---
+agent: docs-agent
+cadence: daily
+run-start: "2026-02-20T05:00:00Z"
+prompt: src/prompts/daily/docs-agent.md
+---
+
+# Decisions — docs-agent — 2026-02-20
+
+## Decision 1: Add missing env vars to README.md
+
+**Decision:** Add the 4 missing environment variables to the README.md "Environment variables" section.
+
+**Alternatives considered:**
+- Open an issue instead of fixing — rejected; the change is small, safe, and well-supported by TORCH.md as authoritative source.
+- Add to TORCH.md only — rejected; README.md is the consumer-facing entry point and should be complete.
+
+**Rationale:** `TORCH.md` lists all env vars and is synchronized with `src/torch-config.mjs`. README.md was missing `NOSTR_LOCK_PUBLISH_TIMEOUT_MS`, `NOSTR_LOCK_MIN_SUCCESSFUL_PUBLISHES`, `NOSTR_LOCK_RELAY_FALLBACKS`, and `NOSTR_LOCK_MIN_ACTIVE_RELAY_POOL`. These affect production lock reliability and users configuring these env vars would not find them in README.md.
+
+**Consequences/follow-ups:** Keep README.md env var list synchronized with TORCH.md on future changes.
+
+---
+
+## Decision 2: Add missing torch-config.json options to README.md
+
+**Decision:** Add 8 missing configuration keys to README.md's `torch-config.json` section.
+
+**Alternatives considered:**
+- Open an issue instead of fixing — rejected; all keys are verified in TORCH.md and code.
+- Only add the most user-facing ones — rejected; all 8 keys are production-relevant and documented in TORCH.md.
+
+**Rationale:** `TORCH.md` is the authoritative configuration reference. The README.md configuration section was a subset, omitting scheduler behavior keys (`handoffCommandByCadence`, `strict_lock`, `degraded_lock_retry_window`, `max_deferrals`) and lock reliability keys (`publishTimeoutMs`, `minSuccessfulRelayPublishes`, `relayFallbacks`, `minActiveRelayPool`) that users configuring production deployments need.
+
+**Consequences/follow-ups:** Keep README.md config section synchronized with TORCH.md on future changes.
+
+---
+
+## Decision 3: No changes to CONTRIBUTING.md
+
+**Decision:** No changes made to CONTRIBUTING.md.
+
+**Rationale:** All commands verified against package.json. Node.js >=22 requirement, npm install, npm run build, npm test, npm run lint, npm run test:unit:lock-backend, npm run test:extended-main, npm run validate:scheduler — all exist. Referenced docs (docs/lib-overview.md, docs/lock-ops-overview.md) exist.
+
+---
+
+## Decision 4: No changes to AGENTS.md
+
+**Decision:** No changes made to AGENTS.md.
+
+**Rationale:** AGENTS.md is the test integrity policy document. It is accurate and consistent with CLAUDE.md. No broken paths or incorrect commands found.

src/decisions/DECISIONS_2026-02-20T06-00-00Z.md

@@ -0,0 +1,50 @@
+---
+agent: docs-alignment-agent
+cadence: daily
+run-start: "2026-02-20T06:00:00Z"
+prompt: src/prompts/daily/docs-alignment-agent.md
+---
+
+# Decisions — docs-alignment-agent — 2026-02-20
+
+## Decision 1: Fix RACE_CHECK_DELAY_MS in docs/lib-overview.md (2000→1500ms)
+
+**Decision:** Update the docs to reflect the actual value.
+
+**Evidence:** `src/constants.mjs` line 2: `export const RACE_CHECK_DELAY_MS = 1500;`
+
+**Rationale:** docs/lib-overview.md stated "Wait `RACE_CHECK_DELAY_MS` (default 2000ms)" — that value is wrong. The constant is 1500. This is a P1 incorrect doc claim.
+
+**Alternatives considered:** Open an issue instead — rejected; the fix is a single-word change with unambiguous ground truth in code.
+
+---
+
+## Decision 2: Fix USAGE_TEXT query timeout default in src/constants.mjs (15000→30000)
+
+**Decision:** Update the `--help` display string to reflect the actual default.
+
+**Evidence:** `DEFAULT_QUERY_TIMEOUT_MS = 30_000` in `src/constants.mjs` line 10. The USAGE_TEXT on line 72 said `(default: 15000)` which matches `DEFAULT_PUBLISH_TIMEOUT_MS` (15_000), not the query timeout.
+
+**Rationale:** The USAGE_TEXT is a documentation string displayed in CLI `--help` output. Showing an incorrect default misleads users configuring `NOSTR_LOCK_QUERY_TIMEOUT_MS`. The fix is a one-character change with clear code evidence. Permitted as a small, safe correctness fix.
+
+**Alternatives considered:** Open an issue only — rejected; code change is trivial and unambiguous.
+
+---
+
+## Decision 3: Add 4 missing env vars to docs/removal.md cleanup list
+
+**Decision:** Add `NOSTR_LOCK_PUBLISH_TIMEOUT_MS`, `NOSTR_LOCK_MIN_SUCCESSFUL_PUBLISHES`, `NOSTR_LOCK_RELAY_FALLBACKS`, `NOSTR_LOCK_MIN_ACTIVE_RELAY_POOL` to the manual cleanup list.
+
+**Evidence:** These vars are used in `src/torch-config.mjs` and were already added to README.md in the prior docs-agent run. The removal guide's env var list was incomplete.
+
+**Rationale:** Users following the manual removal guide would leave these env vars set in their shell profile / CI / .env files. Completing the list is a P2 completeness fix.
+
+---
+
+## Decision 4: Fix Playwright claim in docs/AGENT_COVERAGE_GAPS.md
+
+**Decision:** Replace "playwright dependency and test/ integration files" with "test/ integration/e2e files (Node.js --test)".
+
+**Evidence:** `package.json` has no playwright in dependencies or devDependencies. The `test/scheduler-preflight-lock.e2e.test.mjs` file uses the Node.js built-in `--test` runner, not Playwright.
+
+**Rationale:** The Playwright claim is factually wrong. Leaving it misleads any agent/developer who reads this doc to look for Playwright configuration that does not exist.

src/decisions/DECISIONS_2026-02-20T07-00-00Z.md

@@ -0,0 +1,77 @@
+---
+agent: docs-code-investigator
+cadence: daily
+run-start: "2026-02-20T07:00:00Z"
+prompt: src/prompts/daily/docs-code-investigator.md
+---
+
+# Decisions — docs-code-investigator — 2026-02-20
+
+## Decision 1: Target file = scripts/agent/run-scheduler-cycle.mjs
+
+**Decision:** Document `scripts/agent/run-scheduler-cycle.mjs` (926 lines).
+
+**Rationale:**
+- Largest undocumented source file in the repo.
+- Central orchestrator for all agent scheduling — highest maintenance risk and value.
+- `src/lib.mjs`, `src/lock-ops.mjs`, `src/services/memory/index.js` already have overview docs.
+- Recent active commits (time-window guard, summary printing, platform detection) without documentation.
+
+**Alternatives considered:**
+- `src/ops.mjs` (795 lines) — also undocumented, but less critical than the scheduler.
+- `dashboard/app.js` (822 lines) — frontend UI, lower maintenance priority.
+
+---
+
+## Decision 2: Add top-of-file module JSDoc block with 19-step flow comment
+
+**Decision:** Add a multi-line JSDoc comment before the imports that describes the
+module's purpose, role, and numbered main flow steps.
+
+**Rationale:** The file has a comment stub ("Source of truth: numbered MUST steps…")
+but no description of what the module does or the complete execution flow. The
+19-step flow directly mirrors `src/prompts/scheduler-flow.md` and is the clearest
+way to help future maintainers understand the script.
+
+**Constraints:** Documentation only — no behavioral changes.
+
+---
+
+## Decision 3: Add JSDoc to all internal helper functions
+
+**Decision:** Add JSDoc (description, @param, @returns, @throws where applicable) to:
+parseArgs, ts, categorizeFailureMetadata, validatePromptFile, artifactExistsSince,
+verifyMemoryStep, getLatestFile, selectNextAgent, getSchedulerConfig, readRunState,
+writeRunState, createIdempotencyKey, writeLog, printRunSummary, exitWithSummary.
+
+**Rationale:** These functions are the building blocks of the scheduler loop.
+Without docs, their contracts, side effects, and error modes are unclear to
+contributors who did not write them.
+
+**Constraints:** Documentation only — no changes to function signatures or behavior.
+
+---
+
+## Decision 4: Add targeted inline comments for non-obvious logic
+
+**Decision:** Add inline comments at:
+- Lock exit 3 handling (loop restart vs. error)
+- Exclusion set fallback construction (why the union of locked/paused/completed)
+- Memory file path pre-creation (why SCHEDULER_MEMORY_FILE is injected)
+- Memory mode check (required vs. optional semantics)
+
+**Rationale:** These are the spots most likely to confuse contributors doing
+bug investigation or adding new validation gates.
+
+---
+
+## Decision 5: Create docs/scheduler-cycle-overview.md
+
+**Decision:** Create a full overview document mirroring the style of docs/lib-overview.md.
+
+**Rationale:** The scheduler cycle is the most complex operational entry point in TORCH.
+An overview doc provides a call-flow diagram, API reference, invariant documentation,
+and error path table — material that does not fit cleanly in inline comments.
+
+**No issues opened:** No correctness problems, security issues, or design concerns found
+that require maintainer decision.