|
1 | 1 | # FlyPython repository 0.0.4 update plan |
2 | 2 |
|
3 | | -Version: 0.0.4 (planning draft) |
4 | | -Updated: 2026-09-12 |
| 3 | +Version: 0.0.4 (planning draft, revision 2) |
| 4 | +Updated: 2026-09-12 (rev 2 — supersedes the same-day local-first draft) |
5 | 5 | Chinese version: [repo-plan-0.0.4_cn.md](./repo-plan-0.0.4_cn.md) |
6 | 6 | Related: flypython.com `docs/product-and-growth-plan-0.0.4.md` |
7 | 7 |
|
8 | 8 | Status: planning document only. Nothing here is implemented. The repository |
9 | 9 | boundary from `AGENTS.md` holds: this repo owns reviewed content, runnable |
10 | | -evidence, and stable JSON contracts; the website owns presentation and |
11 | | -conversion. All new content ships English and Chinese in sync. |
12 | | - |
13 | | -## 1. Theme: the challenge/badge layer lives in course folders |
14 | | - |
15 | | -The 0.0.4 site plan adds a "challenges and badges" progression layer over |
16 | | -the agent-taught course format — learned from PentesterLab's badge model but |
17 | | -implemented **local-first**: progress evidence is written by `verify.py` into |
18 | | -the learner's folder, never to a server. This repo owns everything that makes |
19 | | -that real: the verifier behavior, the course narrative, and the contract |
20 | | -checks. |
21 | | - |
22 | | -Binding rules: |
23 | | - |
24 | | -- No accounts, no network calls, no telemetry in any course tooling. |
25 | | -- Badges are self-reported local evidence; tooling must never print |
26 | | - certification-style claims. |
27 | | -- Every narrative or badge string ships EN+ZH in the same change. |
28 | | -- `PROGRESS.json` and `BADGE.md` are versioned course outputs with a stable |
29 | | - shape (documented in the course contract), so the website and external |
30 | | - tools can render them without guessing. |
| 10 | +evidence, and stable JSON contracts; the website owns presentation, |
| 11 | +accounts, and conversion. All new content ships English and Chinese in sync. |
| 12 | + |
| 13 | +Revision note: the first 0.0.4 draft proposed local-only progress artifacts |
| 14 | +(`PROGRESS.json`, `BADGE.md`). The owner moved the 0.0.4 core to accounts, |
| 15 | +server-recorded progress, and a leaderboard (Cloudflare D1 + Workers). This |
| 16 | +revision refocuses the repo work on what the website needs from course |
| 17 | +folders: **deterministic checkpoint claim codes** and the challenge |
| 18 | +narrative. Local artifacts are dropped; the claim code is the contract. |
| 19 | + |
| 20 | +## 1. Theme: checkpoint claim codes for server-recorded progress |
| 21 | + |
| 22 | +The website records progress when a learner enters a claim code printed by |
| 23 | +`verify.py` after a checkpoint's suite passes. This repo owns everything |
| 24 | +that makes those codes trustworthy and stable: |
| 25 | + |
| 26 | +- The code derives deterministically from `(course_id, checkpoint_id, |
| 27 | + evidence)` where evidence is the objective suite outcome — the same |
| 28 | + inputs always produce the same code, on any machine, offline. |
| 29 | +- Codes are short and human-enterable (e.g. 8 chars of base32). |
| 30 | +- Codes are spot-checkable, not tamper-proof; the framing everywhere is |
| 31 | + "self-reported evidence", never certification. |
| 32 | +- No network access, no accounts, no telemetry in course tooling — the |
| 33 | + website side owns everything behind login. |
31 | 34 |
|
32 | 35 | ## 2. Work items |
33 | 36 |
|
34 | | -### FP-411 `verify.py progress` (every course) |
| 37 | +### FP-411 Checkpoint claim codes (`verify.py`) |
35 | 38 |
|
36 | | -- New subcommand: `python verify.py progress` reads the current |
37 | | - implementation state and writes `PROGRESS.json` next to `verify.py`: |
38 | | - `{"course", "tool", "checkpoints": [{"id", "name", "status": "passed" | |
39 | | - "open", "evidence_command", "recorded_on"}], "all_passed": bool}`. |
40 | | -- Checkpoint status derives from the objective suite (starter-fails and |
41 | | - solution-passes per lesson), not from self-assessment. |
| 39 | +- New subcommand: `python verify.py progress` prints, per checkpoint, its |
| 40 | + id, name, pass state (derived from the objective suite), and — when |
| 41 | + passed — its claim code. |
| 42 | +- Codes are stable across runs and platforms; the derivation (including |
| 43 | + any per-course salt constant) is documented in the course contract and |
| 44 | + reviewed like code. |
42 | 45 | - Stdlib only; deterministic output; safe to re-run. |
43 | 46 |
|
44 | 47 | ### FP-412 Challenge narrative (COURSE.md + lessons) |
45 | 48 |
|
46 | | -- COURSE.md gains a badge contract section: course badge name (e.g. |
| 49 | +- COURSE.md gains the badge contract section: course badge name (e.g. |
47 | 50 | "Verified Report Tool"), the five checkpoint challenges, and the honest |
48 | | - self-reported-evidence framing. |
49 | | -- Lessons are labeled as challenges ("Challenge 01: reproduce the failure"); |
50 | | - checkpoint sections name the badge requirement they satisfy. |
51 | | -- EN+ZH in the same commit; `reviewed_on` bumped; content_version bump per |
| 51 | + self-reported-evidence framing — now pointing at the website's recording |
| 52 | + flow. |
| 53 | +- Lessons are labeled as challenges ("Challenge 01: reproduce the |
| 54 | + failure"); checkpoint sections name the badge requirement they satisfy |
| 55 | + and the claim step. |
| 56 | +- EN+ZH in the same commit; `reviewed_on` and `content_version` bumped per |
52 | 57 | manifest rules. |
53 | 58 |
|
54 | | -### FP-413 Badge artifact |
| 59 | +### FP-413 Badge contract alignment |
55 | 60 |
|
56 | | -- `python verify.py progress --badge` writes `BADGE.md` when — and only |
57 | | - when — all checkpoints pass: badge name, course, tool + version, dates, |
58 | | - and the replay commands. Self-reported evidence; explicitly not a |
59 | | - certificate. |
| 61 | +- Each course's `COURSE.md` declares its badge metadata as structured |
| 62 | + front matter/fields (badge id, display name EN+ZH, requirement text) so |
| 63 | + the website can render badge maps and server records from course data — |
| 64 | + no hand-copied badge definitions on the site side. |
60 | 65 |
|
61 | 66 | ### FP-414 Agent-skill packaging (evaluation) |
62 | 67 |
|
@@ -67,31 +72,31 @@ Binding rules: |
67 | 72 |
|
68 | 73 | ### FP-415 `verify_courses.py` extension |
69 | 74 |
|
70 | | -- Extend the course-contract verifier: `PROGRESS.json` (when present) |
71 | | - validates against the documented shape; `BADGE.md` may exist only when |
72 | | - the record shows all checkpoints passed; the progress subcommand is |
| 75 | +- Extend the course-contract verifier: every checkpoint exposes a claim |
| 76 | + code; codes are deterministic (same inputs → same code across two runs |
| 77 | + and two platforms); format is validated; the progress subcommand is |
73 | 78 | exercised in CI. |
74 | 79 |
|
75 | 80 | ## 3. Non-goals |
76 | 81 |
|
77 | | -No accounts, no server-side judging, no points/leaderboards/streaks, no |
78 | | -network access from course tooling, no certification language, no second |
79 | | -copy of site content. The website renders badge maps from its own course |
80 | | -data; this repo does not ship site assets. |
| 82 | +No accounts, no server-side judging in this repo, no network access from |
| 83 | +course tooling, no certification language, no second copy of site content. |
| 84 | +Anti-fraud design stays deliberately light (spot-checkable codes); heavy |
| 85 | +anti-fraud is the website's concern and is out of scope here. |
81 | 86 |
|
82 | 87 | ## 4. TODO (all unverified) |
83 | 88 |
|
84 | | -- [ ] FP-411 `verify.py progress` + `PROGRESS.json` contract, all five |
85 | | - courses. |
| 89 | +- [ ] FP-411 claim-code subcommand, all five courses, documented derivation. |
86 | 90 | - [ ] FP-412 badge contract + challenge narrative, EN+ZH, one change. |
87 | | -- [ ] FP-413 `BADGE.md` generation gated on all-checkpoints-passed. |
| 91 | +- [ ] FP-413 structured badge metadata for site rendering. |
88 | 92 | - [ ] FP-414 SKILL.md packaging evaluation with a written record. |
89 | | -- [ ] FP-415 `verify_courses.py` progress-contract coverage in CI. |
| 93 | +- [ ] FP-415 `verify_courses.py` claim-code coverage in CI. |
90 | 94 |
|
91 | 95 | ## 5. Execution order |
92 | 96 |
|
93 | | -1. FP-411 + FP-412 + FP-415 in one change (contract, narrative, checker). |
94 | | -2. FP-413 once the progress contract is stable. |
| 97 | +1. FP-411 + FP-412 + FP-415 in one change (codes, narrative, checker), |
| 98 | + paired with the website's FP-401/FP-402 groundwork. |
| 99 | +2. FP-413 once the website badge rendering shape is fixed. |
95 | 100 | 3. FP-414 after one real external-tool run is recorded. |
96 | 101 |
|
97 | 102 | ## 6. Carried forward from 0.0.3 (open) |
|