chore(harness): align with CoderSkills continuous-project-loop (plan check, harness tests, fresh plan files)

AGENTS.md

@@ -13,3 +13,10 @@ Project harness follows `jammyfu/CoderSkills` → `skills/continuous-project-loo
 - The "hottest new repos (7 days)" ranking is discovered by `tools/newcomers.py` from the search API; it must never repeat a project from another ranking (see `docs/NEW_ARRIVALS.md`).
 
 - Categories (AI primary + others) are defined in `data/categories.json` and documented in `docs/CATEGORIES.md`. Newcomers are per-category; see `docs/NEW_ARRIVALS.md`.
+
+## Harness rules (from `jammyfu/CoderSkills`: `skills/continuous-project-loop`, `skills/multi-project-program-management`)
+
+- Each round: Assess (read this file, `CURRENT_PLAN.md`, `TODO_BACKLOG.md`, `WORKLOG.md`) -> Plan (one Goal, 3-7 verifiable tasks, Out of Scope, Next Candidates; check with `python3 tools/next_plan.py --check`) -> Implement one minimal closed loop -> Verify (`python3 tools/verify.py`) -> Record (`CURRENT_PLAN.md`, `WORKLOG.md`, `TODO_BACKLOG.md`, `DECISIONS.md`, `CHANGELOG.md` when users can see the change) -> Continue (write the next step into the files, not only into the reply).
+- Dirty worktree: if a run starts with uncommitted changes, finish or park them first (`verify` -> PR); do not stack new work on top. `tools/local_daily.sh` refuses to run on a dirty tree or off `main`.
+- Verification must not depend on the shell PATH: `tools/verify.py` and `tools/local_daily.sh` use explicit interpreters, no `shell=True` (guarded by `tests/test_harness.py`).
+- Do not edit the plan files to claim a result that `tools/verify.py` has not confirmed.

CURRENT_PLAN.md

@@ -1,16 +1,39 @@
-# CURRENT_PLAN
+# CURRENT_PLAN.md
+
+## Plan ID
+
+PLAN-001
 
 ## Goal
 
-Rebrand `ai-growth-atlas` → `github-risers` with multi-category rankings (AI primary). Open PR only; rename repo after CI green; do not merge.
+Align `github-risers` with the CoderSkills harness (`continuous-project-loop`, `multi-project-program-management`) without touching rankings, translations, GEO files or the slim README.
+
+## In Scope
+
+- Plan files and governance records that are accurate and rollable (`CURRENT_PLAN.md`, `MASTER_PLAN.md`, `TODO_BACKLOG.md`, `docs/project-governance/*`)
+- The loop rules written into repo files, not only into chat (`AGENTS.md`, `docs/AUTOMATION_COMMANDS.md`, `docs/LONG_RUNNING_AUTONOMY.md`)
+- `tools/next_plan.py --check` plus regression tests for the verify and local-daily entry points (`tests/test_harness.py`)
+
+## Out of Scope
+
+- Ranking logic, categories, the ⚠ suspected-crack rules, `data/`, `latest/`, `rankings/`, generated READMEs
+- The translation library, glossary, GEO files (`docs/index.html`, `llms.txt`, `CITATION.cff`, FAQ, FACTS, social preview)
+- Any new telemetry, any data not coming from the GitHub API
+
+## Tasks
+
+- [x] Audit the repo against `skills/continuous-project-loop/SKILL.md` and `skills/multi-project-program-management/SKILL.md`; list the gaps in `docs/project-governance/DECISIONS.md`
+- [x] Replace the stale plan, master plan, backlog, acceptance, worklog, decisions and changelog with the current state
+- [x] Put the dirty-worktree rule, the record order and the verify hardening rule into `AGENTS.md` and `docs/`
+- [x] Add `python3 tools/next_plan.py --check` (planning rules) and `tests/test_harness.py` (required files, plan shape, rolling, verify and local_daily hardening)
+- [ ] Owner reviews the PR; merge only with approval
 
-## Done this round
+## Verification
 
-- Categories: ai, devtools, security, web, infra, design, data
-- Per-category newcomers + week/month/year/total
-- Rename strings, docs, launchd, User-Agent, llms.txt
-- Real API run + verify green
+- `python3 tools/verify.py`
+- `python3 tools/next_plan.py --check`
 
-## Next
+## Next Candidates
 
-- CI green on PR → `gh repo rename github-risers`
+- Thin Developer Tools / Design / Data new-repo boards: see `TODO_BACKLOG.md`
+- Acceleration column (this week vs the week before)

MASTER_PLAN.md

@@ -2,32 +2,38 @@
 
 ## Goal
 
-A trustworthy, daily-refreshed ranking of fast-rising AI projects, readable in five languages.
+A trustworthy ranking of fast-rising GitHub repositories by stars gained per day, grouped by category (AI first), refreshed twice a day from the GitHub API and readable in five languages.
 
 ## Current phase
 
-Phase 2: growth rankings, i18n, daily automation (done); Phase 2b: top-20 rankings, 20+ projects, dual-midnight schedule.
+Phase 4: harness and upkeep (Phases 1-3 are done and merged).
 
 ## Phases
 
 ### Phase 1: Structure (done)
-- Problem-based categories, project list, short descriptions
+- Project list, short descriptions, five languages
 
-### Phase 2: Growth data and automation
-- stars/day for 7/30/365 days from the GitHub API
-- Five-language READMEs, star-history curves
-- Daily update (Actions + local fallback)
+### Phase 2: Growth data and automation (done)
+- stars/day for 7/30/365 days from `stargazers/history`
+- Daily update (Actions + local fallback) at Beijing 00:00 and Los Angeles 00:00, per-slot history, `latest/`
+- Top-20 boards, 7-day newcomers board
 
-### Phase 3: Discovery
-- Automatically surface candidate projects from GitHub search/trending-style API queries, owner approves additions
-- Acceleration (change in stars/day) column once enough snapshots exist
+### Phase 3: Categories, i18n pipeline, discovery (done)
+- Rebrand to `github-risers`; categories ai (primary), devtools, security, web, infra, design, data; 70 tracked projects
+- Per-category newcomers by topic only; suspected cracked/pirated repos flagged, ranked last, never leaders
+- Translation library + glossary, slim README first screen, GEO (Pages, `llms.txt`, `CITATION.cff`, FAQ, FACTS)
 
-## Definition of done for Phase 2
+### Phase 4: Harness and upkeep (now)
+- Plan and governance files follow `jammyfu/CoderSkills` (`continuous-project-loop`, `multi-project-program-management`)
+- Thin boards (Developer Tools quality, Design, Data) and the acceleration column: see `TODO_BACKLOG.md`
+
+## Definition of done for a phase
 
 - `python3 tools/verify.py` passes; data in `data/stats.json` came from a real run
-- A daily update has run unattended at least once (Actions or local), at both the Beijing and Los Angeles slots
+- A daily update has run unattended at both the Beijing and Los Angeles slots
 
 ## Questions for next review
 
-- Should the year ranking use repo age as divisor for young repos (current behaviour, flagged with †)?
+- Should the year ranking keep dividing young repos by their age (current behaviour, flagged with †)?
 - Which projects should be added or retired?
+- Is a quality signal (beyond topics and the ⚠ rules) wanted for the Developer Tools new-repo board?

TODO_BACKLOG.md

@@ -2,18 +2,21 @@
 
 ## Now
 
-- [ ] Confirm the first scheduled `daily-update` run after merge (check Actions tab or `gh run list`)
+- [ ] Confirm the first unattended cron runs after the merge: `cn-0000` (Beijing) and `pt-0000` (Los Angeles) folders appear under `rankings/<date>/` (`gh run list --workflow daily-update.yml`)
+- [ ] Developer Tools new-repo board: 15 of 20 entries were flagged ⚠ in the last run because star-farmed repos use `cli` / `developer-tools`; decide whether to add a quality signal (owner call)
+- [ ] Design and Data new-repo boards are thin (0-2 entries): widen with specific topics only (no generic ones; `tests/test_spam.py` guards that)
 
 ## Next
 
 - [ ] Acceleration column (stars/day this week vs. previous week) from `data/stars.json` snapshots
-- [ ] Add more projects (needs five-language `desc`)
+- [ ] Add more tracked projects (needs five-language `desc`)
 
 ## Later
 
-- [ ] Candidate discovery via GitHub search API with owner approval
+- [ ] Candidate discovery for tracked projects with owner approval
 
 ## Risks / Blockers
 
-- [ ] GitHub may change or rate-limit `stargazers/history` (documented max 30 weeks/page, page ≤ 100)
-- [ ] If the repo becomes private, Actions fails on the account billing problem; use `tools/local_daily.sh`
+- [ ] GitHub may change or rate-limit `stargazers/history` (documented max 30 weeks/page, page <= 100)
+- [ ] If Actions cannot run (billing, quota), use `tools/local_daily.sh`
+- [ ] The search API is index-based and can lag by minutes; thin categories can be empty in one run

docs/AUTOMATION_COMMANDS.md

@@ -13,7 +13,8 @@ python3 tools/verify.py
 ## Roll to the next plan
 
 ```bash
-python3 tools/next_plan.py
+python3 tools/next_plan.py          # roll a finished plan forward (draft: edit it by hand)
+python3 tools/next_plan.py --check  # validate CURRENT_PLAN.md: one Goal, 3-7 tasks, Out of Scope, Next Candidates
 ```
 
 ## Refresh star data (GitHub API)
@@ -31,8 +32,8 @@ tools/local_daily.sh --no-push          # full local daily cycle, commit but do
 1. Read `CURRENT_PLAN.md`, `MASTER_PLAN.md`, `TODO_BACKLOG.md`, `docs/project-governance/WORKLOG.md`
 2. Finish the smallest closed loop
 3. `python3 tools/verify.py`
-4. Update the record files
-5. If the plan is complete, `python3 tools/next_plan.py`
+4. Update the record files (`CURRENT_PLAN.md`, `TODO_BACKLOG.md`, `WORKLOG.md`, `DECISIONS.md`, `CHANGELOG.md`)
+5. If the plan is complete, `python3 tools/next_plan.py`, edit the draft, `python3 tools/next_plan.py --check`
 
 `update_stars.py` also re-discovers the 7-day new-repo ranking (about 2 minutes; rules in [NEW_ARRIVALS.md](NEW_ARRIVALS.md)).
 

docs/LONG_RUNNING_AUTONOMY.md

@@ -11,8 +11,8 @@ For scheduled and long-running agents working on this repo.
 1. Read `AGENTS.md`, `PROJECT_BRIEF.md`, `MASTER_PLAN.md`, `CURRENT_PLAN.md`
 2. Finish the current minimal closed loop
 3. Run `python3 tools/verify.py`
-4. Update `docs/project-governance/WORKLOG.md`, `DECISIONS.md`, `CHANGELOG.md`
-5. If the plan is complete, run `python3 tools/next_plan.py` and hand-edit the draft
+4. Record: `CURRENT_PLAN.md`, `TODO_BACKLOG.md`, `docs/project-governance/WORKLOG.md`, `DECISIONS.md`; `CHANGELOG.md` only when users can see the change
+5. If the plan is complete, run `python3 tools/next_plan.py`, hand-edit the draft, then `python3 tools/next_plan.py --check`
 
 ## Rules
 
@@ -21,3 +21,10 @@ For scheduled and long-running agents working on this repo.
 - Zero telemetry
 - Open pull requests; do not merge to `main` without the owner's approval
 - Do not claim done without a green `tools/verify.py`
+
+## Dirty worktree rule
+
+- If a wake-up starts with uncommitted changes, deal with them first: if they already form a closed loop, `verify` and open a PR; if not, finish or park them in `WORKLOG.md` and stop. Do not stack a new task on top.
+- The only automated writer of `data/`, `latest/`, `rankings/` and `README*.md` is the daily job; `tools/local_daily.sh` refuses to run on a dirty tree or off `main` and uses its own PATH and `python3` path.
+- `tools/verify.py` runs with `sys.executable`, never `shell=True` and never a bare `python`/`pytest` (`tests/test_harness.py`).
+- The daily data run (Actions `schedule` / `workflow_dispatch`, or `tools/local_daily.sh` with `RISERS_DAILY_RUN=1`) skips the doc-state checks in `tests/test_harness.py`, so a stale plan file can never block a data update; CI runs them on every pull request.

docs/project-governance/ACCEPTANCE.md

@@ -9,3 +9,17 @@
 - No analytics/tracking script anywhere (`tests/test_repo.py::ZeroTelemetryTests`)
 - `daily-update.yml` and `tools/local_daily.sh` exist; `docs/DAILY_UPDATE.md` states whether Actions can run and why
 - `python3 tools/verify.py` passes
+
+## Phase 3: categories and newcomers
+
+- Categories in `data/categories.json` (ai primary + 6 others), each with newcomers / week / month / year / total, total last
+- New repos are found by topic only and must carry a category topic; no generic topics (`tests/test_spam.py`)
+- Suspected cracked / pirated repos are listed after every normal repo, marked ⚠, and never appear in "Category leaders"
+- Every scheduled entry (both Beijing and Los Angeles crons, `workflow_dispatch`, local launchd) runs `tools/update_stars.py` (`tests/test_spam.py::ScheduledPathTests`)
+- README is a first screen (top 10 per board); the full top 20 is in `latest/`; GEO files exist and are linked
+
+## Phase 4: harness
+
+- `CURRENT_PLAN.md` passes `python3 tools/next_plan.py --check` (one Plan ID, one Goal, 3-7 tasks, Out of Scope, Verification, Next Candidates)
+- `tools/verify.py` and `tools/local_daily.sh` do not depend on the shell PATH or `shell=True` (`tests/test_harness.py`)
+- The harness files from `continuous-project-loop` exist and `AGENTS.md` names the two CoderSkills skills

docs/project-governance/CHANGELOG.md

@@ -25,3 +25,12 @@
 - `data/glossary.json`: fixed terms for common words; only the terms present in a batch go into the prompt. Polish sends only un-polished entries and logs how many were skipped.
 - READMEs in all five languages are now a first screen: headline, one sentence, update stamp, the category leaders table (rows link to the category boards), then the category boards. Intro, schedule, "how it is produced", categories table and contributing moved to generated `docs/HOW_IT_WORKS*.md`; the long new-repo explanation moved there too.
 - README first screen reworked (generator only): first line `GitHub 涨星榜 / GitHub Risers` (English: `GitHub Risers: Ranked by Stars Gained per Day`), header image `.github/social-preview.png`, three badges (MIT, CI, last updated), website link, three Q&A subheads linking `docs/FAQ.md`, a star prompt, a "how to cite" line (`CITATION.cff`) and a link to `docs/FACTS.md`. Each board shows the top 10 in the README; the full top 20 stays in `latest/`. Those linked files come from the GEO pull request (#9); the generator only links them, and a test checks the FAQ anchors.
+
+## 2026-10-30 (categories)
+
+- Rebranded to GitHub Risers with categories (AI first, then developer tools, security, web, infrastructure, design, data), each with new-repo, week, month, year and total boards.
+- New-repo discovery is topic-only; suspected cracked/pirated repos are marked ⚠, ranked last and never shown as category leaders.
+
+## 2026-10-30 (harness)
+
+- Plan, backlog and governance files brought up to date; `python3 tools/next_plan.py --check`; harness regression tests. No change to rankings or generated pages.

docs/project-governance/DECISIONS.md

@@ -38,3 +38,25 @@
 
 - Hotness = stars / max(age days, 1); descriptions are the repo's own GitHub text (not translated).
 - Dedup excludes tracked projects and all displayed top-20 repos, so no project is in two rankings; a repo must be added to `data/projects.json` by the owner to be tracked.
+
+## 2026-10-30 (categories)
+
+### Newcomers are found by topic only
+
+- Keyword and language searches pulled in unrelated and star-farmed repos. A repo must carry one of the category's topics; generic topics are not used.
+
+### Suspected cracked / pirated repos: keep, flag, rank last
+
+- Owner decision: do not exclude them. They are marked ⚠, always rank after every normal repo and never lead a category or the leaders table. Rules in `tools/spam.py`, documented in `docs/CATEGORIES.md`.
+
+### One code path for every scheduled run
+
+- Beijing cron, both Los Angeles crons, `workflow_dispatch` and the local launchd jobs all end in `tools/update_stars.py --slot <slot>`, so the rules above apply to every run.
+
+## 2026-10-30 (CoderSkills harness)
+
+### Follow `continuous-project-loop` and `multi-project-program-management`; other CoderSkills skills do not apply
+
+- Applied: standard file set, one plan entry, record order, verify hardening rule, dirty-worktree rule written into repo files, planning rules (one Goal, 3-7 tasks, Out of Scope, Next Candidates).
+- Not adopted: `sync_or_queue.py` / LaunchAgent safe-sync tooling (this repo changes through pull requests; the only automated writer is the daily job), `docs/architecture/*ROADMAP*.md` (not a platform-core project), `git-autosync-signal` (supports only `dramaforge` and `clippipeline`).
+- `readme-tech-visualizer`: audit only. The README stays the slim first screen; the header image belongs to the GEO work, so no hero or tech-badge block is generated.

docs/project-governance/WORKLOG.md

@@ -35,3 +35,20 @@
 - Replaced AI-only subcategories with top-level categories: ai (primary), devtools, security, web, infra, design, data.
 - Each category has newcomers / week / month / year / total (top 20); newcomers deduped within category and AI-first across categories.
 - Tracked projects expanded to 70; real API run stored as rankings/2026-10-30/manual-0750.
+
+## 2026-10-30 — categories, topic-only discovery, suspected-crack rules (#6 follow-up)
+
+- Newcomers: topic-only queries, repos must carry a category topic, generic topics removed; suspected cracked/pirated repos are kept, marked ⚠, ranked last and never leaders (`tools/spam.py`).
+- Real re-run, then `daily-update` triggered by `workflow_dispatch` after merge: green, committed `chore(data)`.
+- Verification: `python3 tools/verify.py` green (93 tests at the time).
+
+## 2026-10-30 — i18n pipeline, GEO, slim README (#7-#10)
+
+- Translation library + glossary, local polish with `agy`, CI translates only; GEO Pages and `llms.txt`/`CITATION.cff`/FAQ/FACTS; README cut to a first screen.
+- Verification: `python3 tools/verify.py` green (159 tests on `41a555e`).
+
+## 2026-10-30 — CoderSkills harness alignment (PLAN-001)
+
+- Read `jammyfu/CoderSkills` (`d37305a`). Applicable: `skills/continuous-project-loop`, `skills/multi-project-program-management`; partly: `skills/readme-tech-visualizer` (audit only, README first screen already free of runtime tables, timestamps-as-noise and "Generated by"). Not applicable: `git-autosync-signal` (only `dramaforge`/`clippipeline`), `skill-lab-builder`, content and media skills.
+- Gaps found: stale `CURRENT_PLAN.md`/`MASTER_PLAN.md`/`TODO_BACKLOG.md`/governance files; dirty-worktree and record-order rules only in chat; no check of the plan shape; no regression test that `verify.py` and `local_daily.sh` avoid PATH/`shell=True`.
+- Added `tools/next_plan.py --check`, `tests/test_harness.py`, and wrote the rules into `AGENTS.md` and `docs/`.