Use US English spelling throughout and check it in npm test

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-26 06:36:46 -07:00
1 parent e67aaabdce
commit 899b3a48d8
84 files changed
+319 -240

No files matched your search

@@ -1,9 +1,9 @@
# Chart Playbook
> Part of plan2code-0-pathfinder — loaded at the top of MODE A (Chart). Expands the numbered Chart steps.
>
> **Backend note.** Steps 0, 2, and 4 — the gates and the grills — are identical either way, and so is every judgement call below (fog vs question, in scope vs out, the destination test). What differs is where Steps 3 and 5-7 put the bytes: on `**Backend:** github`, `github-issues.md` overrides the `map.md` and question-file templates here, the single-pass rule under *Step 6: Numbering and dependency order*, and the timing of the recon. Read it alongside this file, not instead of it.
> **Backend note.** Steps 0, 2, and 4 — the gates and the grills — are identical either way, and so is every judgment call below (fog vs question, in scope vs out, the destination test). What differs is where Steps 3 and 5-7 put the bytes: on `**Backend:** github`, `github-issues.md` overrides the `map.md` and question-file templates here, the single-pass rule under *Step 6: Numbering and dependency order*, and the timing of the recon. Read it alongside this file, not instead of it.
Charting produces a map and a set of question files. It resolves nothing by hand. Every judgement below serves one goal: put a sharp question on the map for everything you can phrase now, and leave everything else honestly in the fog.
Charting produces a map and a set of question files. It resolves nothing by hand. Every judgment below serves one goal: put a sharp question on the map for everything you can phrase now, and leave everything else honestly in the fog.
---
@@ -33,7 +33,7 @@ This gate and the Step 4 no-fog off-ramp are the same instinct at two moments: t
## Step 2: The destination grill
The destination is settled **first** because it fixes scope. Every later judgement — is this a question or fog, is this in scope or past the edge, is this map cleared — is measured against it. A vague destination makes all three unanswerable, and you will spend the rest of the map arguing about boundaries instead of decisions.
The destination is settled **first** because it fixes scope. Every later judgment — is this a question or fog, is this in scope or past the edge, is this map cleared — is measured against it. A vague destination makes all three unanswerable, and you will spend the rest of the map arguing about boundaries instead of decisions.
A destination is **one or two lines** describing what exists when the map clears. It is not a feature description. It is not a value proposition. It names the artifact and draws the edge.
@@ -50,7 +50,7 @@ Recommend an answer with each probe — the human corrects faster than they comp
Two round trips, not six. Three probes each — exactly the cap, so neither batch needs splitting.
Batch 2 bends the independence test on purpose. The arrival signal (5) can shift under the smallest arrival (4), so strictly it should be held back — but holding it costs a third round trip to catch a conflict that is rare and cheap to spot. The trade is to send them together and reconcile at the recap: if the smallest arrival comes back materially smaller than the artifact you were told about, re-check the arrival signal against it before writing the destination. A knowing trade here, not a licence to batch dependent probes elsewhere.
Batch 2 bends the independence test on purpose. The arrival signal (5) can shift under the smallest arrival (4), so strictly it should be held back — but holding it costs a third round trip to catch a conflict that is rare and cheap to spot. The trade is to send them together and reconcile at the recap: if the smallest arrival comes back materially smaller than the artifact you were told about, re-check the arrival signal against it before writing the destination. A knowing trade here, not a license to batch dependent probes elsewhere.
**Both batches go through the structured question tool.** Give each probe genuine candidate options with trade-offs and a recommendation; the built-in `Other` path is where the human composes the actor, a further feature to leave out, the arrival signal, or forcing-function detail in their own words. A clicked option is not written verbatim as the destination — the recap-confirmation tool call turns all six answers into the agreed one-or-two-line destination before disk write.
@@ -141,7 +141,7 @@ Recon is `legwork · AFK` — you do it alone, and you write it down **already r
Two disciplines keep this file useful:
- **Verify behaviour against actual code, never against a filename.** A file called `auditLogger.ts` may log nothing.
- **Verify behavior against actual code, never against a filename.** A file called `auditLogger.ts` may log nothing.
- **Scope the recon to the destination.** A recon of the whole repo is unreadable and stale in a week. If a subtree cannot plausibly be touched by the destination, say so in one line and move on.
Record what you could **not** determine as an explicit gap. Gaps at recon time are often the first real fog bullets.
@@ -257,7 +257,7 @@ The destination grill went **deep on one thing**. This grill goes **wide on ever
**You are not resolving anything here.** You are taking inventory. The instant an answer feels satisfying, you are probably going deep.
### Recognising that you have gone deep
### Recognizing that you have gone deep
Watch for these. Any one of them means stop and pull back:
@@ -312,7 +312,7 @@ Record each answer as one line in your working notes with an area label. At the
## The fog-vs-question test
This is the single most important judgement in the skill. Get it wrong toward questions and the map fills with unanswerable stubs that block the frontier. Get it wrong toward fog and the map has nothing takeable on it.
This is the single most important judgment in the skill. Get it wrong toward questions and the map fills with unanswerable stubs that block the frontier. Get it wrong toward fog and the map has nothing takeable on it.
> **The test is whether you can STATE the question precisely now — not whether you can ANSWER it now.**
@@ -446,7 +446,7 @@ plan, not at shipped code. Continuous streaming to external systems is not on th
- Questions are put to the human in plain English. Technical terms only where the term is the decision.
- HITL questions are answered by the human in their own words. Never self-answered.
- No new runtime dependency is assumed without a `research` question backing it.
- Compliance language is reviewed by Dana before anything user-facing is finalised.
- Compliance language is reviewed by Dana before anything user-facing is finalized.
- Sketches are throwaway and live only under `pathfinder/sketch-NN/`.
## Glossary
@@ -4,7 +4,7 @@
>
> **Local-file maps never load this file.** If `## Ground rules` says `**Backend:** local`, close it and use `questions.md`.
Everything the skill says about *judgement* is unchanged by the backend: the fog-vs-question test, the destination grill, one question at a time, the decide-menu-checkpoint cadence, HITL is never self-answered, the Clearing Gate rubric. This file changes only *where the bytes go*.
Everything the skill says about *judgment* is unchanged by the backend: the fog-vs-question test, the destination grill, one question at a time, the decide-menu-checkpoint cadence, HITL is never self-answered, the Clearing Gate rubric. This file changes only *where the bytes go*.
---
@@ -17,13 +17,13 @@ A map on GitHub Issues buys three things local files cannot:
| | Local files | GitHub Issues |
|---|---|---|
| Visibility | One machine, one person | Anyone with repo access, in a UI they already have open |
| Blocking | A `Blocked by:` line only an agent reads | Native issue dependencies — GitHub greys out blocked issues in its own UI |
| Blocking | A `Blocked by:` line only an agent reads | Native issue dependencies — GitHub grays out blocked issues in its own UI |
| Concurrency | One session at a time by construction | Several people can work unblocked questions at once; the assignee is a real lock |
It costs three things too, and the human must know all three before they pick it:
1. **Issues on a public repo are public.** The destination, the rejected alternatives, the codebase recon, the technical debt in the blast radius — all of it is world-readable the moment it is written. Never chart to a public repo's tracker anything that would embarrass the project or leak a customer.
2. **It writes to shared state.** A local map costs nothing to abandon. Twelve stale issues labelled `pathfinder:grill-hitl` on a team's tracker is litter someone has to clean.
2. **It writes to shared state.** A local map costs nothing to abandon. Twelve stale issues labeled `pathfinder:grill-hitl` on a team's tracker is litter someone has to clean.
3. **It needs `gh`, auth, and issues enabled.** More that can break, in a step whose whole job is to remove friction.
---
@@ -69,7 +69,7 @@ This is the whole mapping. Everything below expands a row.
| Local file model | GitHub Issues model |
|---|---|
| `specs/<idea>/pathfinder/map.md` | One issue, labelled `pathfinder:map`, titled `Map: <idea>` |
| `specs/<idea>/pathfinder/map.md` | One issue, labeled `pathfinder:map`, titled `Map: <idea>` |
| `questions/NN-<slug>.md` | A **sub-issue** of the map, titled with the question name |
| `NN` ordering | The map's sub-issue order — the order they were created, which is dependency order |
| `## Question` in the file | The issue body |
@@ -79,7 +79,7 @@ This is the whole mapping. Everything below expands a row.
| `State: open` | Issue open, **no assignee** |
| `State: claimed` | Issue open, **assigned** |
| `State: resolved` | Issue **closed as completed**, with an `## Answer` comment |
| `State: out-of-scope` | Issue **closed as not planned**, labelled `pathfinder:out-of-scope`, no `## Answer` |
| `State: out-of-scope` | Issue **closed as not planned**, labeled `pathfinder:out-of-scope`, no `## Answer` |
| `Blocked by: 02, 04` | Native issue dependencies (`dependencies/blocked_by`) |
| `Locked: yes` | The `pathfinder:locked` label |
| `Claimed: <timestamp>` | GitHub's own assignment event in the timeline |
@@ -221,7 +221,7 @@ gh api --method POST repos/<owner>/<repo>/issues/<blocked-number>/dependencies/b
**The database id is the single most common failure in this backend.** `gh api repos/o/r/issues/42 --jq .id` returns something like `2716143027`. The `42` is the *number*; `I_kwDO...` is the *node id*. The node id is rejected outright. The *number* is worse: a small integer like `42` is itself a perfectly valid database id — of some unrelated issue created years ago — so the call can succeed and silently attach the wrong thing. Fetch `.id` for every issue you are about to reference, and never hand-assemble one.
Charting still writes `00-codebase-context`'s equivalent — the Step 3 recon you held. Create it **first**, labelled `pathfinder:legwork-afk`, post the recon as an `## Answer` comment, and close it as completed in the same pass. It is resolved on arrival, exactly as in local mode, and it is what the handoff's `## System Context` is built from.
Charting still writes `00-codebase-context`'s equivalent — the Step 3 recon you held. Create it **first**, labeled `pathfinder:legwork-afk`, post the recon as an `## Answer` comment, and close it as completed in the same pass. It is resolved on arrival, exactly as in local mode, and it is what the handoff's `## System Context` is built from.
### If the endpoints are unavailable
@@ -384,7 +384,7 @@ Research subagents work the same way with one substitution: the brief carries th
Identical in shape; the inputs come from the query instead of the checklist.
- **Heading** — `🧭 <idea> · <Status> · <closed>/<total> cleared`, where `<total>` excludes anything labelled `pathfinder:out-of-scope`.
- **Heading** — `🧭 <idea> · <Status> · <closed>/<total> cleared`, where `<total>` excludes anything labeled `pathfinder:out-of-scope`.
- **Glyph order** — sub-issue order, the same order Chart Step 6 created them in.
- **Glyphs** — `●` closed as completed · `◉` open and assigned to you · `○` open, unassigned, unblocked · `⊘` open with `blocked_by > 0` · `⊝` closed as not planned.
- **Named legend** — names, never `#numbers`. `(blocked:<name>)` names the blocker rather than numbering it, since there is no stable `NN` to point at.
@@ -112,13 +112,13 @@ The primary channel. One question object per probe, up to three in a single call
- **Header** — the decision in two or three plain words (`Export format`, `Size cap`). Not a type, not a marker, not a number.
- **Question** — the probe, with its why-it-matters. This is prose and it is not rationed; the same sentences you would have written in a Q block go here.
- **Options** — the genuine alternatives, each described by its trade-off, with the recommended one named as such in its description. Two to four; the free-text escape hatch covers the rest. Label plainly, then let the description carry the precise term: `One file per message` labelling the `.eml`-in-a-ZIP option, with `.eml` named in the description.
- **Options** — the genuine alternatives, each described by its trade-off, with the recommended one named as such in its description. Two to four; the free-text escape hatch covers the rest. Label plainly, then let the description carry the precise term: `One file per message` labeling the `.eml`-in-a-ZIP option, with `.eml` named in the description.
A short *label* is not a short *decision*. The label is a handle — `Fixed tick count` — and the description carries the trade-off that makes it choosable. A label bundling several independent answers is a probe that wants splitting.
**A click is a decision, not a sentence.** The HITL rule wants an `## Answer` traceable to something the human actually said, and a selected option label is thin evidence on its own. What makes tool-delivered answers legitimate is the recap turn in *Landing the grill* — you play the choices back in the tool's question text and they confirm or correct in their own words. Never skip the recap on the grounds that the tool already captured the answer; the tool captured the *pick*, and the recap captures the *agreement*.
**If a reply comes back thinner than the decision** — a bare click on something you now realise carries weight — do not paper over it. Fold the why into the recap turn as one more probe before writing the `## Answer`.
**If a reply comes back thinner than the decision** — a bare click on something you now realize carries weight — do not paper over it. Fold the why into the recap turn as one more probe before writing the `## Answer`.
#### Numbered Q blocks
@@ -102,7 +102,7 @@ Pathfinder writes `specs/<idea>/PLAN-DRAFT-<YYYYMMDD>.md` with the header line:
`**Status:** Phase 3 Complete - Resume at Phase 4`
`/plan2code-1-plan` **already recognises that exact string.** Its "Check for Existing Progress" block, which runs before Phase 1, reads:
`/plan2code-1-plan` **already recognizes that exact string.** Its "Check for Existing Progress" block, which runs before Phase 1, reads:
`- Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4`
@@ -128,7 +128,7 @@ Everything in the draft traces to something on the map. Nothing is invented at h
| `## Destination` | Section 1 Executive Summary (2-3 sentences, present tense) and Section 7 Success Criteria (the destination restated as checkable outcomes) |
| Resolved `grill` answers describing behavior | Section 2.1 Functional Requirements, one `FR-N` per decided behavior |
| Resolved `grill` answers describing performance, security, scale, operability | Section 2.2 Non-Functional Requirements, one `NFR-N` each |
| `## Out of scope` | Section 2.3 Out of Scope — copied line for line, wording and order intact. The ONLY permitted change is the link prefix: `./questions/` becomes `./pathfinder/questions/`, because the draft sits one level above the map. Do not re-word, re-order, or summarise; a re-worded scope boundary is a re-litigated one. |
| `## Out of scope` | Section 2.3 Out of Scope — copied line for line, wording and order intact. The ONLY permitted change is the link prefix: `./questions/` becomes `./pathfinder/questions/`, because the draft sits one level above the map. Do not re-word, re-order, or summarize; a re-worded scope boundary is a re-litigated one. |
| The testing-posture question's answer | Section 2.4 Testing Strategy table (Types / Phase Testing / Coverage) |
| Resolved `research` answers and their `## Evidence` | Section 3 Tech Stack — the cited source becomes the Justification cell |
| `questions/00-codebase-context.md` | The `## System Context` section, and the components table in 4.3 |
@@ -211,7 +211,7 @@ next run rather than truncating.
| Entry points to change | `AuditExportJob`, registered in `HangfireStartup.ConfigureRecurringJobs()` | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| Existing patterns to follow | Jobs resolve tenant scope via `ITenantScopeFactory`; no job reads config directly | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| Integration surfaces | S3 (customer-owned), Hangfire scheduler, `TenantConfigStore` | [Destination auth](./pathfinder/questions/03-destination-auth.md), [Scheduling model](./pathfinder/questions/02-scheduling-model.md) |
| Technical debt in the path | `AuditQuery` materialises full result sets; streaming reader needed before FR-1 | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| Technical debt in the path | `AuditQuery` materializes full result sets; streaming reader needed before FR-1 | [Codebase context](./pathfinder/questions/00-codebase-context.md) |
| System boundaries | Read-only against the audit store; writes only to customer buckets and the run-log table | [Retention and replay](./pathfinder/questions/04-retention-and-replay.md) |
| Conventions in force | `AGENTS.md` present and read; its logging and DI conventions govern | `pathfinder/map.md` ## Ground rules |
@@ -280,7 +280,7 @@ Manifest sequence numbers are per tenant, monotonic, and reused on replay.
| Cross-account role assumption is unexercised in this codebase | Medium | High | Spike `S3RoleAssumer` against a second AWS account before any other component |
| A tenant exceeds the daily ceiling indefinitely | Medium | Medium | Spill oldest-first plus a three-run alarm — [Overflow behavior](./pathfinder/questions/08-overflow-behavior.md) |
| Partial objects visible after a failed run | Low | High | Upload to a run-scoped prefix, publish the manifest last — the manifest is the commit point |
| `AuditQuery` materialises full result sets | High | High | Streaming reader is a prerequisite, not an optimisation |
| `AuditQuery` materializes full result sets | High | High | Streaming reader is a prerequisite, not an optimization |
| Customer revokes the role mid-run | Low | Medium | Fail the run whole; replay window covers recovery |
## 7. Success Criteria
@@ -335,7 +335,7 @@ Ruled out of scope: [Failure notification](./pathfinder/questions/07-failure-not
**No scrapable confidence numbers anywhere in the file.** Write the confidence as `Requirements-clarity 22/25 · Feasibility-technical 21/25 · Integration-points 23/25 · Risk-assessment 20/25` — hyphenated dimension labels, sub-scores over 25, no total, no percent sign.
The reason is exact. When a PLAN-DRAFT carries no `METRICS_JSON` comment, the metrics collector falls back to scraping it by regex: an overall-confidence pattern that requires a literal `%`, and four breakdown patterns that match a bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed directly by whitespace, a colon, or a pipe and then digits. **The breakdown patterns do not require a percent sign.** A pathfinder-written draft always lacks that comment until `/plan2code-1-plan` Phase 7 appends one, so both the percent sign *and* the bare dimension words have to be kept off the page — otherwise the pipeline records a planning-step confidence that no planning step ever produced. The hyphen in `Requirements-clarity` breaks the match; a table row reading `| Requirements | 11 |` does not, which is why the Scope Assessment row is labelled `Requirements decided`.
The reason is exact. When a PLAN-DRAFT carries no `METRICS_JSON` comment, the metrics collector falls back to scraping it by regex: an overall-confidence pattern that requires a literal `%`, and four breakdown patterns that match a bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed directly by whitespace, a colon, or a pipe and then digits. **The breakdown patterns do not require a percent sign.** A pathfinder-written draft always lacks that comment until `/plan2code-1-plan` Phase 7 appends one, so both the percent sign *and* the bare dimension words have to be kept off the page — otherwise the pipeline records a planning-step confidence that no planning step ever produced. The hyphen in `Requirements-clarity` breaks the match; a table row reading `| Requirements | 11 |` does not, which is why the Scope Assessment row is labeled `Requirements decided`.
**The `**Next:**` footer must ship with both bullets.** Pathfinder cannot edit the planning skill, so those two instructions travel inside the artifact:
@@ -40,7 +40,7 @@ One idea per session, so there is only ever one trail.
Confidence: solid, but Risk is borderline.
WAITING ON YOU · answer here, in this conversation:
Q2 Ceiling behaviour past the cap (re-ask) · Q3 Who sees the truncation warning
Q2 Ceiling behavior past the cap (re-ask) · Q3 Who sees the truncation warning
```
- The heading counts resolved questions over every question except out-of-scope ones.
@@ -1097,31 +1097,31 @@ async function cmdLint(loc) {
if (b === q.nn) add("error", q.path, "is blocked by itself");
}
}
// Cycles in Blocked by: a three-colour depth-first search (grey = on the
// Cycles in Blocked by: a three-color depth-first search (gray = on the
// current path, black = fully explored), so each question is explored once
// however densely the questions block each other. Every back edge is a
// cycle, reported once, against the question it starts from.
const reported = new Set();
const colour = new Map();
const color = new Map();
const pathStack = [];
const visit = (nn) => {
colour.set(nn, "grey");
color.set(nn, "gray");
pathStack.push(nn);
for (const b of byNN.get(nn).blockedBy) {
if (!byNN.has(b)) continue;
if (colour.get(b) === "grey") {
if (color.get(b) === "gray") {
const c = [...pathStack.slice(pathStack.indexOf(b)), b];
const key = [...new Set(c)].sort().join(",");
if (!reported.has(key)) {
reported.add(key);
add("error", byNN.get(b).path, `Blocked by: cycle ${c.join(" -> ")}; a cycle is one decision phrased twice (merge them or drop an edge)`);
}
} else if (!colour.has(b)) visit(b);
} else if (!color.has(b)) visit(b);
}
pathStack.pop();
colour.set(nn, "black");
color.set(nn, "black");
};
for (const q of questions) if (!colour.has(q.nn)) visit(q.nn);
for (const q of questions) if (!color.has(q.nn)) visit(q.nn);
// Scraper bait in the files the collector or a reader treats as planning output.
const baitFiles = [loc.mapPath, ...walk(path.join(loc.pf, "briefs"))];
for (const n of fs.existsSync(loc.ideaDir) ? fs.readdirSync(loc.ideaDir) : []) {
+1 -1
View File
@@ -23,7 +23,7 @@ The map lives in ONE of two places — the human's pick at Chart Step 1, never y
Read references/github-issues.md — REQUIRED on `github`, skip on `local`.
> Fallback: map = a `pathfinder:map` issue titled `Map: <idea>`; questions = its sub-issues, labelled `pathfinder:<type>-<mode>`; blocking = native dependencies; claim = assign `@me`; resolve = `## Answer` comment, then close.
> Fallback: map = a `pathfinder:map` issue titled `Map: <idea>`; questions = its sub-issues, labeled `pathfinder:<type>-<mode>`; blocking = native dependencies; claim = assign `@me`; resolve = `## Answer` comment, then close.
Recorded as the first `## Ground rules` bullet (`**Backend:** local|github`), never re-asked or switched. Either way the PLAN-DRAFT lands in local `specs/<idea>/` — downstream steps read files, not issues.
+1 -1
View File
@@ -164,7 +164,7 @@ Use kebab-case for feature name (e.g., `user-authentication`).
- "Run after each phase": Add testing task block at end of EVERY phase
- "Dedicated phase only": Create final Phase N: Testing
- "None" or empty: Omit testing tasks
- `| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: <where the test drives the behaviour>` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` ``
- `| Approach | Test first |` in 2.4: in every phase, order each task's test before its code and put a plain sub-bullet ` - Test: <where the test drives the behavior>` directly under the task line (no checkbox, so the loop's task count is unchanged), for example `` - Test: through `POST /votes` ``
**Small Projects (1-2 phases):** Combine sections, still create separate overview.md and phase-1.md. Note: "Small project - phases combined"
+1 -1
View File
@@ -26,7 +26,7 @@ The FIRST thing you do, before anything else in this file — before reading a s
- Run tests ONLY if a phase task or a task's `Test:` line lists them
- Do NOT run git commands - provide commit instructions for user
- Flag blockers clearly - never skip silently
- Read `references/building-habits.md` when a bug or unexpected failing test turns up, before any task in a Test first phase (its tasks carry `Test:` lines), and before any task that changes no behaviour; follow it.
- Read `references/building-habits.md` when a bug or unexpected failing test turns up, before any task in a Test first phase (its tasks carry `Test:` lines), and before any task that changes no behavior; follow it.
- No file tools: output contents in code blocks with a file path header; no filesystem: ask the user to paste file contents
## Required Context
+1 -1
View File
@@ -71,7 +71,7 @@ A reproduction written as a new test inside the project is offered, never assume
### Step 3: Narrow
- **A known-good version exists** (it worked before): `git bisect` with the reproduction as the check, in a throwaway worktree (`git worktree add <tmp> HEAD`, removed at the end) so the person's checkout never moves; in place only on a clean tree, with `git bisect reset` before you finish. Then read the commit it lands on.
- **Otherwise:** read the code path from the entry point the reproduction hits to where the wrong value or behaviour first appears.
- **Otherwise:** read the code path from the entry point the reproduction hits to where the wrong value or behavior first appears.
- Temporary logging only outside the source tree, or reverted at once.
Stop when you can name the line where right turns into wrong.
+2 -2
View File
@@ -59,7 +59,7 @@ On the console the page draws the board itself from `state.git`; you never post
1. Post an `activity` line ("Pulling from origin…"); collecting the click already set the page to working.
2. Run `git.mjs plan <op>` with the action's fields as flags.
3. With `ask: true`: a `confirm` becomes a `confirm` card, posted verbatim (`danger` and `consequences` as given; `files` as a `[{ path, state }]` table where the plan names files). A `card` of kind `switch`, `dirty` or `remote` becomes a `choice` card with exactly its `options`, labelled **Switch and bring them** (`bring`), **Commit first** (`commit-first`) and **Cancel** (`cancel`), or for `remote` one option per remote with `preset` recommended; put git's `reason` in `body` when given. Then wait for the answer. A `remote` pick plans `publish --remote <it>` again and asks its `confirm`.
3. With `ask: true`: a `confirm` becomes a `confirm` card, posted verbatim (`danger` and `consequences` as given; `files` as a `[{ path, state }]` table where the plan names files). A `card` of kind `switch`, `dirty` or `remote` becomes a `choice` card with exactly its `options`, labeled **Switch and bring them** (`bring`), **Commit first** (`commit-first`) and **Cancel** (`cancel`), or for `remote` one option per remote with `preset` recommended; put git's `reason` in `body` when given. Then wait for the answer. A `remote` pick plans `publish --remote <it>` again and asks its `confirm`.
4. Run the command(s).
5. In ONE post: `{ "reread": true }`, the `git-result` notice (one line: what happened, with short hashes, and after a push or publish the link from `pr-url`), `board: { describe }` when changes remain (a short kebab-case description of them, for the Create prompt), posted with `--wait`.
@@ -74,7 +74,7 @@ On a non-zero exit, save git's stderr to the session folder, run `classify-error
- **commit** commits only the paths in `files`. With `ignore[]`, first propose those `.gitignore` lines as a doc plus a `review` card (approve / change), write them on approve, and add `.gitignore` to the commit.
- **abort**, **continue**: `plan abort` / `plan continue`, then `reread`.
- **pr-host**: the server already saved the answer; post `reread` only.
- **done** (Done with git): Session End; a card of yours still open is cancelled first (notes/git.md).
- **done** (Done with git): Session End; a card of yours still open is canceled first (notes/git.md).
- Deleting a branch on the remote is never offered and never run.
## Conflict help
+2 -2
View File
@@ -71,7 +71,7 @@ The `Failure log` section below is a recording of mistakes made by previous AI A
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
1. Add one line to the `Failure log` below, in the imperative, describing the correct behavior.
2. Keep it specific to this repo. General advice belongs nowhere.
3. If this fix is a workflow rather than a rule, put it in `.claude/skills/` and link it from here.
4. Include the change in the same commit and mention it in your summary.
@@ -156,7 +156,7 @@ Present the user with update options:
| Testing | Commands? Fixtures? Mocking? |
| Environment | Local/CI/deploy? Env vars/files? |
| Rules | Project-wide or specific? Why? |
| Failure Log | What went wrong? Correct behaviour (imperative, one line)? Merge into an entry on the same topic if one exists; over 17 entries, propose what to prune (rule 7). |
| Failure Log | What went wrong? Correct behavior (imperative, one line)? Merge into an entry on the same topic if one exists; over 17 entries, propose what to prune (rule 7). |
| Other | "Tell me what to add." |
| Sync & Maintain | Scope: all surfaces or specific? Then follow the Sync & Maintain section. |
| Review | Per section: "Still accurate?" |
+1 -1
View File
@@ -74,7 +74,7 @@ The `Failure log` section below is a recording of mistakes made by previous AI A
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
1. Add one line to the `Failure log` below, in the imperative, describing the correct behaviour.
1. Add one line to the `Failure log` below, in the imperative, describing the correct behavior.
2. Keep it specific to this repo. General advice belongs nowhere.
3. If this fix is a workflow rather than a rule, put it in `.claude/skills/` and link it from here.
4. Include the change in the same commit and mention it in your summary.
+2 -2
View File
@@ -40,7 +40,7 @@ Check for `./AGENTS.md` first:
- Standalone workflow - does NOT create spec files or feed into steps 2-4
- Launched with a spec folder holding a `DIAGNOSIS-*.md`: read it first, as the bug's context (its cause and suggested fix are already found; re-run its reproduction before and after the fix). Once it passes, set the diagnosis `**Status:**` to `Fixed`; escalating, use that folder rather than asking for a name. Fixed, with nothing in the folder past the diagnosis (no `PLAN-CONVERSATION`, `PLAN-DRAFT`, `pathfinder/map.md` or `overview.md`)? It is done: run `node "<S>/specs.mjs" archive <spec> --dry-run` from the project root (`<S>` is `scripts/` beside this SKILL.md, `~/.agents/skills/plan2code-quick-task/scripts/` globally), show its `files`, ask "Archive it to `specs--completed/`? (yes / no)", and on yes run it without `--dry-run`. On no it stays on the dashboard as "Bug fixed".
- Cause unclear or the fix big? Stop and suggest `/plan2code-diagnose`.
- Read `references/building-habits.md` when the ask is a bug fix or a test fails unexpectedly, after a yes to "Write the test first?", and before a change meant to alter no behaviour; follow it.
- Read `references/building-habits.md` when the ask is a bug fix or a test fails unexpectedly, after a yes to "Write the test first?", and before a change meant to alter no behavior; follow it.
```
⋅
@@ -52,7 +52,7 @@ Check for `./AGENTS.md` first:
Ask what feature the user wants, then ask follow-up questions until 100% clear. Console: that first card carries `"templates": "idea"` (console.md → The kinds).
**Write the test first?** Ask it with the follow-ups (or on its own if there are none) only when the change alters behaviour AND the project already has a test runner you can see (a `test` script in `package.json`, pytest config in `pytest.ini` or `pyproject.toml`, `go.mod` with `_test.go` files, or similar). Never for a pure refactor, a docs change, or a project with no runner. Console: one `confirm` card in the same batch as the other plan questions; terminal: one line in the same prompt. On yes, name the test spot in the plan's Verify section and follow the test-first habit.
**Write the test first?** Ask it with the follow-ups (or on its own if there are none) only when the change alters behavior AND the project already has a test runner you can see (a `test` script in `package.json`, pytest config in `pytest.ini` or `pyproject.toml`, `go.mod` with `_test.go` files, or similar). Never for a pure refactor, a docs change, or a project with no runner. Console: one `confirm` card in the same batch as the other plan questions; terminal: one line in the same prompt. On yes, name the test spot in the plan's Verify section and follow the test-first habit.
## Scope Validation
+2 -2
View File
@@ -19,7 +19,7 @@ If `open` fails outright, fall back without drama: list the skills in the termin
## The menu
The page draws the cards itself — you never send the list. It also knows the repo already: `open` scans `AGENTS.md` and `specs/` into `state.scan` (`{ hasAgents, isGit, specs: [{ dir, name, state, detail, touched }] }`), and the picker at the top enables or greys every card from it — the spec the person picks there is the target their launch carries. What you post is your judgment on top of that:
The page draws the cards itself — you never send the list. It also knows the repo already: `open` scans `AGENTS.md` and `specs/` into `state.scan` (`{ hasAgents, isGit, specs: [{ dir, name, state, detail, touched }] }`), and the picker at the top enables or grays every card from it — the spec the person picks there is the target their launch carries. What you post is your judgment on top of that:
```jsonc
{
@@ -137,6 +137,6 @@ You arrive here mid-conversation after a `__dashboard` press — from a finished
## While it waits
- Bounded slices per console.md, using the longest safe slice: exit 10 → relay one line and immediately wait again — never end the turn after an arbitrary number of slices; exit 20 → `open --resume <sid>` (no `--workflow` — it stays `dashboard` until a launch overwrites it); exit 30 → they cancelled, ask in the terminal what they want.
- Bounded slices per console.md, using the longest safe slice: exit 10 → relay one line and immediately wait again — never end the turn after an arbitrary number of slices; exit 20 → `open --resume <sid>` (no `--workflow` — it stays `dashboard` until a launch overwrites it); exit 30 → they canceled, ask in the terminal what they want.
- A `__stop` action is the person ending the session before picking: post `finish` (a headline that says paused, `"command": "/plan2code"`) then `stop`, per console-stop.md.
- The console keeps `agent.status` honest: collecting a pick sets `working`, and waiting on the menu sets `waiting`. Post an `activity` while a launch becomes a skill.
+4 -4
View File
@@ -15,17 +15,17 @@ When a bug is reported or turns up, or a test fails unexpectedly:
Applies only when the phase's tasks carry `Test:` lines (the plan picked Test first), or the person said yes to "Write the test first?" in Quick Task. For each task:
1. Write the test at the task's named test spot (its `Test:` line, or the plan's Verify section).
2. Run it and see it fail for the right reason: the behaviour is missing, not a typo or an import error.
2. Run it and see it fail for the right reason: the behavior is missing, not a typo or an import error.
3. Write the code until the test passes. Keep the change to what the test asks for.
4. Never weaken, skip or delete a test to make it pass. If the test itself is wrong, say so and fix the test on its own.
## Pin behaviour first
## Pin behavior first
For a task meant to change no behaviour (a restructure, a rename, a move):
For a task meant to change no behavior (a restructure, a rename, a move):
1. Before touching the code, add or confirm tests that cover what the task touches.
2. Run them and see them pass.
3. Make the change.
4. Run the same tests, unchanged. They must pass. A test that needs editing means behaviour changed: stop and say so.
4. Run the same tests, unchanged. They must pass. A test that needs editing means behavior changed: stop and say so.
Adapted from Matt Pocock's `diagnose` and `tdd` skills and pstack's debugging playbook (both MIT).
+1 -1
View File
@@ -177,7 +177,7 @@ export function writeIfChanged(file, content) {
return true;
}
/** Normalise line endings for parsing; keep the original for writing back. */
/** Normalize line endings for parsing; keep the original for writing back. */
export function eol(text) {
return text.includes("\r\n") ? "\r\n" : "\n";
}
+1 -1
View File
@@ -206,7 +206,7 @@ function parseGroups(overview) {
if (cells.length < 2 || /^group$/i.test(cells[0])) continue;
const id = plainText(cells[0]);
const phases = phaseList(cells[1]);
// "None", a dash, a single phase, a group its author labelled sequential
// "None", a dash, a single phase, a group its author labeled sequential
// ("A (sequential)"), or a Phases cell written as a chain ("1 → 2") is not
// a parallel group.
if (!id || /^(none|-|–|—)$/i.test(id) || /\bsequential\b/i.test(id) || /→|->|\bthen\b/i.test(cells[1]) || phases.length < 2) continue;
+1 -1
View File
@@ -73,7 +73,7 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
A bounded wait slice, sized below your shell timeout. Exit 0 = the
result is on stdout, 10 = still waiting ("Waiting on your answer
in the web console"; call again), 20 = server gone (open --resume
<sid>), 30 = cancelled. Exits 0 and 10 carry terminalLine.
<sid>), 30 = canceled. Exits 0 and 10 carry terminalLine.
Exit 0 may carry "chat" (Quick questions); with no card send it
is type: "chat" and actions is empty. Exit 0 may also carry
"workspace" (changes since you last heard, each once, with a
+1 -1
View File
@@ -73,7 +73,7 @@ export function useCli(cli) {
// PLAN2CODE_CONSOLE_TRACE=1 prints where the time goes, to stderr: the
// start path is what stands between someone and their first look at the page,
// and it is only worth optimising with numbers in hand.
// and it is only worth optimizing with numbers in hand.
const TRACE = Boolean(process.env.PLAN2CODE_CONSOLE_TRACE);
function trace(what) {
if (TRACE) process.stderr.write(`trace ${Math.round(performance.now())}ms ${what}\n`);
+2 -2
View File
@@ -50,9 +50,9 @@ first, and post before anything slow.
`state.scan` is `{ hasAgents, isGit, pending, specs: [{ dir, name, state, detail, touched }], handoffs, handoffsDir }`,
a snapshot of the last `open` (a spec created mid-session appears the next time
the session resumes as a dashboard). `pending` is how many files a commit would
take (`null` when git cannot say): the Git card never greys out, shows the count
take (`null` when git cannot say): the Git card never grays out, shows the count
when there is one, and outside a repository says Git can start one. The picker
greys the cards that do not fit the selected spec — or hides them, while the
grays the cards that do not fit the selected spec — or hides them, while the
**Hide unavailable workflows** switch under it is on (the default).
The `menu` you post (`note`, `recommend`, `details`) describes the initially
+1 -1
View File
@@ -59,7 +59,7 @@ export class NotepadError extends Error {
/* ------------------------------------------------------------------ names */
// `<folder-name>-<first 12 hex of sha256(foldKey(folder))>`: recognisable in a
// `<folder-name>-<first 12 hex of sha256(foldKey(folder))>`: recognizable in a
// file browser, safe on every OS, and one notepad per folder however its case
// is typed where the file system ignores case.
export function notepadKey(folder) {
+4 -4
View File
@@ -64,7 +64,7 @@ answer. `__git` names no question, like `__stop`.
| `plan` says | On the page |
| --- | --- |
| `confirm` | A `confirm` card with its `title`, `body`, `danger` and `consequences` verbatim (the consequences end with the exact command). Where the plan names files, add them as `files: [{ "path", "state" }]`. |
| `card.kind: "switch"` | A `choice`, "Bring your changes?": exactly the `options` given, labelled **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); the files in `body`, and `reason` when git would refuse (then there is no `bring`). `allowOther: false`. |
| `card.kind: "switch"` | A `choice`, "Bring your changes?": exactly the `options` given, labeled **Switch and bring them** (`bring`), **Commit first** (`commit-first`), **Cancel** (`cancel`); the files in `body`, and `reason` when git would refuse (then there is no `bring`). `allowOther: false`. |
| `card.kind: "dirty"` | The same `choice` for a pull that needs a clean tree: **Commit first** / **Cancel**, `reason` in `body`. |
| `card.kind: "remote"` | A `choice`, "Publish to which remote?": one option per remote, `preset` recommended. Then `plan publish --remote <it>` and its `confirm`. |
| `ask: false` | No card: run it on the click. |
@@ -109,9 +109,9 @@ after each commit step (N commits made), and `run: { "event": "git-conflict",
"id": "conflict-<n>" }` once per conflict help, resolved or aborted.
**Finishing** (`console-finish.md`). **Done with git** (`op: "done"`). A `done`
that arrives while one of your cards is still open is the person cancelling it:
record that card as cancelled (`{ "items": [{ "id": "<id>", "status":
"answered", "answer": { "text": "Cancelled by Done with git" } }] }`, not
that arrives while one of your cards is still open is the person canceling it:
record that card as canceled (`{ "items": [{ "id": "<id>", "status":
"answered", "answer": { "text": "Canceled by Done with git" } }] }`, not
`settle`, which refuses a card nothing was sent to) in the same post as the
finish, or, with nothing done, before resuming as the dashboard. Never run what
the card was asking for. With something done this session: a `finish` with a
+1 -1
View File
@@ -8,7 +8,7 @@
import { spawn } from "node:child_process";
/** The link to open, normalised, or null when it is not a plain http or https link. */
/** The link to open, normalized, or null when it is not a plain http or https link. */
export function linkToOpen(raw) {
if (typeof raw !== "string" || raw.length > 4096) return null;
let url;
+1 -1
View File
@@ -249,7 +249,7 @@ export function pickerCommand(start, prompt) {
* Show the picker and settle on what the person did: `{ path }` for a pick,
* `{ cancelled: true }` when they closed it, `{ error }` when the picker
* itself failed or this OS has none. Pickers exit 0 or 1 with nothing printed
* when cancelled.
* when canceled.
*/
export function pickFolder(start, prompt, { spawnImpl = spawn } = {}) {
const picker = pickerCommand(start, prompt);
+4 -4
View File
@@ -244,7 +244,7 @@ export function suggestionFrom(item) {
if (!raw) return "";
const stripped = raw.replace(EXAMPLE_LEAD, "").trim();
if (!stripped) return "";
// Recapitalise only when a lead-in was actually removed, and never on a
// Recapitalize only when a lead-in was actually removed, and never on a
// field with a shape to match: "audit-export" must not become "Audit-export".
if (stripped !== raw && !item.pattern && /^[a-z]/.test(stripped)) {
return stripped[0].toUpperCase() + stripped.slice(1);
@@ -358,7 +358,7 @@ export function stopAction({ handoff } = {}) {
* answers into the files, and a request landing then is how a question ends up
* half recorded. `waiting` is the caller's "the agent is working or a reply is
* owed, and it has not gone adrift" -- an agent that has stopped checking in
* never replies, and a button greyed out forever would lock the person in. An
* never replies, and a button grayed out forever would lock the person in. An
* uncollected send still blocks even then, because the server takes one at a
* time.
*/
@@ -665,7 +665,7 @@ export function dashNoteKind({ menu, hasMenu, onInitial, working }) {
* availability — but its folder still goes along on a Pathfinder or Plan
* launch, since the files may be reference docs.
*
* Returns { on, reason?, note?, next? } — `reason` is the one line a greyed card
* Returns { on, reason?, note?, next? } — `reason` is the one line a grayed card
* shows, `note` the one line a clickable card shows when there is something to
* know before launching it, `next` marks the state's natural step. `lookup` is
* stateFor unless a test hands in its own table.
@@ -681,7 +681,7 @@ export function cardAvailability(entry, scan, sel, lookup = stateFor) {
if (entry.skill === "plan2code-init") return hasAgents ? off(rule.greyed.default) : ON;
if (entry.skill === "plan2code-init-update") return hasAgents ? ON : off(rule.greyed.default);
if (entry.skill === "plan2code-git") {
// Never greyed: a clean tree still has branches to switch, pull and push.
// Never grayed: a clean tree still has branches to switch, pull and push.
if (scan && scan.isGit === false) return { on: true, note: GIT_INIT_NOTE };
if (scan && Number.isInteger(scan.pending) && scan.pending > 0) return { on: true, note: pendingNote(scan.pending) };
return ON;
+2 -2
View File
@@ -1,4 +1,4 @@
// Planny's wake-up on a freshly opened dashboard: he sits powered down centre
// Planny's wake-up on a freshly opened dashboard: he sits powered down center
// stage until the first click or key, gets nudged awake (he rocks side to side
// for one snore), then about five seconds of him powering on, then a glide
// into the rail as the menu comes in.
@@ -68,7 +68,7 @@ export function playWake({ stage, bot, target, skipEl, stir, onStart, onGlide, o
// between the two top-left corners and the scale is the width ratio.
// The target's own box, not its bounding rect: the rail's Planny is
// usually tilted mid-flight, and a tilted box measures wider than he
// is. Centred on the rect, which the tilt barely moves.
// is. Centered on the rect, which the tilt barely moves.
const from = bot.getBoundingClientRect();
const rect = target.getBoundingClientRect();
const w = target.clientWidth || rect.width;
+1 -1
View File
@@ -147,7 +147,7 @@ const ABOUT_HISTORY = 3;
*
* The tracker is `{ history, about }`; each entry and `about` are
* `{ kind, id, label }` (`about` may be null), in the exact shape POST /chat
* takes. An old `{ about, frozen, dropped }` tracker normalises to an empty
* takes. An old `{ about, frozen, dropped }` tracker normalizes to an empty
* history.
*/
export function nextAbout(prev, event) {
+2 -2
View File
@@ -12,7 +12,7 @@
// className, id, type, value, checked, disabled, textContent, placeholder,
// title, open, href, target, rel, tabIndex. Text runs are h.el("span", null, text).
//
// Every button, input and select is made through control(), which greys it
// Every button, input and select is made through control(), which grays it
// out whenever controlAllowed(mode, role) says no and stamps data-gate with
// its role; one disabled for a reason of the view's own also carries
// data-own. The guard test in scripts/test-web-console-git-board.mjs holds
@@ -64,7 +64,7 @@ function control(ctx, tag, className, label, { role = "action", onClick, onInput
return node;
}
// A copy button is a control like any other: greyed while busy.
// A copy button is a control like any other: grayed while busy.
function copy(ctx, text, cls, codeEl) {
const b = ctx.h.copyButton(text, cls, codeEl);
b.setAttribute("data-gate", "action");
+1 -1
View File
@@ -194,7 +194,7 @@ const button = (shown, enabled, label, title) => ({ shown, enabled: shown && ena
/**
* Every board button as `{ shown, enabled, label, title? }`. Pull is enabled
* only with an upstream to pull from; Push shows with an upstream, Publish
* without one. `busy` greys everything out but Done; an operation in
* without one. `busy` grays everything out but Done; an operation in
* progress hides everything but Done (its banner carries Abort / Continue).
*/
export function boardActions(git, { busy = false } = {}) {
+2 -2
View File
@@ -7,11 +7,11 @@
// that reads and writes the user's files and holds the session cookie. Script
// running here could post arbitrary answers back to the agent, which would then
// act on them with the agent's full tool permissions. And the markdown is only
// nominally agent-authored: in practice the agent is summarising a dependency
// nominally agent-authored: in practice the agent is summarizing a dependency
// README, a scraped page, a PR description, a log. Treat it as hostile.
//
// Building nodes rather than parsing a string makes injection structurally
// impossible instead of filtered, so there is nothing for a sanitiser bypass to
// impossible instead of filtered, so there is nothing for a sanitizer bypass to
// bypass. `html` tokens render as visible text, on purpose.
import { marked } from "./vendor/marked.esm.js";
+3 -3
View File
@@ -245,7 +245,7 @@ export function buildPager(item) {
// Once this question is answered, the step is the next unanswered one, not
// Send. Send lighting up the moment a single answer is staged pulls people
// into sending one question at a time, which is three round trips where the
// workflow wanted one. So the emphasis moves to whichever neighbour still
// workflow wanted one. So the emphasis moves to whichever neighbor still
// needs them, and Send goes quiet until nothing does.
const here = Boolean(page.local.staged[item.id]);
const nextT = open[at + 1];
@@ -257,7 +257,7 @@ export function buildPager(item) {
const leadNext = here && needs(nextT);
const leadPrev = here && !leadNext && needs(prevT);
// An end of the queue is an empty slot, not a disabled button. A greyed
// An end of the queue is an empty slot, not a disabled button. A grayed
// "Previous" pointing at nothing is a control that exists only to say no.
const mk = (target, back, lead) => {
if (!target) return el("span", "pager-slot");
@@ -1348,7 +1348,7 @@ function buildList(card, item, staged) {
// over the array from render time. A reorder replaces that array, so a stale
// closure would quietly undo the reorder the next time a rename committed.
// A name still being typed counts too: the tool buttons below keep the
// field's focus (their mousedown is cancelled), so its `change` has not
// field's focus (their mousedown is canceled), so its `change` has not
// fired yet when they act, and the re-render would otherwise drop it.
const ul = el("ul", "rows");
const baseRows = () => {
+2 -2
View File
@@ -225,7 +225,7 @@ export function renderDashboard(main) {
if (!page.local.launching && !page.launchScoping && wantScope !== page.scopeMine) hooks.syncWorkspaceScope();
// "Unavailable" is the scan's verdict for the selected spec, not the
// momentary greying while a launch is in flight or the server is away, so
// momentary graying while a launch is in flight or the server is away, so
// cards never blink out of the menu mid-handoff.
const hide = looks.hideUnavailable;
const sel = selSpec();
@@ -640,7 +640,7 @@ function dashCard(entry, menu) {
const presentation = cardPresentation(entry, scan(), selSpec(), menu);
// The agent's `recommend` and detail describe the initially selected spec.
// Other picker choices derive both from the scan, so stale context never
// follows a person to a different spec or to "start from scratch". A greyed
// follows a person to a different spec or to "start from scratch". A grayed
// recommendation also yields to the selected spec's actual next step.
const going = page.local.launching && (page.local.launching.skill === entry.skill || page.local.launching.skill === entry.review);
const b = el(
+1 -1
View File
@@ -333,7 +333,7 @@ async function reorder(order, focus) {
}
// A tab is no longer there (deleted here, or from another page): off the bar,
// its unsaved text dropped without a save, and its neighbour on screen.
// its unsaved text dropped without a save, and its neighbor on screen.
async function gone(id, index = tabs.findIndex((t) => t.id === id), announce = true) {
const here = id === activeId;
if (here || id === saveTab) discard();
+1 -1
View File
@@ -21,7 +21,7 @@ const LAUNCH_QUIPS = [
let launchTicker = null;
// Planny flies centre stage: the same drawing as the dock's, cloned so the
// Planny flies center stage: the same drawing as the dock's, cloned so the
// markup stays the single source of him, and the same sky the dock fills.
function flightStage() {
const stage = el("div", "launch-stage");
+1 -1
View File
@@ -33,7 +33,7 @@
// always on whatever is picked; null for no card
// marksNext the card can be a state's natural next step, so its answer
// always says whether it is (`next`)
// greyed its greyed reasons: `default`, plus one per state whose
// greyed (the field keeps its old spelling) its grayed reasons: `default`, plus one per state whose
// wording differs, and `finished` for any finished state
// (spec-states.js); Init and Init update use `default` for the
// AGENTS.md check, which is a rule on the scan, not on the spec
+2 -2
View File
@@ -2,7 +2,7 @@
//
// Each spec state the dashboard scan can report; data only, imported by the
// page and by Node. In the order the scan's SPEC_STATES lists them. Which
// cards a state lights or greys lives on the skill list (skills.js), and how
// cards a state lights or grays lives on the skill list (skills.js), and how
// a folder's files map to a state stays with the scan (classifySpec in
// scan.mjs). No imports and no DOM access: nothing runs at load but building
// the frozen data.
@@ -14,7 +14,7 @@
// null when it has none
// finished the work is done: the spec is hidden while unavailable
// workflows are, never the picker's default, deleted after one
// confirm, and greyed with the card's `finished` reason
// confirm, and grayed with the card's `finished` reason
// (skills.js) on the cards that would otherwise take it
function state(label, next, finished = false) {
+4 -4
View File
@@ -51,7 +51,7 @@ export const TEMPLATES = Object.freeze({
"The engineers who will build and review it.",
"",
"## What it should pin down",
"The behaviour, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"The behavior, the parts of the code it touches, the interfaces between them, the simpler options we're turning down, and how we'll know it works.",
"",
"## Out of scope",
"[what this deliberately won't do]",
@@ -181,7 +181,7 @@ export const TEMPLATES = Object.freeze({
"[the screen or component]",
"",
"## What looks or feels off",
"[spacing, alignment, colour, states, small screens]",
"[spacing, alignment, color, states, small screens]",
"",
"## What good looks like",
"[a reference, screenshot or description]",
@@ -204,7 +204,7 @@ export const TEMPLATES = Object.freeze({
]),
"add-a-test": template("add-a-test", "Add a test", [
"## Add a test",
"[the function, behaviour or bug]",
"[the function, behavior or bug]",
"",
"## Cases to cover",
"- [the normal case]",
@@ -234,7 +234,7 @@ export const TEMPLATES = Object.freeze({
"## Why now",
"[what the current shape makes hard]",
"",
"## Behaviour that must not change",
"## Behavior that must not change",
"[the public API, outputs or tests that must stay the same]",
"",
"## Done when",
+1 -1
View File
@@ -33,7 +33,7 @@
padding: 18px 22px;
display: flex; flex-direction: column; gap: 10px;
}
/* An empty conversation's starter questions, centred where the list is empty. */
/* An empty conversation's starter questions, centered where the list is empty. */
.ask-starters { display: flex; flex-direction: column; gap: 6px; margin: auto 0; width: 100%; max-width: 520px; align-self: center; }
.ask-starters-lead { color: var(--ink-3); font-size: 13.5px; margin: 0 0 4px; text-align: center; }
.ask-starter {
+6 -6
View File
@@ -26,7 +26,7 @@
font-size: 14px;
}
.dash-nudge-text { flex: 1 1 16em; }
/* The session meter at red: the same slot, in the careful colour. */
/* The session meter at red: the same slot, in the careful color. */
.dash-nudge.meter-banner {
background: var(--warn-soft);
border-color: var(--warn);
@@ -57,7 +57,7 @@
cursor: pointer;
}
.update-banner-open:hover { text-decoration: underline; }
/* Pinned to the right edge, out of the flow, so the label centres on the
/* Pinned to the right edge, out of the flow, so the label centers on the
whole banner rather than on what the × leaves of it. */
.update-banner-dismiss {
position: absolute;
@@ -239,7 +239,7 @@
.dash-card-go { color: var(--accent); font-weight: 700; transition: transform 0.15s ease; }
.dash-card:hover:not(:disabled) .dash-card-go { transform: translateX(3px); }
/* The reason a card is off. The card greys via :disabled; this line is why,
/* The reason a card is off. The card grays via :disabled; this line is why,
so the menu teaches the pipeline instead of just refusing clicks. */
.dash-card-off { font-size: 12px; color: var(--ink-3); font-style: italic; }
@@ -276,7 +276,7 @@
}
.spec-chip:not(.is-sel) .spec-chip-state { color: var(--ink-3); }
.spec-chip-detail { font-size: 11.5px; color: var(--ink-3); }
/* A handoff in the picker: the same lozenge, dashed, in the stage colour. */
/* A handoff in the picker: the same lozenge, dashed, in the stage color. */
.spec-chip.is-handoff { border-style: dashed; }
.spec-chip.is-handoff .spec-chip-state, .spec-chip.is-handoff:not(.is-sel) .spec-chip-state { color: var(--stage); }
.spec-chip.is-handoff.is-sel { border-style: solid; border-color: var(--stage); }
@@ -379,7 +379,7 @@
/* ------------------------------------------------- dashboard confirm */
/* The beat between "I clicked a card" and "it is running": what the pick is,
what it will do, and a START that means it. Narrower than the menu, centred
what it will do, and a START that means it. Narrower than the menu, centered
like the launching pane it precedes. */
.dash-confirm {
max-width: 560px;
@@ -448,7 +448,7 @@
mask-image: radial-gradient(120% 100% at 50% 40%, #000 42%, transparent 78%);
}
.launch-sky { opacity: 0.9; }
/* The dock only animates its stars while .is-flying; centre stage they are
/* The dock only animates its stars while .is-flying; center stage they are
the show, so the flight runs unconditionally. */
.launch-stage .sky .star { animation: star-fly var(--dur, 5s) linear var(--delay, 0s) infinite; }
+2 -2
View File
@@ -91,8 +91,8 @@
.presets-label { font-size: 12.5px; color: var(--ink-3); }
/* "Before you close this": three rows on every finished screen. The icon sits
in a coloured circle and the label says the same thing, so no meaning rests
on colour alone. */
in a colored circle and the label says the same thing, so no meaning rests
on color alone. */
.handoff-guide {
margin: 20px 0 0; padding: 14px 16px;
background: var(--panel-2); border: 1px solid var(--rule-2); border-radius: var(--radius);
+1 -1
View File
@@ -25,7 +25,7 @@
it does not stretch), so a note box grows with what is typed instead, where
the browser can, rather than scrolling inside a 96px box. */
.git-cards > .card textarea { field-sizing: content; max-height: 50vh; }
/* The card and the pager centre themselves with auto inline margins, and a
/* The card and the pager center themselves with auto inline margins, and a
grid item with auto margins shrinks to its content, so a short confirm sat
narrow in the middle of the board. In the slot both fill the board's width
instead; the slot's gap spaces them. */
+1 -1
View File
@@ -144,7 +144,7 @@
.help-mood-bot { width: 40px; height: 56px; }
.help-mood span { font-size: 12.5px; color: var(--ink-2); text-align: center; }
/* The travelling highlight on the flow diagrams: only on the visible panel,
/* The traveling highlight on the flow diagrams: only on the visible panel,
only while the dialog is open, and only when the system allows motion.
Otherwise the dashes simply sit still. */
@media (prefers-reduced-motion: no-preference) {
+1 -1
View File
@@ -101,7 +101,7 @@
/* The full-screen preview: the whole viewport, the picture contained in it,
on a near-black backdrop in both themes (a picture is judged against dark,
whatever the page's theme), so its colours are fixed, not tokens. */
whatever the page's theme), so its colors are fixed, not tokens. */
.modal.notepad-preview {
inset: 0;
width: 100vw;
+5 -5
View File
@@ -153,7 +153,7 @@
@keyframes foot-step-a { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-1.1px); } }
@keyframes foot-step-b { 0%, 100% { transform: translateY(-1.1px); } 50% { transform: translateY(0); } }
/* Something for you to do: star lit in the highlight colour, a wave. */
/* Something for you to do: star lit in the highlight color, a wave. */
.planny.is-point { animation: planny-lean 2.6s ease-in-out infinite; }
.planny.is-point .eye { fill: var(--accent); }
@@ -167,7 +167,7 @@
/* The server is up, but nothing is answering at the other end of it. Not the
faded, eye-shut `gone` look: this page is working perfectly, and the thing
that is not is somewhere else. Grey, still, and no arms: he has nothing to
that is not is somewhere else. Gray, still, and no arms: he has nothing to
do with them until someone answers. */
.planny.is-adrift .eye { fill: var(--ink-3); animation: none; }
.planny.is-adrift .smile { opacity: 0.6; }
@@ -178,7 +178,7 @@
.planny.is-done .eye { fill: var(--ok); animation: none; }
.planny.is-done .smile { stroke-width: 1.5; }
/* No server: faded, eye shut in the warning colour, arms hanging. */
/* No server: faded, eye shut in the warning color, arms hanging. */
.planny.is-gone { opacity: 0.5; }
.planny.is-gone .eye { fill: var(--warn); animation: none; transform: scaleY(0.12); }
@@ -293,13 +293,13 @@
/* ------------------------------------------------------------ wake-up
A freshly opened dashboard: Planny powers on centre stage, then glides
A freshly opened dashboard: Planny powers on center stage, then glides
into the rail (boot.js). Each beat is a keyframe on a delay under
`.booting`, one class for the whole run; the glide's target depends on
where the rail sits, so boot.js hands it over as --wake-glide. The layer
takes clicks so none lands on a card underneath while he wakes. */
.wake { position: fixed; inset: 0; z-index: 45; pointer-events: auto; }
/* Solid page colour behind the sleeping bot, following light/dark via --bg. */
/* Solid page color behind the sleeping bot, following light/dark via --bg. */
.wake::before { content: ""; position: absolute; inset: 0; background: var(--bg); }
.wake[hidden] { display: none; }
.wake-bot {
+6 -6
View File
@@ -2,7 +2,7 @@
/* ------------------------------------------------------------- banner */
/* A pill floated over the footer, centred on the bar. It used to be the top
/* A pill floated over the footer, centered on the bar. It used to be the top
grid row, and every time it appeared it pushed the whole page down a track;
overlaying it means the message lands without the layout moving under the
reader's cursor. It covers the footer's middle while it is up, which is
@@ -100,8 +100,8 @@
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
/* The session meter: a ring that fills with the points and a few words, in
the level's colour. Green, amber and red are the page's own done / staged /
careful colours, so both themes are covered by the variables. */
the level's color. Green, amber and red are the page's own done / staged /
careful colors, so both themes are covered by the variables. */
.meter-slot { position: relative; flex: none; align-self: center; }
.meter-pill {
--m: var(--ok);
@@ -478,8 +478,8 @@ h1 {
/* ------------------------------------------------------------- footer */
/* Three columns: summary, where, actions. Equal side tracks keep the middle
centred on the bar, and because they are tracks rather than an overlay, a
long summary wraps and a wide actions block nudges the centre over instead
centered on the bar, and because they are tracks rather than an overlay, a
long summary wraps and a wide actions block nudges the center over instead
of either running underneath it. The middle track gives way first: it can
shrink to an ellipsis, the summary and Send never do. */
.footer {
@@ -490,7 +490,7 @@ h1 {
}
.footer-summary { min-width: 200px; font-size: 13.5px; color: var(--ink-2); }
.footer-summary strong { color: var(--ink); }
/* Where this session is running: the workspace label, centred on the bar. A
/* Where this session is running: the workspace label, centered on the bar. A
click opens the Workspace dialog. The notification pill sits over the same
spot and covers it while it shows. */
.footer-where {
+2 -2
View File
@@ -1,4 +1,4 @@
/* tokens.css: Colours, type, sizes and the light and dark themes: the variables every other file reads. */
/* tokens.css: Colors, type, sizes and the light and dark themes: the variables every other file reads. */
/* Plan2Code Console.
Light by default, dark when the system asks. No external fonts: the page must
@@ -24,7 +24,7 @@
--warn: #9c3327;
--warn-soft: #fbe7e3;
--focus: #1f6feb;
/* Rank colours for low / mid / high badges (a helper's strength and effort). */
/* Rank colors for low / mid / high badges (a helper's strength and effort). */
--lvl-1: #23716a;
--lvl-1-soft: #e1f1ee;
--lvl-2: #9a6a12;
+3 -3
View File
@@ -11,7 +11,7 @@ import { SKILLS, subagentsFor } from "./skills.js";
// The skills that offer the switch, each with its instruction: an entry's
// `subagents` in skills.js is the one place a skill opts in (FR-1). Wording is
// behaviour-level and names no harness tool, so any agent can follow it or
// behavior-level and names no harness tool, so any agent can follow it or
// harmlessly ignore it.
export const SUBAGENT_WORKFLOWS = Object.freeze(
Object.fromEntries(
@@ -222,7 +222,7 @@ export function switchLabel(frame) {
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended, and a reported strength or
// effort as one line ("Standard, medium effort") plus a badge each, ranked 1-3
// so the page can colour them (0 for the session's own model, which has no rank).
// so the page can color them (0 for the session's own model, which has no rank).
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
@@ -248,7 +248,7 @@ export function helperRows(helpers) {
}
const HELPER_STRENGTH_WORDS = Object.freeze({ light: "Light", standard: "Standard", strongest: "Strongest", inherit: "Session model" });
// Each value's rank for its badge colour; the session's own model has none.
// Each value's rank for its badge color; the session's own model has none.
const HELPER_STRENGTH_LEVELS = Object.freeze({ light: 1, standard: 2, strongest: 3, inherit: 0 });
const HELPER_EFFORT_LEVELS = Object.freeze({ low: 1, medium: 2, high: 3 });
+4 -4
View File
@@ -54,7 +54,7 @@ import { handle } from "./routes.mjs";
import { checkForUpdate } from "./update-check.mjs";
const args = parseArgs(process.argv.slice(2));
// Canonicalise before anything derives a path from it: a session dir reached
// Canonicalize before anything derives a path from it: a session dir reached
// through a junction or a subst'd drive is watched under the wrong spelling,
// which is the libuv assert described below. The native realpath resolves
// those AND expands 8.3 short names, which lets the watcher run in a TEMP
@@ -251,7 +251,7 @@ const subagents = serverSubagents({ dir: DIR, worktree: sessionWorktree });
// process's whole life (the env var that says so is set once, at spawn), so
// read once rather than on every frame. The page uses it to drop advice that
// only makes sense in a plain terminal (a command to copy into a new
// conversation) in favour of the app's own Restart and Update skills buttons.
// conversation) in favor of the app's own Restart and Update skills buttons.
const IN_APP = Boolean(inAppSignal());
// What the page needs to draw itself, in the shape of the SSE state frame.
@@ -525,12 +525,12 @@ setInterval(() => {
// This is the mechanism, not a nicety.
//
// Windows has no real SIGTERM, Node only synthesises SIGINT for Ctrl+C on an
// Windows has no real SIGTERM, Node only synthesizes SIGINT for Ctrl+C on an
// attached console, and this process is detached with no console at all.
// taskkill /F and Task Manager give zero cleanup opportunity. A Job Object with
// KILL_ON_JOB_CLOSE would be the proper fix and needs native code, which is out
// under zero-dependencies. So the only thing that reliably stops an orphan is
// the server deciding to stop. Do not "optimise" this away.
// the server deciding to stop. Do not "optimize" this away.
setInterval(() => {
const idle = Date.now() - lastContact;
// Answers nobody has collected yet keep the server up (bounded by MAX_LIFE_MS):
+1 -1
View File
@@ -1,4 +1,4 @@
// Plan2Code Web Console - serving the page's own files: the allow-list, types, caching and the accent colours.
// Plan2Code Web Console - serving the page's own files: the allow-list, types, caching and the accent colors.
import fs from "node:fs";
import path from "node:path";