mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 07:52:24 +00:00
chore(agents): migrate persistent state files to timestamped directories
- Move `CONTEXT.md`, `TODO.md`, `DECISIONS.md`, `TEST_LOG.md` to `context/`, `todo/`, `decisions/`, `test_logs/` directories with timestamps. - Update `AGENTS.md` and `CLAUDE.md` to define the new workflow: agents must read the latest timestamped file and create a new one when updating. - Update `daily-scheduler.md` and `weekly-scheduler.md` to initialize tasks using the new file structure. - Update all daily agent prompts to reference the new directory structure. - This change prevents merge conflicts on persistent state files by treating them as an append-only log of snapshots. Co-authored-by: PR0M3TH3AN <[email protected]>
This commit is contained in:
google-labs-jules[bot]andPR0M3TH3AN committed
1 parent
78aef106b3
commit
77ec8e18c3
20 files changed
+156
-152
No files matched your search
@@ -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_<timestamp>.md` | Current goal, scope, assumptions, constraints, and "Definition of Done" | At start; when scope changes |
|
||||
| `todo/` | `TODO_<timestamp>.md` | Checkbox task list with "Done" and "Blocked/Questions" sections | After planning; after tasks |
|
||||
| `decisions/` | `DECISIONS_<timestamp>.md` | Key choices made, alternatives considered, and rationale | When making tradeoffs |
|
||||
| `test_logs/` | `TEST_LOG_<timestamp>.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_<timestamp>.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 |
|
||||
|
||||
---
|
||||
|
||||
@@ -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) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
File renamed without changes.
File renamed without changes.
@@ -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_<timestamp>.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/<filename>`.
|
||||
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.
|
||||
|
||||
|
||||
@@ -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_<timestamp>.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_<timestamp>.md` — run metadata: target branch, date/time, node version, OS, purpose.
|
||||
- `todo/TODO_<timestamp>.md` — checklist for the audit run and follow-ups.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — any decisions or tradeoffs (e.g., what qualifies as grandfathered).
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md` describing assumptions.
|
||||
- Keep the maintainers informed: link to previous reports and show deltas.
|
||||
|
||||
===============================================================================
|
||||
|
||||
@@ -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/<domain>.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_<timestamp>.md` — Why this refactor run exists and what it touches.
|
||||
- `todo/TODO_<timestamp>.md` — List of duplicated constants to canonicalize and status for each.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — Where canonical constants were placed and why. Record alternatives considered.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md` excerpt
|
||||
- Manual QA steps
|
||||
- `DECISIONS.md` pointer
|
||||
- `decisions/DECISIONS_<timestamp>.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_<timestamp>.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`.
|
||||
|
||||
===============================================================================
|
||||
|
||||
@@ -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_<timestamp>.md` / `test_logs/TEST_LOG_<timestamp>.md` / `decisions/DECISIONS_<timestamp>.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_<timestamp>.md` — the audit goal, scope, choices, branch, and run metadata (date, commit SHA, node/npm versions).
|
||||
- `todo/TODO_<timestamp>.md` — checklist of pages and claims to verify, with statuses.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — design choices, alternatives considered, and rationale for doc/code changes.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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.
|
||||
|
||||
@@ -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_<timestamp>.md` — the chosen file, reason for selection, commit SHA, Node/npm versions, extraction plan (blocks to extract).
|
||||
- `todo/TODO_<timestamp>.md` — checklist of extraction items (2–3 blocks) and status.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — rationale for chosen extraction boundaries, naming, and module placement.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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/<short-file-name>-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_<timestamp>.md` and `todo/TODO_<timestamp>.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`.
|
||||
Begin now: run the file-size report, pick the file, and document the plan in `context/CONTEXT_<timestamp>.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_<timestamp>.md` — run metadata: date, package manager, Node version, CI matrix.
|
||||
- `todo/TODO_<timestamp>.md` — upgrade tasks and statuses.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — rationale for upgrade choices and tradeoffs.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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-<pkg>-vX.Y.Z`
|
||||
- Title: `chore(deps): bump <pkg> 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_<timestamp>.md` snippets, `decisions/DECISIONS_<timestamp>.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_<timestamp>.md`.
|
||||
- Open issue `upgrade-<pkg>` with failure reproduction steps & suggested remediation.
|
||||
|
||||
G. DevDependency rules (special care)
|
||||
@@ -115,7 +115,7 @@ H. Major / risky upgrades (manual path)
|
||||
- Create `upgrade-<pkg>` 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_<timestamp>.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_<timestamp>.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 <pkg> 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_<timestamp>.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_<timestamp>.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.
|
||||
|
||||
|
||||
@@ -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_<timestamp>.md` if repo uses it).
|
||||
|
||||
5) DELIVER — PR + summary
|
||||
- Open a PR with:
|
||||
|
||||
@@ -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 -- <path>`).
|
||||
3. Document your choice in `CONTEXT.md` with:
|
||||
3. Document your choice in `context/CONTEXT_<timestamp>.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_<timestamp>.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_<timestamp>.md` describing the pick and the plan.
|
||||
5. Perform static analysis steps A→K above and add in-code JSDoc/comments.
|
||||
6. Create `docs/<module>-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/<module>-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.
|
||||
Begin now: run the file discovery commands, pick the top candidate, and add the first entries to `context/CONTEXT_<timestamp>.md` describing your plan.
|
||||
@@ -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_<timestamp>.md` — file chosen, reason, date/commit SHA, Node/npm versions, short plan.
|
||||
- `todo/TODO_<timestamp>.md` — checklist of assignments in the file and status.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — decisions & rationale for each replaced `innerHTML` (escape vs textContent vs createElement).
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md` so reviewers can understand assumptions.
|
||||
|
||||
Begin now:
|
||||
|
||||
|
||||
@@ -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_<timestamp>.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_<timestamp>.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_<timestamp>.md` — Goal, scope, timeline, and Definition of Done.
|
||||
- `todo/TODO_<timestamp>.md` — Checklist: NIPs/kinds to research and next actions (tests/PRs/issues).
|
||||
- `decisions/DECISIONS_<timestamp>.md` — Rationale for choices and tradeoffs.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md`, `todo/TODO_<timestamp>.md`, `decisions/DECISIONS_<timestamp>.md` and `test_logs/TEST_LOG_<timestamp>.md`.
|
||||
- `test/nostr-specs/fixtures/` — representative events/ciphertexts used for validation.
|
||||
|
||||
===============================================================================
|
||||
|
||||
@@ -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_<timestamp>.md`.
|
||||
- Preserve repo style & architecture; record tradeoffs in `decisions/DECISIONS_<timestamp>.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_<timestamp>.md` — goal, scope, assumptions, DoD.
|
||||
- `todo/TODO_<timestamp>.md` — tasks (Done / Blocked).
|
||||
- `decisions/DECISIONS_<timestamp>.md` — design choices & rationale.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.md`, `test_logs/TEST_LOG_<timestamp>.md`, `decisions/DECISIONS_<timestamp>.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_<timestamp>.md`.
|
||||
D) DOCUMENT: update `decisions/DECISIONS_<timestamp>.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_<timestamp>.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
|
||||
|
||||
@@ -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_<timestamp>.md`, `todo/TODO_<timestamp>.md`, `decisions/DECISIONS_<timestamp>.md`,
|
||||
`test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md`, `todo/TODO_<timestamp>.md`, `decisions/DECISIONS_<timestamp>.md`,
|
||||
`test_logs/TEST_LOG_<timestamp>.md`).
|
||||
- Commit message documenting exactly what changed.
|
||||
|
||||
───────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -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_<timestamp>.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_<timestamp>.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_<timestamp>.md` — reason for the audit run, scope, DoD (definition of done).
|
||||
- `todo/TODO_<timestamp>.md` — checklist of specific tests/issues to investigate/fix.
|
||||
- `decisions/DECISIONS_<timestamp>.md` — decisions, tradeoffs, and approval notes for any changes.
|
||||
- `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md`, `todo/TODO_<timestamp>.md`, `test_logs/TEST_LOG_<timestamp>.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_<timestamp>.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_<timestamp>.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_<timestamp>.md` with full commands and outputs (timestamped).
|
||||
- PRs for test fixes and Issues for larger/risky work.
|
||||
|
||||
===============================================================================
|
||||
|
||||
@@ -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_<timestamp>.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/<filename>`.
|
||||
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.
|
||||
|
||||
|
||||
Whitespace-only changes.
File renamed without changes.
Reference in new issue
Block a user