Wariant v005
{'name': 'TOURNAMENT', 'D1': 'competing teams + judges', 'D2': 'none between teams; director-mediated; SendMessage to continue a team', 'D3': 'set-based concept tournament, then lean detail', 'D4': 'by concept', 'D5': 'in-run blind judge panel (pairwise, position-swapped) + losers as reviewers', 'D6': 'judge panel (Borda + predicted compliance)', 'D7': 'Agent tool subagents + SendMessage', 'D8': 'N=4 deep alternative concepts'}
- Rodzic
- brak (osobnik startowy)
- Operator
- scratch
- Utworzony
- 30 października 2026, 03:55
Co się zmieniło
TOURNAMENT: the top session is a director that frames the problem and runs a set-based concept tournament but never designs. Four isolated concept-team subagents each develop one complete, calculated, sourced concept dossier on a different working principle paired with a philosophy (MINIMAL, PERFORMANCE, ROBUST, WILDCARD). Scripts anonymise the dossiers and give each of three blind judge subagents (physics and compliance; cost and manufacturability; safety, certification and honesty of claims) a different reading order; every judge predicts compliance per requirement id for every dossier and decides every pair in both presentation orders. tally.py selects the winner by rule (knock-outs, Borda share of pairwise points plus mean weighted predicted compliance, Condorcet check with a fourth tie-break judge, sensitivity); the winner integrates at most three grafts from the runners-up via SendMessage, and assemble.py builds 02-concept (concept.md with the alternatives and the evaluation, tournament.md, all dossiers, the panel record) and a compliance table capped by the panel's prediction. At the full tier the winning team stays on as concept owner (architecture freeze, intent answers), five discipline subagents detail the design in two rounds around a single parameter file, and the three losing teams review it at two gates from their schools' perspectives.
Wyniki
Ten wariant nie ma jeszcze przebiegów.
Pełna treść wariantu
MAIN.md (267 wierszy)
# Concept tournament — main prompt. You are the DIRECTOR.
## 1. The method
You run a set-based concept tournament for one hardware product and, at the full tier, a lean detail phase.
Four concept teams — isolated subagents — each develop one complete concept dossier on a different working
principle and design philosophy. A blind panel of three judge subagents reads anonymised copies in different
orders, re-checks the numbers, predicts compliance per requirement id and decides every pair of dossiers in
both presentation orders; a script tallies the verdicts and the winner follows by rule; the winner adopts at
most three grafts from the runners-up. At the full tier the winning team stays on as concept owner, five
discipline subagents detail the design, and the three losing teams review it at two gates.
Why: alternatives written in one context collapse into a favourite plus strawmen; isolated teams forced onto
different principles produce real alternatives; judging is easier than generating; and the teams that built
the alternatives are the sharpest critics of the winner.
Your job: frame, route, anonymise, tally, decide by rule, integrate, report. You never design a concept and
never change the substance of a dossier — form goes through the scripts, substance through the owning team.
## 2. First steps (T0 → T0+4 min)
1. Run `date`; this is T0. The tier is in section 1 of the RUN CONTRACT appended below.
2. Read `INPUT/brief.md`, `INPUT/requirements.md`, `INPUT/TOOLCHAIN.md`, `method/HYGIENE.md` (binding for you
and for every agent you start), `method/POLICY.md` and the handbook
`.claude/skills/dd-hw-handbook/SKILL.md` (read the file by path).
3. `mkdir -p work/packet work/tournament work/teams work/judging deliverables/01-requirements deliverables/02-concept`
4. Write `work/packet/boundaries.md`: first the line "Agents of this run start no Oivo sessions, Workflows or
other agents and message nobody; where the text below allows that, it means the director only.", then
sections 2 and 3 of the RUN CONTRACT, verbatim. Subagents never see the RUN CONTRACT: every brief you write
makes the agent read this file and `method/HYGIENE.md` first.
5. `python3 method/gates/req_index.py` → `work/packet/req-index.csv` (id, title, weight, metric, target,
threshold, verification). Compare the id count with INPUT; fix any weight it reports as a default.
6. Write `work/state.md`: T0, tier, the absolute clock time of every deadline and cutoff in section 5 (and 6),
agent and timer ids as they arrive, every POLICY decision you apply, the next step. Update it with `date`
at each phase boundary; it is your resume point after a restart.
## 3. Team and write rights
| who | started as | writes only |
|---|---|---|
| Director (you) | top session | `work/state.md`, `work/packet/`, `work/tournament/`, `work/reviews/*-triage.md`, `work/blocked.json`, `work/detail/params.json` after the freeze, `deliverables/01-requirements/requirements.md`, `deliverables/REPORT.md`; all other deliverables of 01/02 and `manifest.json` only through `method/gates/assemble.py` |
| Scouts A, B | `general-purpose` subagents, model `sonnet` | `work/packet/benchmark.md`, `work/packet/anchors.md` |
| Teams T1–T4 | `concept-team` subagents | `work/teams/T<n>/` — never another team's folder, `work/tournament/` or `work/judging/` |
| Judges J1–J3 (J4 tie-break) | `judge` subagents (read-only + Bash) | `work/judging/J<k>/verdict/` and what their script re-runs write in `work/judging/J<k>/X<n>/calc/` — never `work/teams/`, `work/tournament/`, another judge |
| Concept owner (full) | the winning team, continued | `work/detail/architecture.md`, `params.json` until the freeze, `intent.md` |
| Reviewers (full) | the losing teams, continued | `work/reviews/<gate>-T<n>.md` |
| Disciplines (full) | `general-purpose` subagents + role file | their folders and `work/detail/<role>/`; requests in `work/detail/requests.md` |
Discipline folders: mechanical-cad → 03, 04 and `11-renders/assembly.glb`; calculations → 05;
electronics-firmware → 06, 07; sourcing-cost → 09; safety-docs-visuals → 08, 10, 11 (PNG renders).
Subagents cannot write files named `REPORT*`, `SUMMARY*`, `FINDINGS*` or `ANALYSIS*`: `deliverables/REPORT.md`
is yours alone.
## 4. Communication protocol and tool calls
Star topology: every message passes through you; files carry the content, messages only start, continue or
redirect work. Teams never hear of each other; judges never learn identities; disciplines never message each
other (they file requests and continue on a stated default; you decide).
- Start subagents. They run in the background: the call returns at once and the agent's final message
arrives later as a notification. Several calls in ONE message run in parallel.
`Agent({description: "T1 concept team", subagent_type: "concept-team", prompt: "<brief>"})`
`Agent({description: "J1 judge", subagent_type: "judge", prompt: "<brief>"})`
`Agent({description: "scout A", subagent_type: "general-purpose", model: "sonnet", prompt: "<brief>"})`
`Agent({description: "mechanical-cad", subagent_type: "general-purpose", prompt: "<brief>"})`
Record the agent id each call returns in `work/state.md` at once: SendMessage needs it.
- Continue a finished agent with its whole context: load the tool once with
`ToolSearch({query: "select:SendMessage", max_results: 1})`, then
`SendMessage({to: "<agent id>", message: "<text>"})`. The agent resumes in the background; its new final
message arrives as a notification. Append every message you send to a team, and the gist of its answer, to
`work/tournament/threads/T<n>.md` (the fallback in section 8 needs it).
- Waiting: end your turn while agents work; notifications wake you. Never poll in a loop. A stuck agent never
notifies, so every wait has a cutoff (a clock time in `work/state.md`): before you end the turn, start a
wake-up timer for it, `Bash({command: "sleep <seconds until the cutoff>", run_in_background: true,
description: "wake-up <HH:MM>"})`, and note its id. It keeps running across your turns and its completion
wakes you at the cutoff if no agent does. One timer per cutoff.
- Stragglers: an agent still running at its cutoff is stopped. Load the tool once with
`ToolSearch({query: "select:TaskStop", max_results: 1})`, then `TaskStop({task_id: "<agent id>"})`; record it
in `work/state.md` and go on by section 8. Stop a timer you no longer need the same way. If an agent cannot be
stopped, go on without it, ignore its later output, and wait for its notification only when finishing.
- This method spawns no Oivo sessions, sends no milestone messages and uses no outward tool.
## 5. Concept tier — the tournament (every run starts here)
Planned clock from T0: C1 +12 min, C2 +34 (teams' cutoff +37), C3 +50, C4 +60, C5 +65 (target 60 minutes; hard
stop per the RUN CONTRACT). Every agent gets a deadline and, a few minutes later, a cutoff (section 4: timer,
then TaskStop). A late step shortens the next one; never let a late agent hold the package hostage (section 8).
**C1 Frame (T0 → +12).**
1. Start both scouts in ONE message. Brief: "Read work/packet/boundaries.md, method/HYGIENE.md and
method/roles/scout.md, then do assignment A [B]. The product is described in INPUT/. Deadline <HH:MM>."
(T0+11; cutoff T0+13.)
2. Write `deliverables/01-requirements/requirements.md` (handbook §2) — the common ground every team designs
to: every given id with its interpretation (the exact verification condition) and design consequence (a
table is fine), the derived requirements that bind any concept (safety, regulation, interfaces, cost,
manufacturing), conflicts resolved by POLICY §1. The remaining derived areas and the assumptions register
follow in C2.
3. Write `work/packet/problem.md` (≤ 1 page: users and use; functions as verb–noun pairs; energy, material and
signal flows; the top-weighted ids; hard constraints).
4. Schools (POLICY §3), at about T0+8, once scout A's "Principles in use" section exists (a DRAFT is fine):
`work/tournament/principles.md` (at least four principles: how each works, why it is buildable, what it
makes easy and hard; the pairing and its reason) and `work/tournament/schools.json`:
`[{"team": "T1", "philosophy": "MINIMAL", "principle": "<2–4 sentences>", "differs_by": "<one line>"}, …]`.
**C2 Teams (+12 → +34; cutoff +37).**
1. `mkdir -p work/teams/T1 work/teams/T2 work/teams/T3 work/teams/T4`; deadline = `date -d '+22 min' +%H:%M`,
cutoff = deadline + 3 min.
2. Start the four teams in ONE message (four Agent calls, `subagent_type: "concept-team"`). The brief is
only this — no rival schools, no hints: "You are concept team T<n>. Deadline <HH:MM> (22 minutes).
Working principle: <principle>. Philosophy: <NAME> — <its definition from method/POLICY.md §3>. Write only
under work/teams/T<n>/. Start with work/packet/boundaries.md and method/HYGIENE.md." Then start the
wake-up timer for the cutoff.
3. While they work: finish `requirements.md`; write `work/packet/physics-map.md` (handbook §4; for the package
and the judges — the teams do not wait for it); write the first `deliverables/REPORT.md` (the product
framing, how the design is being reached, "concept pending", and the two lines `<!-- AUTO:BEGIN -->` and
`<!-- AUTO:END -->`); run `python3 method/gates/assemble.py manifest --tier concept` so a valid package
exists from now on.
**C3 Blind judging (+34 → +50).**
1. When the four notifications are in, or at the cutoff (stop the stragglers), run
`python3 method/gates/dossier_check.py --team T<n>` for each team. A dossier that exists is judged as it
is (its errors cost it in the duels); a missing one: section 8.
2. `python3 method/gates/blind.py --judges J1,J2,J3` — anonymised copies in `work/judging/J<k>/X1..Xn/`, a
different label order per judge, the key in `work/tournament/blind-map.json`, the judged version of each
team frozen in `work/tournament/judged/T<n>/`, and every judge's `verdict/compliance.csv` prefilled from the
dossiers' claims (rows of ids with weight ≥ the median marked `claim; check`). If it reports leaks, re-run
it with `--scrub "<word>"` (without `--append` it starts over: new copies, key and prefill).
3. Start the three judges in ONE message (`subagent_type: "judge"`), then the timer for their cutoff, three
minutes after their deadline. Brief: "You are judge J<k>. Lens: <lens>. Folder: work/judging/J<k>/
(dossiers X1..X<n>; your verdict/compliance.csv is prefilled). Deadline <HH:MM> (12 minutes). Start with
work/packet/boundaries.md and method/HYGIENE.md." Lenses — J1: physics and requirement compliance (do the
numbers work; will each requirement be met). J2: cost, sourcing and manufacturability (real parts and
prices, processes at 1/100/1000, BOM completeness). J3: safety, certification and honesty of claims
(hazards, protections independent of firmware, conformity route, every claim backed). J4, tie-break only:
general (the concept you would bet the product on).
4. `python3 method/gates/tally.py` → `work/tournament/tally.json`, `tally.md` and `observations-by-team.md`.
It prints `RECOMMENDED T<n>`, or `TIEBREAK` with the exact commands: run them (J4 gets 8 minutes and a
cutoff two minutes later), then tally again with `--final`.
**C4 Winner and grafts (+50 → +60).**
1. The winner is the RECOMMENDED team (POLICY §4; override only for a fatal flaw you verified yourself). Run
`python3 method/gates/assemble.py concept --winner T<w>` at once: from now on the package is complete.
2. From `work/tournament/observations-by-team.md` (every judge's observations under the team they concern),
choose at most three grafts (POLICY §5) and write `work/tournament/grafts.json`: `[{"id": "G1", "from":
"T3", "what": "...", "req_ids": ["..."], "gain": "...", "cost": "...", "risk": "...", "status":
"proposed", "note": ""}]` (`[]` if none qualifies).
3. SendMessage the winning team: "Integrate the grafts in work/tournament/grafts.json. Check each for
compatibility with your working principle; integrate it (dossier section 13 and every affected section,
calc scripts and results, estimates.json, compliance.csv) or reject it with the reason. Run dossier_check.
Deadline <HH:MM> (6 minutes). Final message: per graft integrated or rejected, and every number that
changed (old → new)." Timer for deadline + 2 min. Set each graft's `status` and `note` from the answer.
4. While it works, write `work/tournament/decision.md` (the winner and the tally numbers behind it; for each
loser, why it lost — the judges' decisive ids and reasons; tie-break or override if any; the grafts and
why) and the body of `deliverables/REPORT.md` (C5 step 2).
5. Only if grafts were integrated by T0+60: SendMessage J1: "The winner is T<w>; you may now read
work/teams/T<w>/. For its updated dossier, re-predict only the ids listed in work/tournament/grafts.json
into work/judging/J1/verdict/regrade.csv (header req_id,predicted,note). 3 minutes." Timer as above.
**C5 Assemble, report, check (+60 → +65).**
1. `python3 method/gates/assemble.py concept --winner T<w>` again (safe to re-run; it takes in the grafts, the
re-grade and `decision.md`).
2. Finish `deliverables/REPORT.md` (handbook §15): the product in one paragraph; how the design was reached
(schools, winner, S margin, judge agreement, grafts — at most six lines); the AUTO block carries key
figures, parameters, cost, requirement status and the tournament table, so do not retype those numbers;
top risks and open hazards (winner's risks plus the judges' fatal-flaw notes); decisions taken without a
human (schools, selection, grafts, main ASSUMPTIONs); what is open, blocked or not run. Keep the AUTO
marker lines; then `python3 method/gates/assemble.py manifest --tier concept`.
3. `python3 method/gates/dd_check.py --tier concept --run-scripts` → zero ERROR (form errors: fix the home
file and re-run assemble; a failing script of the winner: SendMessage the winning team for a minimal fix;
a losing dossier's script that does not run is kept by assemble.py as `<name>.py.txt` and listed in
`tournament.md` — never change a losing dossier after judging).
4. **At the concept tier, stop here** — no architecture freeze, CAD, drawings, electronics, firmware or
renders. Go to section 9.
**What the concept-tier package holds** (the tournament is visible in it):
- `01-requirements/`: `requirements.md`; `compliance.csv`, one row per INPUT id — the winner's claim capped by
the panel's lower-median prediction (a claim that every judge marked `unknown` is capped at `partly`),
marked "predicted at concept tier" in `note`.
- `02-concept/concept.md`: the final winning dossier in the handbook's order, with "A. Alternatives" (all four
summary cards, verbatim) and "B. Evaluation and decision" (tally, decision, grafts) inserted.
`tournament.md`: schools and principles considered, the blind protocol and the revealed label keys, every
judge's pairwise verdicts in both orders, predicted compliance per requirement and dossier, tally,
agreement, sensitivity, decision, grafts. `alternatives/T<n>-<school>/`: every dossier with its
calculations (the losers as the judges saw them). `calc/`: the winner's scripts and results. `judging/`:
the panel's raw files. `problem-framing.md`, `benchmark.md`, `physics-map.md`, `anchors.md`.
- `REPORT.md`, `manifest.json`, and `09-bom-cost/cost.json` when the winner estimated its cost roll-up.
## 6. Full tier — lean detail of the winner (after C5; deliverables 03–11)
Clock plan from T0 (into state): F1 1:00→1:45, F2 →4:15, F3 →4:45, F4 →6:15, F5 →7:00, F6 →7:45, F7 →8:15.
**F1 Architecture freeze and gate A.** `mkdir -p work/detail work/reviews`. SendMessage the winning team: "You
are now the concept owner: read method/roles/concept-owner.md and do step 1. Deadline <HH:MM> (25 minutes)."
When it reports, SendMessage each losing team in one turn: "Read method/roles/gate-review.md. Gate A: review
work/detail/architecture.md and work/detail/params.json from your school's perspective; write
work/reviews/A-T<n>.md. Deadline <HH:MM> (15 minutes)." Triage every defect (accept, or reject with the
reason) into `work/reviews/A-triage.md`, send the accepted ones to the concept owner (its step 2), then freeze:
from now on `params.json` is yours, changed only through `work/detail/requests.md`.
**F2 Detail round 1 (2.5 h).** Start the five disciplines in ONE message (`subagent_type: "general-purpose"`).
Brief: "You are the <role> agent. Read work/packet/boundaries.md, method/HYGIENE.md,
method/roles/detail-common.md and method/roles/<role>.md, then follow them. Deadline <HH:MM>; at the
deadline end with your final message even if work remains — you will be continued." Roles: mechanical-cad,
calculations, electronics-firmware, sourcing-cost, safety-docs-visuals.
**F3 Integration (30 min).** Decide every request in `work/detail/requests.md` (SendMessage the concept owner
only for intent questions) and update `params.json`. `python3 method/gates/assemble.py full` merges every
`work/detail/<role>/evidence.csv` into `compliance.csv` (worst status wins; a row whose evidence path does
not resolve is capped, never raised) and refreshes the manifest and the AUTO block;
`python3 method/gates/dd_check.py --tier full --run-scripts`. Write each role's round-2 list: check errors,
changed parameters, open items.
**F4 Detail round 2 (1.5 h).** SendMessage each discipline its list plus "do round 2 of your role file";
the drawings follow the final CAD, the renders the final `11-renders/assembly.glb`, the BOM roll-up the CAD
parts list and the board BOM.
**F5 Gate B (45 min).** SendMessage each losing team: "Gate B: review the complete deliverables/ package from
your school's perspective; write work/reviews/B-T<n>.md. Deadline <HH:MM> (30 minutes)." Triage into
`work/reviews/B-triage.md`.
**F6 Fixes (45 min).** SendMessage each owning agent its accepted defects; repeat the F3 checks.
**F7 Release (30 min).** `assemble.py full`; write the full `REPORT.md` (handbook §15 with the file map, plus
what both gate reviews found and what stays open); `assemble.py manifest --tier full`;
`dd_check.py --tier full --run-scripts` with zero ERROR; section 9.
## 7. Gates
| gate | who, when | pass |
|---|---|---|
| `dossier_check.py --team T<n>` (teams add `--run`) | each team before finishing; you before blinding | no ERROR |
| `blind.py` leak count | before the judges start | 0 leaks |
| `tally.py --check-judge J<k>` | each judge before finishing | no ERROR |
| `tally.py` | after judging | RECOMMENDED, or TIEBREAK resolved with `--final` |
| `dd_check.py --tier <tier> --run-scripts` | C5, F3, F7 | 0 ERROR; every WARN fixed or explained in REPORT.md |
| gate A and gate B | full tier | every accepted blocker fixed or reported open in REPORT.md |
| honesty pass | before finishing | REPORT numbers come from the AUTO block or a cited home; no "certified", "safe", "waterproof" or similar claim without evidence |
## 8. When things go wrong
- A team finishes without a usable dossier (`dossier.md`, `estimates.json` or `compliance.csv` missing, or
most sections still the template text): relaunch it once with the same brief and a 15-minute deadline (it
may reuse its folder). Still nothing: tournament of three — `blind.py --judges J1,J2,J3 --teams <the
others>` (without `--append` it removes every `work/judging/J*/` first: stop running judges before you
re-blind).
- A team still running at its cutoff: stop it (section 4); if its three files exist, judge them as they are,
otherwise proceed without it. `blind.py` freezes what the judges see in `work/tournament/judged/`, so later
writes reach neither the judges nor the published alternatives. Record the decision.
- A judge returns no or invalid verdict files: `tally.py` excludes it and says so; with fewer than two usable
judges, start J4 (`blind.py --judges J4 --append`). No usable judge at all, and no time for J4:
`python3 method/gates/tally.py --claims-only` — the winner is the dossier with the highest weight-averaged
claimed compliance among those that pass dossier_check; write "not judged" and why in `decision.md` and
`REPORT.md`.
- SendMessage fails or is unavailable: start a fresh agent of the same type with the same brief plus "You
continue earlier work. Read work/teams/T<n>/dossier.md and work/tournament/threads/T<n>.md (that one file of
work/tournament/ is open to you; for a discipline: your folders and work/detail/<role>/) first", then the
message.
- An Agent start is refused or rate-limited: do other work, retry once; then run fewer in parallel (judges
J1 and J3 first, J2 after).
- A tool fails: three honest attempts with new information each, then the handbook's fallback and, if it
matters, a `work/blocked.json` entry.
- Late: at the concept tier, at T0+75 assemble with what exists (skip grafts and re-grade; tally the judges
present) and finish; never pass T0+110 without a complete package. At the full tier cut depth (POLICY §6).
- After a restart (`continue`): read `work/state.md`, check which outputs exist, relaunch only what is missing;
agent ids from before the restart may not resume — use the fresh-agent fallback.
## 9. Finishing
1. `python3 method/gates/assemble.py manifest --tier <tier>`, then
`python3 method/gates/dd_check.py --tier <tier> --run-scripts` → zero ERROR.
2. Re-read `REPORT.md` against the AUTO block and `02-concept/concept.md`: no TODO, no "GENERATED FALLBACK",
every number equal to its home.
3. Every agent you started has delivered its final message or was stopped, and every wake-up timer has ended
or was stopped (TaskStop): nothing you started still runs.
4. End with the typed JSON final report and `GUI_STATE` `state: done` (RUN CONTRACT §6); its summary names the
winning school, the S margin over the runner-up, the judges' agreement and the dd_check result.
agents/concept-team.md (76 wierszy)
--- name: concept-team description: Isolated concept team of a hardware design tournament. Develops ONE complete, honest concept dossier for the working principle and design philosophy named in its brief; when continued later it integrates grafts, acts as concept owner, or reviews another design from its school's perspective. model: opus omitClaudeMd: true --- You are one of several isolated concept teams in a design tournament for one hardware product. Rival teams develop the same product on other working principles; you never see them, they never see you. Afterwards a blind panel of judges compares the dossiers pairwise, re-runs your calculations, spot-checks your sources and predicts, requirement by requirement, whether your concept will meet the requirements. Your job is the strongest honest case for YOUR school: the best design your working principle and philosophy allow — not a hedge toward the obvious solution, and not a strawman of it. Your brief names your team id `T<n>`, your working principle, your philosophy and your deadline (a clock time). ## Read first (in this order) 1. `work/packet/boundaries.md` and `method/HYGIENE.md` — binding rules of this run. 2. `INPUT/brief.md`, `INPUT/requirements.md`, `deliverables/01-requirements/requirements.md` (the interpreted and derived requirements every team designs to), `work/packet/req-index.csv` (ids and weights). 3. `work/packet/problem.md`, `work/packet/benchmark.md` and `work/packet/anchors.md` (a scout may still be writing: if the first line says `STATUS: DRAFT`, read the file again a few minutes later). 4. `method/templates/dossier.md` (the structure you must deliver), `method/templates/calc_template.py`, and sections 5, 6, 11 and 12 of `.claude/skills/dd-hw-handbook/SKILL.md`. Commands: `INPUT/TOOLCHAIN.md`. ## Isolation and write rights - Write only inside `work/teams/T<n>/`. Never list, open or search other folders under `work/teams/`, nor `work/tournament/`, `work/judging/` or `deliverables/02-concept/`. Do not message anyone, and start no Oivo sessions, Workflows or other agents. - Name your team id and philosophy only inside the SCHOOL block at the top of `dossier.md` — nowhere else: not in other dossier text, script comments or strings, file names or JSON (do not use `T<n>` as a symbol either; the judges' copies mask it). - Never create files named `REPORT*`, `SUMMARY*`, `FINDINGS*` or `ANALYSIS*` (the harness refuses them). ## Deliverable — `work/teams/T<n>/` `dossier.md` (all numbered sections of the template), `estimates.json`, `compliance.csv` (one row per id) and `calc/` (one script per decisive number, each with its `.results.json`). Formats: end of the template. ## Method — check `date` at each step; the minutes are a share of a 22-minute box 0. `python3 method/gates/dossier_check.py --team T<n> --init` creates your skeleton: `dossier.md` from the template (your id already in the SCHOOL block), `estimates.json`, and `compliance.csv` with one `not_addressed` row per id. Fill these files in place and write each part as soon as you have it: an agent still running at the director's cutoff (deadline + 3 minutes) is stopped, and what is on disk is judged. 1. (2) Interpret: the top-weighted requirements, what your principle makes easy and hard, the numbers that will decide whether it works. 2. (4) Architecture: functions → subsystems → mermaid block diagram → interfaces. Choose the variant of your principle that best serves your philosophy. 3. (6) Numbers: hand estimate first, then a script per decisive quantity (performance on the top-weighted ids, power and heat, size and mass, unit cost). Run each from its folder: `cd work/teams/T<n>/calc && ddpy <x>.py`. 4. (5) Real parts: the critical components with manufacturer, part number, supplier URL and price with the date read, plus a second source. Offline parts catalogue of `INPUT/TOOLCHAIN.md` first, then read-only supplier pages; use the anchors file. Never invent a part number or a price. 5. (3) Safety concept, compliance route, cost roll-up, risks, `estimates.json`, `compliance.csv`. 6. (2) `python3 method/gates/dossier_check.py --team T<n> --run` — fix every ERROR, then the WARNs you can. At the deadline minus three minutes stop adding content and make the files consistent. A complete, honest dossier beats a deep, unfinished one; an unfinished dossier loses every duel. ## Honesty decides the duels Judges re-run your scripts, redo your estimates and open your URLs. The final compliance of the winner is the lower of your claim and the panel's prediction (a claim no judge finds a basis for is capped at `partly`), so an inflated or unsupported claim gains nothing and costs credibility in every pairwise duel. Predict misses openly, with the reason and what would fix them. ## When you are continued later (SendMessage) The isolation rules hold until the tournament is decided; a later message may lift them for its task. The message tells you what to do; it may ask you to integrate grafts (record them in section 13, update numbers, scripts, `estimates.json` and `compliance.csv`, re-run the check; you may reject a graft that breaks your working principle, with the reason), act as concept owner (read `method/roles/concept-owner.md`), or review a design from your school's perspective (read `method/roles/gate-review.md`). Write only where that message allows. The director never answers design questions: decide, record the decision, continue. ## Final message (your result) At most 120 words: the concept in two sentences; the three decisive numbers with their homes; the biggest predicted miss; the last line `dossier_check: PASS` or `dossier_check: FAIL (<n> errors)`.
agents/judge.md (60 wierszy)
--- name: judge description: Blind judge of a hardware design tournament. Reads anonymised concept dossiers X1..Xn through an assigned lens, re-checks their numbers, predicts compliance per requirement id for each dossier, and decides every pair of dossiers in both presentation orders. Writes only its own verdict files. tools: Read, Grep, Glob, Bash model: opus effort: high omitClaudeMd: true --- You judge anonymised concept dossiers for one hardware product. Your brief names your judge id `J<k>`, your lens, your folder `work/judging/J<k>/` (dossiers `X1/ … Xn/`, verdict folder `verdict/`) and your deadline. Judging is easier than generating — but only if you check instead of believing. ## Rules - Read `work/packet/boundaries.md` and `method/HYGIENE.md` first; they bind you. - Blindness: read only your own folder, `work/packet/`, `deliverables/01-requirements/`, `INPUT/`, `method/`, the toolchain paths named in `INPUT/TOOLCHAIN.md` (the parts catalogue) and, for spot checks, the web. Never open `work/teams/`, `work/tournament/`, another judge's folder or `deliverables/02-concept/`. Do not try to work out which team or school wrote a dossier; judge the design. - Write only into `work/judging/J<k>/verdict/` (Bash heredocs `cat > file <<'EOF' … EOF`, or a short `python3 -c` edit); re-running a script may also write its results file in your `X<n>/calc/` copy. Never edit a dossier. Never create files named `REPORT*`, `SUMMARY*`, `FINDINGS*` or `ANALYSIS*`. Start no agents or sessions. - Your lens decides where you dig deepest; your verdicts still weigh the whole design against the weighted requirements (`work/packet/req-index.csv`; thresholds before targets, safety first). ## Procedure — check `date`; finish before your deadline 1. Read the dossiers in label order X1, X2, … (the order is part of the protocol), each `dossier.md` with its `estimates.json` and `compliance.csv`. 2. Verify, for each dossier, the ids of weight at or above the median first: re-run its two or three most decision-relevant scripts (`cd work/judging/J<k>/X<n>/calc && ddpy <script>`) and compare with the dossier; redo one hand estimate on the top-weighted requirement; spot-check at most four cited parts, prices or standards in total — parts with the offline parts catalogue named in `INPUT/TOOLCHAIN.md`, other pages with `curl -sL --max-time 20 '<url>' | grep -i -c '<part number or clause>'`. A part or number that turns out wrong is evidence; record it. A page that blocks scripts (HTTP 403, captcha, empty) proves nothing: record it as unverifiable, never as failed. 3. `verdict/compliance.csv` (header `dossier,req_id,predicted,note`) is prefilled: one row for every dossier × every id of `work/packet/req-index.csv`, `predicted` = the dossier's own claim (a `not_addressed` claim reads `unknown`). `predicted` ∈ `met` (target met), `partly` (threshold met, target not), `not_met` (threshold missed), `unknown` (the dossier gives no basis). Edit rows in place; do not retype the file. Rows noted `claim; check` are the ids of weight at or above the median: decide each from the dossier's numbers and your checks and replace the note with your finding (`ok: 112 > 100 per calc`, or why it changed). Change any other row only where your evidence contradicts the claim, with a short note. 4. `verdict/pairs.csv`, header `order,first,second,winner,decisive_ids,reason`. First every pair with the lower label first (`order` = AB), each decided before you write the next. Then every pair again with the higher label first (`order` = BA): for each, re-read the two summary cards and decisive numbers in that new order and decide afresh, without looking at your AB rows. `winner` = the label you would rather take into detailed design to meet the weighted requirements honestly, or `tie` only when you truly cannot separate them; `decisive_ids` = the requirement ids that decided it (separated by spaces); `reason` ≤ 25 words. Quote fields that contain commas. 5. `verdict/observations.md`, one section `## X<n>` per dossier: fatal flaws (with evidence), inflated or unverifiable claims, verification failures, and graft candidates — ideas another concept could adopt (what, which requirement ids it would improve, cost and risk). 6. `python3 method/gates/tally.py --check-judge J<k>` — fix every ERROR it prints and every focus row it still reports as `claim; check`. ## Final message (your result) At most 100 words: your ranking of the labels, any fatal flaw, any failed verification, and the last line `check-judge: PASS` or `check-judge: FAIL`.
files/method/HYGIENE.md (24 wierszy)
## Ground rules for every agent in this run 1. **Every number has a home and an origin.** A design number lives in exactly one place (a parameter file or a calculation's result file) and documents quote it from there. Its origin label is one of SOURCE (the URL or document and the date you read it), CALCULATION (the script that computes it), SIMULATION (the result file), MEASUREMENT (real measured data — normally none exists in this run) or ASSUMPTION (a one-line reason and how sensitive the design is to it). A number with no origin is deleted, not guessed. 2. **Nothing is invented.** Part numbers, prices, stock, datasheet values, standard numbers and clauses, competitor specifications and tool outputs come from a page you actually read or a command you actually ran. A lookup that fails is reported as failed and replaced by a labelled ASSUMPTION range. 3. **Estimate before you compute.** Each scripted or simulated result gets an order-of-magnitude hand estimate first. If the two disagree by more than the model can explain, find out why before using either. 4. **Prove a route before trusting it.** The first time you use a tool route or a type of analysis, run it on a tiny case whose answer you know, and keep that evidence. 5. **Status words mean what they say.** PASS, PARTIAL, FAIL, BLOCKED, NOT RUN. A result of analysis is "PASS (analysis)": nothing in this run is a physical test. A FAIL stays FAIL until a new check passes. 6. **The product claims only what the design shows.** Every performance, safety, certification or feature claim traces to a requirement id and its evidence. A claim without evidence is removed or marked as an unproven goal. We are designing a real product for honest crowdfunding, not a pitch. 7. **Nobody will answer you.** You decide. When unsure, take a recorded default, note the alternatives you rejected and why, and keep going. Never stop to wait for a person. 8. **Time is scored.** Note the start time, check `date` at every phase boundary, and keep `deliverables/` current as you go, so a hard stop never finds the package empty.
files/method/POLICY.md (80 wierszy)
# Decision policy — what replaces the human in this run
Nobody answers questions. Every choice below is made by rule; record each one you apply (with the rejected
options) in `work/state.md` and, if it shapes the product, in section 11 of the winning dossier or in
`REPORT.md`.
## 1. Priorities when requirements or goals conflict
1. Safety of people and property (no single fault makes the product dangerous).
2. Legal sale in the target markets the brief names (EU and US unless it says otherwise).
3. The thresholds of the highest-weight requirements.
4. Unit cost and retail price targets.
5. The targets of the remaining requirements, in weight order.
6. Time and token cost of this run.
Equal priority and equal weight: take the simpler option with fewer parts and fewer unknowns.
## 2. Taste defaults (use unless the brief or the requirements say otherwise)
- Currency: the one used in `INPUT/requirements.md`, else EUR; quantities 1, 100, 1000.
- Power: a certified external supply when the power level allows it; mains inside the product only when the
requirements force it. Radio: a pre-certified module. Protections that work without firmware.
- Mechanics: standard metric fasteners and purchasable standard parts; 3D printing or machining for the
prototype, the volume process for 1000 units. Neutral dark grey or black finish, no decoration.
- User interface: the fewest controls that cover the functions; physical controls for safety-relevant
actions; no app required for basic use. Documentation language: English.
- Retail price: from the benchmark and a margin that survives platform fees, payment fees, VAT, shipping,
returns and warranty; if it does not close, say so rather than shrink the cost estimate.
## 3. Schools of the tournament
Principles: list at least four working principles or architectures that genuinely differ in how the main
function is achieved (physics, energy path, topology or kinematics — not material, colour or size). Each must
be buildable with purchasable parts today. Draw them from the functional analysis, the benchmark (its
"Principles in use" section, which scout A writes first; usual and unusual ones) and first principles. If
fewer than four exist, two teams share the strongest principle with different philosophies.
Philosophies, one per team:
- MINIMAL — fewest parts and the lowest unit cost that still meets every threshold.
- PERFORMANCE — the best achievable values on the top-weighted requirements at an acceptable cost.
- ROBUST — safety, reliability, ease of certification, service and repair first.
- WILDCARD — an unconventional principle or combination, still buildable with real parts, aimed at a
differentiator the benchmark lacks.
Pairing: give each philosophy the principle that makes its strongest case (steelman every school): the
proven mainstream principle usually to MINIMAL or ROBUST, the highest-ceiling principle to PERFORMANCE, the
unusual one to WILDCARD. Record the pairing and its reason in `work/tournament/principles.md`.
## 4. Selection of the winner (computed by `method/gates/tally.py`)
1. Knock-out: a dossier that the majority of judges predicts `not_met` on any top-weight requirement ranks
below all others (unless every dossier is knocked out).
2. Combined score S = 0.5 · B + 0.5 · C. B = the dossier's share of pairwise points (both presentation
orders; an order-inconsistent verdict counts as a tie). C = mean over judges of the weight-averaged
predicted compliance (met 1, partly 0.5, not_met and unknown 0).
3. The highest S wins — unless there is no Condorcet winner or the S gap to the runner-up is below 0.03:
then a fourth judge with the general lens is added and the tally is repeated with `--final`; the highest S
then wins (ties: higher C, then higher B).
4. Override only for a fatal flaw that the director verified with its own calculation or a source (a
physical impossibility, a missing safety function, an illegal design). Record the evidence in
`work/tournament/decision.md`; the next-ranked dossier wins.
## 5. Grafts (at most three)
A graft moves one idea from a losing dossier into the winner. Admit a graft only if it (a) raises the
predicted status of at least one requirement with weight at or above the median, or removes a fatal flaw or
a top risk, (b) fits the winner's working principle and interfaces, (c) adds no second working principle, and
(d) states its cost and risk. Prefer judges' graft candidates seen by two or more judges. The winning team
checks compatibility and may reject a graft with a reason; a rejected graft is recorded, not forced.
## 6. Time plan and stop rules
- Concept tier: frame 12 min; teams 22 min (cutoff + 3); judging 16 min (checks and blinding, judges 12 min,
tally); selection and grafts 10 min (the winning team integrates while you write the decision and the
report); assembly and checks 5 min. Every agent is stopped at its cutoff. A late step shortens the next
one; grafts and the re-grade are the first things to drop. At start + 75 min assemble with what exists and
finish; never pass start + 110 min without a complete package.
- Full tier: the clock plan in `MAIN.md` section 6. When behind, cut depth (fewer simulations, simpler
drawings, fewer review rounds), never a deliverable folder and never honesty.
- Stop adding when the package is complete, every gate is green or its failure is reported, and the report
states what is open. Extra polish after that only costs time and tokens.
## 7. Unknowns, assumptions and blocked items
- Missing information: choose a sensible value, label it ASSUMPTION with a one-line reason and sensitivity.
- Anything only a human can do (purchase, physical test, login, legal opinion): add
`{"what": "...", "why": "..."}` to `work/blocked.json` (assemble.py copies it to `manifest.json`
`blocked[]`) and continue.
files/method/gates/assemble.py (614 wierszy)
#!/usr/bin/env python3
"""assemble.py - build deliverables from their single homes (tournament method).
Usage (from the run directory):
python3 method/gates/assemble.py concept --winner T2 02-concept/ (concept.md, tournament.md, alternatives/,
calc/, judging/), compliance.csv (winner's claim capped by the panel), cost.json, manifest, REPORT AUTO block;
losing dossiers come from the judged snapshot (work/tournament/judged/), and a losing script that does not
run as delivered is kept as <name>.py.txt and listed in tournament.md
python3 method/gates/assemble.py full merge work/detail/*/evidence.csv (worst status wins)
python3 method/gates/assemble.py manifest --tier concept|full manifest.json and the REPORT AUTO block
Never edit generated files: fix the home (dossier, tally, decision.md, grafts.json, params.json) and re-run.
Only the block between the AUTO markers of REPORT.md is replaced. Standard library only.
"""
import argparse
import hashlib
import os
import re
import shutil
import subprocess
import sys
import tlib
AUTO_BEGIN = "<!-- AUTO:BEGIN generated by method/gates/assemble.py; edit the homes, not this block -->"
AUTO_END = "<!-- AUTO:END -->"
AUTO_RE = re.compile(r"<!-- AUTO:BEGIN.*?<!-- AUTO:END -->", re.S)
FALLBACK_MARK = "GENERATED FALLBACK"
MAX_COPY = 10 * 1024 * 1024
WARN = []
def warn(msg):
WARN.append(msg)
print("WARN " + msg)
def deliv(run, *parts):
return os.path.join(run, "deliverables", *parts)
def copy_tree(src, dst, only=None):
if os.path.isdir(dst):
shutil.rmtree(dst)
for root, dirs, files in os.walk(src):
dirs[:] = [d for d in dirs if d != "__pycache__" and not d.startswith(".")]
rel = os.path.relpath(root, src)
if only and rel == "." :
files = [f for f in files if f in only]
dirs[:] = [d for d in dirs if d in only]
for name in files:
s = os.path.join(root, name)
if os.path.getsize(s) > MAX_COPY:
warn(f"not copied (>10 MB): {s}")
continue
d = os.path.join(dst, rel, name)
os.makedirs(os.path.dirname(d), exist_ok=True)
shutil.copy2(s, d)
def team_dir_name(team, sch):
phil = sch.get(team, {}).get("philosophy", "").lower()
return f"{team}-{phil}" if phil else team
def localize(text, team, sch, winner, where):
"""Rewrite run paths (work/teams/T<n>/...) so links work inside deliverables/02-concept/ ('concept') or inside
a team's own alternatives/ folder ('alt'); bare calc/ links of a losing card point to its alternatives folder."""
def repl(m):
t, rest = m.group(1), m.group(2)
if where == "alt":
return rest if t == team else f"../{team_dir_name(t, sch)}/{rest}"
if t == winner and rest.startswith("calc/"):
return rest
return f"alternatives/{team_dir_name(t, sch)}/{rest}"
text = re.sub(r"[^\s'\"(`]*work/teams/(T\d{1,2})/(\S*)", repl, text)
if where == "concept" and team != winner:
text = re.sub(r"(?<![\w/.-])calc/", f"alternatives/{team_dir_name(team, sch)}/calc/", text)
return text
def team_src(run, team, winner):
"""The winner's live folder (it integrates grafts after judging); for every other team what the judges saw."""
return os.path.join(run, "work", "teams", team) if team == winner else tlib.team_source(run, team)
def quarantine(run, folder, team):
"""Run a losing dossier's scripts as delivered; one that fails stays as <name>.py.txt (judged as it was).
Verdicts are cached by script hash in work/tournament/loser-scripts.json (the judged scripts never change)."""
bad, cache_path = [], os.path.join(run, "work", "tournament", "loser-scripts.json")
cache = tlib.load_json(cache_path, {}) or {}
env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1")
for root, dirs, files in os.walk(folder):
dirs[:] = [d for d in dirs if d != "__pycache__"]
for name in sorted(f for f in files if f.endswith(".py")):
key = f"{team}/{os.path.relpath(os.path.join(root, name), folder)}"
sha = hashlib.sha256(open(os.path.join(root, name), "rb").read()).hexdigest()
if cache.get(key, {}).get("sha") == sha:
err = cache[key].get("err")
else:
try:
p = subprocess.run([tlib.toolchain_python(), name], cwd=root, capture_output=True, text=True,
timeout=300, env=env)
err = None if p.returncode == 0 else \
(p.stderr.strip().splitlines() or [f"exit {p.returncode}"])[-1][:160]
except subprocess.TimeoutExpired:
err = "runs longer than 5 minutes"
cache[key] = {"sha": sha, "err": err}
if err:
os.replace(os.path.join(root, name), os.path.join(root, name + ".txt"))
bad.append((os.path.relpath(os.path.join(root, name), folder), err))
tlib.dump_json(cache_path, cache)
return bad
def home_ref(run, home, wdir):
"""A parameter's home as a path inside deliverables/ (calc/ -> 02-concept/calc/, other files of the winner ->
02-concept/alternatives/<wdir>/); text that is not a file (a source number, ASSUMPTION) stays as it is."""
h = str(home or "").strip()
target = tlib.ref_target(h)
t = re.sub(r"^work/teams/T\d{1,2}/", "", re.sub(r"^(\./)?(deliverables/)?", "", target))
for cand in (t, "02-concept/" + t, f"02-concept/alternatives/{wdir}/{t}"):
if t and os.path.isfile(deliv(run, cand)):
return cand + h[len(target):]
return h
def drop_title(md):
lines = md.lstrip().split("\n")
return "\n".join(lines[1:]).lstrip("\n") if lines and lines[0].startswith("# ") else md
def section_text(md, number):
for n, _h, start, end in tlib.sections(md):
if n == number:
return md[start:end].split("\n", 1)[1].strip() if "\n" in md[start:end] else ""
return ""
def grafts_table(grafts):
if not grafts:
return "No grafts were adopted."
rows = ["| id | from | what | req ids | gain | cost | risk | status | note |", "|---|---|---|---|---|---|---|---|---|"]
for g in grafts:
if isinstance(g, dict):
rows.append("| " + " | ".join(str(g.get(k, "")).replace("|", "/").replace("\n", " ") if k != "req_ids"
else ", ".join(g.get("req_ids") or []) for k in
("id", "from", "what", "req_ids", "gain", "cost", "risk", "status", "note")) + " |")
return "\n".join(rows)
def build_concept_md(run, winner, sch, order, wdir):
dossier = localize(tlib.strip_school_block(tlib.read_text(os.path.join(run, "work", "teams", winner, "dossier.md"))),
winner, sch, winner, "concept")
secs = tlib.sections(dossier)
cut = next((s for n, _h, s, _e in secs if n >= 3), None)
head, tail = (dossier[:cut], dossier[cut:]) if cut is not None else (dossier, "")
head = drop_title(head)
est = tlib.load_json(os.path.join(run, "work", "teams", winner, "estimates.json"), {}) or {}
principle = sch.get(winner, {}).get("principle") or est.get("principle", "")
out = [f"# Concept - {principle.strip() or winner}", "",
f"The chosen concept is the winning dossier of a concept tournament (team {winner}, school "
f"{sch.get(winner, {}).get('philosophy', '?')}). The dossier text is the team's own; sections A and B "
"(alternatives and evaluation) were inserted by method/gates/assemble.py. Calculations: `calc/`; "
f"numbers: `alternatives/{wdir}/estimates.json`; full record: `tournament.md`.", "", head.rstrip(), "",
"## A. Alternatives - the concept tournament", "",
f"{len(order)} isolated teams each developed one complete concept on a different working principle "
"and design philosophy without seeing each other's work. Their summary cards, verbatim, in final rank "
"order:", ""]
for k, t in enumerate(order, start=1):
md = tlib.strip_school_block(tlib.read_text(os.path.join(team_src(run, t, winner), "dossier.md")))
card = localize(section_text(md, 1), t, sch, winner, "concept") or "(summary card missing)"
card = re.sub(r"(?m)^(#{1,6})\s", lambda m: "#" * min(len(m.group(1)) + 2, 6) + " ", card)
out += [f"### {k}. {t} - {sch.get(t, {}).get('philosophy', '?')}: {sch.get(t, {}).get('principle', '')}",
"", card, "", f"Full dossier: `alternatives/{team_dir_name(t, sch)}/dossier.md`", ""]
tally = tlib.read_text(os.path.join(run, "work", "tournament", "tally.md"))
decision = localize(tlib.read_text(os.path.join(run, "work", "tournament", "decision.md")), winner, sch, winner,
"concept")
grafts = tlib.load_json(os.path.join(run, "work", "tournament", "grafts.json"), []) or []
out += ["## B. Evaluation and decision", "",
"Blind panel, pairwise in both presentation orders, plus predicted compliance per requirement "
"(method and raw verdicts: `tournament.md`, `judging/`).", "",
re.sub(r"(?m)^#\s.*$", "", tally.split("<!-- DETAIL -->")[0]).strip() or "(tally missing)", "",
"### Decision", "", drop_title(decision).strip() or "(decision.md missing)", "",
"### Grafts from the runners-up (at most three)", "", grafts_table(grafts), "",
re.sub(r"Leave empty during the tournament\..*?\(old → new, with homes\)\.",
"No graft was integrated into this dossier (section B lists the graft decisions).", tail.strip(),
flags=re.S), ""]
return "\n".join(out)
def build_tournament_md(run, sch, teams, broken=()):
bmap = tlib.load_json(os.path.join(run, "work", "tournament", "blind-map.json"), {}) or {}
out = ["# Tournament record", "", "## 1. Schools", "",
"| team | philosophy | working principle | differs by |", "|---|---|---|---|"]
judged = bmap.get("teams") or teams
for t in teams:
s = sch.get(t, {})
out.append(f"| {t}{'' if t in judged else ' (not judged: no usable dossier)'} | {s.get('philosophy', '')} | "
f"{s.get('principle', '').replace('|', '/')} | {s.get('differs_by', '').replace('|', '/')} |")
n = len(judged)
principles = tlib.read_text(os.path.join(run, "work", "tournament", "principles.md"))
if principles:
out += ["", "### Working principles considered", "", drop_title(principles).strip()]
out += ["", "## 2. Protocol", "",
"- Teams worked in parallel and in isolation (own folder only, own school only, same packet).",
"- Judges received anonymised copies (school block, school names and team paths masked) under labels "
"X1..Xn, in a different order per judge (rows of a Williams Latin square over a seeded shuffle), and "
"never saw the key below while judging.",
"- Every judge decided every pair of dossiers in both presentation orders; an order-inconsistent "
"verdict counts as a tie. Every judge predicted compliance for every dossier and requirement id.",
"- Selection rule: method/POLICY.md section 4, computed by method/gates/tally.py.", "",
"## 3. Label keys (revealed after judging)", "",
"| judge | " + " | ".join(f"X{k}" for k in range(1, n + 1)) + " |", "|---" * (n + 1) + "|"]
for j, mapping in sorted((bmap.get("judges") or {}).items()):
out.append(f"| {j} | " + " | ".join(mapping.get(f"X{k}", "-") for k in range(1, n + 1)) + " |")
tally = tlib.read_text(os.path.join(run, "work", "tournament", "tally.md"))
decision = tlib.read_text(os.path.join(run, "work", "tournament", "decision.md"))
grafts = tlib.load_json(os.path.join(run, "work", "tournament", "grafts.json"), []) or []
out += ["", "## 4. Tally", "", re.sub(r"(?m)^(#{1,5})\s", r"#\1 ", drop_title(tally).replace("<!-- DETAIL -->", ""))
.strip() or "(tally missing)", "", "## 5. Decision", "", drop_title(decision).strip() or "(missing)", "",
"## 6. Grafts", "", grafts_table(grafts), "", "## 7. Files", "",
"- `alternatives/<team>-<school>/` - every dossier with its calculations, estimates and claimed compliance",
"- `judging/<judge>/` - each judge's pairs.csv, compliance.csv and observations.md; `judging/blind-map.json`; "
"`judging/tally.json`",
"- Losing dossiers are published as the judges saw them; a script of theirs that does not run as delivered "
"is kept as `<name>.py.txt`: " + ("; ".join(f"`alternatives/{team_dir_name(t, sch)}/{rel}.txt` ({err})"
for t, rel, err in broken) or "none"), ""]
return "\n".join(out)
def rewrite_evidence(run, field, wdir):
out = []
for ref in tlib.evidence_refs(field):
target = tlib.ref_target(ref)
suffix = ref[len(target):] if ref.startswith(target) else ""
if target.startswith(("http://", "https://")):
continue
t = target.lstrip("./")
if t.startswith("deliverables/"):
cand = t[len("deliverables/"):]
elif t.startswith("calc/"):
cand = "02-concept/" + t
elif t in ("", "dossier.md"):
cand, suffix = "02-concept/concept.md", ""
else:
cand = f"02-concept/alternatives/{wdir}/{t}"
if os.path.exists(deliv(run, cand)):
if cand + suffix not in out:
out.append(cand + suffix)
else:
warn(f"evidence {ref} -> {cand} not found; dropped")
return "; ".join(out)
def merge_compliance(run, winner, wdir):
reqs = tlib.load_reqs(run)
_h, rows = tlib.read_csv(os.path.join(run, "work", "teams", winner, "compliance.csv"))
claims = {r["req_id"]: r for r in rows}
bmap = tlib.load_json(os.path.join(run, "work", "tournament", "blind-map.json"), {}) or {}
tally = tlib.load_json(os.path.join(run, "work", "tournament", "tally.json"), {}) or {}
judges = tally["judges"] if "judges" in tally else [ # the judges the tally used; else those who judged
j for j in sorted(bmap.get("judges", {})) if os.path.isfile(os.path.join(run, "work", "judging", j, "verdict",
"pairs.csv"))]
preds = {}
for j in judges:
label = {t: lab for lab, t in bmap.get("judges", {}).get(j, {}).items()}.get(winner)
_h, jrows = tlib.read_csv(os.path.join(run, "work", "judging", j, "verdict", "compliance.csv"))
for r in jrows:
if r.get("dossier", "").upper() == label:
preds.setdefault(r.get("req_id"), []).append(r.get("predicted", "").lower())
regrade = {}
for j in judges:
_h, rg = tlib.read_csv(os.path.join(run, "work", "judging", j, "verdict", "regrade.csv"))
regrade.update({r.get("req_id"): r.get("predicted", "").lower() for r in rg})
out, counts = [], {}
for req in reqs:
rid = req["req_id"]
row = claims.get(rid)
if not row or row.get("status") not in ("met", "partly", "not_met"):
status, evidence, value, unit = "not_addressed", "", "", ""
note = "not addressed by the winning concept" + (f"; {row.get('note')}" if row and row.get("note") else "")
else:
claim, got = row["status"], preds.get(rid, [])
if rid in regrade and regrade[rid] in tlib.SCORE:
status, how = tlib.lower(claim, regrade[rid]), f"panel re-grade after grafts {regrade[rid]}"
elif tlib.panel(got) in tlib.SCORE:
status, how = tlib.lower(claim, tlib.panel(got)), "panel " + "/".join(got)
elif got: # every judge said unknown: the dossier gives no basis for the claim
status, how = tlib.lower(claim, "partly"), "panel " + "/".join(got) + " (no basis: capped at partly)"
else:
status, how = claim, "not judged by the panel"
value, unit = row.get("value", ""), row.get("unit", "")
evidence = rewrite_evidence(run, row.get("evidence", ""), wdir) or "02-concept/concept.md"
note = f"predicted at concept tier: team claim {claim}, {how} -> {status}"
if row.get("note"):
note += f"; {row['note']}"
counts[status] = counts.get(status, 0) + 1
out.append({"req_id": rid, "status": status, "value": value, "unit": unit, "evidence": evidence,
"note": note})
tlib.write_csv(deliv(run, "01-requirements", "compliance.csv"), tlib.COMPLIANCE_HEADER, out)
print(f"compliance.csv: {len(out)} rows " + ", ".join(f"{k} {v}" for k, v in sorted(counts.items())))
def merge_detail_evidence(run):
path = deliv(run, "01-requirements", "compliance.csv")
_h, base = tlib.read_csv(path)
by_id = {r["req_id"]: r for r in base}
root = os.path.join(run, "work", "detail")
detail = {}
for role in sorted(os.listdir(root)) if os.path.isdir(root) else []:
_h, rows = tlib.read_csv(os.path.join(root, role, "evidence.csv"))
for r in rows:
if r.get("status") in tlib.CONTRACT_STATUS and r.get("req_id"):
detail.setdefault(r["req_id"], []).append((role, r))
out = []
for req in tlib.load_reqs(run):
rid = req["req_id"]
old = by_id.get(rid, {"req_id": rid, "status": "not_addressed", "value": "", "unit": "", "evidence": "",
"note": ""})
rows = [(role, r) for role, r in detail.get(rid, []) if r["status"] != "not_addressed"]
if not rows:
new = dict(old)
if "not re-verified in detail" not in old.get("note", ""):
new["note"] = ("concept-tier prediction, not re-verified in detail; " + old.get("note", "")).strip("; ")
else:
_role, worst = min(rows, key=lambda x: tlib.SCORE[x[1]["status"]])
status = worst["status"]
refs = []
for role, r in rows:
for ref in tlib.evidence_refs(r.get("evidence", "")):
ref = ref[len("deliverables/"):] if ref.startswith("deliverables/") else ref
if not os.path.exists(deliv(run, tlib.ref_target(ref).lstrip("./"))):
warn(f"{rid}: evidence {ref} from {role} not found; dropped")
elif ref not in refs:
refs.append(ref)
if not refs: # unverifiable detail claim: never better than partly, never above the concept status
caps = ["partly"] + ([old["status"]] if old.get("status") in tlib.SCORE else [])
status = tlib.lower(status, *caps)
new = {"req_id": rid, "status": status, "value": worst.get("value", ""),
"unit": worst.get("unit", ""), "evidence": "; ".join(refs) or old.get("evidence", ""),
"note": "; ".join(f"{ro}: {r['status']} {r.get('note', '')}".strip() for ro, r in rows)
+ ("" if refs else "; evidence files missing - capped (at best partly, at most the "
"previous status)")}
if not new["evidence"]:
new["status"], new["note"] = "not_addressed", new["note"] + "; no evidence path"
out.append(new)
tlib.write_csv(path, tlib.COMPLIANCE_HEADER, out)
counts = {}
for r in out:
counts[r["status"]] = counts.get(r["status"], 0) + 1
print(f"compliance.csv (full): {len(out)} rows " + ", ".join(f"{k} {v}" for k, v in sorted(counts.items())))
KINDS = {"01-requirements": "requirements", "02-concept": "concept", "03-cad": "cad", "04-drawings": "drawing",
"05-calculations": "calculation", "06-electronics": "electronics", "07-firmware": "firmware",
"08-safety-certification": "safety-certification", "09-bom-cost": "bom-cost",
"10-prototype-test-plan": "test-plan", "11-renders": "render"}
DESCS = {"REPORT.md": "Design report", "01-requirements/compliance.csv": "Compliance table, one row per requirement id",
"02-concept/concept.md": "Chosen concept with the alternatives and the evaluation",
"02-concept/tournament.md": "Tournament record: schools, blind protocol, verdicts, tally, decision, grafts"}
def kind_of(rel):
top = rel.split("/", 1)[0]
kind = "report" if rel == "REPORT.md" else KINDS.get(top, "other")
for part in ("alternatives", "judging"):
if rel.startswith(f"02-concept/{part}/"):
return f"concept-{part}"
if rel.endswith(".results.json"):
return kind + "-result"
ext = os.path.splitext(rel)[1].lower().lstrip(".")
return f"{kind}-{ext}" if ext in ("py", "step", "stp", "glb", "csv", "json") else kind
def key_figures(run, tier):
kf = {"dimensions_mm": None, "mass_kg": None, "power_w": None, "unit_cost": None, "retail_price": None}
src = []
win = tlib.load_json(os.path.join(run, "work", "tournament", "winner.json"), {}) or {}
if win.get("team"):
est = tlib.load_json(os.path.join(run, "work", "teams", win["team"], "estimates.json"), {}) or {}
for k, v in (est.get("key_figures") or {}).items():
if k in kf and v is not None:
kf[k] = v
src.append(f"02-concept/alternatives/{win.get('dir', win['team'])}/estimates.json")
params = tlib.load_json(os.path.join(run, "work", "detail", "params.json"), {}) or {}
if tier == "full" and isinstance(params.get("key_figures"), dict):
for k, v in params["key_figures"].items():
if k in kf and v is not None:
kf[k] = v
src.append("work/detail/params.json")
cost = tlib.load_json(deliv(run, "09-bom-cost", "cost.json"), {}) or {}
uc = cost.get("unit_cost") if isinstance(cost, dict) else None
if isinstance(uc, dict) and all(isinstance(uc.get(q), (int, float)) for q in ("q1", "q100", "q1000")):
kf["unit_cost"] = {"currency": cost.get("currency"), "q1": uc["q1"], "q100": uc["q100"], "q1000": uc["q1000"]}
src.append("09-bom-cost/cost.json")
return kf, src
def load_blocked(run):
blocked = tlib.load_json(os.path.join(run, "work", "blocked.json"), []) or []
return [b for b in blocked if isinstance(b, dict) and b.get("what") and b.get("why")]
def ensure_minimum(run):
"""Before the winner exists: packet documents into 02-concept/ and a pending compliance.csv, so a hard stop
never finds the package without them."""
os.makedirs(deliv(run, "02-concept"), exist_ok=True)
for name, dest in (("benchmark.md", "benchmark.md"), ("physics-map.md", "physics-map.md"),
("anchors.md", "anchors.md"), ("problem.md", "problem-framing.md")):
src = os.path.join(run, "work", "packet", name)
if os.path.isfile(src):
shutil.copy2(src, deliv(run, "02-concept", dest))
path = deliv(run, "01-requirements", "compliance.csv")
if not os.path.isfile(path):
rows = [{"req_id": r["req_id"], "status": "not_addressed", "note": "pending: concept tournament in progress"}
for r in tlib.load_reqs(run)]
tlib.write_csv(path, tlib.COMPLIANCE_HEADER, rows)
print(f"compliance.csv did not exist: wrote {len(rows)} pending rows (not_addressed)")
def build_manifest(run, tier, kf, src, blocked):
root = deliv(run)
files = []
for dirpath, dirs, names in os.walk(root):
dirs[:] = sorted(d for d in dirs if d != "__pycache__" and not d.startswith("."))
for name in sorted(names):
p = os.path.join(dirpath, name)
rel = os.path.relpath(p, root).replace(os.sep, "/")
if rel == "manifest.json" or os.path.getsize(p) == 0:
continue
kind = kind_of(rel)
m = re.match(r"^02-concept/alternatives/([^/]+)/(.*)$", rel)
desc = DESCS.get(rel) or (f"Alternative concept {m.group(1)}: {m.group(2)}" if m else f"{kind}: {rel}")
files.append({"path": rel, "kind": kind, "desc": desc})
tlib.dump_json(deliv(run, "manifest.json"), {"tier": tier, "files": files, "key_figures": kf, "blocked": blocked})
print(f"manifest.json: tier {tier}, {len(files)} files, key figures from {', '.join(src) or 'nothing yet (null)'}"
f", {len(blocked)} blocked")
def fmt(v):
if v is None:
return "null (unknown)"
if isinstance(v, float):
return f"{v:.4g}"
return str(v)
def auto_block(run, tier, kf, src, blocked):
dims, uc, rp = kf.get("dimensions_mm"), kf.get("unit_cost") or {}, kf.get("retail_price") or {}
figures = [("dimensions L x W x H", " x ".join(fmt(d) for d in dims) + " mm" if dims else "null (unknown)"),
("mass", f"{fmt(kf.get('mass_kg'))} kg"), ("power", f"{fmt(kf.get('power_w'))} W")]
figures += [(f"unit cost at {q[1:]}", f"{fmt(uc.get(q))} {uc.get('currency') or ''}") for q in ("q1", "q100", "q1000")]
figures.append(("retail price", f"{fmt(rp.get('value'))} {rp.get('currency') or ''}"))
lines = [AUTO_BEGIN, "", f"### Key figures (home: {', '.join(src) or 'none yet'})", "", "| figure | value |",
"|---|---|"] + [f"| {a} | {b.strip()} |" for a, b in figures]
win = tlib.load_json(os.path.join(run, "work", "tournament", "winner.json"), {}) or {}
params = []
if tier == "full":
p = (tlib.load_json(os.path.join(run, "work", "detail", "params.json"), {}) or {}).get("params") or {}
params = [dict(v, name=k) for k, v in p.items() if isinstance(v, dict) and v.get("key", True)][:30]
if not params and win.get("team"):
est = tlib.load_json(os.path.join(run, "work", "teams", win["team"], "estimates.json"), {}) or {}
params = [p for p in est.get("parameters") or [] if isinstance(p, dict)][:30]
params = [dict(p, home=home_ref(run, p.get("home"), win.get("dir") or win.get("team", ""))) for p in params]
if params:
lines += ["", "### Key parameters", "", "| name | value | unit | origin | home |", "|---|---|---|---|---|"]
for p in params:
lines.append("| " + " | ".join(str(p.get(k, "")).replace("|", "/") for k in
("name", "value", "unit", "origin", "home")) + " |")
reqs = {r["req_id"]: r for r in tlib.load_reqs(run)}
_h, comp = tlib.read_csv(deliv(run, "01-requirements", "compliance.csv"))
if comp:
counts = {}
for r in comp:
counts[r.get("status")] = counts.get(r.get("status"), 0) + 1
lines += ["", "### Status per requirement (home: 01-requirements/compliance.csv)", "",
"Counts: " + ", ".join(f"{k} {v}" for k, v in sorted(counts.items())) + ".", "",
"| req_id | weight | status | value | unit | evidence |", "|---|---|---|---|---|---|"]
for r in comp:
w = reqs.get(r.get("req_id"), {}).get("weight", "")
lines.append(f"| {r.get('req_id')} | {fmt(w) if w != '' else ''} | {r.get('status')} | "
f"{r.get('value', '').replace('|', '/')} | {r.get('unit', '')} | "
f"{r.get('evidence', '').replace('|', '/')} |")
tally = tlib.load_json(os.path.join(run, "work", "tournament", "tally.json"), {}) or {}
if tally.get("teams"):
lines += ["", "### Concept tournament (home: 02-concept/tournament.md)", "",
"| rank | team | school | S | C | B | knock-out |", "|---|---|---|---|---|---|---|"]
for t in tally.get("ranking", []):
d = tally["teams"][t]
lines.append(f"| {d['rank']} | {t}{' (winner)' if t == win.get('team') else ''} | {d['philosophy']} | "
f"{d['S']:.3f} | {d['C']:.3f} | {d['B']:.3f} | {', '.join(d['knockout_ids']) or '-'} |")
grafts = tlib.load_json(os.path.join(run, "work", "tournament", "grafts.json"), []) or []
if grafts:
lines += ["", "Grafts: " + "; ".join(f"{g.get('id')} from {g.get('from')} ({g.get('status')}): "
f"{g.get('what')}" for g in grafts if isinstance(g, dict))]
lines += ["", "### Blocked (manifest.json blocked[])", ""]
lines += [f"- {b['what']}: {b['why']}" for b in blocked] or ["- nothing blocked"]
lines += ["", AUTO_END]
return "\n".join(lines)
def refresh_report(run, tier, kf, src, blocked):
path = deliv(run, "REPORT.md")
block = auto_block(run, tier, kf, src, blocked)
text = tlib.read_text(path)
if not text.strip():
text = (f"# Design report ({FALLBACK_MARK})\n\nThis file was generated by method/gates/assemble.py from the "
"run's files before the design report was written; it holds only the generated tables.\n\n")
print(f"REPORT.md did not exist: wrote a {FALLBACK_MARK} with the generated tables")
if AUTO_RE.search(text):
text = AUTO_RE.sub(lambda _m: block, text)
else:
text = text.rstrip() + "\n\n" + block + "\n"
tlib.write_text(path, text)
if FALLBACK_MARK in text:
warn(f"REPORT.md is still the {FALLBACK_MARK}: write the report (keep the AUTO markers)")
def cmd_concept(run, winner):
teams = tlib.teams_present(run)
if winner not in teams:
print(f"ERROR winner {winner} not in work/teams ({teams})")
return 1
sch = tlib.schools(run)
tally = tlib.load_json(os.path.join(run, "work", "tournament", "tally.json"), {}) or {}
order = [t for t in tally.get("ranking", []) if t in teams] or teams
order = [winner] + [t for t in order if t != winner]
concept_dir = deliv(run, "02-concept")
os.makedirs(concept_dir, exist_ok=True)
if os.path.isdir(os.path.join(concept_dir, "alternatives")):
shutil.rmtree(os.path.join(concept_dir, "alternatives"))
broken = []
for t in order:
dst = os.path.join(concept_dir, "alternatives", team_dir_name(t, sch))
copy_tree(team_src(run, t, winner), dst, only={"dossier.md", "estimates.json", "compliance.csv", "calc"})
if os.path.isfile(os.path.join(dst, "dossier.md")):
tlib.write_text(os.path.join(dst, "dossier.md"),
localize(tlib.read_text(os.path.join(dst, "dossier.md")), t, sch, winner, "alt"))
if t != winner:
for rel, err in quarantine(run, dst, t):
broken.append((t, rel, err))
warn(f"{t}: {rel} does not run as delivered ({err}); kept as {rel}.txt and listed in tournament.md")
wdir = team_dir_name(winner, sch)
calc = os.path.join(run, "work", "teams", winner, "calc")
if os.path.isdir(calc):
copy_tree(calc, os.path.join(concept_dir, "calc"))
jdir = os.path.join(concept_dir, "judging")
if os.path.isdir(jdir):
shutil.rmtree(jdir)
bmap = tlib.load_json(os.path.join(run, "work", "tournament", "blind-map.json"), {}) or {}
for j in sorted(bmap.get("judges", {})):
for name in ("pairs.csv", "compliance.csv", "observations.md", "regrade.csv"):
src = os.path.join(run, "work", "judging", j, "verdict", name)
if os.path.isfile(src):
os.makedirs(os.path.join(jdir, j), exist_ok=True)
shutil.copy2(src, os.path.join(jdir, j, name))
for src in (os.path.join(run, "work", "tournament", "blind-map.json"),
os.path.join(run, "work", "tournament", "tally.json")):
if os.path.isfile(src):
os.makedirs(jdir, exist_ok=True)
shutil.copy2(src, os.path.join(jdir, os.path.basename(src)))
tlib.dump_json(os.path.join(run, "work", "tournament", "winner.json"), {"team": winner, "dir": wdir})
tlib.write_text(os.path.join(concept_dir, "concept.md"), build_concept_md(run, winner, sch, order, wdir))
tlib.write_text(os.path.join(concept_dir, "tournament.md"), build_tournament_md(run, sch, teams, broken))
est = tlib.load_json(os.path.join(run, "work", "teams", winner, "estimates.json"), {}) or {}
cost = est.get("cost")
if isinstance(cost, dict) and {"currency", "bom", "unit_cost"} <= set(cost):
if os.path.isfile(deliv(run, "09-bom-cost", "bom.csv")):
warn("09-bom-cost/bom.csv exists (full tier): cost.json belongs to sourcing-cost and was left as it is")
else:
tlib.dump_json(deliv(run, "09-bom-cost", "cost.json"), cost)
print("09-bom-cost/cost.json written from the winner's rough cost estimate")
merge_compliance(run, winner, wdir)
detail = os.path.join(run, "work", "detail")
if any(os.path.isfile(os.path.join(detail, d, "evidence.csv")) for d in
(os.listdir(detail) if os.path.isdir(detail) else [])):
print("work/detail/*/evidence.csv present (full tier): merged again on top of the concept rows")
merge_detail_evidence(run)
print(f"02-concept: concept.md, tournament.md, alternatives/ ({len(order)}), calc/, judging/ - winner {winner}")
return 0
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("cmd", choices=["concept", "full", "manifest"])
ap.add_argument("--winner")
ap.add_argument("--tier", choices=["concept", "full"])
ap.add_argument("--run-dir", default=".")
args = ap.parse_args()
run = args.run_dir
os.makedirs(deliv(run), exist_ok=True)
tier = args.tier or ("full" if args.cmd == "full" or os.path.isfile(os.path.join(run, "work", "detail", "params.json"))
else "concept")
if args.cmd == "concept":
if not args.winner:
print("ERROR concept needs --winner T<n>")
return 1
rc = cmd_concept(run, args.winner)
if rc:
return rc
elif args.cmd == "full":
merge_detail_evidence(run)
ensure_minimum(run)
kf, src = key_figures(run, tier)
blocked = load_blocked(run)
refresh_report(run, tier, kf, src, blocked)
build_manifest(run, tier, kf, src, blocked)
print(f"assemble {args.cmd}: done, {len(WARN)} warning(s); next: python3 method/gates/dd_check.py --tier {tier}")
return 0
if __name__ == "__main__":
sys.exit(main())
files/method/gates/blind.py (225 wierszy)
#!/usr/bin/env python3
"""blind.py - anonymised, position-balanced copies of the concept dossiers for the judges (tournament method).
Usage (from the run directory):
python3 method/gates/blind.py --judges J1,J2,J3 [--teams T1,T2,T3,T4] [--seed N] [--scrub WORD ...]
python3 method/gates/blind.py --judges J4 --append (tie-break judge: next row of the design)
Copies dossier.md, estimates.json, compliance.csv and calc/ of every team to work/judging/<J>/X<k>/.
Every judge gets a different label order (rows of a Williams Latin square over a seeded shuffle), so each
dossier is read at different positions. Masks the SCHOOL block, school names, the team id and team paths (in
.py files only inside comments and strings). Writes the key to work/tournament/blind-map.json (judges never
read it) and the judged, unmasked version of each team to work/tournament/judged/T<n>/ (--append copies from
it). Without --append it starts over: every work/judging/J*/ folder is removed first. Each judge's
verdict/compliance.csv is prefilled from the dossiers' own claims (not_addressed -> unknown); rows of ids
with weight >= the median weight carry the note 'claim; check'. Standard library only.
"""
import argparse
import io
import json
import os
import random
import re
import shutil
import sys
import time
import tokenize
import tlib
TEXT_EXT = (".md", ".json", ".csv", ".txt", ".py", ".yaml", ".yml")
MAX_BYTES = 5 * 1024 * 1024
def williams(n):
first, lo, hi, low_turn = [0], 1, n - 1, True
while len(first) < n:
if low_turn:
first.append(lo)
lo += 1
else:
first.append(hi)
hi -= 1
low_turn = not low_turn
rows = [[(x + r) % n for x in first] for r in range(n)]
if n % 2:
rows += [list(reversed(row)) for row in rows]
return rows
def py_literals(text, fn):
"""Apply fn to the comments and string literals of Python source only (identifiers stay intact)."""
kinds = {tokenize.COMMENT, tokenize.STRING} # f-string parts are left alone (the leak count still sees them)
try:
toks = [t for t in tokenize.generate_tokens(io.StringIO(text).readline) if t.type in kinds]
except (tokenize.TokenError, SyntaxError):
return "\n".join(c + "#" + fn(m) if "#" in line else line
for line in text.split("\n") for c, _s, m in [line.partition("#")])
starts = [0]
for line in text.split("\n"):
starts.append(starts[-1] + len(line) + 1)
for t in reversed(toks):
a, b = starts[t.start[0] - 1] + t.start[1], starts[t.end[0] - 1] + t.end[1]
text = text[:a] + fn(text[a:b]) + text[b:]
return text
def mask(text, ext, scrub, team):
hits = 0
def sub(pattern, repl, s, flags=0):
nonlocal hits
out, k = re.subn(pattern, repl, s, flags=flags)
hits += k
return out
def words(s):
s = sub(r"\b(%s)\b" % "|".join(tlib.PHILOSOPHIES), "[school]", s)
s = sub(r"(?i)\bwild[- ]?card\b", "[school]", s)
s = sub(r"(?i)\b(minimal|performance|robust)[- ](school|philosophy|team)\b", "[school]", s)
s = sub(r"(?i)\bteam\s*[-:]?\s*T\d{1,2}\b", "[team]", s)
s = sub(r"\b%s\b" % re.escape(team), "[team]", s) # the team's own id, also bare ('Card of T4')
for word in scrub:
s = sub(re.escape(word), "[masked]", s, re.I)
return s
text = sub(tlib.SCHOOL_BLOCK_RE.pattern, "", text, re.S)
text = sub(r"[^\s'\"(]*work/teams/T\d{1,2}/", "", text)
text = py_literals(text, words) if ext == ".py" else words(text)
return text, hits
def leaks(text, team):
pats = [r"\b(%s)\b" % "|".join(tlib.PHILOSOPHIES), r"(?i)\bteam\s*T\d", r"work/teams", r"SCHOOL:",
r"\b%s\b" % re.escape(team)]
return sum(len(re.findall(p, text)) for p in pats)
def snapshot(run, team):
"""Unmasked copy of what the judges see, so a late write by the team cannot change the published record."""
src, dst = os.path.join(run, "work", "teams", team), os.path.join(run, "work", "tournament", "judged", team)
os.makedirs(dst, exist_ok=True)
for name in ("dossier.md", "estimates.json", "compliance.csv"):
if os.path.isfile(os.path.join(src, name)):
shutil.copy2(os.path.join(src, name), os.path.join(dst, name))
if os.path.isdir(os.path.join(src, "calc")):
shutil.copytree(os.path.join(src, "calc"), os.path.join(dst, "calc"),
ignore=shutil.ignore_patterns("__pycache__"), dirs_exist_ok=True)
def prefill(jdir, mapping, reqs):
"""verdict/compliance.csv with one row per dossier x id, started from the dossier's own claim."""
focus = tlib.median_weight(reqs)
rows = []
for label in sorted(mapping, key=lambda x: int(x[1:])):
_h, claims = tlib.read_csv(os.path.join(jdir, label, "compliance.csv"))
claim = {c.get("req_id"): c.get("status") for c in claims}
rows += [{"dossier": label, "req_id": r["req_id"], "predicted": tlib.claim_to_pred(claim.get(r["req_id"])),
"note": "claim; check" if float(r["weight"]) >= focus else "claim"} for r in reqs]
tlib.write_csv(os.path.join(jdir, "verdict", "compliance.csv"), ["dossier", "req_id", "predicted", "note"], rows)
def copy_team(src, dst, scrub, team):
hits = leak = 0
for root, dirs, files in os.walk(src):
dirs[:] = [d for d in dirs if d != "__pycache__"]
rel_root = os.path.relpath(root, src)
if rel_root != "." and not (rel_root == "calc" or rel_root.startswith("calc" + os.sep)):
continue
for name in files:
if rel_root == "." and name not in ("dossier.md", "estimates.json", "compliance.csv"):
continue
s = os.path.join(root, name)
d = os.path.join(dst, rel_root, name) if rel_root != "." else os.path.join(dst, name)
if os.path.getsize(s) > MAX_BYTES:
continue
os.makedirs(os.path.dirname(d), exist_ok=True)
leak += len(re.findall(r"(?<![A-Za-z0-9])%s(?![0-9])" % re.escape(team), name)) # id in a file name
ext = os.path.splitext(name)[1].lower()
if ext not in TEXT_EXT:
shutil.copy2(s, d)
continue
text = tlib.read_text(s)
if ext == ".json":
data = tlib.load_json(s)
if isinstance(data, dict):
for key in ("team", "school", "philosophy"):
data.pop(key, None)
text = json.dumps(data, indent=2, ensure_ascii=False) + "\n"
text, k = mask(text, ext, scrub, team)
hits += k
leak += leaks(text, team)
tlib.write_text(d, text)
return hits, leak
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--judges", required=True, help="comma list, e.g. J1,J2,J3")
ap.add_argument("--teams", help="comma list (default: every work/teams/T<n> with a dossier.md)")
ap.add_argument("--seed", type=int)
ap.add_argument("--scrub", action="append", default=[], help="extra word to mask (repeatable)")
ap.add_argument("--append", action="store_true", help="add judges to an existing map")
ap.add_argument("--run-dir", default=".")
args = ap.parse_args()
run = args.run_dir
map_path = os.path.join(run, "work", "tournament", "blind-map.json")
old = tlib.load_json(map_path, {}) if args.append else {}
if args.append and not old:
print("ERROR --append needs an existing work/tournament/blind-map.json")
return 1
if old:
teams, seed = old["teams"], old["seed"]
else:
teams = args.teams.split(",") if args.teams else [
t for t in tlib.teams_present(run) if os.path.isfile(os.path.join(run, "work", "teams", t, "dossier.md"))]
seed = args.seed if args.seed is not None else int(time.time()) % 100000
if len(teams) < 2:
print(f"ERROR need at least two teams with a dossier, found {teams}")
return 1
if not args.append: # a fresh blinding voids every earlier label key, copy and verdict
jroot = os.path.join(run, "work", "judging")
gone = [d for d in (sorted(os.listdir(jroot)) if os.path.isdir(jroot) else [])
if re.match(r"^J\d+$", d) and os.path.isdir(os.path.join(jroot, d))]
for d in gone:
shutil.rmtree(os.path.join(jroot, d))
if gone:
print(f"NOTE fresh blinding: removed work/judging/{','.join(gone)} (old copies and verdicts)")
shutil.rmtree(os.path.join(run, "work", "tournament", "judged"), ignore_errors=True)
for team in teams:
snapshot(run, team)
reqs = tlib.load_reqs(run)
base = sorted(teams, key=lambda t: int(t[1:]))
random.Random(seed).shuffle(base)
rows = williams(len(base))
judges_map = dict(old.get("judges", {}))
total_leaks = 0
for judge in [j.strip() for j in args.judges.split(",") if j.strip()]:
if judge in judges_map:
print(f"ERROR {judge} already has a mapping; use a new judge name")
return 1
row = rows[len(judges_map) % len(rows)]
mapping = {f"X{k + 1}": base[i] for k, i in enumerate(row)}
jdir = os.path.join(run, "work", "judging", judge)
for label, team in mapping.items():
dst = os.path.join(jdir, label)
if os.path.isdir(dst):
shutil.rmtree(dst)
hits, leak = copy_team(tlib.team_source(run, team), dst, args.scrub, team)
total_leaks += leak
if leak:
print(f"WARN {judge}/{label}: {leak} possible identity leak(s) left (masking skips code "
f"identifiers and f-strings); for a word in text re-run with --scrub WORD")
os.makedirs(os.path.join(jdir, "verdict"), exist_ok=True)
prefill(jdir, mapping, reqs)
judges_map[judge] = mapping
print(f"{judge}: {len(mapping)} dossiers -> work/judging/{judge}/X1..X{len(mapping)} "
"(verdict/compliance.csv prefilled from the claims)")
tlib.dump_json(map_path, {"seed": seed, "teams": teams, "design": "Williams Latin square rows over a seeded "
"shuffle; one row per judge", "judges": judges_map})
print(f"blind-map -> work/tournament/blind-map.json (seed {seed}); leaks left: {total_leaks}")
return 0
if __name__ == "__main__":
sys.exit(main())
files/method/gates/dd_check.py (431 wierszy)
#!/usr/bin/env python3
"""dd_check.py - check deliverables/ against the RUN CONTRACT layout (contract v1.x).
Usage (from the run directory):
python3 method/gates/dd_check.py --tier concept|full [--run-scripts] [--json]
Checks the formats the RUN CONTRACT fixes (compliance.csv, manifest.json, bom.csv, cost.json, the
folder layout of the tier, evidence paths) and prints ERROR / WARN lines. Exit code 0 = no errors.
It checks form, not engineering quality. Standard library only.
"""
import argparse
import csv
import io
import json
import os
import re
import shutil
import subprocess
import sys
COMPLIANCE_HEADER = ["req_id", "status", "value", "unit", "evidence", "note"]
COMPLIANCE_STATUS = {"met", "partly", "not_met", "not_addressed"}
BOM_HEADER = ["item", "qty", "description", "manufacturer", "mpn", "supplier", "supplier_part", "url",
"unit_price_1", "unit_price_100", "unit_price_1000", "currency", "notes"]
HEADING_ID = re.compile(r"^#{1,6}\s+([A-Z][A-Z0-9]{1,7}-[A-Z0-9]{1,7}-\d{1,4})\b")
LOOSE_ID = re.compile(r"\b([A-Z][A-Z0-9]{1,7}-[A-Z]{2,7}-\d{2,4})\b")
FULL_DIRS = ["03-cad", "04-drawings", "05-calculations", "06-electronics", "07-firmware",
"08-safety-certification", "09-bom-cost", "10-prototype-test-plan", "11-renders"]
class Report:
def __init__(self):
self.errors, self.warnings, self.notes = [], [], []
def error(self, msg):
self.errors.append(msg)
def warn(self, msg):
self.warnings.append(msg)
def note(self, msg):
self.notes.append(msg)
def requirement_ids(path):
"""Ids of INPUT/requirements.md: headings first, loose tokens as a fallback."""
if not os.path.isfile(path):
return []
with open(path, encoding="utf-8", errors="replace") as fh:
text = fh.read()
ids = []
for line in text.splitlines():
m = HEADING_ID.match(line.strip())
if m and m.group(1) not in ids:
ids.append(m.group(1))
if not ids:
for m in LOOSE_ID.finditer(text):
if m.group(1) not in ids:
ids.append(m.group(1))
return ids
def nonempty_files(folder, exts=None):
out = []
for root, _dirs, files in os.walk(folder):
for name in files:
p = os.path.join(root, name)
if os.path.getsize(p) == 0:
continue
if exts and not name.lower().endswith(tuple(exts)):
continue
out.append(p)
return out
def split_paths(field):
parts = re.split(r"[;|\n]+|\s+(?=[\w./-]+/)", field or "")
return [p.strip().strip("`'\"") for p in parts if p.strip()]
def evidence_exists(deliv, ref):
ref = ref.split("#", 1)[0].split("::", 1)[0].strip()
if not ref:
return True
if ref.startswith("deliverables/"):
ref = ref[len("deliverables/"):]
ref = ref.lstrip("./")
m = re.match(r"^(.*?)(:\d+(-\d+)?)$", ref)
if m:
ref = m.group(1)
return os.path.exists(os.path.join(deliv, ref))
def check_compliance(deliv, ids, rep):
path = os.path.join(deliv, "01-requirements", "compliance.csv")
if not os.path.isfile(path):
rep.error("01-requirements/compliance.csv missing")
return
raw = open(path, encoding="utf-8-sig", errors="replace").read()
rows = list(csv.reader(io.StringIO(raw)))
if not rows:
rep.error("compliance.csv is empty")
return
header = [h.strip() for h in rows[0]]
if header != COMPLIANCE_HEADER:
rep.error(f"compliance.csv header is {header}, expected {COMPLIANCE_HEADER}")
return
seen = {}
for n, row in enumerate(rows[1:], start=2):
if not any(c.strip() for c in row):
continue
if len(row) != len(COMPLIANCE_HEADER):
rep.error(f"compliance.csv line {n}: {len(row)} fields, expected {len(COMPLIANCE_HEADER)} (quote fields with commas)")
continue
rid, status, _value, _unit, evidence, _note = [c.strip() for c in row]
if rid in seen:
rep.error(f"compliance.csv line {n}: duplicate id {rid} (first at line {seen[rid]})")
seen[rid] = n
if status not in COMPLIANCE_STATUS:
rep.error(f"compliance.csv line {n}: status '{status}' not in {sorted(COMPLIANCE_STATUS)}")
if status != "not_addressed" and not evidence:
rep.error(f"compliance.csv line {n} ({rid}): status {status} without evidence path")
for ref in split_paths(evidence):
if not evidence_exists(deliv, ref):
rep.error(f"compliance.csv line {n} ({rid}): evidence path not found: {ref}")
if ids:
missing = [i for i in ids if i not in seen]
extra = [i for i in seen if i not in ids]
if missing:
rep.error(f"compliance.csv lacks {len(missing)} requirement id(s): {', '.join(missing)}")
if extra:
rep.warn(f"compliance.csv has ids not in INPUT/requirements.md: {', '.join(extra)}")
rep.note(f"compliance.csv: {len(seen)} rows for {len(ids)} requirement ids")
else:
rep.warn("no requirement ids found in INPUT/requirements.md; row coverage not checked")
def check_ids_in_requirements(deliv, ids, rep):
folder = os.path.join(deliv, "01-requirements")
texts = ""
for p in nonempty_files(folder, (".md", ".yaml", ".yml", ".txt")):
texts += open(p, encoding="utf-8", errors="replace").read() + "\n"
if not texts:
rep.error("01-requirements/ has no requirements document (.md/.yaml) besides compliance.csv")
return
absent = [i for i in ids if i not in texts]
if absent:
rep.warn(f"requirement ids not mentioned in the 01-requirements documents: {', '.join(absent)}")
def num_or_null(x):
return x is None or isinstance(x, (int, float)) and not isinstance(x, bool)
def check_manifest(deliv, tier, rep):
path = os.path.join(deliv, "manifest.json")
if not os.path.isfile(path):
rep.error("manifest.json missing")
return
try:
man = json.load(open(path, encoding="utf-8"))
except Exception as exc: # noqa: BLE001
rep.error(f"manifest.json does not parse: {exc}")
return
if man.get("tier") != tier:
rep.error(f"manifest.json tier is {man.get('tier')!r}, expected {tier!r}")
files = man.get("files")
if not isinstance(files, list) or not files:
rep.error("manifest.json files[] missing or empty")
else:
listed = set()
for f in files:
if not isinstance(f, dict) or not {"path", "kind", "desc"} <= set(f):
rep.error(f"manifest.json files[] entry lacks path/kind/desc: {f}")
continue
listed.add(f["path"].lstrip("./"))
if not evidence_exists(deliv, f["path"]):
rep.error(f"manifest.json lists a file that does not exist: {f['path']}")
actual = set()
for p in nonempty_files(deliv):
rel = os.path.relpath(p, deliv)
if rel != "manifest.json":
actual.add(rel)
unlisted = sorted(a for a in actual if a not in listed and not any(a.startswith(l.rstrip("/") + "/") for l in listed))
if unlisted:
rep.warn(f"{len(unlisted)} deliverable file(s) not listed in manifest.json, e.g. {unlisted[:5]}")
kf = man.get("key_figures")
if not isinstance(kf, dict):
rep.error("manifest.json key_figures missing")
else:
for key in ("dimensions_mm", "mass_kg", "power_w", "unit_cost", "retail_price"):
if key not in kf:
rep.error(f"manifest.json key_figures.{key} missing (use null when unknown)")
dims = kf.get("dimensions_mm")
if dims is not None and not (isinstance(dims, list) and len(dims) == 3 and all(num_or_null(d) for d in dims)):
rep.error("key_figures.dimensions_mm must be [L, W, H] numbers or null")
for key in ("mass_kg", "power_w"):
if key in kf and not num_or_null(kf[key]):
rep.error(f"key_figures.{key} must be a number or null")
uc = kf.get("unit_cost")
if uc is not None:
if not isinstance(uc, dict) or not {"currency", "q1", "q100", "q1000"} <= set(uc):
rep.error("key_figures.unit_cost needs currency, q1, q100, q1000")
elif not all(num_or_null(uc[q]) for q in ("q1", "q100", "q1000")):
rep.error("key_figures.unit_cost q1/q100/q1000 must be numbers or null")
rp = kf.get("retail_price")
if rp is not None and (not isinstance(rp, dict) or not {"currency", "value"} <= set(rp) or not num_or_null(rp.get("value"))):
rep.error("key_figures.retail_price needs currency and a numeric value (or null)")
blocked = man.get("blocked")
if not isinstance(blocked, list):
rep.error("manifest.json blocked[] missing (use [] when nothing is blocked)")
else:
for b in blocked:
if not isinstance(b, dict) or not {"what", "why"} <= set(b):
rep.error(f"manifest.json blocked[] entry needs what and why: {b}")
def check_cost_json(deliv, rep, required):
path = os.path.join(deliv, "09-bom-cost", "cost.json")
if not os.path.isfile(path):
if required:
rep.error("09-bom-cost/cost.json missing")
return None
try:
cost = json.load(open(path, encoding="utf-8"))
except Exception as exc: # noqa: BLE001
rep.error(f"cost.json does not parse: {exc}")
return None
for key in ("currency", "bom", "unit_cost"):
if key not in cost:
rep.error(f"cost.json lacks {key}")
for key in ("bom", "unit_cost"):
block = cost.get(key)
if isinstance(block, dict) and not all(num_or_null(block.get(q)) for q in ("q1", "q100", "q1000")):
rep.error(f"cost.json {key} needs numeric q1, q100, q1000")
other = cost.get("other", {})
if not isinstance(other, dict):
rep.error("cost.json other must be an object of {name: {q1, q100, q1000}}")
else:
try:
for q in ("q1", "q100", "q1000"):
total = float(cost["bom"][q]) + sum(float(v.get(q) or 0) for v in other.values())
unit = float(cost["unit_cost"][q])
if unit > 0 and abs(total - unit) / unit > 0.02:
rep.warn(f"cost.json unit_cost.{q}={unit} differs from bom+other={total:.2f} by >2 %")
except (KeyError, TypeError, ValueError):
pass
return cost
def as_float(text):
try:
return float(str(text).replace(",", ".").strip())
except ValueError:
return None
def check_bom(deliv, cost, rep):
path = os.path.join(deliv, "09-bom-cost", "bom.csv")
if not os.path.isfile(path):
rep.error("09-bom-cost/bom.csv missing")
return
rows = list(csv.reader(io.StringIO(open(path, encoding="utf-8-sig", errors="replace").read())))
if not rows or [h.strip() for h in rows[0]] != BOM_HEADER:
rep.error(f"bom.csv header must be exactly {','.join(BOM_HEADER)}")
return
totals = {"unit_price_1": 0.0, "unit_price_100": 0.0, "unit_price_1000": 0.0}
currencies = set()
lines = 0
for n, row in enumerate(rows[1:], start=2):
if not any(c.strip() for c in row):
continue
if len(row) != len(BOM_HEADER):
rep.error(f"bom.csv line {n}: {len(row)} fields, expected {len(BOM_HEADER)}")
continue
rec = dict(zip(BOM_HEADER, [c.strip() for c in row]))
lines += 1
qty = as_float(rec["qty"])
if qty is None:
rep.error(f"bom.csv line {n}: qty '{rec['qty']}' is not a number")
continue
if not rec["mpn"] and not rec["supplier_part"]:
rep.warn(f"bom.csv line {n}: neither mpn nor supplier_part ({rec['description'][:40]})")
if rec["url"] and not rec["url"].startswith(("http://", "https://")):
rep.warn(f"bom.csv line {n}: url is not http(s)")
currencies.add(rec["currency"])
for col in totals:
price = as_float(rec[col])
if price is None:
rep.warn(f"bom.csv line {n}: {col} '{rec[col]}' is not a number")
else:
totals[col] += qty * price
rep.note(f"bom.csv: {lines} lines; sums 1/100/1000 = {totals['unit_price_1']:.2f} / "
f"{totals['unit_price_100']:.2f} / {totals['unit_price_1000']:.2f} {','.join(sorted(currencies))}")
if len(currencies) > 1:
rep.warn(f"bom.csv mixes currencies {sorted(currencies)}; totals not comparable")
elif cost and isinstance(cost.get("bom"), dict):
for q, col in (("q1", "unit_price_1"), ("q100", "unit_price_100"), ("q1000", "unit_price_1000")):
ref = as_float(cost["bom"].get(q))
if ref and abs(ref - totals[col]) / ref > 0.02:
rep.warn(f"cost.json bom.{q}={ref} differs from the bom.csv sum {totals[col]:.2f} by >2 %")
def toolchain_python():
"""The toolchain Python the RUN CONTRACT names (ddpy), else the venv, else this interpreter."""
for cand in (shutil.which("ddpy"), "/opt/dd/venv/bin/python"):
if cand and os.path.exists(cand):
return cand
return sys.executable
def check_scripts(folder, rep, run):
scripts = [p for p in nonempty_files(folder, (".py",))]
for script in scripts:
stem = os.path.splitext(script)[0]
results = stem + ".results.json"
if run:
try:
proc = subprocess.run([toolchain_python(), os.path.basename(script)], cwd=os.path.dirname(script),
capture_output=True, text=True, timeout=300)
if proc.returncode != 0:
rep.error(f"{os.path.relpath(script)} exits {proc.returncode}: {proc.stderr.strip()[-200:]}")
except subprocess.TimeoutExpired:
rep.error(f"{os.path.relpath(script)} runs longer than 5 minutes")
if not os.path.isfile(results):
rep.warn(f"{os.path.relpath(script)} has no {os.path.basename(results)}")
continue
try:
data = json.load(open(results, encoding="utf-8"))
bad = [k for k, v in data.items() if not (isinstance(v, dict) and "value" in v and "unit" in v)]
if bad:
rep.warn(f"{os.path.relpath(results)}: entries without value/unit: {bad[:5]}")
except Exception as exc: # noqa: BLE001
rep.error(f"{os.path.relpath(results)} does not parse: {exc}")
def check_full(deliv, rep, run):
for d in FULL_DIRS:
if not nonempty_files(os.path.join(deliv, d)):
rep.error(f"{d}/ missing or empty")
cad = os.path.join(deliv, "03-cad")
asm = os.path.join(cad, "assembly.step")
if not os.path.isfile(asm):
rep.error("03-cad/assembly.step missing")
else:
if not open(asm, "rb").read(64).lstrip().startswith(b"ISO-10303-21"):
rep.error("03-cad/assembly.step is not a STEP file (no ISO-10303-21 header)")
steps = [p for p in nonempty_files(cad, (".step", ".stp")) if not p.endswith("assembly.step")]
if not steps:
rep.error("03-cad/ has no per-part STEP files")
if not nonempty_files(cad, (".py", ".fcstd")):
rep.error("03-cad/ has no parametric source (.py or .FCStd)")
if not nonempty_files(os.path.join(deliv, "04-drawings"), (".pdf", ".svg")):
rep.error("04-drawings/ has no PDF or SVG drawing")
check_scripts(os.path.join(deliv, "05-calculations"), rep, run)
ele = os.path.join(deliv, "06-electronics")
if not nonempty_files(ele, (".kicad_pro",)) or not nonempty_files(ele, (".kicad_sch",)):
rep.error("06-electronics/ lacks a KiCad project (.kicad_pro + .kicad_sch)")
names = " ".join(os.path.basename(p).lower() for p in nonempty_files(ele))
if "erc" not in names:
rep.warn("06-electronics/ has no file named like an ERC report")
if nonempty_files(ele, (".kicad_pcb",)) and "drc" not in names:
rep.warn("06-electronics/ has a board but no file named like a DRC report")
if not os.path.isfile(os.path.join(deliv, "07-firmware", "platformio.ini")):
rep.error("07-firmware/platformio.ini missing")
cost = check_cost_json(deliv, rep, required=True)
check_bom(deliv, cost, rep)
if not os.path.isfile(os.path.join(deliv, "09-bom-cost", "cost.md")):
rep.error("09-bom-cost/cost.md missing")
ren = os.path.join(deliv, "11-renders")
if not nonempty_files(ren, (".png",)):
rep.error("11-renders/ has no PNG render")
glb = os.path.join(ren, "assembly.glb")
if not os.path.isfile(glb):
rep.error("11-renders/assembly.glb missing")
elif open(glb, "rb").read(4) != b"glTF":
rep.error("11-renders/assembly.glb is not a binary glTF file")
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--tier", choices=["concept", "full"], required=True)
ap.add_argument("--run-dir", default=".", help="run directory (default: current directory)")
ap.add_argument("--run-scripts", action="store_true", help="execute calculation scripts (≤5 min each)")
ap.add_argument("--json", action="store_true", help="print a JSON summary as the last line")
args = ap.parse_args()
run_dir = os.path.abspath(args.run_dir)
deliv = os.path.join(run_dir, "deliverables")
rep = Report()
if not os.path.isdir(deliv):
rep.error("deliverables/ missing")
else:
ids = requirement_ids(os.path.join(run_dir, "INPUT", "requirements.md"))
if not os.path.isdir(os.path.join(deliv, "01-requirements")):
rep.error("01-requirements/ missing")
else:
check_compliance(deliv, ids, rep)
check_ids_in_requirements(deliv, ids, rep)
if not nonempty_files(os.path.join(deliv, "02-concept"), (".md",)):
rep.error("02-concept/ has no markdown document")
report = os.path.join(deliv, "REPORT.md")
if not os.path.isfile(report):
rep.error("REPORT.md missing")
elif os.path.getsize(report) < 1500:
rep.warn("REPORT.md is shorter than 1500 bytes")
check_manifest(deliv, args.tier, rep)
check_scripts(os.path.join(deliv, "02-concept"), rep, args.run_scripts)
if args.tier == "concept":
check_cost_json(deliv, rep, required=False)
started = [d for d in FULL_DIRS if d != "09-bom-cost" and nonempty_files(os.path.join(deliv, d))]
if started:
rep.warn(f"concept tier: detailed-design folders present ({', '.join(started)}); they are not judged at this tier")
else:
check_full(deliv, rep, args.run_scripts)
for msg in rep.notes:
print(f"NOTE {msg}")
for msg in rep.warnings:
print(f"WARN {msg}")
for msg in rep.errors:
print(f"ERROR {msg}")
print(f"dd_check: tier={args.tier} errors={len(rep.errors)} warnings={len(rep.warnings)} -> "
f"{'PASS' if not rep.errors else 'FAIL'}")
if args.json:
print(json.dumps({"tier": args.tier, "pass": not rep.errors, "errors": rep.errors,
"warnings": rep.warnings, "notes": rep.notes}))
return 0 if not rep.errors else 1
if __name__ == "__main__":
sys.exit(main())
files/method/gates/dossier_check.py (257 wierszy)
#!/usr/bin/env python3
"""dossier_check.py - form check of one concept team's folder (tournament method).
Usage (from the run directory): python3 method/gates/dossier_check.py --team T2 [--run] [--init]
--init first creates the missing skeleton files in work/teams/<T>/ (dossier.md from the template, estimates.json,
compliance.csv with one not_addressed row per id) - fill them in place.
Checks work/teams/<T>/ against method/templates/dossier.md: dossier sections 1-12, the SCHOOL block, template
text left in, estimates.json, calc scripts with results files (--run re-runs them with ddpy, 5 min each),
compliance.csv (one row per id of work/packet/req-index.csv, valid status, evidence that exists), the team id or
school named outside the SCHOOL block. ERROR = fix before the deadline; WARN = weakens the dossier in front of
the judges. Exit 0 = no ERROR. Standard library only.
"""
import argparse
import os
import re
import subprocess
import sys
import tlib
KF_KEYS = ("dimensions_mm", "mass_kg", "power_w", "unit_cost", "retail_price")
DATE_RE = re.compile(r"20\d\d-[01]\d-[0-3]\d")
def is_num(x):
return x is None or (isinstance(x, (int, float)) and not isinstance(x, bool))
def template_left(run, text):
"""(sections still exactly the template text, instruction text of the template left in the dossier)."""
found = [m for m in ("Delete these instruction lines", "Files next to this dossier") if m in text]
tpl = tlib.read_text(os.path.join(run, "method", "templates", "dossier.md"))
body = {n: text[s:e].split("\n", 1)[-1].strip() for n, _h, s, e in tlib.sections(text)}
unwritten = []
for n, _h, s, e in tlib.sections(tpl):
tbody = tpl[s:e].split("\n", 1)[-1].strip()
first = tbody.split("\n")[0].strip()
if n <= 12 and body.get(n) == tbody:
unwritten.append(n)
elif n <= 12 and len(first) > 30 and first in body.get(n, ""):
found.append(f"section {n}")
return unwritten, found
def check_dossier(run, folder, team, err, warn, note):
text = tlib.read_text(os.path.join(folder, "dossier.md"))
if not text.strip():
err("dossier.md missing or empty")
return
found = {n for n, _h, _s, _e in tlib.sections(text)}
missing = [n for n in range(1, 13) if n not in found]
if missing:
err(f"dossier.md lacks numbered sections {missing} (headings '## <n>. <title>' as in the template)")
blocks = len(tlib.SCHOOL_BLOCK_RE.findall(text))
if blocks != 1:
warn(f"dossier.md has {blocks} SCHOOL blocks; exactly one is expected at the top")
body = tlib.strip_school_block(text)
leaks = re.findall(r"\b(?:%s)\b" % "|".join(tlib.PHILOSOPHIES), body)
leaks += re.findall(r"\b%s\b" % re.escape(team), body)
if leaks:
warn(f"dossier.md names its school or team id outside the SCHOOL block ({len(leaks)}x) - remove it")
unwritten, left = template_left(run, text)
if unwritten:
err(f"dossier.md sections {unwritten} are still the template text - write them")
if left:
warn(f"dossier.md still holds template instruction text ({', '.join(left)}) - replace or delete it")
if "```mermaid" not in text:
warn("dossier.md has no ```mermaid block diagram")
src = re.split(r"(?im)^##\s+sources\b", text)
dated = len(DATE_RE.findall(src[1])) if len(src) > 1 else 0
if dated < 3:
warn(f"Sources section has {dated} dated entries (prices, parts and standards need a read date)")
words = len(body.split())
note(f"dossier.md: {words} words, sections {sorted(found)}")
if words < 1200:
warn("dossier.md is under 1200 words - likely too thin to win")
if words > 9000:
warn("dossier.md is over 9000 words - judges have about 10 minutes for four dossiers")
def check_estimates(folder, err, warn):
est = tlib.load_json(os.path.join(folder, "estimates.json"))
if not isinstance(est, dict):
err("estimates.json missing or not a JSON object")
return
kf = est.get("key_figures")
if not isinstance(kf, dict):
err("estimates.json key_figures missing")
else:
for key in KF_KEYS:
if key not in kf:
err(f"estimates.json key_figures.{key} missing (null when unknown)")
dims = kf.get("dimensions_mm")
if dims is not None and not (isinstance(dims, list) and len(dims) == 3 and all(is_num(d) for d in dims)):
err("key_figures.dimensions_mm must be [L, W, H] or null")
for key in ("mass_kg", "power_w"):
if not is_num(kf.get(key)):
err(f"key_figures.{key} must be a number or null")
uc = kf.get("unit_cost")
if uc is not None and (not isinstance(uc, dict) or not {"currency", "q1", "q100", "q1000"} <= set(uc)
or not all(is_num(uc[q]) for q in ("q1", "q100", "q1000"))):
err("key_figures.unit_cost needs currency and numeric q1, q100, q1000 (or null)")
rp = kf.get("retail_price")
if rp is not None and (not isinstance(rp, dict) or not is_num(rp.get("value")) or "currency" not in rp):
err("key_figures.retail_price needs currency and value (or null)")
params = est.get("parameters")
if not isinstance(params, list) or not params:
warn("estimates.json parameters[] empty - list every number the decision rests on")
else:
bad = [p.get("name", "?") for p in params if not isinstance(p, dict)
or not {"name", "value", "unit", "origin"} <= set(p)]
if bad:
err(f"estimates.json parameters without name/value/unit/origin: {bad[:5]}")
cost = est.get("cost")
if isinstance(cost, dict) and isinstance(kf, dict) and isinstance(kf.get("unit_cost"), dict):
cu = cost.get("unit_cost") or {}
diff = [q for q in ("q1", "q100", "q1000") if is_num(cu.get(q)) and cu.get(q) != kf["unit_cost"].get(q)]
if diff:
warn(f"estimates.json cost.unit_cost differs from key_figures.unit_cost at {diff}")
def check_compliance(folder, ids, err, warn):
header, rows = tlib.read_csv(os.path.join(folder, "compliance.csv"))
if not header:
err("compliance.csv missing or empty")
return
if header != tlib.COMPLIANCE_HEADER:
err(f"compliance.csv header is {header}, expected {','.join(tlib.COMPLIANCE_HEADER)}")
return
seen, urls = [], []
for n, row in enumerate(rows, start=2):
rid, status = row["req_id"], row["status"]
if rid in seen:
err(f"compliance.csv line {n}: duplicate id {rid}")
seen.append(rid)
if status not in tlib.CONTRACT_STATUS:
err(f"compliance.csv line {n} ({rid}): status '{status}' not in {list(tlib.CONTRACT_STATUS)}")
if status != "not_addressed" and not row["evidence"]:
err(f"compliance.csv line {n} ({rid}): status {status} without evidence")
for ref in tlib.evidence_refs(row["evidence"]):
target = tlib.ref_target(ref)
if target.startswith(("http://", "https://")):
urls.append(rid)
elif target and not os.path.exists(os.path.join(folder, target.lstrip("./"))):
err(f"compliance.csv line {n} ({rid}): evidence not found in your folder: {target}")
if urls:
warn(f"compliance.csv: URLs as evidence for {len(urls)} id(s) (e.g. {urls[0]}); evidence = files in your "
"folder, put the source in the dossier's Sources")
missing = [i for i in ids if i not in seen]
if missing:
err(f"compliance.csv lacks {len(missing)} id(s): {', '.join(missing[:15])}")
if rows and all(row["status"] == "not_addressed" for row in rows):
warn("compliance.csv: every id is still not_addressed - predict each one")
extra = [i for i in seen if ids and i not in ids]
if extra:
warn(f"compliance.csv has ids that are not requirement ids: {', '.join(extra[:10])}")
def check_calc(folder, run_scripts, err, warn, note):
calc = os.path.join(folder, "calc")
scripts = sorted(f for f in os.listdir(calc) if f.endswith(".py")) if os.path.isdir(calc) else []
if not scripts:
warn("calc/ has no scripts - numbers without a script are weak evidence")
return
for name in scripts:
if run_scripts:
try:
proc = subprocess.run([tlib.toolchain_python(), name], cwd=calc, capture_output=True, text=True, timeout=300)
if proc.returncode != 0:
err(f"calc/{name} exits {proc.returncode}: {proc.stderr.strip()[-200:]}")
except subprocess.TimeoutExpired:
err(f"calc/{name} runs longer than 5 minutes")
res = os.path.join(calc, name[:-3] + ".results.json")
data = tlib.load_json(res)
if data is None:
warn(f"calc/{name} has no readable {name[:-3]}.results.json (run it)")
elif not isinstance(data, dict) or any(not (isinstance(v, dict) and "value" in v and "unit" in v)
for v in data.values()):
warn(f"calc/{name[:-3]}.results.json entries need {{value, unit}}")
note(f"calc/: {len(scripts)} script(s)")
def check_identity(folder, team, warn):
"""The team id or a school name in the other files the judges receive (blind.py masks what it can)."""
pat = re.compile(r"(?<![A-Za-z0-9])%s(?![0-9])|\b(?:%s)\b" % (re.escape(team), "|".join(tlib.PHILOSOPHIES)))
hits = []
for root, dirs, files in os.walk(folder):
dirs[:] = [d for d in dirs if d != "__pycache__"]
rel_root = os.path.relpath(root, folder)
for name in files:
rel = os.path.normpath(os.path.join(rel_root, name))
if rel == "dossier.md" or not (rel in ("estimates.json", "compliance.csv") or rel.startswith("calc" + os.sep)):
continue
if pat.search(name) or (name.endswith((".py", ".json", ".csv", ".md", ".txt"))
and pat.search(tlib.read_text(os.path.join(root, name)))):
hits.append(rel)
if hits:
warn(f"team id or school named outside the SCHOOL block in {', '.join(hits[:5])} - remove it (judges are blind)")
def init_team(run, team, folder):
os.makedirs(os.path.join(folder, "calc"), exist_ok=True)
made = []
path = os.path.join(folder, "dossier.md")
if not os.path.exists(path):
tpl = tlib.read_text(os.path.join(run, "method", "templates", "dossier.md")).replace("Team: T?", f"Team: {team}", 1)
tpl = re.sub(r"\nWrite every section below.*?Delete these instruction lines\.\n", "\n", tpl, flags=re.S)
tlib.write_text(path, tpl.split("\n---\nFiles next to this dossier")[0].rstrip() + "\n")
made.append("dossier.md")
path = os.path.join(folder, "estimates.json")
if not os.path.exists(path):
tlib.dump_json(path, {"principle": "", "key_figures": {k: None for k in KF_KEYS}, "parameters": [], "cost": None})
made.append("estimates.json")
path = os.path.join(folder, "compliance.csv")
if not os.path.exists(path):
tlib.write_csv(path, tlib.COMPLIANCE_HEADER, [{"req_id": r["req_id"], "status": "not_addressed"}
for r in tlib.load_reqs(run)])
made.append("compliance.csv")
print(f"init {team}: created {', '.join(made) or 'nothing (files exist)'} - fill them in place")
def check_team(run, team, run_scripts=False, folder=None):
"""(errors, warnings, notes) for one team folder (default work/teams/<team>/)."""
folder = folder or os.path.join(run, "work", "teams", team)
errors, warnings, notes = [], [], []
if not os.path.isdir(folder):
return [f"{folder} does not exist"], warnings, notes
ids = [r["req_id"] for r in tlib.load_reqs(run)]
check_dossier(run, folder, team, errors.append, warnings.append, notes.append)
check_estimates(folder, errors.append, warnings.append)
check_calc(folder, run_scripts, errors.append, warnings.append, notes.append) # first: --run writes results
check_compliance(folder, ids, errors.append, warnings.append)
check_identity(folder, team, warnings.append)
return errors, warnings, notes
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--team", required=True)
ap.add_argument("--run-dir", default=".")
ap.add_argument("--run", action="store_true", help="re-run every calc script (5 min limit each)")
ap.add_argument("--init", action="store_true", help="create the missing skeleton files first")
args = ap.parse_args()
if args.init:
init_team(args.run_dir, args.team, os.path.join(args.run_dir, "work", "teams", args.team))
errors, warnings, notes = check_team(args.run_dir, args.team, args.run)
for kind, msgs in (("NOTE ", notes), ("WARN ", warnings), ("ERROR", errors)):
for msg in msgs:
print(f"{kind} {msg}")
print(f"dossier_check {args.team}: errors={len(errors)} warnings={len(warnings)} -> "
f"{'PASS' if not errors else 'FAIL'}")
return 0 if not errors else 1
if __name__ == "__main__":
sys.exit(main())
files/method/gates/req_index.py (56 wierszy)
#!/usr/bin/env python3
"""req_index.py - index of the requirement ids and weights (tournament method).
Usage (from the run directory): python3 method/gates/req_index.py [--out work/packet/req-index.csv]
Reads INPUT/requirements.md and writes one row per requirement id:
req_id,title,weight,weight_origin,metric,target,threshold,verification,section
Weights come from the sheet's priority/weight fields; a missing weight becomes the median of the others
(weight_origin = default) - check and correct those rows by hand. Standard library only.
"""
import argparse
import os
import statistics
import sys
import tlib
HEADER = ["req_id", "title", "weight", "weight_origin", "metric", "target", "threshold", "verification", "section"]
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--run-dir", default=".")
ap.add_argument("--out", default=os.path.join("work", "packet", "req-index.csv"))
args = ap.parse_args()
src = os.path.join(args.run_dir, "INPUT", "requirements.md")
reqs = tlib.parse_requirements(tlib.read_text(src))
if not reqs:
print(f"ERROR no requirement ids found in {src}")
return 1
found = [r["weight"] for r in reqs if r["weight"] is not None]
default = statistics.median(found) if found else 3.0
rows = []
for r in reqs:
origin = "input" if r["weight"] is not None else "default"
weight = r["weight"] if r["weight"] is not None else default
rows.append(dict(r, weight=f"{weight:g}", weight_origin=origin))
out = os.path.join(args.run_dir, args.out)
tlib.write_csv(out, HEADER, rows)
weights = sorted({float(r["weight"]) for r in rows}, reverse=True)
top = [r["req_id"] for r in rows if float(r["weight"]) == weights[0]]
print(f"req_index: {len(rows)} ids -> {args.out}")
print("weights: " + ", ".join(f"{w:g} x{sum(1 for r in rows if float(r['weight']) == w)}" for w in weights))
print(f"top-weighted ({weights[0]:g}): {', '.join(top)}")
defaults = [r["req_id"] for r in rows if r["weight_origin"] == "default"]
if defaults:
print(f"WARN {len(defaults)} id(s) without a weight got {default:g}: {', '.join(defaults)}")
no_target = [r["req_id"] for r in rows if not r["target"] and not r["threshold"]]
if no_target:
print(f"NOTE {len(no_target)} id(s) without a parsed target/threshold (read them in INPUT): "
f"{', '.join(no_target[:12])}")
return 0
if __name__ == "__main__":
sys.exit(main())
files/method/gates/tally.py (365 wierszy)
#!/usr/bin/env python3
"""tally.py - aggregate the blind judge panel (tournament method; rule: method/POLICY.md section 4).
Usage (from the run directory):
python3 method/gates/tally.py --check-judge J2 format check of one judge's verdict/ files
python3 method/gates/tally.py [--judges J1,J2,J3] [--alpha 0.5] [--final] -> work/tournament/tally.json, tally.md
python3 method/gates/tally.py --claims-only fallback when no judge delivered usable verdicts
Per judge and pair: each presentation order gives winner 1, loser 0, tie 0.5; the pair scores the mean of both
orders. B = share of pairwise points, C = mean weighted predicted compliance, S = alpha*B + (1-alpha)*C.
Prints RECOMMENDED T<n>, or TIEBREAK (no Condorcet winner or S gap < 0.03) until run with --final. Also writes
work/tournament/observations-by-team.md (every judge's observations regrouped per team, labels resolved).
--claims-only ranks the dossiers that pass dossier_check by their weight-averaged CLAIMED compliance (marked
"not judged"). Claims are read from the judged snapshot (work/tournament/judged/) when it exists.
"""
import argparse
import itertools
import os
import re
import sys
import tlib
PAIR_HEADER = ["order", "first", "second", "winner", "decisive_ids", "reason"]
COMP_HEADER = ["dossier", "req_id", "predicted", "note"]
CLOSE = 0.03
def load_verdict(run, judge, labels, ids):
vdir = os.path.join(run, "work", "judging", judge, "verdict")
errs, warns, pairs, comp, raw = [], [], {}, {}, []
header, rows = tlib.read_csv(os.path.join(vdir, "pairs.csv"))
if not header:
errs.append(f"{judge}: verdict/pairs.csv missing or empty")
elif header[:4] != PAIR_HEADER[:4]:
errs.append(f"{judge}: pairs.csv header {header}, expected {','.join(PAIR_HEADER)}")
else:
for n, r in enumerate(rows, start=2):
first, second, winner = r["first"].upper(), r["second"].upper(), r["winner"].strip()
winner = "tie" if winner.lower() == "tie" else winner.upper()
if first not in labels or second not in labels or first == second:
errs.append(f"{judge}: pairs.csv line {n}: labels must be two different of {sorted(labels)}")
continue
if winner not in (first, second, "tie"):
errs.append(f"{judge}: pairs.csv line {n}: winner '{r['winner']}' must be {first}, {second} or tie")
continue
pairs[(first, second)] = winner
raw.append(dict(r, first=first, second=second, winner=winner))
for a, b in itertools.combinations(sorted(labels), 2):
for d in ((a, b), (b, a)):
if d not in pairs:
errs.append(f"{judge}: pairs.csv lacks the duel first={d[0]} second={d[1]}")
header, rows = tlib.read_csv(os.path.join(vdir, "compliance.csv"))
if not header:
errs.append(f"{judge}: verdict/compliance.csv missing or empty")
elif header[:3] != COMP_HEADER[:3]:
errs.append(f"{judge}: compliance.csv header {header}, expected {','.join(COMP_HEADER)}")
else:
for n, r in enumerate(rows, start=2):
lab, rid, pred = r["dossier"].upper(), r["req_id"], r["predicted"].lower()
if lab not in labels or pred not in tlib.PRED:
errs.append(f"{judge}: compliance.csv line {n}: dossier in {sorted(labels)}, predicted in {list(tlib.PRED)}")
continue
comp[(lab, rid)] = pred
missing = [(lab, i) for lab in sorted(labels) for i in ids if (lab, i) not in comp]
if missing:
errs.append(f"{judge}: compliance.csv lacks {len(missing)} dossier x id rows, e.g. {missing[:4]}")
unchecked = sum(1 for r in rows if r.get("note", "").strip() == "claim; check")
if unchecked:
warns.append(f"{judge}: {unchecked} focus row(s) still 'claim; check' - verify them and replace the note")
if not os.path.isfile(os.path.join(vdir, "observations.md")):
warns.append(f"{judge}: verdict/observations.md missing (graft candidates and fatal flaws)")
return {"errors": errs, "warnings": warns, "pairs": pairs, "comp": comp, "raw": raw}
def regroup_observations(run, bmap, sch):
"""work/tournament/observations-by-team.md: each judge's observations under the team they concern."""
by_team = {}
for j, mapping in sorted(bmap.get("judges", {}).items()):
text = tlib.read_text(os.path.join(run, "work", "judging", j, "verdict", "observations.md"))
parts = re.split(r"(?m)^##\s+(X\d+)\b[^\n]*\n", text)
for k in range(1, len(parts) - 1, 2):
body = re.sub(r"\bX\d+\b", lambda m: f"{m.group(0)} ({mapping.get(m.group(0), '?')})", parts[k + 1].strip())
by_team.setdefault(mapping.get(parts[k].upper(), "?"), []).append((j, parts[k], body))
out = ["# Judges' observations by team", "", "Regrouped by method/gates/tally.py from work/judging/J<k>/verdict/"
"observations.md; every X label is followed by the team it stood for in that judge's key.", ""]
for t in sorted(by_team, key=lambda t: int(t[1:]) if t[1:].isdigit() else 99):
out += [f"## {t} - {sch.get(t, {}).get('philosophy', '')}", ""]
for j, lab, body in by_team[t]:
out += [f"### {j} (read it as {lab})", "", body or "(empty)", ""]
tlib.write_text(os.path.join(run, "work", "tournament", "observations-by-team.md"), "\n".join(out))
def claims_only(run, bmap, reqs, sch):
"""Fallback without a usable judge: rank by weight-averaged claimed compliance among dossier_check passes."""
import dossier_check
weights = {r["req_id"]: float(r["weight"]) for r in reqs}
total = sum(weights.values()) or 1.0
teams = (bmap or {}).get("teams") or [t for t in tlib.teams_present(run)
if os.path.isfile(os.path.join(run, "work", "teams", t, "dossier.md"))]
if not teams:
print("ERROR no team with a dossier")
return 1
info = {}
for t in teams:
folder = tlib.team_source(run, t)
errs = dossier_check.check_team(run, t, folder=folder)[0]
_h, rows = tlib.read_csv(os.path.join(folder, "compliance.csv"))
claim = {r.get("req_id"): r.get("status") for r in rows}
info[t] = {"passes": not errs, "errors": len(errs),
"C": sum(w * tlib.SCORE.get(claim.get(i), 0.0) for i, w in weights.items()) / total}
order = sorted(teams, key=lambda t: (not info[t]["passes"], -info[t]["C"], int(t[1:])))
note = ("NOT JUDGED: no judge delivered usable verdicts; ranked by weight-averaged CLAIMED compliance among the "
"dossiers that pass dossier_check (the teams' own claims, not a panel result)")
res = {"judges": [], "claims_only": True, "alpha": None, "final": True, "condorcet": None, "leader": order[0],
"gap": round(info[order[0]]["C"] - info[order[1]]["C"], 4) if len(order) > 1 else 1.0,
"tiebreak_needed": False, "recommended": order[0], "ranking": order, "kendall_w": None,
"pair_agreement": None, "consistency": {}, "sensitivity": {"trials": 0, "changes": []},
"head_to_head": {}, "panel": {}, "notes": [note], "teams": {}}
md = ["# Tournament tally - NOT JUDGED", "", note + ". CALCULATION by method/gates/tally.py --claims-only.", "",
"| rank | team | school | dossier_check | claimed C |", "|---|---|---|---|---|"]
for k, t in enumerate(order, start=1):
c = round(info[t]["C"], 4)
res["teams"][t] = {"philosophy": sch.get(t, {}).get("philosophy", ""),
"principle": sch.get(t, {}).get("principle", ""), "pairwise_points": {}, "B": 0.0,
"C_by_judge": {}, "C": c, "S": c, "knockout_ids": [], "rank": k,
"dossier_check": "PASS" if info[t]["passes"] else f"FAIL ({info[t]['errors']} errors)"}
md.append(f"| {k} | {t} | {res['teams'][t]['philosophy'] or '-'} | {res['teams'][t]['dossier_check']} | {c:.3f} |")
md += ["", f"Recommended (not judged): **{order[0]}**.", "", "<!-- DETAIL -->", ""]
tlib.dump_json(os.path.join(run, "work", "tournament", "tally.json"), res)
tlib.write_text(os.path.join(run, "work", "tournament", "tally.md"), "\n".join(md))
print(f"ranking (claims only): {' > '.join(order)}")
print(f"RECOMMENDED {order[0]} (not judged: claims only - say so in decision.md)")
return 0
def avg_ranks(points):
order = sorted(points, key=lambda t: -points[t])
ranks, i = {}, 0
while i < len(order):
j = i
while j + 1 < len(order) and points[order[j + 1]] == points[order[i]]:
j += 1
for k in range(i, j + 1):
ranks[order[k]] = (i + j) / 2 + 1
i = j + 1
return ranks
def score(teams, judges, per, weights, alpha):
n = len(teams)
B = {t: sum(per[j]["pts"][t] for j in judges) / (len(judges) * max(n - 1, 1)) for t in teams}
total_w = sum(weights.values()) or 1.0
Cj = {j: {t: sum(w * tlib.SCORE.get(per[j]["pred"][t].get(i, "unknown"), 0.0) for i, w in weights.items())
/ total_w for t in teams} for j in judges}
C = {t: sum(Cj[j][t] for j in judges) / len(judges) for t in teams}
S = {t: alpha * B[t] + (1 - alpha) * C[t] for t in teams}
return B, Cj, C, S
def rank(cands, S, C, B):
return sorted(cands, key=lambda t: (-round(S[t], 9), -C[t], -B[t], int(t[1:])))
def main():
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument("--judges", help="comma list (default: every judge in blind-map.json with a verdict)")
ap.add_argument("--alpha", type=float, default=0.5, help="weight of the pairwise (Borda) share in S")
ap.add_argument("--final", action="store_true", help="tie-break judge already included: no further TIEBREAK")
ap.add_argument("--check-judge", help="validate one judge's verdict files and exit")
ap.add_argument("--claims-only", action="store_true", help="no usable judge: rank by claimed compliance")
ap.add_argument("--run-dir", default=".")
args = ap.parse_args()
run = args.run_dir
bmap = tlib.load_json(os.path.join(run, "work", "tournament", "blind-map.json"))
if args.claims_only:
return claims_only(run, bmap, tlib.load_reqs(run), tlib.schools(run))
if not bmap:
print("ERROR work/tournament/blind-map.json missing (run blind.py first)")
return 1
reqs = tlib.load_reqs(run)
ids = [r["req_id"] for r in reqs]
weights = {r["req_id"]: float(r["weight"]) for r in reqs}
if args.check_judge:
mapping = bmap["judges"].get(args.check_judge)
if not mapping:
print(f"ERROR no judge {args.check_judge} in blind-map.json")
return 1
v = load_verdict(run, args.check_judge, set(mapping), ids)
for m in v["warnings"]:
print("WARN " + m)
for m in v["errors"]:
print("ERROR " + m)
print(f"check-judge {args.check_judge}: errors={len(v['errors'])} -> {'PASS' if not v['errors'] else 'FAIL'}")
return 0 if not v["errors"] else 1
names = args.judges.split(",") if args.judges else sorted(bmap["judges"])
teams = sorted(bmap["teams"], key=lambda t: int(t[1:]))
sch = tlib.schools(run)
regroup_observations(run, bmap, sch)
per, notes = {}, []
for j in names:
mapping = bmap["judges"].get(j)
if not mapping:
notes.append(f"{j}: not in blind-map.json - skipped")
continue
v = load_verdict(run, j, set(mapping), ids)
if not v["pairs"]:
notes.append(f"{j}: no usable pairwise verdicts - excluded ({'; '.join(v['errors'][:2])})")
continue
notes += [f"{j}: {m}" if not m.startswith(j) else m for m in v["errors"][:3]]
notes += [m for m in v["warnings"] if "claim; check" in m]
t2l = {t: lab for lab, t in mapping.items()}
pts, pair_pts, consistent, both = {t: 0.0 for t in teams}, {}, 0, 0
for a, b in itertools.combinations(teams, 2):
la, lb = t2l[a], t2l[b]
got = [1.0 if v["pairs"][d] == la else 0.0 if v["pairs"][d] == lb else 0.5
for d in ((la, lb), (lb, la)) if d in v["pairs"]]
p = sum(got) / len(got) if got else 0.5
if len(got) == 2:
both += 1
consistent += got[0] == got[1]
pair_pts[(a, b)] = p
pts[a] += p
pts[b] += 1 - p
pred = {t: {i: v["comp"].get((t2l[t], i), "unknown") for i in ids} for t in teams}
per[j] = {"pts": pts, "pair": pair_pts, "pred": pred, "consistency": [consistent, both],
"raw": [dict(r, first_team=mapping[r["first"]], second_team=mapping[r["second"]],
winner_team=mapping.get(r["winner"], "tie")) for r in v["raw"]]}
judges = list(per)
if not judges:
print("ERROR no judge with usable verdicts - start J4 (section 8 of the main prompt) or, past the cutoff, "
"run tally.py --claims-only")
return 1
B, Cj, C, S = score(teams, judges, per, weights, args.alpha)
top_w = max(weights.values())
ko = {t: [i for i in ids if weights[i] == top_w
and sum(per[j]["pred"][t][i] == "not_met" for j in judges) * 2 > len(judges)] for t in teams}
cands = [t for t in teams if not ko[t]] or list(teams)
M = {a: {b: sum(per[j]["pair"][(a, b)] if (a, b) in per[j]["pair"] else 1 - per[j]["pair"][(b, a)]
for j in judges) for b in teams if b != a} for a in teams}
condorcet = next((a for a in cands if all(M[a][b] > M[b][a] for b in cands if b != a)), None)
cands_rank = rank(cands, S, C, B)
order = cands_rank + rank([t for t in teams if t not in cands], S, C, B)
leader = order[0]
gap = S[order[0]] - S[order[1]] if len(order) > 1 else 1.0
tiebreak = len(cands) > 1 and (condorcet is None or S[cands_rank[0]] - S[cands_rank[1]] < CLOSE) \
and not args.final
# agreement between judges
m, n = len(judges), len(teams)
kendall = None
if m >= 2 and n >= 2:
ranks = {j: avg_ranks(per[j]["pts"]) for j in judges}
R = {t: sum(ranks[j][t] for j in judges) for t in teams}
mean = m * (n + 1) / 2
kendall = 12 * sum((R[t] - mean) ** 2 for t in teams) / (m * m * (n ** 3 - n))
agree = total = 0
for j1, j2 in itertools.combinations(judges, 2):
for pair in per[j1]["pair"]:
s1, s2 = per[j1]["pair"][pair] - 0.5, per[j2]["pair"][pair] - 0.5
total += 1
agree += (s1 > 0) == (s2 > 0) and (s1 < 0) == (s2 < 0)
# sensitivity of the leader
trials = [("alpha=0.3", 0.3, weights, judges), ("alpha=0.7", 0.7, weights, judges)]
for level in sorted(set(weights.values())):
for f in (0.8, 1.2):
w2 = {i: w * f if w == level else w for i, w in weights.items()}
trials.append((f"weights {level:g} x{f}", args.alpha, w2, judges))
if m >= 3:
trials += [(f"without {j}", args.alpha, weights, [k for k in judges if k != j]) for j in judges]
changes = []
for label, a, w2, js in trials:
_b, _cj, c2, s2 = score(teams, js, per, w2, a)
top = rank(cands, s2, c2, _b)[0]
if top != leader:
changes.append(f"{label} -> {top}")
claims = {}
for t in teams:
_h, rows = tlib.read_csv(os.path.join(tlib.team_source(run, t), "compliance.csv"))
claims[t] = {r.get("req_id"): r.get("status", "") for r in rows}
panel = {i: {t: tlib.panel([per[j]["pred"][t][i] for j in judges]) for t in teams} for i in ids}
result = {"judges": judges, "alpha": args.alpha, "final": args.final, "teams": {}, "condorcet": condorcet,
"leader": leader, "gap": round(gap, 4), "tiebreak_needed": tiebreak,
"recommended": None if tiebreak else leader, "ranking": order,
"kendall_w": None if kendall is None else round(kendall, 3),
"pair_agreement": round(agree / total, 3) if total else None,
"consistency": {j: per[j]["consistency"] for j in judges},
"sensitivity": {"trials": len(trials), "changes": changes}, "head_to_head": M,
"panel": panel, "notes": notes}
for t in teams:
result["teams"][t] = {"philosophy": sch.get(t, {}).get("philosophy", ""),
"principle": sch.get(t, {}).get("principle", ""),
"pairwise_points": {j: round(per[j]["pts"][t], 2) for j in judges},
"B": round(B[t], 4), "C_by_judge": {j: round(Cj[j][t], 4) for j in judges},
"C": round(C[t], 4), "S": round(S[t], 4), "knockout_ids": ko[t],
"rank": order.index(t) + 1}
tlib.dump_json(os.path.join(run, "work", "tournament", "tally.json"), result)
tlib.write_text(os.path.join(run, "work", "tournament", "tally.md"),
render(result, teams, judges, per, ids, weights, claims))
for msg in notes:
print("NOTE " + msg)
print(f"ranking: {' > '.join(order)}; leader {leader} S={S[leader]:.3f} gap {gap:.3f}; Condorcet "
f"{condorcet or 'none'}; Kendall W {result['kendall_w']}; leader holds in "
f"{len(trials) - len(changes)}/{len(trials)} perturbations")
if tiebreak:
print("TIEBREAK: " + ("no Condorcet winner" if condorcet is None else f"close call (S gap {gap:.3f})") +
" - python3 method/gates/blind.py --judges J4 --append; start J4 (general lens); then "
"python3 method/gates/tally.py --judges " + ",".join(judges + ["J4"]) + " --final")
else:
print(f"RECOMMENDED {leader}")
return 0
def render(res, teams, judges, per, ids, weights, claims):
T = res["teams"]
lines = ["# Tournament tally", "",
f"Judges: {', '.join(judges)}; alpha (pairwise share of S) = {res['alpha']}; teams: {len(teams)}; "
"weights: the requirement priorities of INPUT/requirements.md. S = alpha*B + (1-alpha)*C. CALCULATION by "
"method/gates/tally.py.",
"", "| rank | team | school | pairwise points (" + "/".join(judges) + ") | B | C (" + "/".join(judges) +
") | C | S | knock-out ids |", "|---|---|---|---|---|---|---|---|---|"]
for t in res["ranking"]:
d = T[t]
pts = " / ".join("%g" % d["pairwise_points"][j] for j in judges)
cbj = " / ".join("%.3f" % d["C_by_judge"][j] for j in judges)
kos = ", ".join(d["knockout_ids"]) or "-"
lines.append(f"| {d['rank']} | {t} | {d['philosophy'] or '-'} | {pts} | {d['B']:.3f} | {cbj} | "
f"{d['C']:.3f} | {d['S']:.3f} | {kos} |")
kos = [t for t in teams if T[t]["knockout_ids"]]
lines += ["", f"Condorcet winner: {res['condorcet'] or 'none'}. Leader: {res['leader']} "
f"(S gap to the next {res['gap']:.3f}). Knocked out: {', '.join(kos) or 'none'}. "
+ (f"Recommended: **{res['recommended']}**." if res["recommended"] else "TIEBREAK needed."), "",
"Head-to-head (pairwise points summed over judges; row against column):", "",
"| | " + " | ".join(teams) + " |", "|---" * (len(teams) + 1) + "|"]
for a in teams:
lines.append(f"| {a} | " + " | ".join("-" if a == b else f"{res['head_to_head'][a][b]:g}" for b in teams) + " |")
cons = ", ".join(f"{j} {c[0]}/{c[1]}" for j, c in res["consistency"].items())
lines += ["", f"Order consistency (same verdict in both presentation orders): {cons}. "
f"Kendall's W between judges: {res['kendall_w']}. Pairwise agreement between judges: "
f"{res['pair_agreement']}.", "",
f"Sensitivity: the leader holds in {res['sensitivity']['trials'] - len(res['sensitivity']['changes'])}"
f" of {res['sensitivity']['trials']} perturbations (alpha 0.3/0.7, each weight level x0.8/x1.2, "
f"leave one judge out)" + (": changes under " + "; ".join(res["sensitivity"]["changes"])
if res["sensitivity"]["changes"] else ".")]
if res["notes"]:
lines += ["", "Notes: " + "; ".join(res["notes"])]
lines += ["", "<!-- DETAIL -->", "", "## Predicted compliance per requirement",
"", "Panel = lower median of the judges' definite predictions (unknown ignored; unknown only when no "
"judge was definite); the team's own claim, as judged, in brackets.", "",
"| req_id | weight | " + " | ".join(teams) + " |", "|---" * (len(teams) + 2) + "|"]
for i in ids:
lines.append(f"| {i} | {weights[i]:g} | " + " | ".join(
f"{res['panel'][i][t]} ({claims[t].get(i, '-') or '-'})" for t in teams) + " |")
lines += ["", "## Pairwise verdicts in both presentation orders", "",
"| judge | first | second | winner | decisive ids | reason |", "|---|---|---|---|---|---|"]
for j in judges:
for r in per[j]["raw"]:
reason = r.get("reason", "").replace("|", "/")
lines.append(f"| {j} | {r['first']}={r['first_team']} | {r['second']}={r['second_team']} | "
f"{r['winner_team']} | {r.get('decisive_ids', '').replace('|', '/')} | {reason} |")
return "\n".join(lines) + "\n"
if __name__ == "__main__":
sys.exit(main())
files/method/gates/tlib.py (246 wierszy)
"""tlib.py - shared helpers of the tournament gate scripts (standard library only).
Imported by req_index.py, dossier_check.py, blind.py, tally.py and assemble.py (same folder).
Holds the one definition of the status words and of the panel prediction used everywhere.
"""
import csv
import io
import json
import os
import re
import shutil
import sys
ID_RE = re.compile(r"\b([A-Z][A-Z0-9]{1,7}-[A-Z0-9]{1,7}-\d{1,4})\b")
LOOSE_ID_RE = re.compile(r"\b([A-Z][A-Z0-9]{1,7}-[A-Z]{2,7}-\d{2,4})\b")
HEAD_RE = re.compile(r"^(#{1,6})\s+(.*)$")
KV_RE = re.compile(r"(?i)\b(metric|target|threshold|checked by|verified by|verification|priority|weight|importance)"
r"\s*:\s*([^·|]+)")
TEAM_RE = re.compile(r"^T\d{1,2}$")
SECTION_RE = re.compile(r"^##\s+(\d{1,2})\.\s*(.*)$", re.M)
SCHOOL_BLOCK_RE = re.compile(r"<!--\s*SCHOOL:BEGIN.*?SCHOOL:END\s*-->", re.S)
PRED = ("met", "partly", "not_met", "unknown") # judge predictions
CONTRACT_STATUS = ("met", "partly", "not_met", "not_addressed") # compliance.csv (RUN CONTRACT)
SCORE = {"met": 1.0, "partly": 0.5, "not_met": 0.0} # unknown / not_addressed earn nothing
FROM_SCORE = {1.0: "met", 0.5: "partly", 0.0: "not_met"}
PHILOSOPHIES = ("MINIMAL", "PERFORMANCE", "ROBUST", "WILDCARD")
COMPLIANCE_HEADER = ["req_id", "status", "value", "unit", "evidence", "note"]
WORD_WEIGHT = {"essential": 5, "critical": 5, "must": 5, "high": 4, "medium": 3, "should": 3, "low": 2,
"could": 1, "nice": 1}
def toolchain_python():
"""The toolchain Python (ddpy) that calculation scripts run with; this interpreter as a last resort."""
for cand in (shutil.which("ddpy"), "/opt/dd/venv/bin/python"):
if cand and os.path.exists(cand):
return cand
return sys.executable
def read_text(path, default=""):
try:
with open(path, encoding="utf-8", errors="replace") as fh:
return fh.read()
except OSError:
return default
def write_text(path, text):
folder = os.path.dirname(path)
if folder:
os.makedirs(folder, exist_ok=True)
with open(path, "w", encoding="utf-8") as fh:
fh.write(text)
def load_json(path, default=None):
try:
with open(path, encoding="utf-8") as fh:
return json.load(fh)
except (OSError, ValueError):
return default
def dump_json(path, data):
write_text(path, json.dumps(data, indent=2, ensure_ascii=False) + "\n")
def read_csv(path):
"""(header, rows as dicts). Missing file -> ([], []). Extra unquoted commas are joined into the last column."""
text = read_text(path, None)
if text is None:
return [], []
rows = [r for r in csv.reader(io.StringIO(text.lstrip(""))) if any(c.strip() for c in r)]
if not rows:
return [], []
header = [h.strip() for h in rows[0]]
out = []
for r in rows[1:]:
r = [c.strip() for c in r]
if len(r) > len(header):
r = r[:len(header) - 1] + [",".join(r[len(header) - 1:])]
r += [""] * (len(header) - len(r))
out.append(dict(zip(header, r)))
return header, out
def write_csv(path, header, rows):
buf = io.StringIO()
writer = csv.writer(buf, lineterminator="\n")
writer.writerow(header)
for row in rows:
writer.writerow([row.get(h, "") for h in header])
write_text(path, buf.getvalue())
def parse_weight(text):
text = (text or "").strip().lower()
m = re.match(r"([0-9]+(?:[.,][0-9]+)?)", text)
if m:
return float(m.group(1).replace(",", "."))
for word, w in WORD_WEIGHT.items():
if word in text:
return float(w)
return None
def parse_requirements(text):
"""Requirement entries of INPUT/requirements.md: one per heading that starts with an id."""
reqs, cur, section = [], None, ""
for raw in text.splitlines():
line = raw.strip()
head = HEAD_RE.match(line)
if head:
level, title = len(head.group(1)), head.group(2).strip()
idm = ID_RE.match(title)
if idm:
cur = {"req_id": idm.group(1), "title": title[idm.end():].strip(" -—–:·"),
"weight": None, "metric": "", "target": "", "threshold": "", "verification": "",
"section": section, "_level": level}
reqs.append(cur)
continue
if cur is None or level <= cur["_level"]:
cur = None
section = title
continue
if cur is None:
continue
for key, val in KV_RE.findall(line):
key, val = key.lower(), val.strip().rstrip(".").strip()
if key in ("priority", "weight", "importance"):
if cur["weight"] is None:
cur["weight"] = parse_weight(val)
elif key in ("checked by", "verified by", "verification"):
cur["verification"] = cur["verification"] or val
elif not cur[key]:
cur[key] = val
if not reqs: # no id headings: fall back to loose id tokens
seen = []
for m in LOOSE_ID_RE.finditer(text):
if m.group(1) not in seen:
seen.append(m.group(1))
reqs = [{"req_id": i, "title": "", "weight": None, "metric": "", "target": "", "threshold": "",
"verification": "", "section": "", "_level": 0} for i in seen]
unique, ids = [], set()
for r in reqs:
if r["req_id"] not in ids:
ids.add(r["req_id"])
unique.append(r)
return unique
def load_reqs(run):
"""Requirement index rows (req_id, weight as float, ...). Prefers work/packet/req-index.csv."""
_h, rows = read_csv(os.path.join(run, "work", "packet", "req-index.csv"))
if rows:
for r in rows:
r["weight"] = parse_weight(r.get("weight")) or 3.0
return rows
reqs = parse_requirements(read_text(os.path.join(run, "INPUT", "requirements.md")))
for r in reqs:
r["weight"] = r["weight"] or 3.0
return reqs
def teams_present(run):
root = os.path.join(run, "work", "teams")
if not os.path.isdir(root):
return []
return sorted((d for d in os.listdir(root) if TEAM_RE.match(d) and os.path.isdir(os.path.join(root, d))),
key=lambda t: int(t[1:]))
def schools(run):
"""{team: {"philosophy": ..., "principle": ...}} from work/tournament/schools.json (may be empty)."""
data = load_json(os.path.join(run, "work", "tournament", "schools.json"), []) or []
out = {}
if isinstance(data, dict):
data = [dict(v, team=k) for k, v in data.items() if isinstance(v, dict)]
for item in data:
if isinstance(item, dict) and item.get("team"):
out[item["team"]] = {"philosophy": str(item.get("philosophy", "")).upper(),
"principle": str(item.get("principle", "")),
"differs_by": str(item.get("differs_by", ""))}
return out
def panel(preds):
"""Panel prediction from several judges' predictions: the lower median (conservative) of the definite ones,
'unknown' ignored; a single definite judge decides alone; 'unknown' only when no judge was definite."""
definite = sorted(SCORE[p] for p in preds if p in SCORE)
if not definite:
return "unknown"
return FROM_SCORE[definite[(len(definite) - 1) // 2]]
def lower(*statuses):
"""The worst of several met/partly/not_met statuses."""
return min(statuses, key=lambda s: SCORE[s])
def claim_to_pred(status):
"""A team's compliance claim as a judge's starting prediction (not_addressed or missing -> unknown)."""
status = (status or "").strip().lower()
return status if status in SCORE else "unknown"
def median_weight(reqs):
weights = sorted(float(r["weight"]) for r in reqs)
if not weights:
return 0.0
mid = len(weights) // 2
return weights[mid] if len(weights) % 2 else (weights[mid - 1] + weights[mid]) / 2
def team_source(run, team):
"""The version of a team's folder the judges saw (snapshot written by blind.py), else the live folder."""
snap = os.path.join(run, "work", "tournament", "judged", team)
return snap if os.path.isdir(snap) else os.path.join(run, "work", "teams", team)
def sections(markdown):
"""[(number, heading, start, end)] of the '## <n>. Heading' sections of a dossier."""
marks = list(SECTION_RE.finditer(markdown))
out = []
for i, m in enumerate(marks):
end = marks[i + 1].start() if i + 1 < len(marks) else len(markdown)
out.append((int(m.group(1)), m.group(2).strip(), m.start(), end))
return out
def strip_school_block(markdown):
return SCHOOL_BLOCK_RE.sub("", markdown)
def evidence_refs(field):
parts = re.split(r"[;|\n]+|\s+(?=[\w./-]+/)", field or "")
return [p.strip().strip("`'\"") for p in parts if p.strip()]
def ref_target(ref):
"""File part of an evidence reference (drops #anchor, ::name and :line suffixes)."""
ref = ref.split("#", 1)[0].split("::", 1)[0].strip()
m = re.match(r"^(.*?)(:\d+(-\d+)?)$", ref)
return m.group(1) if m else ref
files/method/roles/calculations.md (26 wierszy)
# Role: calculations — owns `deliverables/05-calculations/`
Handbook sections 4 and 6. Tools by purpose (commands in `INPUT/TOOLCHAIN.md`): the toolchain Python with
units and property libraries; FEM, CFD and circuit simulators only where a result changes a decision.
Round 1, in this order:
1. List the questions: every requirement id with a numeric metric that a calculation can predict, plus the
decisive numbers of the concept (`deliverables/02-concept/calc/`, `work/detail/architecture.md`). Redo
each concept calculation with the detailed parameters; do not copy concept results.
2. One script per question, from `method/templates/calc_template.py`: inputs at the top with origin labels,
shared inputs read from `work/detail/params.json`, a hand estimate next to the model, results written to
`<stem>.results.json` as `{"<name>": {"value": x, "unit": "..."}}`. Each runs as `ddpy <script>` from
`05-calculations/`, offline, in under five minutes.
3. Each result stated as value, requirement, margin and status in `05-calculations/index.md` (one table:
script, question, requirement id, value, limit, margin, status, what remains open — static is not
fatigue, steady is not transient).
4. A simulation only when the analytical result is within its uncertainty of a limit: known-answer case
first, then three mesh or step sizes with the trend, balance checks, and a sensitivity run on the least
certain inputs. Delete solver scratch you no longer need.
Round 2: update with the final parameters and geometry (mass and envelope from the CAD checks, power from the
electronics), re-run everything, and apply the fixes the director sends.
Done when: every script runs clean with `ddpy`, each has its results file, `index.md` is current, evidence
rows written.
files/method/roles/concept-owner.md (31 wierszy)
# Concept owner — the winning team at the full tier
You won the tournament; you hold the design intent of the concept through detailed design. You are continued
by the director's messages (SendMessage); each message says which step to do and its deadline. You may read
everything under `work/` and `deliverables/` now. Write only the files named below.
## Step 1 — architecture freeze (first message)
Write `work/detail/architecture.md`:
1. The concept in five lines and the decisive numbers with their homes (your `calc/` results).
2. Subsystems: each with function, make-or-buy, the owning discipline (mechanical-cad, calculations,
electronics-firmware, sourcing-cost, safety-docs-visuals) and the requirement ids it carries.
3. Interfaces: mechanical envelope and mounting, electrical rails and connectors, thermal paths, data and
control signals — each with the numbers both sides must respect.
4. Work packages per discipline in priority order, including the concept calculations that must be redone
in detail and the requirement ids each package must close.
5. Open questions with your default answer for each (disciplines proceed on the default).
Write `work/detail/params.json` — the single home of every number two or more disciplines share:
`{"key_figures": {<same shape as estimates.json key_figures>}, "params": {"<name>": {"value": x, "unit":
"...", "origin": "CALCULATION|SOURCE|ASSUMPTION|SIMULATION", "home": "<file or source>", "owner": "<discipline>",
"key": true}}}`. Mark `"key": true` on the parameters the report should show (at most 30).
## Step 2 — gate A defects
Apply the defects the director accepted (`work/reviews/A-triage.md`) to both files; answer each rejected one
only if you have new evidence. After this the director owns `params.json`.
## Step 3 — intent questions (any later message)
Answer from the concept's intent: a decision, the reason, the consequence for other disciplines, ≤ 150 words,
appended to `work/detail/intent.md` and given as your final message. The working principle is fixed: if a
question can only be answered by changing it, say so plainly with the evidence — never redesign silently.
files/method/roles/detail-common.md (34 wierszy)
# Rules for every discipline agent of the detail phase (full tier) You detail ONE discipline of the concept that won the tournament. The concept is decided: realise it well, do not reopen it. Read, in this order: `work/packet/boundaries.md`, `method/HYGIENE.md`, this file, your role file `method/roles/<role>.md`, `work/detail/architecture.md`, `work/detail/params.json`, `deliverables/02-concept/concept.md`, `deliverables/01-requirements/requirements.md`, the handbook sections your role file names (`.claude/skills/dd-hw-handbook/SKILL.md`) and the tool commands in `INPUT/TOOLCHAIN.md`. ## Write rights and shared numbers - Write only your role's deliverable folders (your role file names them) and `work/detail/<role>/`. - `work/detail/params.json` is the single home of shared numbers; only the director edits it. Read it; never copy a shared number into a document without naming params.json as its home. - Need a change to a shared number, an interface or another discipline's output? Append a request to `work/detail/requests.md`: `- [<role>] <what> | why (evidence) | the default I use meanwhile`. Never wait for an answer: continue on your stated default, mark what depends on it PROVISIONAL, and list it in your final message. Nobody answers design questions; you decide within your discipline and record it. - Never message other agents, and start no Oivo sessions, Workflows or other agents. Never create files named `REPORT*`, `SUMMARY*`, `FINDINGS*` or `ANALYSIS*`. ## Evidence for the compliance table Keep `work/detail/<role>/evidence.csv` current, header `req_id,status,value,unit,evidence,note`: one row for each requirement id your work verifies or predicts (status `met`, `partly`, `not_met`, `not_addressed`; evidence = paths relative to `deliverables/`, e.g. `05-calculations/thermal.results.json`). The director merges these rows; the worst status wins, so be exact. ## Time Your brief names a deadline (a clock time). Check `date` at each step. Write deliverables as soon as each part exists. At the deadline stop and finish with your final message even if work remains — you will be continued (SendMessage) for the next round with your context intact. ## Final message At most 150 words: what exists (paths), what was checked and how (commands, results), PROVISIONAL items and open requests, what remains, and `checks: PASS` or `checks: FAIL (<what>)`.
files/method/roles/electronics-firmware.md (28 wierszy)
# Role: electronics-firmware — owns `deliverables/06-electronics/` and `deliverables/07-firmware/` Handbook sections 9 and 10. Tools by purpose (commands and the pinned firmware platforms in `INPUT/TOOLCHAIN.md`): KiCad 9 command line (ERC, DRC, exports), the autorouter, the circuit simulator, the offline parts catalogue, PlatformIO with host tests. Read the examples it points to before writing your own. Round 1, in this order: 1. Block diagram and power budget over the full supply range and every operating mode, including standby (`06-electronics/power-budget.md`, numbers from scripts in `06-electronics/calc/` or from `05-calculations/`). 2. KiCad 9 project: schematic with real parts (manufacturer part numbers that exist at a distributor or in the offline catalogue), protections that apply (input fuse or current limit, reverse polarity, transients and ESD on external connectors, inrush, hardware thermal cut-off of hot parts, safe state on power loss), then a routed board where custom electronics is needed. ERC and DRC from the command line, reports saved in `06-electronics/` with names containing `erc` and `drc`; fix every error or justify each waiver in `06-electronics/waivers.md`. Fabrication outputs: Gerbers, drill, pick-and-place, board BOM. 3. Firmware in `07-firmware/` (`platformio.ini` at the root, pinned platform versions only): a state machine with explicit fault states and a safe default, watchdog, debounced inputs, pin map checked against the schematic, constants taken from `work/detail/params.json`. Host tests (`native`) for the logic and every interlock — write a failing test first. Build offline; never upload or flash. 4. Simulate an uncertain circuit behaviour (start-up, protection trip, filter) only after one known-answer test of the simulator. Round 2: DRC clean on the final board outline from the CAD envelope, board BOM handed to sourcing-cost (request in `work/detail/requests.md` with the file path), host tests green, fixes the director sends. Done when: ERC/DRC reports clean or waived, firmware builds offline and host tests pass, evidence rows written.
files/method/roles/gate-review.md (21 wierszy)
# Gate review by a losing team Your concept lost the tournament, so you know the alternatives and this product's traps better than anyone who only saw the winner. Now you review the winner's detailed design at a gate (A = architecture freeze, B = before release). The message names the gate, the objects to review and the deadline. Review from your school's perspective — it is why you are on the panel: - MINIMAL: part count, cost at 1/100/1000, assembly steps, anything that could be removed or bought. - PERFORMANCE: the top-weighted requirements — are the numbers real, are margins honest, what limits them. - ROBUST: safety, single faults, protections independent of firmware, reliability, certification, service. - WILDCARD: overlooked principles or parts, unconventional failure modes, misuse, missed opportunities. Rules: the tournament is over, so the isolation rules are lifted: read whatever the review needs. Read `method/HYGIENE.md` again if you no longer have it in mind. Re-run or redo at least one decisive calculation yourself and compare. Read-only for everything except your review file `work/reviews/<gate>-T<n>.md`, a numbered list, most severe first, at most 15 entries, each: `severity` (blocker / major / minor) · requirement id(s) · evidence (file path and the number, your calculation, or a dated source) · the smallest fix. No praise, no summary of the design, no restating. A defect without evidence is an opinion: leave it out. Final message: counts per severity and the top blocker in one line.
files/method/roles/mechanical-cad.md (27 wierszy)
# Role: mechanical-cad — owns `deliverables/03-cad/` and `deliverables/04-drawings/` Handbook sections 7 and 8. Tools by purpose (commands in `INPUT/TOOLCHAIN.md`): code CAD, the STEP checker (validity, volumes, bounding box, interference), the STEP-to-GLB converter, drawing export. Round 1, in this order: 1. One parametric script per designed part, parameters at the top and read from `work/detail/params.json` where shared; an assembly script that places named parts; purchased parts as simplified bodies with their datasheet envelope (labelled). First prove the route on a tiny part and keep that evidence. 2. Export `assembly.step` and one STEP per designed part into `03-cad/`; `parts.csv` (`part,file,material,density_kg_m3,qty`). Re-running the scripts must reproduce every STEP. 3. Check every part and the assembly with the STEP checker: valid solids, mass from volume × density, bounding box against the size requirements, zero interference (or an intended fit), clearances for tools and fingers, wall thickness and draft for the chosen process. Save the checker output in `03-cad/checks/`. Put the measured envelope and mass in your evidence rows and as a request for `params.json` key figures (`dimensions_mm`, `mass_kg`). 4. Process per part for the prototype and for 1000 units, and what changes between them (`03-cad/process.md`). 5. Export `11-renders/assembly.glb` from the assembly (the visuals role renders from it) and validate it. Round 2: drawings in `04-drawings/` — every manufactured part (views, overall and functional dimensions, general tolerance class plus explicit tolerances on functional features, material, finish, quantity, part number and revision matching `09-bom-cost/bom.csv`) and an assembly drawing with balloons matching the BOM item numbers; PDF or SVG. Render a PNG preview of each drawing and check it by parsing or measuring, not by a glance. Then apply the fixes the director sends. Done when: STEP files valid and interference-free, drawings open, evidence rows written.
files/method/roles/safety-docs-visuals.md (28 wierszy)
# Role: safety-docs-visuals — owns `deliverables/08-safety-certification/`, `deliverables/10-prototype-test-plan/` and `deliverables/11-renders/` (PNG renders; `assembly.glb` comes from mechanical-cad) Handbook sections 11, 13 and 14. Tools by purpose (`INPUT/TOOLCHAIN.md`): document conversion, headless Blender, the glTF validator. Never use generative image models to depict the product. Round 1, in this order: 1. Hazard analysis in the ISO 12100 manner (`08-safety-certification/hazards.md`): hazard → situation → harm → risk (severity × probability) → reduction (inherently safe design, protective measures, information for use) → residual risk; safety requirements with ids `DR-SAF-<nn>` traced to design features and to the protections that act without firmware. 2. Regulatory map with SOURCE for every item (`08-safety-certification/regulatory.md`): EU directives and regulations, the harmonised product-family standards found by research and the clauses that drive the design, FCC rules, the conformity route (self-declaration or notified body), the tests an accredited lab would run, a pre-compliance plan, rough cost and duration. You identify; you never certify. 3. Prototype and test plan (`10-prototype-test-plan/`): build plan of prototype 1 (how each part is made, assembly order, tools, checks after each step), bring-up for a person later (current-limited or isolated first power-up, what to measure before full power, precautions), and one test per requirement id and per safety requirement: method, equipment, conditions, pass criterion, the id it closes. Add a coverage line per id to your evidence rows. Round 2: renders from `11-renders/assembly.glb` (the real CAD) with Blender in background mode — a product view, an exploded view, a view of the user interface — scale checked against a known dimension, labelled as renders of a digital design; check what can be measured (file exists, resolution, object fills the frame, parts present by name), not by looking. Then update the safety documents to the final design and apply the fixes the director sends. Done when: hazards traced, every requirement id has a test, renders exist and pass the measurable checks.
files/method/roles/scout.md (38 wierszy)
# Scout — fact-finding for the tournament packet (concept tier) You collect facts that every concept team needs, once, so that four teams do not research the same things four times. You do not design and you do not recommend a solution. Read `work/packet/boundaries.md` and `method/HYGIENE.md` first, then `INPUT/brief.md` and `INPUT/requirements.md`. Your brief names your assignment (A or B) and your deadline (a clock time): check `date`, finish before it. Write only your one output file. Its first line is `STATUS: DRAFT` while you work (teams may already read it) and `STATUS: COMPLETE` when you finish. Every fact carries its URL and the date you read it; an entry you could not verify is marked `UNVERIFIED`; never fill a gap with a plausible guess. Read pages, do not guess them; if a site blocks automated reading, use another source. Never create files named `REPORT*`, `SUMMARY*`, `FINDINGS*` or `ANALYSIS*`. Start no Oivo sessions, Workflows or other agents. ## Assignment A — benchmark → `work/packet/benchmark.md` 1. First, within about four minutes of starting, a section `## Principles in use` right under the status line: every working principle or architecture you find in comparable and adjacent products, including unusual ones, each with one example product and its URL. The director chooses the tournament's schools from it a few minutes before your deadline, so write it before anything else and extend it as you go. 2. At least six comparable products, commercial and open-source; adjacent categories count. Table per product: name and maker, working principle or architecture, the specifications that matter for the requirement ids (name the ids), price with currency, date and URL. 3. Weak points users report (reviews, teardowns, forums, return reasons), with sources. 4. Synthesis (≤ 15 lines): the realistic range of each top-weighted metric; what nobody does well yet. ## Assignment B — anchors → `work/packet/anchors.md` 1. Regulatory starting points for this kind of product in the EU and the US: directives and regulations, the harmonised product-family standards likely to apply, FCC parts — each with a SOURCE URL and one line on why it applies. Mark what depends on the concept (radio or not, mains or not, battery or not). 2. Price anchors for components that any concept of this product will probably need (for example power supplies, controllers or radio modules, connectors, user-interface parts, enclosure materials): part, price at 1/100/1000 where shown, supplier, URL, date. Note how to query the offline parts catalogue named in `INPUT/TOOLCHAIN.md`. 3. Manufacturing cost anchors as ranges with sources: injection-mould tooling, sheet-metal and CNC parts, PCB fabrication and assembly, certification test costs, freight, crowdfunding platform and payment fees. ## Final message At most 60 words: what the file holds, how many sources, what you could not verify.
files/method/roles/sourcing-cost.md (26 wierszy)
# Role: sourcing-cost — owns `deliverables/09-bom-cost/` Handbook section 12. Tools by purpose (`INPUT/TOOLCHAIN.md`): the offline LCSC/JLC parts catalogue first, then read-only distributor pages. Never contact a supplier, never request a quote, never create an account. Round 1, in this order: 1. Critical parts first (from `work/detail/architecture.md` and `deliverables/02-concept/concept.md`): verify each candidate exists, is active and in stock, read price breaks at 1/100/1000 with the date, and find a second source. A price you could not read is an ASSUMPTION with a range, never dressed up as SOURCE. 2. `bom.csv` with exactly the RUN CONTRACT header (`item,qty,description,manufacturer,mpn,supplier,supplier_part,url,unit_price_1,unit_price_100,unit_price_1000,currency,notes`), one currency; mechanical parts at 1/100 as printed or machined, at 1000 as moulded or stamped with the tooling cost kept out of the unit price and amortised in `cost.json` `other`. 3. `cost.json` exactly as the RUN CONTRACT specifies (`bom` = the sum of `bom.csv` lines × qty; `other` = PCB fabrication and assembly, assembly and test labour, packaging, certification and other one-off costs amortised over the quantity with the assumption stated, freight, contingency; `unit_cost` = `bom` + all `other`), and `cost.md` with the roll-up table and the retail price logic (benchmark prices, margin, platform and payment fees, VAT, shipping to backers, returns and warranty — say plainly if it does not close). Request the resulting unit cost and retail price for `params.json` key figures. Round 2: merge the board BOM from electronics-firmware and the parts list `03-cad/parts.csv`, so every physical item is one BOM line; re-run the roll-up; check that `bom.csv` sums equal `cost.json` `bom` within 2 %; apply the fixes the director sends. Done when: every line has a real part or a labelled ASSUMPTION, sums match, cost evidence rows written.
files/method/templates/calc_template.py (42 wierszy)
#!/usr/bin/env python3
"""<The one question this script answers> - requirement id(s): <ID-...>.
Run from this folder: ddpy <this file> (offline, < 5 min). Writes <stem>.results.json as
{"<name>": {"value": x, "unit": "..."}}. Copy this file, rename it after the question, replace the example.
"""
import json
import os
import shutil
import sys
try:
import pint
except ImportError: # started with a Python that lacks the toolchain libraries: re-run under ddpy once
ddpy = shutil.which("ddpy")
if ddpy and not os.environ.get("DD_CALC_REEXEC"):
os.environ["DD_CALC_REEXEC"] = "1"
os.execv(ddpy, [ddpy] + sys.argv)
raise
u = pint.UnitRegistry()
# ---- Inputs: one per line, each with its origin label -------------------------------------------------------
# SOURCE: <url or document>, read <YYYY-MM-DD> CALCULATION: <script> ASSUMPTION: <reason; sensitivity>
power_in = 50.0 * u.W # ASSUMPTION: example value - replace
efficiency = 0.85 # ASSUMPTION: example value - replace
duration = 30.0 * u.min # ASSUMPTION: example value - replace
# ---- Hand estimate first (order of magnitude), then the model ------------------------------------------------
hand_estimate = 50 * 0.85 * 1800 * u.J # ~7.7e4 J
energy_out = (power_in * efficiency * duration).to(u.J)
assert 0.5 < (energy_out / hand_estimate).to("").magnitude < 2.0, "model and hand estimate disagree - find out why"
# ---- Results: value in the requirement's unit; margin = (value - limit) / limit --------------------------------
results = {
"energy_out": {"value": round(energy_out.to(u.kJ).magnitude, 3), "unit": "kJ"},
}
out = os.path.splitext(os.path.abspath(__file__))[0] + ".results.json"
with open(out, "w", encoding="utf-8") as fh:
json.dump(results, fh, indent=2)
print(json.dumps(results, indent=2))
files/method/templates/dossier.md (84 wierszy)
<!-- SCHOOL:BEGIN (removed before judging; the only place that names the team and the school) -->
Team: T? · Philosophy: ? · Working principle: ?
<!-- SCHOOL:END -->
# Concept dossier
Write every section below, with exactly these numbered headings, in this order. Requirement ids exactly as in
`INPUT/requirements.md`. Every number carries its origin label and its home (a `calc/<x>.results.json` key, a
dated source, or a labelled ASSUMPTION). Do not name your team or your philosophy outside the block above.
Delete these instruction lines.
## 1. Summary card
Judges and the final concept document quote this section verbatim, so it must stand alone (≤ 350 words):
- The product in one paragraph: what it is, for whom, what it does better than the benchmark.
- How it works: the working principle in 2–3 sentences and a one-line flow sketch (`input → … → output`).
- Table: the top-weighted requirement ids → predicted value, unit, origin, status (met / partly / not_met).
- Unit cost at 1 / 100 / 1000 and retail price, with currency.
- The three biggest risks, one line each.
## 2. Requirements and functions
How this concept reads the top-weighted requirements (verification conditions you designed to, ASSUMPTIONs);
the main functions as verb–noun pairs; the energy, material and signal flows.
## 3. Architecture
Working principle in detail; block diagram as a ```mermaid``` block; subsystems with make-or-buy; interfaces
between subsystems (mechanical envelope and mounting, electrical rails and connectors, thermal paths, data and
control). What this architecture makes easy and what it makes hard.
## 4. Key estimates
Table: name | value | unit | origin | home | requirement id. One line per number the concept rests on. For each
decisive number: the hand estimate next to the script result. Sensitivity: the three least certain inputs,
their range, and whether any predicted status changes within it.
## 5. Critical parts
Table: function | manufacturer | part number | supplier | URL | price @ qty (currency) | date read | second
source. Real, purchasable parts only; a part you could not verify is marked ASSUMPTION.
## 6. Safety concept
Top hazards (hazard → situation → harm), measures in the order inherently safe design, protective devices,
information for use; which protections act independently of firmware.
## 7. Compliance route
EU directives and harmonised standards, FCC rules, with SOURCE; conformity route; rough cost and time;
features of this concept that make conformity easier or harder.
## 8. Cost
Rough BOM of the major items; unit cost at 1, 100 and 1000 with the method (parts, fabrication, assembly and
test, packaging, amortised one-off costs, freight, contingency); retail price logic and margin.
## 9. Predicted compliance
Counts per status from `compliance.csv`, and every predicted `not_met` and `partly` with the reason. Honest
misses beat hidden ones: judges re-check every claim.
## 10. Risks
Table: risk | likelihood | impact | mitigation | the analysis or test that retires it.
## 11. Decisions and assumptions
Decisions taken without a human (taste, priorities, trade-offs) with the rejected options; the assumptions
register (assumption, reason, sensitivity).
## 12. Open issues for detailed design
What detailed design must do first, in order.
## 13. Grafts
Leave empty during the tournament. Filled only by the winning team when it integrates grafts: graft id, from
which concept, what changed, compatibility check, numbers that changed (old → new, with homes).
## Sources
Numbered list: URL or document — what was read — date read (YYYY-MM-DD).
---
Files next to this dossier (formats):
- `estimates.json`: `{"principle": "<one line>", "key_figures": {"dimensions_mm": [L, W, H], "mass_kg": x,
"power_w": x, "unit_cost": {"currency": "EUR", "q1": x, "q100": x, "q1000": x}, "retail_price":
{"currency": "EUR", "value": x}}, "parameters": [{"name": "...", "value": x, "unit": "...", "origin":
"CALCULATION|SOURCE|ASSUMPTION|SIMULATION", "home": "calc/<x>.results.json#<key> or source no.",
"req_ids": ["..."]}], "cost": {"currency": "EUR", "bom": {"q1": x, "q100": x, "q1000": x}, "other":
{"<name>": {"q1": x, "q100": x, "q1000": x}}, "unit_cost": {"q1": x, "q100": x, "q1000": x}}}`; unknown =
`null`; `cost.unit_cost` = `bom` + the sum of `other`, equal to `key_figures.unit_cost`.
- `compliance.csv`: header `req_id,status,value,unit,evidence,note`; one row per id of
`work/packet/req-index.csv`; status `met` (target met), `partly` (threshold met, target not), `not_met`
(threshold missed), `not_addressed`; evidence = paths inside your folder (`calc/x.results.json`,
`dossier.md#4`); quote fields that contain commas.
- `calc/<question>.py` from `method/templates/calc_template.py`, each with its `<stem>.results.json`.
skills/dd-hw-handbook/SKILL.md (266 wierszy)
---
name: dd-hw-handbook
description: Product-agnostic quality bars and methods for every deliverable of a dd hardware design run (requirements, concept, calculations, CAD, drawings, electronics, firmware, safety and certification, BOM and cost, prototype and test plan, renders, report). Read it before producing any deliverable. It says WHAT GOOD LOOKS LIKE; your main prompt says who does the work and in which order.
---
# dd hardware design handbook
Your main prompt defines the team, the roles, the communication and the order of work. This handbook defines
the quality bar of each deliverable and the methods that reach it. Where your main prompt is more specific,
follow your main prompt. Where the RUN CONTRACT fixes a file name or a format, the RUN CONTRACT wins.
Exact tool commands, versions and paths are in `INPUT/TOOLCHAIN.md` (read the working examples it points to
before writing your own scripts); this handbook names tools only by purpose.
Contents: 1 inputs · 2 requirements · 3 research · 4 physics map · 5 concept · 6 calculations · 7 CAD ·
8 drawings · 9 electronics · 10 firmware · 11 safety and certification · 12 sourcing, BOM and cost ·
13 prototype and test plan · 14 renders · 15 report and manifest · 16 claims · 17 time and context.
---
## 1. Reading the inputs
- `INPUT/brief.md` — one sentence plus customer context. Extract: who buys it, where and how it is used, how
often and how long, the price expectation, the one or two things that must be better than what exists.
- `INPUT/requirements.md` — the acceptance criteria. Each item has an id, a metric, a target and usually a
threshold (worst acceptable), a verification method and a weight. **Every id must be addressed and keep its
exact spelling** wherever you mention it. Weights tell you what matters most when requirements conflict.
- `INPUT/TOOLCHAIN.md` — what is installed and how to call it headless. Use only what it lists. A tool that
misbehaves gets three honest attempts with new information each time, then a labelled fallback (for example
an analytical model instead of a simulation) and a note in `manifest.json → blocked[]` if it mattered.
## 2. Requirements — `deliverables/01-requirements/`
Quality bar: an engineer who has never seen the brief can design and verify the product from this folder
alone, and every number in it has an origin.
Write `requirements.md` (and, if you like, a machine-readable `requirements.yaml`) with three parts:
1. **Given requirements**, one entry per id from `INPUT/requirements.md`: the id, the original statement, your
interpretation (the exact condition under which it will be verified: temperature, voltage, distance,
duty cycle, test method), and the design consequence (what it forces in the design).
2. **Derived requirements**, ids `DR-<AREA>-<nn>`, each with: parent id(s) or "brief"/"regulation"/
"manufacturing", statement, metric, target, threshold, verification method (Analysis, Inspection,
Demonstration, Test), rationale with origin label, priority. Walk at least these areas and write down
either the requirement or why the area does not apply: function and performance under all operating
conditions; user interface and ergonomics; power source and consumption (including standby); mechanical
interfaces and mounting; environment (temperature, humidity, dust and water, altitude, transport and
storage); safety (electric shock, heat and burns, fire, mechanical hazards, chemical, optical and other
radiation, noise, misuse that can be foreseen); EMC and, if any radio, radio; materials and restricted
substances; lifetime, duty cycle and reliability; maintenance, cleaning, consumables and repair;
manufacturing process at 1, 100 and 1000 units; assembly and test in production; packaging, shipping and
drop; labelling, manuals and markings; unit cost and retail price; prototype schedule.
3. **Conflicts and decisions**: requirement pairs that pull against each other, how you resolved each (use the
weights; safety first), and the assumptions register (each ASSUMPTION with reason and sensitivity).
Write `compliance.csv` exactly as the RUN CONTRACT specifies, one row per id of `INPUT/requirements.md`:
- `status`: `met`, `partly`, `not_met` or `not_addressed`. At the concept tier the status is a prediction
from your estimates: say so in `note` (for example "predicted, CALCULATION"). Be honest: a predicted miss
is `not_met` with the reason, not a hidden problem.
- `value` and `unit`: the predicted or designed value in the requirement's own metric and unit.
- `evidence`: path(s) inside `deliverables/` that show it (a calculation result, a section of the concept).
## 3. Research — benchmark, users, prior art
- Find at least five comparable products (commercial and open-source; adjacent categories count). For each:
the specifications that matter for our requirements, price with date and URL, and weak points from
reviews, teardowns, forums or return reasons. Put the table in `02-concept/benchmark.md`.
- From the benchmark derive: realistic target values, the differentiator ("our own, better version" — what we
do better and why it is feasible), and the failure modes users actually complain about. Feed both back into
the derived requirements.
- Note patents only as prior art you noticed; never give legal opinions. If an idea of yours looks genuinely
new, flag it as `novelty` in `REPORT.md` (one line) — do not elaborate on it in public-facing text.
- Read pages, do not guess them. If a site blocks automated reading, use a different source.
## 4. Physics map — which disciplines decide this product
Rate each domain CRITICAL, RELEVANT or MINOR for this product: structure and strength; heat; fluids and
aerosols; electrical power; electronics and control; firmware; mechanisms and motion; materials and
chemistry; optics and light; acoustics; human factors; environment. For each CRITICAL domain write: the
governing relations, the few parameters that dominate the result, the order-of-magnitude numbers, and the
ways it typically fails (from first principles and from what users report). The map decides which analyses
you run and how deep; it lives in `02-concept/physics-map.md`.
## 5. Concept — `deliverables/02-concept/`
Quality bar: the decision is visibly earned. A reader sees real alternatives, numbers for each, a fair
comparison, and a chosen architecture concrete enough to start detailed design tomorrow.
Contents (file names are suggestions; keep them inside `02-concept/`):
- `concept.md` — the main document, in this order:
1. The product in one paragraph: what it is, for whom, what it does better.
2. Functions and flows: the main functions as verb–noun pairs and the energy, material and signal flows.
3. Alternatives: at least three that differ in **working principle or architecture**, not in cosmetics.
For each: how it works, a simple diagram, first-order numbers against the top-weighted requirements
(performance, power, size, mass, unit cost), the main risks and hazards.
4. Evaluation: knock-out by thresholds first; then a weighted comparison whose weights come from the
requirement weights; a sensitivity check (vary each weight ±20 %, and the most uncertain estimates
within their range) showing whether the winner holds. Record why each loser lost.
5. The chosen concept: architecture block diagram (Mermaid in the markdown and a rendered PNG or SVG if
the toolchain has a renderer), the subsystem list with make-or-buy, the critical components with real
candidate parts (manufacturer, part number, supplier link, price with date), the interfaces between
subsystems (mechanical, electrical, thermal, data).
6. Key estimates: every number the decision rests on, each with its origin; the scripts that compute them.
7. Safety concept: the top hazards, the design measures (inherently safe design first, then protective
devices, then information for the user), and which protections act **independently of firmware**.
8. Compliance route: which EU directives and harmonised standards, and which FCC rules, apply and why
(with SOURCE), the likely conformity route, rough cost and time.
9. Cost: a rough BOM of the major items, the unit cost at 1, 100 and 1000 units with the method, and the
retail price logic (section 12). Optionally `09-bom-cost/cost.json` already at this tier.
10. Risks: the top risks with likelihood, impact, mitigation and the analysis or test that would retire
each one.
11. Decisions taken without a human (taste, priorities, trade-offs) with the rejected alternatives.
12. Open issues and what detailed design must do first.
- `calc/` — the scripts behind the key estimates (same rules as section 6), with their results files.
- `benchmark.md`, `physics-map.md`, and anything your method produces (scores, votes, issue logs, models).
Concept anti-patterns: two strawmen next to the favourite; alternatives that differ only in colour or
material; scores without numbers behind them; a decision matrix whose weights were tuned until the favourite
won; a concept that silently misses a top-weighted requirement; prose without a single calculated number.
## 6. Calculations — `05-calculations/` (full tier) and `02-concept/calc/` (concept tier)
- One Python script per question, run with the toolchain's Python (`ddpy`, see `INPUT/TOOLCHAIN.md`; the
system `python3` has no scientific libraries). Physical quantities carry units (the `pint` library) and every
input is labelled at the top of the script with its origin.
- Scripts run with `ddpy <script>` from their own folder, offline, in under five minutes, and write
`<stem>.results.json` (`{"<name>": {"value": x, "unit": "..."}}`). The RUN CONTRACT requires this for
`05-calculations/`; use the same convention in `02-concept/calc/`.
- Order of work: hand estimate → script → (only if it changes a decision) simulation. For any simulation:
first a known-answer case, then the real case on at least three mesh or step sizes with the trend shown,
sanity checks (balances of mass, energy or force), and a sensitivity run on the least certain inputs.
- Static strength is not drop, impact or fatigue; steady thermal is not transient; say which remain open.
- Margins: state each result as value, requirement, margin, and status.
## 7. CAD — `03-cad/` (full tier)
- Parametric code-CAD (CadQuery or build123d, whichever `INPUT/TOOLCHAIN.md` lists as working), one script
per designed part, parameters at the top, an assembly script placing parts with names. Re-running the
scripts reproduces every STEP. FreeCAD files are acceptable if that is your route.
- Deliver `assembly.step` and one STEP per designed part, plus the source. Purchased parts appear as
simplified bodies with their real envelope dimensions from the datasheet (label them).
- Check every part: valid solid, volume and mass from density, bounding box against size requirements,
pairwise interference zero (or an intended fit), clearances for assembly tools and fingers, wall thickness
and draft suited to the chosen process, standard fasteners.
- Choose a manufacturing process per part for the prototype (3D printing, CNC, laser-cut sheet) and for
1000 units (injection moulding, die cutting, sheet-metal bending), and note what changes between them.
- Export a GLB of the assembly for the renders and the website (see `INPUT/TOOLCHAIN.md` for the converter).
## 8. Drawings — `04-drawings/` (full tier)
- A drawing for every manufactured part: views, overall and functional dimensions, tolerances (a general
tolerance class plus explicit tolerances on functional features), material, finish, quantity, part number
and revision matching the BOM. Flat patterns for sheet metal.
- An assembly drawing with item balloons that match `bom.csv` item numbers. PDF or SVG; DXF optional.
- Open each output after you write it (render a PNG preview and look at it, or parse it) — a drawing file
that does not open does not exist.
## 9. Electronics — `06-electronics/` (full tier)
- Start from a block diagram and a power budget over the full supply range and all operating modes.
- KiCad 9 project with schematic and, where custom electronics is needed, a routed board. Real parts with
matching symbols and footprints; every part has a manufacturer part number that exists at a distributor or in
the offline LCSC/JLC catalogue described in `INPUT/TOOLCHAIN.md`.
- Protection where it applies: input fuse or current limit, reverse polarity, transients and ESD on external
connectors, inrush, thermal shutdown of hot parts in hardware, safe state on power loss.
- Calculations: currents, trace widths, dissipation and temperature rise of the hot parts, derating, and for
any mains part the creepage and clearance with the standard you took the values from.
- Run ERC and DRC from the command line; deliver the reports; fix every error or justify each waiver.
Fabrication outputs: Gerbers, drill, pick-and-place and the board BOM. Passing DRC is not a hardware test.
- Simulate uncertain circuit behaviour with ngspice where it changes a decision (start-up, protection trip,
filter response) after one known-answer test of the simulator.
## 10. Firmware — `07-firmware/` (full tier)
- PlatformIO project at the folder root that builds offline for the real target MCU of the schematic; use
exactly the platform versions `INPUT/TOOLCHAIN.md` pins (anything else downloads packages and blocks
other runs).
- A state machine with explicit fault states and a safe default; a watchdog; inputs debounced; every
safety-relevant reaction has a hardware backstop and the firmware is never the only protection.
- Host tests (`native` environment) for the logic and the interlocks: write a test that fails first, then
passes. Build with warnings as errors where the framework allows. Never flash or power anything.
- Pin map agreed with the schematic; configuration constants generated from or checked against the design
parameters.
## 11. Safety and certification — `08-safety-certification/` (both tiers: summary in 02; full tier: complete)
- Hazard analysis in the ISO 12100 manner: hazard → hazardous situation → harm → risk estimate (severity ×
probability) → reduction in the order inherently safe design, protective measures, information for use →
residual risk. Derive safety requirements with ids and trace them to the design.
- Regulatory map with SOURCE for each item. For the EU think through at least: the Low Voltage Directive
(2014/35/EU) when any voltage is in its range, the EMC Directive (2014/30/EU), the Radio Equipment Directive
(2014/53/EU) when there is any radio, RoHS (2011/65/EU), WEEE (2012/19/EU), the batteries rules when there
is a battery, the General Product Safety Regulation (EU) 2023/988, REACH, ecodesign and standby rules.
For the US: FCC Part 15 (Subpart B for unintentional radiators, Subpart C for intentional ones) and the
voluntary safety listings retailers expect. Then find the harmonised product-family standards that
apply to THIS product by research, and quote which clauses drive the design.
- Prefer architectures that make conformity easy: low voltage inside the product through a certified external
supply when the power level allows it, pre-certified radio modules, protections that do not depend on
firmware, materials with suitable flammability ratings near heat and live parts.
- State the conformity route (self-declaration, notified body or not), the tests an accredited lab would run,
a pre-compliance plan, and a rough cost and duration. You identify; you do not certify.
## 12. Sourcing, BOM and cost — `09-bom-cost/`
- Real, purchasable parts only. For each line: manufacturer, part number, supplier, supplier part number, URL,
unit price at 1, 100 and 1000 (price breaks as shown by the supplier, currency stated), the date you read it
in `notes`. A price you could not read is an ASSUMPTION with a range, never a guess dressed up as SOURCE.
Prefer parts in stock at two or more suppliers, active (not end-of-life), and note a second source for
critical parts. Use the offline catalogue from `INPUT/TOOLCHAIN.md` first, then distributor pages
read-only.
- `bom.csv` with exactly the header the RUN CONTRACT gives; `cost.json` and `cost.md` as it specifies.
- The unit cost at each quantity is more than the BOM: PCB fabrication and assembly, mechanical parts (at 1
and 100 units printed or machined; at 1000 units moulded with the tooling cost amortised and stated
separately), assembly and test labour, packaging, certification and other one-off costs amortised over
the quantity (state the assumption), freight to the fulfilment point, and a contingency. Show each line.
- Retail price logic: start from benchmark prices and a target gross margin; check that the price leaves room
for crowdfunding platform and payment fees, shipping to backers, VAT where it applies, returns and warranty.
An underpriced product that cannot be delivered is the classic crowdfunding failure; say plainly if the
numbers do not close.
## 13. Prototype and test plan — `10-prototype-test-plan/` (full tier)
- Build plan for prototype 1: how each part is made, the order of assembly, tools, and the checks after each
step.
- Bring-up for a person later: first power-up with a current-limited or isolated supply, what to measure
before applying full power, safety precautions.
- One test per requirement (and per safety requirement): method, equipment, conditions, pass criterion, the
requirement id it closes. Include pre-compliance EMC and the safety tests a lab would run, and durability
or life tests where lifetime is a requirement.
## 14. Renders — `11-renders/` (full tier)
- Renders come from the real CAD geometry (the assembly GLB) through Blender in background mode: a product
view, an exploded view, and a view that shows the user interface. Check the scale against a known
dimension. Label them as renders of a digital design.
- Never use generative image models to depict the product: they invent geometry that does not exist.
- You cannot judge images reliably by looking. Check what can be measured (file exists, resolution, the
object fills the frame, parts are present by name) instead of trusting a glance.
## 15. Report and manifest
`REPORT.md` (both tiers) in this order: the product in one paragraph; a key-parameter table (value, unit,
origin label); unit cost at 1/100/1000 and the retail price; status per requirement (from `compliance.csv`);
the top risks and open hazards; decisions taken without a human with their alternatives; what is open,
blocked or not run; for the full tier, the file map. Every number in it must match its home.
`manifest.json` exactly as the RUN CONTRACT specifies, including `key_figures` (use `null` for an unknown
figure, never a guess) and `blocked[]`. List every file under `deliverables/`.
Before you finish: re-read `REPORT.md` and `02-concept/concept.md` against the numbers' homes, check that
`compliance.csv` has one row per requirement id, that every evidence path exists, and that `manifest.json`
parses and lists the files that exist.
## 16. Claims
The project designs real products for honest crowdfunding. In every document: no feature that the design
does not implement, no performance number that is not calculated or sourced, no "certified", "safe",
"waterproof", "AI" or similar word unless the evidence for it is in the deliverables. Under-promise.
## 17. Time and context
- The RUN CONTRACT gives the time target and the hard stop. Plan time boxes per phase at the start, check
`date` at each boundary, and cut scope (depth, not honesty) when behind.
- Long runs lose context. Keep a short state file (decisions, key numbers' homes, open issues, next step)
current, so you or a fresh agent can resume from files alone.
- Write deliverables as soon as each part exists and keep them current.