diff --git a/AGENTS.md b/AGENTS.md index dba647c9..8803d66a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -464,20 +464,24 @@ Before writing any code, establish clarity on three things: ### External Notes (Persistent State Files) -Agents lose context across sessions. These files in the repo root act as persistent memory that any agent (or human) can read to resume work or understand project status. **Update them before any likely context reset.** +Agents lose context across sessions. These files act as persistent memory that any agent (or human) can read to resume work or understand project status. **Update them before any likely context reset.** -| File | Purpose | When to Update | -|------|---------|----------------| -| `CONTEXT.md` | Current goal, scope, assumptions, constraints, and a "Definition of Done" checklist | At the start of a task; when scope changes | -| `TODO.md` | Checkbox task list with "Done" and "Blocked/Questions" sections | After planning; after completing or discovering tasks | -| `DECISIONS.md` | Key choices made, alternatives considered, and rationale | When making tradeoffs or architectural decisions | -| `TEST_LOG.md` | Commands run and their results (including failures) | After every lint/test/build run | +**Storage Rule:** To prevent conflicts, these files are stored in dedicated directories with timestamps. +- **Read:** Always look for the **latest** timestamped file in the directory (e.g., `ls context/ | sort | tail -n 1`). +- **Write:** Never overwrite an existing file. Create a **new** file with a new timestamp (e.g., `context/CONTEXT_YYYY-MM-DD_HH-MM-SS.md`). + +| Directory | File Pattern | Purpose | When to Update | +|-----------|--------------|---------|----------------| +| `context/` | `CONTEXT_.md` | Current goal, scope, assumptions, constraints, and "Definition of Done" | At start; when scope changes | +| `todo/` | `TODO_.md` | Checkbox task list with "Done" and "Blocked/Questions" sections | After planning; after tasks | +| `decisions/` | `DECISIONS_.md` | Key choices made, alternatives considered, and rationale | When making tradeoffs | +| `test_logs/` | `TEST_LOG_.md` | Commands run and their results (including failures) | After every lint/test/build run | **Rules for external notes:** -- These files are working documents, not permanent artifacts. They should reflect the *current* state of work. -- When starting a fresh task, clear stale content and re-scope. Don't let old context mislead the next agent. +- These files are working documents. They should reflect the *current* state of work. +- When starting a fresh task, clear stale content (by writing a fresh file) and re-scope. - Keep entries concise — bullet points and checklists, not prose. -- `DECISIONS.md` is especially important: when you make a tradeoff (e.g., "used innerHTML here because the template is static HTML, updated the baseline"), write it down so the next agent doesn't undo it. +- `decisions/` is especially important: when you make a tradeoff, write it down so the next agent doesn't undo it. ### Work Loop @@ -501,24 +505,24 @@ For each task item, repeat this cycle: npm run lint # Required npm run test:unit:shard1 # Fast feedback; run full suite before PR ``` -- If there's no test coverage for your change, add focused tests or document in `DECISIONS.md` why tests aren't feasible. -- Log all commands and results in `TEST_LOG.md`. +- If there's no test coverage for your change, add focused tests or document in `decisions/` why tests aren't feasible. +- Log all commands and results in a new `test_logs/TEST_LOG_.md` file. #### D) Update Notes -- Check off completed items in `TODO.md`. -- Record decisions in `DECISIONS.md`. -- Log verification results in `TEST_LOG.md`. +- Check off completed items in the latest `todo/` file (by creating a new one). +- Record decisions in a new `decisions/` file. +- Log verification results in a new `test_logs/` file. - **Do this before any likely context/memory reset** — if you're about to hit a token limit, finish a long session, or hand off to another agent, update notes first. ### Context Recovery If an agent starts a session and finds existing work-in-progress: -1. **Immediately read** `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, and `TEST_LOG.md`. -2. Resume from the next unchecked item in `TODO.md`. +1. **Immediately read the latest files** in `context/`, `todo/`, `decisions/`, and `test_logs/`. +2. Resume from the next unchecked item in the latest `todo/` file. 3. Verify the current state by running `git status`, `git log --oneline -10`, and a quick lint/test pass. -4. Do not re-do work that `TEST_LOG.md` shows already passed — unless the code has changed since. +4. Do not re-do work that the latest `test_logs/` shows already passed — unless the code has changed since. ### Output Requirements @@ -526,7 +530,7 @@ When finishing a task or handing off, provide: - **Summary** of what changed and why. - **Files changed** (list). -- **Verification results** (from `TEST_LOG.md`). +- **Verification results** (from the latest `test_logs/` file). - **Follow-ups / risks / remaining TODOs**. - **If blocked:** Ask specific questions and propose 1–2 options. @@ -536,8 +540,8 @@ When finishing a task or handing off, provide: |-----------|---------| | Correctness over cleverness | Simple, working code beats elegant abstractions | | Conventions over preference | Match what's already in the repo, even if you'd do it differently | -| Explicit tradeoffs | Write down *why* in `DECISIONS.md`, don't leave the next agent guessing | -| Logged verification | Every claim of "tests pass" must have a `TEST_LOG.md` entry to back it up | +| Explicit tradeoffs | Write down *why* in `decisions/`, don't leave the next agent guessing | +| Logged verification | Every claim of "tests pass" must have a `test_logs/` entry to back it up | | Incremental over sweeping | Small, reviewable changes that keep the build green at every step | --- diff --git a/CLAUDE.md b/CLAUDE.md index 5890894e..996a17c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -84,10 +84,10 @@ bitvid/ | `tests/e2e/helpers/bitvidTestFixture.ts` | Reusable Playwright fixture for agent testing | | `scripts/agent/simple-relay.mjs` | Mock Nostr relay with HTTP seeding API | | `docs/nostr-event-schemas.md` | Event schema documentation | -| `CONTEXT.md` | Agent working state: current goal, scope, assumptions (see AGENTS.md §15) | -| `TODO.md` | Agent task checklist with done/blocked sections (see AGENTS.md §15) | -| `DECISIONS.md` | Agent decision log: choices, alternatives, rationale (see AGENTS.md §15) | -| `TEST_LOG.md` | Agent verification log: commands run and results (see AGENTS.md §15) | +| `context/` | Agent working state: current goal, scope, assumptions (see AGENTS.md §15) | +| `todo/` | Agent task checklist with done/blocked sections (see AGENTS.md §15) | +| `decisions/` | Agent decision log: choices, alternatives, rationale (see AGENTS.md §15) | +| `test_logs/` | Agent verification log: commands run and results (see AGENTS.md §15) | --- @@ -479,7 +479,7 @@ When assigning work to agents: | `docs/playback-fallback.md` | URL-first strategy | | `docs/moderation/README.md` | Moderation system | | `docs/logging.md` | Logger usage | -| `CONTEXT.md` / `TODO.md` / `DECISIONS.md` / `TEST_LOG.md` | Agent persistent state files (see AGENTS.md §15) | +| `context/` / `todo/` / `decisions/` / `test_logs/` | Agent persistent state files (see AGENTS.md §15) | --- diff --git a/CONTEXT.md b/context/CONTEXT_2026-02-13_03-04-34.md similarity index 100% rename from CONTEXT.md rename to context/CONTEXT_2026-02-13_03-04-34.md diff --git a/DECISIONS.md b/decisions/DECISIONS_2026-02-13_03-04-34.md similarity index 100% rename from DECISIONS.md rename to decisions/DECISIONS_2026-02-13_03-04-34.md diff --git a/docs/agents/prompts/daily-scheduler.md b/docs/agents/prompts/daily-scheduler.md index c4fd9773..e3aa4ed3 100644 --- a/docs/agents/prompts/daily-scheduler.md +++ b/docs/agents/prompts/daily-scheduler.md @@ -98,7 +98,7 @@ You must create a visible claim before doing any work. This claim is a **distrib ### 2a. Create your working branch and claim via draft PR 1. Create your working branch. -2. Make a minimal initial commit (e.g., update `CONTEXT.md` with the task scope). +2. Make a minimal initial commit (e.g., create a new `context/CONTEXT_.md` with the task scope). 3. Push the branch and open a **draft PR**: ```bash gh pr create --draft \ @@ -135,7 +135,7 @@ Commit and push this CSV update to your branch. This `started` entry serves as a 1. Read the selected agent's prompt file from `docs/agents/prompts/daily/`. 2. Adopt that prompt as your operating instructions for this session. 3. Follow the agent prompt's workflow end-to-end, including: - - Updating the persistent state files (`CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`) per AGENTS.md Section 15. + - Updating the persistent state files (in `context/`, `todo/`, `decisions/`, `test_logs/`) per AGENTS.md Section 15. - Running any required linting, tests, or audits specified by the agent prompt. - Creating artifacts, reports, or PRs as the agent prompt directs. diff --git a/docs/agents/prompts/daily/bitvid-audit-agent.md b/docs/agents/prompts/daily/bitvid-audit-agent.md index c1e0b6db..584d45e0 100644 --- a/docs/agents/prompts/daily/bitvid-audit-agent.md +++ b/docs/agents/prompts/daily/bitvid-audit-agent.md @@ -8,17 +8,17 @@ Run this every scheduled run (daily or weekly as the team prefers); treat the jo HARD CONSTRAINTS (must follow) - Target branch: **`unstable`**. Do not operate on other branches unless instructed. - Do **not** edit source files as part of this audit. This job runs checks and reports only. -- Work must be reproducible: record exact commands, environment, timestamps, and outputs in `TEST_LOG.md`. +- Work must be reproducible: record exact commands, environment, timestamps, and outputs in `test_logs/TEST_LOG_.md`. - Preserve confidentiality: redact any secrets in logs/screenshots before posting. - When posting to GitHub, follow repo conventions for issues/PR comments and labels (use `audit-report` label if available). - If anything in the audit touches security-sensitive areas, flag maintainers and stop automated fixes — only create issues. =============================================================================== REPO PREP (create/update these artifacts) -- `CONTEXT.md` — run metadata: target branch, date/time, node version, OS, purpose. -- `TODO.md` — checklist for the audit run and follow-ups. -- `DECISIONS.md` — any decisions or tradeoffs (e.g., what qualifies as grandfathered). -- `TEST_LOG.md` — exact commands run + raw outputs (timestamped). +- `context/CONTEXT_.md` — run metadata: target branch, date/time, node version, OS, purpose. +- `todo/TODO_.md` — checklist for the audit run and follow-ups. +- `decisions/DECISIONS_.md` — any decisions or tradeoffs (e.g., what qualifies as grandfathered). +- `test_logs/TEST_LOG_.md` — exact commands run + raw outputs (timestamped). - `artifacts/audit/YYYY-MM-DD/` — store raw reports and parsed summaries: - `file-size-report.json` (script raw output + parsed) - `innerhtml-report.json` @@ -107,7 +107,7 @@ PRIMARY WORKFLOW (end-to-end) 7. **Track and link** - Link this report issue/comment to the previous report (if any), so maintainers can easily see history. - - If automated, add a follow-up task in `TODO.md` or open issues for high-priority items with labels `perf`, `lint`, or `security` as appropriate. + - If automated, add a follow-up task in `todo/TODO_.md` or open issues for high-priority items with labels `perf`, `lint`, or `security` as appropriate. =============================================================================== ADDITIONAL GUIDANCE & BEST PRACTICES @@ -215,7 +215,7 @@ FIRST-RUN CHECKLIST (do this now) - `node scripts/check-innerhtml.mjs --report` - `npm run lint` - Save raw outputs to `artifacts/audit/$(date +%F)/` - - Record commands & outputs in `TEST_LOG.md` + - Record commands & outputs in `test_logs/TEST_LOG_.md` 4. Parse outputs into JSON (use existing script or small Node parser). 5. Compute metrics and compare with the last report (search issues/PRs). 6. Create `artifacts/audit/$(date +%F)/summary.md`. @@ -232,7 +232,7 @@ OUTPUTS (what you must produce each run) - `innerhtml-report.json` - `lint-report.json` - `summary.md` -- `TEST_LOG.md` updated with commands, environment, and outputs. +- `test_logs/TEST_LOG_.md` updated with commands, environment, and outputs. - GitHub: comment on existing audit issue/PR or new issue `Audit Report — YYYY-MM-DD` with the summary and artifacts. - If thresholds exceeded: new issues for regressions (label `perf`, `security`, or `lint`). @@ -240,7 +240,7 @@ OUTPUTS (what you must produce each run) QUALITY BAR & BEHAVIORAL GUIDELINES - Keep the job read-only; do not modify source files. - Keep reports clear, actionable, and prioritized. -- If uncertain about parsing or script semantics, add a note in `DECISIONS.md` describing assumptions. +- If uncertain about parsing or script semantics, add a note in `decisions/DECISIONS_.md` describing assumptions. - Keep the maintainers informed: link to previous reports and show deltas. =============================================================================== diff --git a/docs/agents/prompts/daily/bitvid-const-refactor-agent.md b/docs/agents/prompts/daily/bitvid-const-refactor-agent.md index 822ad97a..8229957a 100644 --- a/docs/agents/prompts/daily/bitvid-const-refactor-agent.md +++ b/docs/agents/prompts/daily/bitvid-const-refactor-agent.md @@ -12,7 +12,7 @@ HIGH-LEVEL GOALS & SUCCESS CRITERIA - If canonical exists, replace duplicates by importing that constant. - If not, add a semantically-named constant to the best shared module (`js/constants.js` for app-wide, `js/nostr/*` for nostr concerns, otherwise `js/constants/.js`) and import it. - Make small, safe edits, run linters and unit tests, and open a PR per change/related group. -- Success: repo passes `npm run lint` and `npm run test:unit`; each PR is atomic and has `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`, and a clear QA plan. +- Success: repo passes `npm run lint` and `npm run test:unit`; each PR is atomic and has files in `context/`, `todo/`, `decisions/`, `test_logs/`, and a clear QA plan. =============================================================================== HARD CONSTRAINTS / SAFETY @@ -26,10 +26,10 @@ HARD CONSTRAINTS / SAFETY =============================================================================== REPO PREP — artifacts to create Create / update these files in each PR branch and include them in the PR: -- `CONTEXT.md` — Why this refactor run exists and what it touches. -- `TODO.md` — List of duplicated constants to canonicalize and status for each. -- `DECISIONS.md` — Where canonical constants were placed and why. Record alternatives considered. -- `TEST_LOG.md` — Exact commands run (lint/tests) and outputs. +- `context/CONTEXT_.md` — Why this refactor run exists and what it touches. +- `todo/TODO_.md` — List of duplicated constants to canonicalize and status for each. +- `decisions/DECISIONS_.md` — Where canonical constants were placed and why. Record alternatives considered. +- `test_logs/TEST_LOG_.md` — Exact commands run (lint/tests) and outputs. - `perf/constants-refactor/` — optional folder to keep discovery data (raw grep output, candidate lists). Commit these artifacts as part of the PR branch (except large raw logs you may attach to the PR). @@ -46,7 +46,7 @@ DETAILED WORKFLOW (step-by-step) - Record baseline: - `git rev-parse HEAD` (commit SHA) - `node -v`, `npm -v` - - Add this metadata to `CONTEXT.md`. + - Add this metadata to `context/CONTEXT_.md`. 2) **Discover numeric duplicates** - Focus numeric values likely used for timeouts, retries, TTLs, thresholds: @@ -133,7 +133,7 @@ DETAILED WORKFLOW (step-by-step) - If tests surface logic regressions (rare if you preserved values), revert and open an **Issue** describing ambiguity and leave the candidate for human review. 7) **Document decisions** - - For each candidate, add an entry to `DECISIONS.md`: + - For each candidate, add an entry to `decisions/DECISIONS_.md`: - Value, chosen constant name, chosen file, reasoning, alternatives considered. - Example: ``` @@ -158,15 +158,15 @@ DETAILED WORKFLOW (step-by-step) - Body: - Short summary of change - Files changed - - Commands run (`npm run lint`, `npm run test:unit`) and the relevant `TEST_LOG.md` excerpt + - Commands run (`npm run lint`, `npm run test:unit`) and the relevant `test_logs/TEST_LOG_.md` excerpt - Manual QA steps - - `DECISIONS.md` pointer + - `decisions/DECISIONS_.md` pointer - Label PR with `chore(deps)` or `refactor` and `requires-review` if necessary 9) **Follow-up** - Track PR reviews and address comments. - When merged, update `INITIAL_BASELINE.md` or a `perf/constants-refactor/history.md` to note the canonicalization for future audits. - - If any replacement surfaced ambiguous semantics that required a behavior change, document in `DECISIONS.md` and open an Issue for broader discussion. + - If any replacement surfaced ambiguous semantics that required a behavior change, document in `decisions/DECISIONS_.md` and open an Issue for broader discussion. =============================================================================== DETECTION HEURISTICS / WHAT TO AVOID @@ -196,7 +196,7 @@ rg --hidden --no-ignore -n --glob 'js/**/*.js' '\b(5000|10000|30000|60000|15000| =============================================================================== PR / REVIEW CHECKLIST (what maintainers expect) - PR includes: -- `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`. +- files in `context/`, `todo/`, `decisions/`, `test_logs/`. - Clear, short commit(s) each focused on a single semantic constant. - Passing `npm run lint` and `npm run test:unit` (include logs). - A short list of modified files and the rationale. @@ -231,7 +231,7 @@ ACCEPTANCE CHECKLIST (before opening PR) * All modified files import the canonical constant correctly. * `npm run lint` succeeds. * `npm run test:unit` succeeds. -* `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` included and accurate. +* files in `context/`, `todo/`, `decisions/`, `test_logs/` included and accurate. * Commit messages start with `[constants]` and PR targets `unstable`. =============================================================================== diff --git a/docs/agents/prompts/daily/bitvid-content-audit-agent.md b/docs/agents/prompts/daily/bitvid-content-audit-agent.md index 9184b3bb..92204a4d 100644 --- a/docs/agents/prompts/daily/bitvid-content-audit-agent.md +++ b/docs/agents/prompts/daily/bitvid-content-audit-agent.md @@ -16,7 +16,7 @@ IDENTITY, SCOPE & GOALS - `/content` examples are copy-pastable and runnable (with placeholders for secrets). - Exact accepted file types, server-enforced limits, resumability, and moderation behavior are documented. - Evidence attached: curl/js examples, test logs, screenshots. - - Any changes come with tests or manual QA steps and `CONTEXT.md` / `TEST_LOG.md` / `DECISIONS.md`. + - Any changes come with tests or manual QA steps and `context/CONTEXT_.md` / `test_logs/TEST_LOG_.md` / `decisions/DECISIONS_.md`. =============================================================================== HARD CONSTRAINTS & SAFETY @@ -28,10 +28,10 @@ HARD CONSTRAINTS & SAFETY =============================================================================== REPO PREP — create these artifacts (commit to your PR branch) Before modifying docs or code, create these files and update them as you work: -- `CONTEXT.md` — the audit goal, scope, choices, branch, and run metadata (date, commit SHA, node/npm versions). -- `TODO.md` — checklist of pages and claims to verify, with statuses. -- `DECISIONS.md` — design choices, alternatives considered, and rationale for doc/code changes. -- `TEST_LOG.md` — exact commands run, environments, outputs, and manual verification notes. +- `context/CONTEXT_.md` — the audit goal, scope, choices, branch, and run metadata (date, commit SHA, node/npm versions). +- `todo/TODO_.md` — checklist of pages and claims to verify, with statuses. +- `decisions/DECISIONS_.md` — design choices, alternatives considered, and rationale for doc/code changes. +- `test_logs/TEST_LOG_.md` — exact commands run, environments, outputs, and manual verification notes. - `artifacts/docs-audit/YYYY-MM-DD/` — raw captures: curl outputs, build logs, screenshots, scripts. =============================================================================== @@ -191,7 +191,7 @@ PR body should include: - **Validation**: test steps executed and attachments (curl outputs, screenshots) - **Notes**: unresolved gaps, follow-up issues, dev changes suggested - **Commands to reproduce**: `npm run dev`, curl examples, or build steps -- Attach `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`, and artifacts in `artifacts/docs-audit/YYYY-MM-DD/` +- Attach files in `context/`, `todo/`, `decisions/`, `test_logs/`, and artifacts in `artifacts/docs-audit/YYYY-MM-DD/` - Add labels: `docs`, `audit`, and `requires-review` if necessary Acceptance Criteria: @@ -242,7 +242,7 @@ QUALITY BAR & BEHAVIOR =============================================================================== FIRST-RUN CHECKLIST (practical) -1. Create `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`. +1. Create files in `context/`, `todo/`, `decisions/`, `test_logs/`. 2. Produce inventory: `artifacts/docs-audit/YYYY-MM-DD/inventory.md`. 3. Run verification for highest-priority pages (upload/contribute). 4. Update `/content` pages and prepare diff. diff --git a/docs/agents/prompts/daily/bitvid-decompose-agent.md b/docs/agents/prompts/daily/bitvid-decompose-agent.md index fe2b70c9..f9757dd6 100644 --- a/docs/agents/prompts/daily/bitvid-decompose-agent.md +++ b/docs/agents/prompts/daily/bitvid-decompose-agent.md @@ -18,10 +18,10 @@ HIGH-LEVEL RULES & SAFETY ------------------------------------------------------------------------------- REPO PREP — artifacts to create/update Create or update these artifacts and include them in your PR branch: -- `CONTEXT.md` — the chosen file, reason for selection, commit SHA, Node/npm versions, extraction plan (blocks to extract). -- `TODO.md` — checklist of extraction items (2–3 blocks) and status. -- `DECISIONS.md` — rationale for chosen extraction boundaries, naming, and module placement. -- `TEST_LOG.md` — exact commands run with outputs (lint/tests/manual checks). +- `context/CONTEXT_.md` — the chosen file, reason for selection, commit SHA, Node/npm versions, extraction plan (blocks to extract). +- `todo/TODO_.md` — checklist of extraction items (2–3 blocks) and status. +- `decisions/DECISIONS_.md` — rationale for chosen extraction boundaries, naming, and module placement. +- `test_logs/TEST_LOG_.md` — exact commands run with outputs (lint/tests/manual checks). - `perf/decompose/` — optional helpers, raw `node scripts/check-file-size.mjs --report` output, and before/after line counts. ------------------------------------------------------------------------------- @@ -39,7 +39,7 @@ node scripts/check-file-size.mjs --report | tee perf/decompose/raw-file-size-rep git log --since="8 weeks ago" --pretty=oneline -- js/path/to/file.js ``` - If significant refactor commits exist, skip and pick the next largest. -4. Choose the single largest file **without** a recent decomposition commit and document the choice in `CONTEXT.md`. +4. Choose the single largest file **without** a recent decomposition commit and document the choice in `context/CONTEXT_.md`. ------------------------------------------------------------------------------- IDENTIFY COHESIVE BLOCKS (2–3) — what to look for @@ -62,7 +62,7 @@ For each candidate block, document: - Reason it’s cohesive - Proposed new module file path and export names -Add these items to `TODO.md`. +Add these items to `todo/TODO_.md`. ------------------------------------------------------------------------------- DECOMPOSITION GUIDELINES — implement safely @@ -162,7 +162,7 @@ TESTING & VERIFICATION (mandatory) * Start dev server if applicable and exercise flows that the original file affects. * Verify console has no errors and runtime behavior is unchanged. -4. **Record all commands & outputs** in `TEST_LOG.md`. +4. **Record all commands & outputs** in `test_logs/TEST_LOG_.md`. --- @@ -179,7 +179,7 @@ UPDATE BASELINE (scripts/check-file-size.mjs) node scripts/check-file-size.mjs --update ``` * The script will print the new `BASELINE` object. **Copy the new `BASELINE`** into `scripts/check-file-size.mjs` (replace old baseline object). -* Add a note to `DECISIONS.md` explaining why the baseline changed (file reduced, new counts). +* Add a note to `decisions/DECISIONS_.md` explaining why the baseline changed (file reduced, new counts). **Important:** Only update the baseline for this file if the size reduction is confirmed; do not change other files’ baseline entries. @@ -205,7 +205,7 @@ COMMIT & PR GUIDELINES * PR title: `[decompose] extract helpers from js/path/to/chosenFile.js` * PR body must include: - * `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` + * files in `context/`, `todo/`, `decisions/`, `test_logs/` * Before/after line count for the file (run `wc -l` or the script). * Lint & unit test outputs. * Manual QA steps & observations. @@ -221,7 +221,7 @@ ACCEPTANCE CRITERIA (must be true before merge) * `npm run test:unit` passes. * The updated `BASELINE` object in `scripts/check-file-size.mjs` reflects the new smaller size. * No behavioral changes observed in smoke tests. -* PR contains required artifacts (`CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`) and clear QA instructions. +* PR contains required artifacts (files in `context/`, `todo/`, `decisions/`, `test_logs/`) and clear QA instructions. --- @@ -252,7 +252,7 @@ FIRST-RUN CHECKLIST (execute now) ``` 2. Identify the largest grandfathered file not decomposed recently (use `git log`). 3. Create branch `ai/decompose/-v1`. -4. Read file, identify 2–3 cohesive blocks, document in `CONTEXT.md` and `TODO.md`. +4. Read file, identify 2–3 cohesive blocks, document in `context/CONTEXT_.md` and `todo/TODO_.md`. 5. Extract blocks to new files, import in original file. 6. Run `npm run lint` and `npm run test:unit`. Fix issues. 7. Update `scripts/check-file-size.mjs` baseline via `--update`; copy new `BASELINE`. @@ -273,4 +273,4 @@ EXTRA TIPS & STYLE NOTES FINAL NOTE This is a conservative, incremental refactor: extract, test, baseline, PR. The goal is smaller files and clearer module boundaries while preserving behavior. Start with the single largest, appropriate, and non-recently-decomposed file. Make 2–3 clean extractions, test thoroughly, update baseline, and open one `[decompose]` PR targeting `unstable`. -Begin now: run the file-size report, pick the file, and document the plan in `CONTEXT.md`. \ No newline at end of file +Begin now: run the file-size report, pick the file, and document the plan in `context/CONTEXT_.md`. \ No newline at end of file diff --git a/docs/agents/prompts/daily/bitvid-deps-security-agent.md b/docs/agents/prompts/daily/bitvid-deps-security-agent.md index 34f658a8..74a5291d 100644 --- a/docs/agents/prompts/daily/bitvid-deps-security-agent.md +++ b/docs/agents/prompts/daily/bitvid-deps-security-agent.md @@ -29,10 +29,10 @@ HARD CONSTRAINTS & GUARDRAILS REPO PREP — artifacts you must create/maintain Create/update these files/folders (commit them in the branch when PRing): - `artifacts/` — hold all audit/outdated/json/report outputs. -- `CONTEXT.md` — run metadata: date, package manager, Node version, CI matrix. -- `TODO.md` — upgrade tasks and statuses. -- `DECISIONS.md` — rationale for upgrade choices and tradeoffs. -- `TEST_LOG.md` — exact commands run and their outputs (timestamped). +- `context/CONTEXT_.md` — run metadata: date, package manager, Node version, CI matrix. +- `todo/TODO_.md` — upgrade tasks and statuses. +- `decisions/DECISIONS_.md` — rationale for upgrade choices and tradeoffs. +- `test_logs/TEST_LOG_.md` — exact commands run and their outputs (timestamped). - Optionally: `scripts/deps-audit.sh` for reproducible automation. Also read `AGENTS.md` and `KNOWN_ISSUES.md` for project-specific caveats (e.g., the repo uses `nostr-tools`, `webtorrent`, `Playwright`, `Tailwind`). Tag these libraries for special handling. @@ -42,7 +42,7 @@ PACKAGE MANAGER DETECTION 1. If `package-lock.json` present → `npm`. 2. Else if `pnpm-lock.yaml` present → `pnpm`. 3. Else if `yarn.lock` present → `yarn`. -Record chosen manager and versions (`node -v`, `npm -v` / `pnpm -v` / `yarn -v`) in `TEST_LOG.md`. +Record chosen manager and versions (`node -v`, `npm -v` / `pnpm -v` / `yarn -v`) in `test_logs/TEST_LOG_.md`. -------------------------------------------------------------------------------- DAILY WORKFLOW (run every day / scheduled) @@ -55,7 +55,7 @@ B. Clean install - npm: `npm ci` - pnpm: `pnpm install --frozen-lockfile` - yarn: `yarn install --frozen-lockfile` - - Save outputs to `TEST_LOG.md`. + - Save outputs to `test_logs/TEST_LOG_.md`. C. Run audits & outdated scans - `npm audit --json > artifacts/npm-audit.json` (or `pnpm audit --json` / `yarn audit --json`) @@ -96,11 +96,11 @@ F. Attempt safe upgrades (patch/minor) — strict flow - Open PR: - Branch: `ai/deps--vX.Y.Z` - Title: `chore(deps): bump to vX.Y.Z` - - Body: include `artifacts/npm-audit.json`, `artifacts/npm-outdated.json`, `TEST_LOG.md` snippets, `DECISIONS.md` rationale, QA steps, and rollback plan. + - Body: include `artifacts/npm-audit.json`, `artifacts/npm-outdated.json`, `test_logs/TEST_LOG_.md` snippets, `decisions/DECISIONS_.md` rationale, QA steps, and rollback plan. - Labels: `chore(deps)` + `requires-review` (if not trivial) or `security` (if security-related). 6. If tests **FAIL**: - Revert local changes. - - Record failure details in `TEST_LOG.md`. + - Record failure details in `test_logs/TEST_LOG_.md`. - Open issue `upgrade-` with failure reproduction steps & suggested remediation. G. DevDependency rules (special care) @@ -115,7 +115,7 @@ H. Major / risky upgrades (manual path) - Create `upgrade-` issue with: - Why upgrade is needed. - Impact analysis: direct & transitive dependents. - - Tests & reproduction steps (attach `TEST_LOG.md`). + - Tests & reproduction steps (attach `test_logs/TEST_LOG_.md`). - Suggested remediation plan (staged PRs, feature flags, compatibility tests). - Optionally propose a staged approach (test-only PRs, integration tests, staged rollout). @@ -154,7 +154,7 @@ REPORTING — artifacts you must produce - `artifacts/npm-outdated.json` — raw outdated output. - `artifacts/ncu.json` (optional) — output from `npm-check-updates`. - `artifacts/deps-report.md` — human-readable triage: top risks, candidate upgrades, PRs created, issues filed, and escalation notes. -- `TEST_LOG.md` — commands executed and test outputs for each attempted upgrade. +- `test_logs/TEST_LOG_.md` — commands executed and test outputs for each attempted upgrade. - PRs for safe upgrades and issues for risky/major/security upgrades. -------------------------------------------------------------------------------- @@ -163,7 +163,7 @@ PR & ISSUE TEMPLATE GUIDANCE - PR title: `chore(deps): bump to vX.Y.Z` - PR body: - Why: security/bug/maintenance reason. - - Commands run + test outputs (snippets), link to `TEST_LOG.md`. + - Commands run + test outputs (snippets), link to `test_logs/TEST_LOG_.md`. - Artifacts: attach `artifacts/npm-audit.json` and `artifacts/npm-outdated.json`. - Risk assessment, manual QA steps, rollback plan. - Labels: `chore(deps)`, `requires-review` / `security` as appropriate. @@ -173,7 +173,7 @@ PR & ISSUE TEMPLATE GUIDANCE QUALITY & SAFETY CHECKS BEFORE OPENING A PR - Unit, integration, e2e, and `npm run build` succeed locally and match CI. - Lockfile updated and committed. -- PR includes `TEST_LOG.md` snippets. +- PR includes `test_logs/TEST_LOG_.md` snippets. - For runtime-sensitive packages (Playwright, browsers): verify browser binaries and smoke tests. - For any package touching crypto/protocol/native bindings: **do not PR** — open issue and request reviewer. diff --git a/docs/agents/prompts/daily/bitvid-docs-alignment-agent.md b/docs/agents/prompts/daily/bitvid-docs-alignment-agent.md index c1ab91c4..a6e8dc2e 100644 --- a/docs/agents/prompts/daily/bitvid-docs-alignment-agent.md +++ b/docs/agents/prompts/daily/bitvid-docs-alignment-agent.md @@ -129,7 +129,7 @@ Deliverable: - explicitly document what was validated vs not validated and why Deliverable: - - Validation notes (in PR body and/or `TEST_LOG.md` if repo uses it). + - Validation notes (in PR body and/or `test_logs/TEST_LOG_.md` if repo uses it). 5) DELIVER — PR + summary - Open a PR with: diff --git a/docs/agents/prompts/daily/bitvid-docs-code-investigator.md b/docs/agents/prompts/daily/bitvid-docs-code-investigator.md index b824e1df..b274ca08 100644 --- a/docs/agents/prompts/daily/bitvid-docs-code-investigator.md +++ b/docs/agents/prompts/daily/bitvid-docs-code-investigator.md @@ -33,7 +33,7 @@ git grep -n -E "TODO|FIXME|XXX" -- js | sed -n '1,200p' - Is large (> 200 LOC) or contains `TODO` / `FIXME` / `XXX`. - Lives in `js/nostr/*`, `js/services/*`, or is `js/app.js` or a big controller. - Hasn’t been documented recently (check `git log -- `). -3. Document your choice in `CONTEXT.md` with: +3. Document your choice in `context/CONTEXT_.md` with: - File path, line count, reason for selection, last significant commit touching file (SHA & date). =============================================================================== @@ -142,7 +142,7 @@ npm run lint ``` - Fix only doc/JSDoc formatting issues if linter complains; do not change behavior. -- Manual quick smoke tests: import the module in node REPL or run a small script that runs the main flows (if safe and no secrets required). Record results in `TEST_LOG.md`. +- Manual quick smoke tests: import the module in node REPL or run a small script that runs the main flows (if safe and no secrets required). Record results in `test_logs/TEST_LOG_.md`. =============================================================================== COMMIT & PR GUIDELINES @@ -165,7 +165,7 @@ chore(ai): document js/path/to/file.js ``` - PR body must include: -- `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` +- files in `context/`, `todo/`, `decisions/`, `test_logs/` - Summary of documentation changes (what was added inline and any `docs/*` files) - Files modified (list) - Commands run + test/lint outputs @@ -210,7 +210,7 @@ git grep -n -E "TODO|FIXME|XXX" -- js | sed -n '1,200p' ``` 3. Select top candidate (prefer `js/nostr/*`, `js/services/*`, `js/app.js`). -4. Create `CONTEXT.md` describing the pick and the plan. +4. Create `context/CONTEXT_.md` describing the pick and the plan. 5. Perform static analysis steps A→K above and add in-code JSDoc/comments. 6. Create `docs/-overview.md` if helpful. 7. Run `npm run lint` and `npm run test:unit`, fix only doc-format issues. @@ -220,7 +220,7 @@ git grep -n -E "TODO|FIXME|XXX" -- js | sed -n '1,200p' OUTPUTS & ACCEPTANCE - Inline JSDoc & comments in the file. - `docs/-overview.md` (when created). -- PR with `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`. +- PR with files in `context/`, `todo/`, `decisions/`, `test_logs/`. - `npm run test:unit` passes and `npm run lint` passes (or only doc-style fixes). - PR labeled `area:docs` and `ai` and ready for maintainer review. @@ -231,4 +231,4 @@ FINAL NOTES - If you find cryptographic issues, stop and open `requires-security-review`. - Keep edits minimal and focused: documentation, examples, and safe comments only. -Begin now: run the file discovery commands, pick the top candidate, and add the first entries to `CONTEXT.md` describing your plan. \ No newline at end of file +Begin now: run the file discovery commands, pick the top candidate, and add the first entries to `context/CONTEXT_.md` describing your plan. \ No newline at end of file diff --git a/docs/agents/prompts/daily/bitvid-innerhtml-migration-agent.md b/docs/agents/prompts/daily/bitvid-innerhtml-migration-agent.md index 2a49dbfa..f604e312 100644 --- a/docs/agents/prompts/daily/bitvid-innerhtml-migration-agent.md +++ b/docs/agents/prompts/daily/bitvid-innerhtml-migration-agent.md @@ -16,10 +16,10 @@ HARD CONSTRAINTS & SAFETY =============================================================================== REPO PREP (create/update these artifacts) -- `CONTEXT.md` — file chosen, reason, date/commit SHA, Node/npm versions, short plan. -- `TODO.md` — checklist of assignments in the file and status. -- `DECISIONS.md` — decisions & rationale for each replaced `innerHTML` (escape vs textContent vs createElement). -- `TEST_LOG.md` — commands executed and outputs (lint/tests/manual checks). +- `context/CONTEXT_.md` — file chosen, reason, date/commit SHA, Node/npm versions, short plan. +- `todo/TODO_.md` — checklist of assignments in the file and status. +- `decisions/DECISIONS_.md` — decisions & rationale for each replaced `innerHTML` (escape vs textContent vs createElement). +- `test_logs/TEST_LOG_.md` — commands executed and outputs (lint/tests/manual checks). - `perf/innerhtml/` — (optional) logs and the `check-innerhtml` raw report output. Commit these artifacts in the PR branch so reviewers can reproduce. @@ -28,7 +28,7 @@ Commit these artifacts in the PR branch so reviewers can reproduce. WORKFLOW — top-level steps (one file only) 1. **Preflight** - `git checkout unstable && git pull --ff-only` - - `node -v` and `npm -v` recorded in `CONTEXT.md` + - `node -v` and `npm -v` recorded in `context/CONTEXT_.md` - Run the innerHTML report: ``` node scripts/check-innerhtml.mjs --report | tee perf/innerhtml/raw-report-$(date +%F).log @@ -37,7 +37,7 @@ WORKFLOW — top-level steps (one file only) - Files labeled `RISKY` in the audit (user data without escaping). - Files with the highest innerHTML counts (profileModalController, searchView, channelProfile). - Avoid low-traffic or generated/minified files (they’re lower risk or irrelevant). - - Document the chosen file and reason in `CONTEXT.md`. + - Document the chosen file and reason in `context/CONTEXT_.md`. 2. **Read the chosen file** - Open the file and locate **every** `innerHTML` assignment (search for `.innerHTML` and `element.innerHTML =`). @@ -51,7 +51,7 @@ WORKFLOW — top-level steps (one file only) - **User-derived** (comes from `profile`, `user input`, event data, server payload) - If templated, note which interpolations are user-sourced vs trusted. - Add this list to `TODO.md` as items to migrate. + Add this list to `todo/TODO_.md` as items to migrate. 3. **Decide replacement strategy (per assignment)** - **Static text**: replace with `element.textContent = "..."`. @@ -68,7 +68,7 @@ WORKFLOW — top-level steps (one file only) - **Event handlers**: - If handlers were embedded in HTML markup (e.g., `onclick="..."`) remove and use `element.addEventListener()` when reconstructing nodes. - Record the strategy per assignment in `DECISIONS.md`. + Record the strategy per assignment in `decisions/DECISIONS_.md`. 4. **Perform replacements (one-by-one)** - For each assignment: @@ -90,14 +90,14 @@ WORKFLOW — top-level steps (one file only) ``` npm run test:unit ``` - If tests fail, revert offending change(s) or adjust tests accordingly. Document failures in `TEST_LOG.md`; if the change is correct but tests need updating, update tests (prefer minimal changes). + If tests fail, revert offending change(s) or adjust tests accordingly. Document failures in `test_logs/TEST_LOG_.md`; if the change is correct but tests need updating, update tests (prefer minimal changes). 6. **Manual verification** - If the file affects UI, run a smoke test: - Start dev server: `npm run dev` (or repo-specific dev command). - Perform the user flows that exercise replaced code (profile modal open, search results, channel profile). - Verify DOM is correct, text visible, events still fire, no console errors. - - Record steps and observations in `TEST_LOG.md`. + - Record steps and observations in `test_logs/TEST_LOG_.md`. 7. **Update baseline** - After verifying, update the baseline counts so the `check-innerhtml` script knows this file was addressed: @@ -105,7 +105,7 @@ WORKFLOW — top-level steps (one file only) node scripts/check-innerhtml.mjs --update ``` - The script prints a new `BASELINE` object. **Copy** the updated `BASELINE` object into `scripts/check-innerhtml.mjs` (replace existing `BASELINE`). - - Commit the updated script with a note in `DECISIONS.md` explaining the baseline change. + - Commit the updated script with a note in `decisions/DECISIONS_.md` explaining the baseline change. NOTE: Only update the baseline after verifying replacements and ensuring the overall innerHTML count has decreased appropriately. @@ -121,7 +121,7 @@ WORKFLOW — top-level steps (one file only) git commit -m "[security] replace innerHTML usages in js/path/to/chosenFile.js — convert to safe DOM APIs" ``` - Push and open a PR targeting `unstable`. PR body must include: - - `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` + - files in `context/`, `todo/`, `decisions/`, `test_logs/` - A short summary of the file and changes: - List of assignments replaced and strategy for each. - Before/after innerHTML counts (run `node scripts/check-innerhtml.mjs --report` before and after and paste results). @@ -221,7 +221,7 @@ TESTING / QA CHECKS (must run before PR) * Optional: `npm run test:integration` if available and relevant. * Manual smoke test of UI flows touched. Record steps + screenshots (redact sensitive info). -Record all commands and outputs in `TEST_LOG.md`. +Record all commands and outputs in `test_logs/TEST_LOG_.md`. =============================================================================== ACCEPTANCE CRITERIA (before merging) @@ -230,7 +230,7 @@ ACCEPTANCE CRITERIA (before merging) * Lint passes and unit tests pass locally and in CI. * `scripts/check-innerhtml.mjs --report` shows reduced count for the chosen file. * Updated `BASELINE` object copied into `scripts/check-innerhtml.mjs`. -* PR contains `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`, summary of before/after, and QA steps. +* PR contains files in `context/`, `todo/`, `decisions/`, `test_logs/`, summary of before/after, and QA steps. * Commit message prefix is `[security]`. =============================================================================== @@ -247,7 +247,7 @@ FINAL NOTES & Etiquette * Do not attempt to be clever: prioritize safety and clarity. * Keep changes small and reversible. * If you have doubts about the nature of an `innerHTML`, stop and ask a maintainer. -* Document everything in `DECISIONS.md` so reviewers can understand assumptions. +* Document everything in `decisions/DECISIONS_.md` so reviewers can understand assumptions. Begin now: diff --git a/docs/agents/prompts/daily/bitvid-nip-research-agent.md b/docs/agents/prompts/daily/bitvid-nip-research-agent.md index 98477bca..e9d495b6 100644 --- a/docs/agents/prompts/daily/bitvid-nip-research-agent.md +++ b/docs/agents/prompts/daily/bitvid-nip-research-agent.md @@ -14,7 +14,7 @@ QUICK SUMMARY / PRIMARY GOALS SUCCESS CRITERIA: 1. Per-NIP / per-kind checklist with status, exact code pointers, and concrete fixes/tests. 2. P0 NIPs/kinds have explicit validation steps and at least one test/PR or a tracked issue. -3. Audit artifacts and documentation (`CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`) are created/updated. +3. Audit artifacts and documentation (files in `context/`, `todo/`, `decisions/`, `test_logs/`) are created/updated. NON-GOALS: - Redesigning Nostr or inventing new NIPs. @@ -23,17 +23,17 @@ NON-GOALS: =============================================================================== HARD CONSTRAINTS & SAFETY - Always consult authoritative sources (nostr-protocol/nips). Don’t assume a NIP behavior without reading its markdown and related PRs/notes. -- Tests and validations must be reproducible — record commands and environment in `TEST_LOG.md`. +- Tests and validations must be reproducible — record commands and environment in `test_logs/TEST_LOG_.md`. - Prefer tiny, incremental changes and test-only PRs. Large refactors must be proposed as issues with a staged plan. - Security-sensitive work (signing, key handling, moderation logic) must be flagged and require maintainer approval before merging. -- Preserve project style/conventions. Record tradeoffs in `DECISIONS.md`. +- Preserve project style/conventions. Record tradeoffs in `decisions/DECISIONS_.md`. =============================================================================== REPO PREP (create these artifacts immediately) -- `CONTEXT.md` — Goal, scope, timeline, and Definition of Done. -- `TODO.md` — Checklist: NIPs/kinds to research and next actions (tests/PRs/issues). -- `DECISIONS.md` — Rationale for choices and tradeoffs. -- `TEST_LOG.md` — Commands, environment, outputs, and manual test evidence. +- `context/CONTEXT_.md` — Goal, scope, timeline, and Definition of Done. +- `todo/TODO_.md` — Checklist: NIPs/kinds to research and next actions (tests/PRs/issues). +- `decisions/DECISIONS_.md` — Rationale for choices and tradeoffs. +- `test_logs/TEST_LOG_.md` — Commands, environment, outputs, and manual test evidence. - `NIP_INVENTORY.md` — blank template for per-NIP entries. - `artifacts/nips/` — local copies of fetched NIP markdowns and related docs. - `test/nostr-specs/` — (optional) test fixtures & spec regression tests. @@ -82,7 +82,7 @@ WORKFLOW — daily operating steps (detailed) - `NIP`, `spec_url`, `short_description`, `repo_locations` (file:lines), `status` (Unknown). 2) **Fetch canonical specs** - - For each NIP found, download the canonical markdown from `nostr-protocol/nips` to `artifacts/nips/`. Record fetch command and timestamp in `TEST_LOG.md`. + - For each NIP found, download the canonical markdown from `nostr-protocol/nips` to `artifacts/nips/`. Record fetch command and timestamp in `test_logs/TEST_LOG_.md`. - Summarize required fields, tag recommendations, canonical serialization, encryption notes, and best practices into the inventory entry. 3) **Map-to-code** @@ -99,7 +99,7 @@ WORKFLOW — daily operating steps (detailed) - Validate tag parsing/normalization (`parseRelayTags`, `sanitizeMuteTags`) with spec-conformant and malformed examples. - Validate decryption flow in `dmDecryptWorker`: feed known nip44_v2/nip44/nip04 ciphertext fixtures and assert fallback order and plaintext. - Validate relay list load/publish: simulate `nostrClient.pool.list` responses and ensure `relayManager.loadRelayList` behaves per spec (fast vs background, timeouts). - - Record commands and outputs to `TEST_LOG.md`. Save fixtures to `test/nostr-specs/fixtures/`. + - Record commands and outputs to `test_logs/TEST_LOG_.md`. Save fixtures to `test/nostr-specs/fixtures/`. 5) **Compliance verdict** - For each NIP/kind, set `status` to: `Compliant`, `Partial`, `Non-compliant`, or `Unknown`. @@ -173,7 +173,7 @@ TESTS & AUTOMATION (what to add) =============================================================================== PR & ISSUE GUIDELINES (what your remediation PRs/issues must include) - PRs for fixes should include: - - `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`. + - files in `context/`, `todo/`, `decisions/`, `test_logs/`. - Minimal code changes with tests that assert spec compliance. - Clear manual QA steps and rollback instructions. - Label: `nip-compliance`, `chore`, `requires-review`, and `security` if relevant. @@ -198,13 +198,13 @@ DELIVERABLES & TIMELINE =============================================================================== BEHAVIORAL & REVIEW RULES -- Always log decisions in `DECISIONS.md` and link to spec markdowns used. +- Always log decisions in `decisions/DECISIONS_.md` and link to spec markdowns used. - If a change touches security (signing, key handling, moderation), **do not merge** — open PR and request maintainer review. - Keep changes minimal and well-documented. If in doubt, open an issue and propose two remediation options. =============================================================================== FIRST-RUN CHECKLIST (do this now) -1. Create and commit `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`, and `NIP_INVENTORY.md`. +1. Create and commit files in `context/`, `todo/`, `decisions/`, `test_logs/`, and `NIP_INVENTORY.md`. 2. Run: `rg "nip[0-9]+|kind\\s*[:=]|nip04|nip44|nip07|nip46|naddr|nevent|BLOCK_LIST_IDENTIFIER" -n > test-audit/nip-hits.txt` 3. For each unique NIP number found, fetch the canonical spec into `artifacts/nips/` and summarize it. 4. Map each NIP to code pointers (use `rg` and open files to find functions). @@ -216,7 +216,7 @@ OUTPUTS (what you must produce each run) - `NIP_INVENTORY.md` — full per-NIP/kind table with code pointers, status, and test plan. - `artifacts/nips/*.md` — canonical NIP markdowns fetched. - `nip-report-YYYY-MM-DD.md` — high-level run report with P0/P1 items and PRs/issues links. -- Tests/PRs/Issues for remediation, with `CONTEXT.md`, `TODO.md`, `DECISIONS.md` and `TEST_LOG.md`. +- Tests/PRs/Issues for remediation, with `context/CONTEXT_.md`, `todo/TODO_.md`, `decisions/DECISIONS_.md` and `test_logs/TEST_LOG_.md`. - `test/nostr-specs/fixtures/` — representative events/ciphertexts used for validation. =============================================================================== diff --git a/docs/agents/prompts/daily/bitvid-perf-agent.md b/docs/agents/prompts/daily/bitvid-perf-agent.md index a12295cb..f478e412 100644 --- a/docs/agents/prompts/daily/bitvid-perf-agent.md +++ b/docs/agents/prompts/daily/bitvid-perf-agent.md @@ -23,23 +23,23 @@ PRIMARY GOALS & SUCCESS CRITERIA - Login/auth & profile hydration not blocked by background tasks. - Decryption/list loads off-main-thread or bounded; measurable user delay reduction. - `/content` accurately documents upload endpoints, types, limits, resumability, moderation. - - Every fix is a small PR with `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` and tests/QA steps. + - Every fix is a small PR with files in `context/`, `todo/`, `decisions/`, `test_logs/` and tests/QA steps. ------------------------------------------------------------------------------- HARD CONSTRAINTS (must-follow) - Never invent files, APIs, libraries, or behaviors — inspect code first. - Prefer minimal incremental changes over rewrites. -- Keep builds/tests green. If tests fail, either fix or document failures in `TEST_LOG.md`. -- Preserve repo style & architecture; record tradeoffs in `DECISIONS.md`. +- Keep builds/tests green. If tests fail, either fix or document failures in `test_logs/TEST_LOG_.md`. +- Preserve repo style & architecture; record tradeoffs in `decisions/DECISIONS_.md`. - Security-sensitive changes (crypto, moderation) require human signoff — do not merge automatically. ------------------------------------------------------------------------------- REPOSITORY PREP (create/update immediately) Commit early and often: -- `CONTEXT.md` — goal, scope, assumptions, DoD. -- `TODO.md` — tasks (Done / Blocked). -- `DECISIONS.md` — design choices & rationale. -- `TEST_LOG.md` — commands, env, outputs, failures. +- `context/CONTEXT_.md` — goal, scope, assumptions, DoD. +- `todo/TODO_.md` — tasks (Done / Blocked). +- `decisions/DECISIONS_.md` — design choices & rationale. +- `test_logs/TEST_LOG_.md` — commands, env, outputs, failures. - `INITIAL_BASELINE.md` — baseline metrics (login time, decrypt queue size, relay latencies, webtorrent count). - `perf/` (optional) — scripts and small helpers. @@ -111,7 +111,7 @@ SMALL SAFE FIX EXAMPLES (PRs) - **docs: `/content` upload alignment** - Audit `/content`, update exact accepted types, size limits, endpoints, resumability examples (curl/JS). -All PRs: small, feature-flagged if risky, include `CONTEXT.md`, `TEST_LOG.md`, `DECISIONS.md`. +All PRs: small, feature-flagged if risky, include `context/CONTEXT_.md`, `test_logs/TEST_LOG_.md`, `decisions/DECISIONS_.md`. ------------------------------------------------------------------------------- DOCS AUDIT (integrated sub-workflow — mandatory when doc/code touched) @@ -125,9 +125,9 @@ DOCS AUDIT (integrated sub-workflow — mandatory when doc/code touched) WORK LOOP & VERIFICATION (for code changes) A) PLAN: 3–7 bullet plan before coding. B) IMPLEMENT: smallest change satisfying requirement. -C) VERIFY: run linters & tests; log to `TEST_LOG.md`. -D) DOCUMENT: update `DECISIONS.md` with rationale. -E) PR: include `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` and QA steps. +C) VERIFY: run linters & tests; log to `test_logs/TEST_LOG_.md`. +D) DOCUMENT: update `decisions/DECISIONS_.md` with rationale. +E) PR: include files in `context/`, `todo/`, `decisions/`, `test_logs/` and QA steps. If blocked: open issue with reproduction & 1–2 options. @@ -147,7 +147,7 @@ PR & ISSUE GUIDELINES (what to include) - PR body: - Summary of change & why. - Plan bullets (3–7). - - Commands run & `TEST_LOG.md` excerpt. + - Commands run & `test_logs/TEST_LOG_.md` excerpt. - QA steps & manual validation instructions. - Risk assessment, rollback plan, and labels: `perf`, `requires-review`, `security` when relevant. @@ -163,7 +163,7 @@ ESCALATION & RISK POLICY ------------------------------------------------------------------------------- FIRST-RUN CHECKLIST (execute now) -1. Commit `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`, `INITIAL_BASELINE.md`. +1. Commit files in `context/`, `todo/`, `decisions/`, `test_logs/`, `INITIAL_BASELINE.md`. 2. Run Search Patterns across repo and save `perf/hits-YYYY-MM-DD.json`. 3. Prioritize P0 findings, open at most 1–3 small PRs (bounded concurrency, worker queue limits, visibility gating). 4. Audit `/content` upload pages: inventory claims → map to code → verify → open docs PR or issue. @@ -177,7 +177,7 @@ OUTPUTS (per run) - Metrics (login-time, queue sizes). - PRs opened / Issues opened. - Blockers & human decisions requested. -- For every PR: branch contains `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`. +- For every PR: branch contains files in `context/`, `todo/`, `decisions/`, `test_logs/`. - For docs PR: verification artifacts attached. ------------------------------------------------------------------------------- @@ -186,7 +186,7 @@ BEHAVIORAL GUARDRAILS & QUALITY BAR - Keep changes small and consistent with conventions. - Log decisions and tests. Add comments near non-obvious tradeoffs. - Do not merge crypto/moderation changes without human review. -- If context is lost: read `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`. +- If context is lost: read files in `context/`, `todo/`, `decisions/`, `test_logs/`. ------------------------------------------------------------------------------- FINAL NOTE diff --git a/docs/agents/prompts/daily/bitvid-scheduler-update-agent.md b/docs/agents/prompts/daily/bitvid-scheduler-update-agent.md index 4a91381f..6b3d3e7f 100644 --- a/docs/agents/prompts/daily/bitvid-scheduler-update-agent.md +++ b/docs/agents/prompts/daily/bitvid-scheduler-update-agent.md @@ -70,8 +70,8 @@ WORKFLOW 1. Preflight - Read `AGENTS.md` and `CLAUDE.md`. - - Update persistent state files (`CONTEXT.md`, `TODO.md`, `DECISIONS.md`, - `TEST_LOG.md`) per AGENTS.md Section 15. + - Update persistent state files (`context/CONTEXT_.md`, `todo/TODO_.md`, `decisions/DECISIONS_.md`, + `test_logs/TEST_LOG_.md`) per AGENTS.md Section 15. 2. Inventory — Daily prompts - List all `.md` files in `/docs/agents/prompts/daily/`. @@ -121,7 +121,7 @@ WORKFLOW 9. Document - Log what changed (additions, removals, renames) in the commit message. - - Update `TEST_LOG.md` with the verification results. + - Update `test_logs/TEST_LOG_.md` with the verification results. ─────────────────────────────────────────────────────────────────────────────── VERIFICATION @@ -152,7 +152,7 @@ FAILURE MODES recreate scheduler files from scratch. - If you cannot determine whether a file was renamed vs. one deleted and another added, treat them as separate deletion + addition. Log the - ambiguity in `DECISIONS.md`. + ambiguity in `decisions/DECISIONS_.md`. - If the roster table format has changed and no longer matches the expected pattern, stop and open an issue rather than risking a malformed edit. @@ -179,8 +179,8 @@ OUTPUTS PER RUN - 0–1 PRs (skip if no changes needed — rosters already in sync). - Updated scheduler files (if changes were needed). -- Updated persistent state files (`CONTEXT.md`, `TODO.md`, `DECISIONS.md`, - `TEST_LOG.md`). +- Updated persistent state files (`context/CONTEXT_.md`, `todo/TODO_.md`, `decisions/DECISIONS_.md`, + `test_logs/TEST_LOG_.md`). - Commit message documenting exactly what changed. ─────────────────────────────────────────────────────────────────────────────── diff --git a/docs/agents/prompts/daily/bitvid-test-audit-agent.md b/docs/agents/prompts/daily/bitvid-test-audit-agent.md index 0e9cca71..b89f62fb 100644 --- a/docs/agents/prompts/daily/bitvid-test-audit-agent.md +++ b/docs/agents/prompts/daily/bitvid-test-audit-agent.md @@ -14,24 +14,24 @@ PRIMARY GOALS / SUCCESS CRITERIA - Success criteria: - A `test-audit-report-YYYY-MM-DD.md` with failing/flaky tests, suspicious tests, coverage map, and prioritized remediation. - Each P0 test problem (login/auth, decryption, relay prefs, moderation lists, watch history) has a PR or an actionable issue. - - Reproducible `TEST_LOG.md` entries detailing test runs and flakiness runs. + - Reproducible `test_logs/TEST_LOG_.md` entries detailing test runs and flakiness runs. =============================================================================== HARD CONSTRAINTS - Detect the real test runner from `package.json` and use it. Don’t assume Jest if the project uses Vitest, Mocha, etc. - Prefer incremental test-only changes. Do not rewrite large test suites in one PR. - Keep CI green: every PR must include rollback instructions. Mark security/moderation test changes for maintainer review. -- Do not change production code solely to satisfy tests unless the change is tiny, safe, well-justified, and recorded in `DECISIONS.md`. +- Do not change production code solely to satisfy tests unless the change is tiny, safe, well-justified, and recorded in `decisions/DECISIONS_.md`. - Make all results reproducible: include exact commands, env, timestamps, node/npm versions. =============================================================================== REPO PREP (create/ensure these artifacts) Create or update these files and folders in the repo before making changes: -- `CONTEXT.md` — reason for the audit run, scope, DoD (definition of done). -- `TODO.md` — checklist of specific tests/issues to investigate/fix. -- `DECISIONS.md` — decisions, tradeoffs, and approval notes for any changes. -- `TEST_LOG.md` — timestamped commands executed and raw outputs (test runs, flakiness reruns, coverage). +- `context/CONTEXT_.md` — reason for the audit run, scope, DoD (definition of done). +- `todo/TODO_.md` — checklist of specific tests/issues to investigate/fix. +- `decisions/DECISIONS_.md` — decisions, tradeoffs, and approval notes for any changes. +- `test_logs/TEST_LOG_.md` — timestamped commands executed and raw outputs (test runs, flakiness reruns, coverage). - `test-audit/` — store artifacts and helper scripts (optional). Example contents: - `test-audit/run-flaky-check.sh` - `test-audit/coverage-summary.json` @@ -46,7 +46,7 @@ DAILY WORKFLOW (run every day or as scheduled) - Inspect `package.json`: - `test` script (e.g., `jest`, `vitest`, `mocha`, `cypress`, `playwright`). - Test-related devDependencies. - - Record the canonical test command in `TEST_LOG.md`. Example commands: + - Record the canonical test command in `test_logs/TEST_LOG_.md`. Example commands: - Jest: `npm test -- --coverage` or `npx jest --coverage` - Vitest: `npx vitest run --coverage` - Mocha + nyc: `npx nyc --reporter=lcov npm test` @@ -60,7 +60,7 @@ DAILY WORKFLOW (run every day or as scheduled) - If the repo has unit/integration/e2e separations, run them individually and capture outputs. - Collect coverage artifacts: - Common outputs: `coverage/lcov.info`, `coverage/coverage-final.json`, `coverage/coverage-summary.json`. - - Save all logs and coverage files into `test-audit/` and note commands in `TEST_LOG.md`. + - Save all logs and coverage files into `test-audit/` and note commands in `test_logs/TEST_LOG_.md`. 3) **Flakiness detection** - Re-run the whole test suite N times (default `N=5` or `N=10`) and produce a run matrix: @@ -125,7 +125,7 @@ DAILY WORKFLOW (run every day or as scheduled) 10) **Daily report** - Produce `test-audit-report-YYYY-MM-DD.md` containing: - One-line summary and run metadata (node/npm/runner versions). - - Test command(s) used and snippet of `TEST_LOG.md`. + - Test command(s) used and snippet of `test_logs/TEST_LOG_.md`. - List of failing tests and stack traces. - Flaky tests with run matrix (which runs passed/failed). - Suspicious tests (zero assertions, heavy mocking, real network calls). @@ -157,12 +157,12 @@ Adapt regexes to repo conventions and test frameworks. =============================================================================== PR & ISSUE GUIDELINES (what to include) - PR types: - 1. **Test-fix PR** — add missing assertions, replace `setTimeout` sleeps with `waitFor`, or mock timers. Include `CONTEXT.md`, `TODO.md`, `TEST_LOG.md`. + 1. **Test-fix PR** — add missing assertions, replace `setTimeout` sleeps with `waitFor`, or mock timers. Include `context/CONTEXT_.md`, `todo/TODO_.md`, `test_logs/TEST_LOG_.md`. 2. **Test-add PR** — add tests for missing critical behavior. Keep them small and deterministic. 3. **Test-refactor PR** — convert overly-mocked tests into higher-level tests that assert observable outcomes. - PR body must include: - Why the change is needed (link to audit). - - Commands run and output snippet (`TEST_LOG.md`). + - Commands run and output snippet (`test_logs/TEST_LOG_.md`). - Manual QA steps to reproduce flaky behavior and validate fix. - Risk assessment and rollback steps. - Labels: `test`, `chore`, `requires-review` (if needed), `security` (if test touches security). @@ -216,14 +216,14 @@ EXAMPLE REMEDIATIONS (what PRs should do) =============================================================================== BEHAVIORAL GUIDELINES & SAFETY -- Do not change production logic just to satisfy tests; update tests instead. If production change is required, document and put in `DECISIONS.md`. +- Do not change production logic just to satisfy tests; update tests instead. If production change is required, document and put in `decisions/DECISIONS_.md`. - For security/moderation tests, create PRs and request explicit maintainer review before merging. - Prefer small, focused PRs. Each change must be reviewable and reversible. - When uncertain, perform the minimal remediation to make failures reproducible and open an issue describing further work. =============================================================================== FIRST-RUN CHECKLIST (execute now) -1. Create `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`, and `test-audit/`. +1. Create files in `context/`, `todo/`, `decisions/`, `test_logs/`, and `test-audit/`. 2. Detect test runner from `package.json`. 3. Run the primary test command with coverage and capture logs. - Example: `npm test -- --coverage 2>&1 | tee test-audit/coverage-run.log` @@ -238,7 +238,7 @@ OUTPUTS (what you must produce each run) - `test-audit/coverage-*` artifacts and `coverage-summary.json`. - `test-audit/flakiness-matrix.json`. - `test-audit/suspicious-tests.json`. -- Updated `TEST_LOG.md` with full commands and outputs (timestamped). +- Updated `test_logs/TEST_LOG_.md` with full commands and outputs (timestamped). - PRs for test fixes and Issues for larger/risky work. =============================================================================== diff --git a/docs/agents/prompts/weekly-scheduler.md b/docs/agents/prompts/weekly-scheduler.md index 64f619ed..2c80ca2e 100644 --- a/docs/agents/prompts/weekly-scheduler.md +++ b/docs/agents/prompts/weekly-scheduler.md @@ -93,7 +93,7 @@ You must create a visible claim before doing any work. This claim is a **distrib ### 2a. Create your working branch and claim via draft PR 1. Create your working branch. -2. Make a minimal initial commit (e.g., update `CONTEXT.md` with the task scope). +2. Make a minimal initial commit (e.g., create a new `context/CONTEXT_.md` with the task scope). 3. Push the branch and open a **draft PR**: ```bash gh pr create --draft \ @@ -130,7 +130,7 @@ Commit and push this CSV update to your branch. This `started` entry serves as a 1. Read the selected agent's prompt file from `docs/agents/prompts/weekly/`. 2. Adopt that prompt as your operating instructions for this session. 3. Follow the agent prompt's workflow end-to-end, including: - - Updating the persistent state files (`CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md`) per AGENTS.md Section 15. + - Updating the persistent state files (in `context/`, `todo/`, `decisions/`, `test_logs/`) per AGENTS.md Section 15. - Running any required linting, tests, or audits specified by the agent prompt. - Creating artifacts, reports, or PRs as the agent prompt directs. diff --git a/test_logs/TEST_LOG_2026-02-13_03-04-34.md b/test_logs/TEST_LOG_2026-02-13_03-04-34.md new file mode 100644 index 00000000..e69de29b diff --git a/TODO.md b/todo/TODO_2026-02-13_03-04-34.md similarity index 100% rename from TODO.md rename to todo/TODO_2026-02-13_03-04-34.md