From 13ba3784e2be024bf0f9bae875e7ad091c928f81 Mon Sep 17 00:00:00 2001 From: Pierrick Bignet Date: Tue, 3 Nov 2026 23:39:07 +0100 Subject: [PATCH 1/5] docs(tasks): spec the crewmate becoming the mason Co-Authored-By: Claude Opus 5.5 --- ...261103-2338-crewmate-becomes-mason.spec.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md b/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md new file mode 100644 index 0000000..2d0a7db --- /dev/null +++ b/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md @@ -0,0 +1,126 @@ +# The Crewmate becomes the Mason, and the Typist ticks only what really ran + +**Status:** ready + +--- + +> πŸ§‘ **REVIEW CAREFULLY** β€” human decision surface. Read it all before code. + +## Context + +Two requests from the Owner, Pierrick, on 2026-11-03. + +**The rename.** In the Harness that runs chisel's projects, "crewmate" +names the per-task session a secondmate launches, and that session plays +chisel's **Architect**. Chisel used the same word for the sub-agent the +Architect launches to plan and close a task. One word for two roles made a +plan reading get skipped (task chisel-intentions). The Owner's words: +"Chisel must not talk about a crewmate. Architect β†’ Mason β†’ Typist." The +**Mason** is the Harness's builder: the sub-agent the Architect launches to +build. + +**The Typist line.** A project equipped with chisel reported, on task +id-by-rivoli: a Typist ticked "run charger.py for real" after running it +only on a throw-away test base. The work document's checkboxes are a fresh +session's resume point, so a false tick skips a step without anyone +seeing it. + +## Scope + +**Included:** +- Rename the role Crewmate β†’ Mason, and every derived word ("The Crewmate + brief", "Crewmates", the `crewmate` actor of `chisel-beads`), in: the + socle (`socle/agents/`, `socle/templates/`), its dogfooded copy + (`.agents/`), `AGENTS.md`, `README.md`, `PHILOSOPHY.md`, `CHARTER.md`, + the task templates of `project-management/`. +- One line in "The Typist brief" of `workflow.md`: a box is ticked only + for what really ran, on the real target; a dry run or a run on a copy + is written in the worklog. +- A `migration` intention in `socle/intentions/unreleased/`, listed in + `src/socle-files.ts`: an equipped repo renames "Crewmate" in its own + files (its `.agents/project.md`, open specs and work documents, its own + skills); the managed files arrive by the update's copy. + +**Not Included:** +- History keeps its words: `CHANGELOG.md`, `project-management/archive/`, + `project-management/JOURNAL.md`, `project-management/review-360-decisions.md`, + the published intentions (`socle/intentions/0.2.0/`, `0.3.0/`), their + file names in `src/socle-files.ts`, and the intention ids recorded in + `.agents/.chisel.json`. +- Any change of what the role does. Only its name changes. + +## Acceptance Criteria + +- [ ] **no-crewmate-outside-history** β€” `git grep -il crewmate` lists only + the history files of "Not Included", the new intention (it names the + old word to find it), and this task's own documents. +- [ ] **no-crewmate-idea-left** β€” a case-insensitive `git grep -w crew` + outside history finds nothing that names the role. +- [ ] **typist-ticks-what-ran** β€” "The Typist brief" of + `socle/agents/workflow.md` carries the tick rule: real run, real target, + dry run or copy in the worklog. +- [ ] **socle-copy-identical** β€” `diff -r .agents socle/agents` shows only + `.chisel.json`, `project.md`/`project.md.tpl` and `skills/chisel-release`. +- [ ] **intention-ships** β€” `socle/intentions/unreleased/crewmate-becomes-mason.md` + follows `socle/intentions/TEMPLATE.md`, classification `migration`, and + is listed in `src/socle-files.ts`. +- [ ] **gates-green** β€” `deno task check` and `deno task test` pass. + +## Seams + +- The managed socle files an equipped repo receives β€” the role reads + "Mason" everywhere a repo installs or updates. +- The intention β€” the page an update session reads to rename the word in + the project's own files. + +## Architecture + +**System design:** a word swap across prose, plus one sentence and one new +intention. The socle under `socle/` is the source; `.agents/` is its copy +and is kept byte-identical for the shared files. + +--- + +> πŸ§‘ **REVIEW IF RELEVANT** β€” decisions, testing, slicing. + +## Implementation Decisions + +- **The word.** "Mason" in English, capitalised like the other roles; + plural "Masons"; the brief section is "The Mason brief"; the + `chisel-beads` actor is `mason`. +- **Read, not replaced blindly.** A sentence where the swap reads badly + ("a Mason", article and rhythm) is rewritten, not just patched. +- **The tick rule** sits in "The Typist brief" as a positive bullet; step + 5 of `workflow.md` keeps "tick as work lands" and does not repeat it. +- **The intention's classification** is `migration`: an agent acts on the + project's own files, the human validating each rename. Its old state + signal is `git grep -i crewmate` outside the managed files and the + project's history. +- Prose written for agents passes through the `writing-for-agents` skill. + +## Testing Strategy + +- No test reads the prose. The criteria above are greps and diffs; the + existing suite guards `src/socle-files.ts` and the intention format. + +## Slices & Dependencies + +- **Slices:** one pass. + +## Deliverables + +- [ ] The renamed socle and its copy, the docs and templates +- [ ] The Typist line +- [ ] The intention +- [ ] A pull request in conventional commits + +## References + +- `.agents/workflow.md`, "The roles" and "The Typist brief" β€” the role and + the brief to change. +- `CONTRIBUTING.md`, "Intention authoring" β€” how an intention ships. +- `socle/intentions/TEMPLATE.md` β€” the intention format. + +## Notes + +## Retrospective From 0b655b426936e6c8e3bf1d59cd4ce1c1b6eb252a Mon Sep 17 00:00:00 2001 From: Pierrick Bignet Date: Tue, 3 Nov 2026 23:44:05 +0100 Subject: [PATCH 2/5] feat(socle): the crewmate becomes the mason "Crewmate" names the Harness's per-task session that plays the Architect; the sub-agent the Architect launches takes the name Mason, so one word stops standing for two roles. Co-Authored-By: Claude Opus 5.5 --- .agents/methodology.md | 6 +- .agents/reference.md | 8 +- .agents/skills/chisel-beads/SKILL.md | 2 +- .agents/skills/retro/SKILL.md | 2 +- .agents/skills/slice-task/SKILL.md | 4 +- .agents/workflow.md | 40 +-- AGENTS.md | 7 +- CHARTER.md | 12 +- PHILOSOPHY.md | 14 +- README.md | 18 +- project-management/000-template.spec.md | 8 +- project-management/000-template.work.md | 14 +- ...261103-2338-crewmate-becomes-mason.spec.md | 2 +- ...261103-2338-crewmate-becomes-mason.work.md | 297 ++++++++++++++++++ socle/agents/methodology.md | 6 +- socle/agents/reference.md | 8 +- socle/agents/skills/chisel-beads/SKILL.md | 2 +- socle/agents/skills/retro/SKILL.md | 2 +- socle/agents/skills/slice-task/SKILL.md | 4 +- socle/agents/workflow.md | 40 +-- .../unreleased/crewmate-becomes-mason.md | 70 +++++ socle/templates/000-template.spec.md | 8 +- socle/templates/000-template.work.md | 14 +- socle/templates/AGENTS-block.md | 4 +- src/socle-files.ts | 1 + 25 files changed, 481 insertions(+), 112 deletions(-) create mode 100644 project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md create mode 100644 socle/intentions/unreleased/crewmate-becomes-mason.md diff --git a/.agents/methodology.md b/.agents/methodology.md index 69c509c..e847c17 100644 --- a/.agents/methodology.md +++ b/.agents/methodology.md @@ -90,7 +90,7 @@ is that the expensive-to-reverse decisions are made, not that it is small. **Program design** β€” the target shape inside the agreed architecture: files, seam signatures, test order β€” is deliberately NOT written with the spec. Designing slice 6's files before slices 1–3 have taught anything produces -stale guesses. The Crewmate writes it at the plan step, with the real code +stale guesses. The Mason writes it at the plan step, with the real code in view, and **persists it in the work document** before any code; the Architect reads and approves it there. Three reasons to persist it: @@ -105,7 +105,7 @@ Architect reads and approves it there. Three reasons to persist it: The delegation boundary is the **system design**: above it the *what* β€” architecture, scope, seams β€” settled in the spec; below it the *how*, -designed and typed by the session that implements. A Crewmate asked to +designed and typed by the session that implements. A Mason asked to "figure out" something the *what* left open is a specification failure, and it goes back to the spec. An open *how* is not a hole: it is what the plan step is for. @@ -113,7 +113,7 @@ step is for. Once the plan is approved it is a complete brief, which is what makes a Typist possible: a cheaper model types a settled plan, and the frontier tier is kept for judgement β€” the spec, the plan, the review. So the -Crewmate hands the typing to a Typist by default. A Crewmate that types its +Mason hands the typing to a Typist by default. A Mason that types its own plan pays the frontier price for typing: on 2026-11-03 one of chisel's own tasks ran 383 calls, all at the frontier tier, none of them a Typist's. The brief is **artifacts diff --git a/.agents/reference.md b/.agents/reference.md index b43dd3c..dee8ea5 100644 --- a/.agents/reference.md +++ b/.agents/reference.md @@ -12,7 +12,7 @@ for every session are `.agents/discipline.md`. |---|---| | **Task** | The unit of work. Its spec document lives in the task workspace declared in `.agents/project.md` (default `/project-management/tasks/`), named `-.spec.md`, whatever tracker also carries it; once planned it has a matching `-.work.md` beside it. | | **Spec document** | The review surface and the requirement: intent, acceptance criteria, seams, system design, decisions, testing strategy, slices, deliverables, references, pre-plan Notes and retrospective. It carries the task's status line and the reading gradient's two πŸ§‘ zones. | -| **Work document** | The Crewmate's companion file, created at the plan step beside the spec document. It carries the program design and its approval line, the worklog, the implementation checkboxes, Notes & Snippets and the review findings. No zone marker. | +| **Work document** | The Mason's companion file, created at the plan step beside the spec document. It carries the program design and its approval line, the worklog, the implementation checkboxes, Notes & Snippets and the review findings. No zone marker. | | **Slice** | A child task produced by cutting a large task: a tracer-bullet vertical cut through every layer, demoable on its own, sized for one fresh context window. Lives as `tasks/-/-.spec.md`. A small task IS its own single slice. | | **Seam** | The public boundary where a feature is tested β€” named in the spec BEFORE implementation. Tests live at seams, never against internals. Fewer is better (ideal: one). | | **Reading gradient** | The ordering of the spec document by review criticality: πŸ§‘ REVIEW CAREFULLY (short, decision-rich) β†’ πŸ§‘ REVIEW IF RELEVANT. Detail is never cut, it is ordered. | @@ -22,7 +22,7 @@ for every session are `.agents/discipline.md`. | **Expand–contract** | The sequencing for wide mechanical refactors (rename a column, retype a shared symbol): add the new form beside the old β†’ migrate call sites in batches β†’ delete the old form. The exception to vertical slicing. | | **One-shot** | Work done without a task artifact. The discipline still applies; only the file bookkeeping is skipped. | -The roles β€” Architect, Crewmate, Typist, reviewers β€” are defined in "The +The roles β€” Architect, Mason, Typist, reviewers β€” are defined in "The roles" of `.agents/workflow.md`. We do NOT use the word "ticket" for local work. It is reserved for items in an @@ -36,7 +36,7 @@ decision tickets and resolves them one at a time). A πŸ§‘ zone belongs to whoever **approved** it. The human approves a spec that carries decisions the task did not state; the Architect approves one written from a clear task, and then the zones carry the task's own decisions, which -are the human's. The work document has no zone: it belongs to the Crewmate +are the human's. The work document has no zone: it belongs to the Mason that wrote it. A πŸ§‘ zone is never overridden silently β€” a conflict with one is surfaced, never edited sideways. @@ -47,7 +47,7 @@ the work β€” how much judgement it needs. | Tier | What it is for | Roles | |---|---|---| -| **frontier** | Thinking and reviewing β€” where a wrong judgement is expensive and caught late | Architect, Crewmate, reviewers | +| **frontier** | Thinking and reviewing β€” where a wrong judgement is expensive and caught late | Architect, Mason, reviewers | | **mid** | Ordinary work that needs competence but not judgement | The Typist, by default | | **cheap** | Typing a mechanical plan: every change named down to its file and place, nothing left to choose | The Typist, when the plan is mechanical | diff --git a/.agents/skills/chisel-beads/SKILL.md b/.agents/skills/chisel-beads/SKILL.md index 7991706..d11a67d 100644 --- a/.agents/skills/chisel-beads/SKILL.md +++ b/.agents/skills/chisel-beads/SKILL.md @@ -28,7 +28,7 @@ bd list --status draft # any other status is a filter ```sh bd create "" --type task --priority <0-4> \ --spec-id "" \ - --actor --silent + --actor --silent ``` `--spec-id` is the whole link; the work document's path follows from it. diff --git a/.agents/skills/retro/SKILL.md b/.agents/skills/retro/SKILL.md index f9f8b72..d88d18a 100644 --- a/.agents/skills/retro/SKILL.md +++ b/.agents/skills/retro/SKILL.md @@ -104,7 +104,7 @@ discussed: ### Implementation vs review All work goes through two stages: implementation and review. The -implementation session (the Crewmate writing its program design at the plan +implementation session (the Mason writing its program design at the plan step, then typing it) carries the most context pressure β€” exploration, writing code, debugging failures. The review sub-agents carry the least β€” it receives a diff, no exploration needed. This is why coding standards diff --git a/.agents/skills/slice-task/SKILL.md b/.agents/skills/slice-task/SKILL.md index f0acd76..6f033c6 100644 --- a/.agents/skills/slice-task/SKILL.md +++ b/.agents/skills/slice-task/SKILL.md @@ -89,7 +89,7 @@ where `` comes from `scripts/task-id.sh` and `` numbers the slices from `01` in dependency order (blockers first). The parent spec document (if one exists) stays in place and links to the slice folder. -No work document is created here. The Crewmate that implements a slice creates +No work document is created here. The Mason that implements a slice creates the matching `-.work.md` beside it at its `plan` step, from the work template declared in Β§A Β· Task workspace of `.agents/project.md`. @@ -122,7 +122,7 @@ user's perspective β€” not a layer-by-layer implementation list. ## Notes _A question or a blocker met before the plan β€” only what is written into -this document before its work document exists. Not the Crewmate's working +this document before its work document exists. Not the Mason's working space: its notes, snippets and worklog live in the work document._ diff --git a/.agents/workflow.md b/.agents/workflow.md index a4353ab..d4d2cea 100644 --- a/.agents/workflow.md +++ b/.agents/workflow.md @@ -18,9 +18,9 @@ or a script. | Role | Who plays it | What it does | |---|---|---| -| **Architect** | The agent a human, or an orchestrator, talks to. This is its default role. | Reads the task, writes or sharpens the spec, launches a Crewmate and talks with it, reads and corrects the plan, rules on what the Crewmate reports, brings the key questions to the human. | -| **Crewmate** | A sub-agent launched by the Architect. | Writes the plan in the work document and stops for the Architect's reading. Then launches a Typist to code it, runs `code-review`, and closes the task. | -| **Typist** | A sub-agent launched by the Crewmate once the plan is approved. | Types code from the approved plan and decides nothing, at a cheaper tier than the Crewmate's (`.agents/reference.md`, "Model tiers"). | +| **Architect** | The agent a human, or an orchestrator, talks to. This is its default role. | Reads the task, writes or sharpens the spec, launches a Mason and talks with it, reads and corrects the plan, rules on what the Mason reports, brings the key questions to the human. | +| **Mason** | A sub-agent launched by the Architect. | Writes the plan in the work document and stops for the Architect's reading. Then launches a Typist to code it, runs `code-review`, and closes the task. | +| **Typist** | A sub-agent launched by the Mason once the plan is approved. | Types code from the approved plan and decides nothing, at a cheaper tier than the Mason's (`.agents/reference.md`, "Model tiers"). | | **Reviewers** | Sub-agents launched by the `code-review` skill. | Read the diff with no context from the session that wrote it. | **The human** owns the intent and the decisions that shape the task. The @@ -29,7 +29,7 @@ made goes back to the human, with the question stated. The Architect's thread can be one long thread that compacts and serves as the entry point to a project, or one thread per piece of work. In a long -thread the Architect can run several Crewmates, one per task or slice. +thread the Architect can run several Masons, one per task or slice. ## The steps @@ -52,8 +52,8 @@ The human approves the spec when it carries decisions the task did not state; otherwise the Architect moves it to `ready` itself. Commit the spec. Status: `draft`, then `ready`. -**3. Plan β€” Crewmate.** The Architect launches a Crewmate with the brief -below. The Crewmate reads the spec document and what it links to, creates +**3. Plan β€” Mason.** The Architect launches a Mason with the brief +below. The Mason reads the spec document and what it links to, creates the work document beside it from the work template, and persists its program design there: files, seam signatures, test order, the decisions the spec left to the implementation. Then it stops and reports. No code before @@ -61,13 +61,13 @@ the plan is approved. Status: `in-progress`, written by the Architect at launch. **4. Read the plan β€” Architect.** Read the spec and the work document, -nothing else. Correct the plan with the Crewmate, then approve it: the +nothing else. Correct the plan with the Mason, then approve it: the approval is written on the work document's `**Plan:**` line, with who and when. A plan that departs from a decision the human made goes to the human first. -**5. Code β€” a Typist the Crewmate launches.** Once the plan is approved, -the Crewmate launches a Typist with the brief below. The Crewmate types +**5. Code β€” a Typist the Mason launches.** Once the plan is approved, +the Mason launches a Typist with the brief below. The Mason types itself only a retouch of a few lines, or while the plan is not settled, and writes which exception applies and why in the work document's worklog. The Typist executes the approved plan in vertical steps, test-first at the @@ -77,12 +77,12 @@ and commit at each green step. Run the gate commands declared in `.agents/project.md`. Reality that contradicts the plan is fixed in the plan, in writing; reality that contradicts the spec is reported. -**6. Review β€” Crewmate.** Run the `code-review` skill on the full diff of +**6. Review β€” Mason.** Run the `code-review` skill on the full diff of the task. Its reviewers are fresh sub-agents that never saw the session that wrote the code β€” never skip this step, even for a small retouch. Write the findings in the work document; fix each one or answer it there. -**7. Close β€” Crewmate.** Tick the spec's acceptance criteria against +**7. Close β€” Mason.** Tick the spec's acceptance criteria against reality. Promote evergreen material into the living docs declared in `.agents/project.md`, the glossary and the ADRs among them. Archive the spec and work documents together. Add the dated journal entry. Run the `retro` skill and put its proposals in the @@ -102,8 +102,8 @@ explicit word on that very action is the only go. | Who stops | For whom | When | |---|---|---| -| Crewmate | Architect | After the plan; after the close, with its report; on a blocker it cannot rule on | -| Typist | Crewmate | After its part of the plan; on anything the plan does not answer | +| Mason | Architect | After the plan; after the close, with its report; on a blocker it cannot rule on | +| Typist | Mason | After its part of the plan; on anything the plan does not answer | | Architect | Human | On an unclear intent; on a spec that carries decisions the task did not state; on a plan that departs from the human's decisions; on a blocker above what it owns | | Architect | Human | Before a merge or a publish, unless the project lets the agent do it | @@ -126,7 +126,7 @@ A task has one status. The thread doing a step writes the status it leaves. |---|---|---| | `draft` | The spec is being written, or waits for the human's approval | step 2 | | `ready` | The spec is approved and nothing holds the task | step 2 | -| `in-progress` | A Crewmate is planning, coding, reviewing or closing it | step 3 | +| `in-progress` | A Mason is planning, coding, reviewing or closing it | step 3 | | `done` | Criteria ticked, documents archived | step 7 | | `blocked` | Held by a named dependency, written after the value | whoever meets the block | | `deferred` | Postponed on purpose | the human | @@ -143,21 +143,21 @@ Launch one only for a context that must stay clean, for work that runs in parallel, or for a cheaper model. Each one costs tokens and a brief to write. Three earn it: -- **The Crewmate** keeps the Architect's context clean for reading the plan +- **The Mason** keeps the Architect's context clean for reading the plan and ruling on reports. - **The Typist** types the approved plan on a cheaper tier than the - Crewmate's. + Mason's. - **The reviewers** bring fresh eyes to the diff. A brief is artifacts and paths, never the conversation: whatever the sub-agent needs must already be in the repo. Reviewers are always fresh. A -Crewmate is reused within a live thread β€” the one that wrote the plan +Mason is reused within a live thread β€” the one that wrote the plan launches its Typist and runs the review β€” and a resumed task starts fresh from the spec and work documents. -## The Crewmate brief +## The Mason brief -What the Architect writes when it launches a Crewmate: +What the Architect writes when it launches a Mason: - the spec document's path, and the work template's; - the branch to work on, and how to commit (explicit paths, no push); @@ -169,7 +169,7 @@ What the Architect writes when it launches a Crewmate: ## The Typist brief -What the Crewmate writes when it launches a Typist: +What the Mason writes when it launches a Typist: - the approved work document's path, and the part of the plan to type; - its tier: *cheap* when the plan is mechanical, *mid* otherwise diff --git a/AGENTS.md b/AGENTS.md index df6644d..a7a798a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,8 @@ methodology it ships. record (`project-management/review-360-decisions.md`), the doctrine β€” never in an assistant's private memory: future agents are not necessarily the same assistant (Owner ruling G17, 2026-09-02). Role reuse follows ruling - G16: reviewers fresh, the Crewmate reused within a live thread. + G16: reviewers fresh, the Mason (named the Crewmate in the record) + reused within a live thread. - The canonical socle now lives in `socle/` (imported from the music-downloader pilot at slice 01). @@ -38,9 +39,9 @@ takes one task from its intent to its commit and pull request, in prose: the roles, the steps, where the work stops, the tracker and the statuses. - By default you are the **Architect**: you read the task, write or sharpen - the spec, launch a Crewmate, read its plan, and bring the key questions to + the spec, launch a Mason, read its plan, and bring the key questions to the human. -- Launched as a **Crewmate** or a **Typist**, follow the brief you were +- Launched as a **Mason** or a **Typist**, follow the brief you were given and the matching steps of `.agents/workflow.md`. - Merging and publishing follow the merge and publish section of `.agents/project.md`. By default they wait for the human's explicit word diff --git a/CHARTER.md b/CHARTER.md index 572109d..de6d8f8 100644 --- a/CHARTER.md +++ b/CHARTER.md @@ -22,7 +22,7 @@ has the task, it follows chisel's method to ship it. scheduling tasks, deciding on its own which task runs next: that belongs to the layer above. That layer can be a human, a harness, a long-lived orchestrator thread, or a script. Inside a conversation, the Architect -running the Crewmates of the tasks it was given is part of processing +running the Masons of the tasks it was given is part of processing tasks, not orchestration. **The workflow is prose.** One page describes the steps of a task, who does @@ -56,18 +56,18 @@ field facts behind this page are in the decisions record, | Role | Who plays it | What it does | |---|---|---| -| **Architect** | The agent the user, or an orchestrator, talks to: the project lead. This is its default role; nobody launches an Architect. | Scopes the task, asks the questions, clarifies the spec. Launches a Crewmate, talks with it, arbitrates, reads and corrects the plan. Brings the key questions up to the human. | -| **Crewmate** | A sub-agent launched by the Architect. | Writes the plan from the template, stops for the Architect's reading, then has a Typist code it. Runs the `code-review` skill and fixes what it finds. | -| **Typist** | A sub-agent launched by the Crewmate once the plan is approved. | Types code from the approved plan, decides nothing, on a cheaper model than the Architect and the Crewmate. The Crewmate types itself only a retouch of a few lines, or while the plan is not settled. | +| **Architect** | The agent the user, or an orchestrator, talks to: the project lead. This is its default role; nobody launches an Architect. | Scopes the task, asks the questions, clarifies the spec. Launches a Mason, talks with it, arbitrates, reads and corrects the plan. Brings the key questions up to the human. | +| **Mason** | A sub-agent launched by the Architect. | Writes the plan from the template, stops for the Architect's reading, then has a Typist code it. Runs the `code-review` skill and fixes what it finds. | +| **Typist** | A sub-agent launched by the Mason once the plan is approved. | Types code from the approved plan, decides nothing, on a cheaper model than the Architect and the Mason. The Mason types itself only a retouch of a few lines, or while the plan is not settled. | | **Reviewers** | Sub-agents launched by the `code-review` skill. | Read the diff with no context from the coding session. | **The Architect's thread** is best kept long: one thread that compacts and serves as the entry point to a project, holding the context of several tasks. The article above recommends the same shape for a main agent loop. It can also be one thread per piece of work. In a long thread the Architect -runs several Crewmates, one per task or slice. +runs several Masons, one per task or slice. -**The fixes after a review belong to the Crewmate** that wrote the code, +**The fixes after a review belong to the Mason** that wrote the code, not to the Architect. **A role is a paragraph of the workflow, not a file.** The Architect writes diff --git a/PHILOSOPHY.md b/PHILOSOPHY.md index 658f1b9..ba85e63 100644 --- a/PHILOSOPHY.md +++ b/PHILOSOPHY.md @@ -85,7 +85,7 @@ These are the beliefs chisel is built on: review, to dependent slices, and to re-runs. - **The fewest roles that hold the quality.** Current frontier models are good enough that heavy guidance costs more than it returns. The Architect - scopes the task and reads the plan; a Crewmate plans and closes, a Typist types; + scopes the task and reads the plan; a Mason plans and closes, a Typist types; fresh reviewers read the diff. The **system design is the delegation boundary**: the architecture, the scope and the seams are settled in the spec; the program design and the typing belong to the session that @@ -123,14 +123,14 @@ Three situations, one discipline: there is nothing to file. - **One task** β€” the Architect reads it where it lives (a file, a bead, a Plane issue) and writes the spec document: straight from the task when - it is clear, after an interview when it is not. A Crewmate plans against + it is clear, after an interview when it is not. A Mason plans against the real code, persists the plan in the work document and stops; the - Architect reads and approves it; a Typist codes it; the Crewmate runs the two-axis + Architect reads and approves it; a Typist codes it; the Mason runs the two-axis review and closes (lint/tests/build, the journal, living docs, the tracker). - **A parent task with slices** β€” big features: a parent spec document plus thin vertical slices with dependency edges. Any slice whose blockers are - done can start, each with its own Crewmate and work document. + done can start, each with its own Mason and work document. **The workflow is prose**, one page, as the first version was. **Chisel processes one task and does not orchestrate**: chaining tasks, watching a @@ -181,6 +181,6 @@ and, for the work document, evea-ai), dry-run tested on a third untouched monorepo, and dogfooded by this very repo β€” every chisel feature was built as a slice of its own methodology. An orchestrator thread has run the first version in production -since 2026-08-03: over one milestone, eleven Crewmates each wrote a plan, -stopped for its reading, then typed their own code; every review launched -two fresh reviewers. +since 2026-08-03: over one milestone, eleven planning sub-agents each wrote +a plan, stopped for its reading, then typed their own code; every review +launched two fresh reviewers. diff --git a/README.md b/README.md index e17b17b..88e3b81 100644 --- a/README.md +++ b/README.md @@ -31,23 +31,23 @@ up where another stopped, even after a session dies. - **The Architect** is the agent you talk to: the project lead. It scopes the task, reads the plans, and brings only the key questions to you. - Because the coding happens elsewhere, it can run several Crewmates in + Because the coding happens elsewhere, it can run several Masons in parallel, each in its own worktree, without drowning its context. -- **The Crewmate** is a frontier model that analyses and plans. It +- **The Mason** is a frontier model that analyses and plans. It writes the plan, stops for the Architect's reading, has a Typist code it test first, and closes the task. - **The reviewers** know nothing of the session that wrote the code, and that is the point. They read the diff against your standards and against the spec, with Pocock's `code-review` skill. -- **The Typist** types the approved plan on a cheaper model. The Crewmate +- **The Typist** types the approved plan on a cheaper model. The Mason types itself only a retouch of a few lines, or while the plan is not settled. **Firm rules for the end of a task.** No task closes without the review and your gate commands: lint, tests, build. What an agent may do on its own is -written down: the Crewmate commits but does not push, and merging and +written down: the Mason commits but does not push, and merging and publishing wait for you unless your project hands them over. The close has -its loops too: the Crewmate ticks the acceptance criteria against reality, +its loops too: the Mason ticks the acceptance criteria against reality, updates the living docs, the glossary and the ADRs, writes the journal entry, and proposes what the process should learn. @@ -56,7 +56,7 @@ entry, and proposes what the process should learn. - **Not an orchestrator.** It does not watch your tracker, schedule tasks or decide which one runs next. That is you, or whatever you put above it: a harness, a script, a long-lived thread. -- **Not built for a swarm.** An Architect runs a handful of Crewmates. +- **Not built for a swarm.** An Architect runs a handful of Masons. Ninety in parallel is another world, with other tools. - **Not tied to a tracker.** Task files (the default), beads, Plane, GitHub Issues: the agent only needs the skill or connector that reads and @@ -109,13 +109,13 @@ In practice, a task goes like this. 1. **The Architect reads the task and the code it touches.** When the task is clear, it writes a short spec straight away. When it is not, it asks you questions first. -2. **It launches a Crewmate**, which writes the plan and stops. +2. **It launches a Mason**, which writes the plan and stops. 3. **The Architect reads the plan**, corrects it and approves it. Only the questions that touch your decisions come back to you. 4. **A Typist codes the plan**, test first, on a cheaper model; the - Crewmate then runs the `code-review` skill on the whole diff, with two + Mason then runs the `code-review` skill on the whole diff, with two fresh reviewers. -5. **The Crewmate fixes what they found and closes the task**: criteria +5. **The Mason fixes what they found and closes the task**: criteria ticked, docs updated, an entry in the project journal, a commit, the tracker updated. 6. **The Architect opens the pull request.** Merging and publishing wait for diff --git a/project-management/000-template.spec.md b/project-management/000-template.spec.md index 48a20d2..ccf219f 100644 --- a/project-management/000-template.spec.md +++ b/project-management/000-template.spec.md @@ -14,7 +14,7 @@ cannot be read without is not. The rule is the writing rule of The spec document is the human review surface, the requirement against which a diff is judged, and the archive record of what was asked. It contains no program design, pseudo-code, worklog or implementation checkboxes: these are -in the work document, created at the plan step by the Crewmate. +in the work document, created at the plan step by the Mason. A spec written from a clear task stays short and links the task rather than copying it. A spec with no work document beside it has never been planned. @@ -32,7 +32,7 @@ copying it. A spec with no work document beside it has never been planned. [reference.md](/.agents/reference.md): whoever approved it. - The πŸ§‘ zones carry their owner's decisions. Surface a conflict; never silently contradict one. -- There is no agent zone here. The Crewmate's working space is the work +- There is no agent zone here. The Mason's working space is the work document, a different file. ## The two documents @@ -140,7 +140,7 @@ belongs wholly to the work document. ## Notes Only material written into this file before a work document exists. The -Crewmate's notes, snippets and worklog belong in the work document's +Mason's notes, snippets and worklog belong in the work document's **Notes & Snippets**. ## Retrospective @@ -176,7 +176,7 @@ the `**Status:**` line: 3. Fill both πŸ§‘ zones carefully. 4. Keep the top short; order detail rather than deleting it. 5. At the close, tick acceptance criteria against reality. -6. The Crewmate creates the work document at the plan step, never before. +6. The Mason creates the work document at the plan step, never before. ## When Reviewing Tasks (human) diff --git a/project-management/000-template.work.md b/project-management/000-template.work.md index e6dcbd9..f1bebf0 100644 --- a/project-management/000-template.work.md +++ b/project-management/000-template.work.md @@ -9,14 +9,14 @@ and its section title β€” never a line number, which is wrong by the next edit β€” and says in one sentence what the reader finds there. The rule is the writing rule of `.agents/discipline.md`. -The work document is the Crewmate's own file: its program design and the +The work document is the Mason's own file: its program design and the line that records its approval, its worklog, its implementation checkboxes, its Notes & Snippets, and the findings of the review. No zone marker: the reading gradient does not apply to working material. The reasoning behind the split is "The two designs β€” and why they do not happen at the same moment" of [methodology.md](/.agents/methodology.md). -**Who creates it, when, where, under what name.** The Crewmate creates it at +**Who creates it, when, where, under what name.** The Mason creates it at the plan step, never earlier. It lives beside its spec, named by replacing the spec's `.spec.md` suffix with `.work.md`: same time id (or slice number), same directory. A spec with no work document beside it has never @@ -30,11 +30,11 @@ system has. A parent spec of a sliced task never gets a work document of its own β€” only its slices do. **The Architect reads it and approves the plan.** It corrects the plan with -the Crewmate, then the approval goes on the `**Plan:**` line. Plan approval +the Mason, then the approval goes on the `**Plan:**` line. Plan approval is that line, not a status. **The review writes into it.** `code-review` reports its findings, and the -Crewmate records each one in the Diff-Review Findings section with its fix +Mason records each one in the Diff-Review Findings section with its fix or its answer. ## Work Document Template @@ -44,7 +44,7 @@ All work documents MUST follow this structure: ```markdown # β€” work -Created by the Crewmate at the plan step, . Spec: +Created by the Mason at the plan step, . Spec: `/.spec.md`. **Plan:** waiting for the Architect's reading. @@ -86,7 +86,7 @@ The findings of `code-review`, judged against the spec document with this file as evidence, each with its fix or its answer. ``` -## When Creating a Work Document (the Crewmate) +## When Creating a Work Document (the Mason) 1. Create it at the plan step, never before β€” an open question about the *what* at this point means the spec is unfinished; report it rather than @@ -102,7 +102,7 @@ file as evidence, each with its fix or its answer. ## When Reading a Work Document - The Architect reads the Program Design at the plan step, corrects it with - the Crewmate, and records the approval on the `**Plan:**` line. + the Mason, and records the approval on the `**Plan:**` line. - The reviewers read the spec document as the requirement and this file as evidence. - A fresh session resuming the work reads the implementation checkboxes and diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md b/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md index 2d0a7db..15be3cd 100644 --- a/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md +++ b/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md @@ -1,6 +1,6 @@ # The Crewmate becomes the Mason, and the Typist ticks only what really ran -**Status:** ready +**Status:** in-progress --- diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md b/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md new file mode 100644 index 0000000..2bb60ea --- /dev/null +++ b/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md @@ -0,0 +1,297 @@ +# The Crewmate becomes the Mason, and the Typist ticks only what really ran β€” work + +Created by the Crewmate at the plan step, 2026-11-03. Spec: +`project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md`. + +**Plan:** approved by the Architect, 2026-11-03 23:55. Rulings: (1) PHILOSOPHY.md reads "eleven planning sub-agents"; (2) gap 3 stays, each rename on the human's word; (3) add the informational intention `typist-ticks-what-ran` in the Typist commit. + +## Program Design + +### The files to touch + +The inventory is `git grep -il crewmate` minus the history the spec keeps. +Each socle file and its `.agents/` copy get the same edit, so +`diff -r .agents socle/agents` stays at its three known differences. + +| File (socle source, then its copy) | Occurrences | +|---|---| +| `socle/agents/workflow.md`, `.agents/workflow.md` | 20 lines: roles table, steps 3 to 7 headings and bodies, "Where the work stops", "Statuses", "Sub-agents", "The Crewmate brief" heading and lead, "The Typist brief" lead | +| `socle/agents/methodology.md`, `.agents/methodology.md` | 3 | +| `socle/agents/reference.md`, `.agents/reference.md` | 4 (work document entry, roles line, zones line, model tiers table) | +| `socle/agents/skills/chisel-beads/SKILL.md`, `.agents/skills/…` | 1: `--actor ` | +| `socle/agents/skills/retro/SKILL.md`, `.agents/skills/…` | 1 | +| `socle/agents/skills/slice-task/SKILL.md`, `.agents/skills/…` | 2 | +| `socle/templates/000-template.spec.md`, `project-management/000-template.spec.md` | 4 | +| `socle/templates/000-template.work.md`, `project-management/000-template.work.md` | 7, including the heading "When Creating a Work Document (the Mason)" | +| `socle/templates/AGENTS-block.md`, `AGENTS.md` | 2 in the block; `AGENTS.md` has a third, the G16 line | +| `CHARTER.md` | 6 | +| `README.md` | 9 | +| `PHILOSOPHY.md` | 5 | +| `src/socle-files.ts` | add `intentions/unreleased/crewmate-becomes-mason.md`; the 0.3.0 file name stays | +| new `socle/intentions/unreleased/crewmate-becomes-mason.md` | the intention | + +Left as is, per "Not Included": `CHANGELOG.md`, `project-management/archive/`, +`JOURNAL.md`, `review-360-decisions.md`, `socle/intentions/0.2.0/` and +`0.3.0/`, their entries in `src/socle-files.ts`, and the id +`unreleased/crewmate-cleans-up` in `.agents/.chisel.json`. No test, fixture +or `.agents/project.md` names the role. `git grep -iw crew` outside history +finds only the spec. + +### Sentences that need more than a word swap + +The article and rhythm read the same with "Mason" ("a Mason", "the +Mason's", "Masons") in every line but these two, whose exact new text is +settled: + +- **`PHILOSOPHY.md`, the field-validation paragraph.** Replace + "eleven Crewmates each wrote a plan," with + "eleven planning sub-agents each wrote a plan," (Architect's ruling 1: + a past run, so no old word and no anachronistic "Masons"). +- **`AGENTS.md`, the G16 line.** Replace + "G16: reviewers fresh, the Crewmate reused within a live thread." with + "G16: reviewers fresh, the Mason (named the Crewmate in the record) + reused within a live thread." The ruling, in the decisions record, keeps + its word; the parenthesis lets a reader following the citation find it. + This one occurrence of "Crewmate" stays, on purpose. + +Everything else is the swap, in every file of the table: `Crewmate` β†’ +`Mason`, `Crewmates` β†’ `Masons`, `Crewmate's` β†’ `Mason's`, `crewmate` (the +beads actor) β†’ `mason`. Re-wrap a paragraph only if a line passes 80 +columns; markdown tables stay one row per line. No gloss on the name's +origin in `workflow.md`: the reason belongs to the intention's Why and the +journal. + +### The Typist line + +In "The Typist brief" of `socle/agents/workflow.md` and its copy +`.agents/workflow.md`, a fifth bullet after the one that ends "reported, +not guessed.": + +```markdown +- tick a box only for what really ran, on the real target; a dry run, or + a run on a copy or a test base, is written in the worklog and leaves + its box open. +``` + +Step 5 keeps "Tick the work document's checkboxes as work lands" unchanged. + +### The rename intention, exact text + +`socle/intentions/unreleased/crewmate-becomes-mason.md`, listed in +`src/socle-files.ts` after `"intentions/0.3.0/03-typist-by-default.md",` +as `"intentions/unreleased/crewmate-becomes-mason.md",`. Gap 3 reaches +into what `chisel-update` lists as "never touched"; the intention names it +explicitly and puts each rename behind the human's word (Architect's +ruling 2). + +````markdown +--- +id: unreleased/crewmate-becomes-mason +classification: migration +--- + +# The Crewmate becomes the Mason + +## Goal + +The project's own files call the sub-agent the Architect launches to plan, +have a Typist code, review and close a task the **Mason**, as the managed +files of chisel now do. + +## Why + +In the Harness that runs chisel's projects, "crewmate" names the per-task +session that plays chisel's Architect. Chisel used the same word for the +sub-agent that Architect launches, and one word for two roles made a plan +reading get skipped. The Owner renamed the role: Architect, Mason, Typist. +A repo whose own files still say "Crewmate" while `.agents/workflow.md` +says "Mason" hands its agents a role the workflow no longer defines. + +## Applies When + +- `git grep -il crewmate` lists a file outside the managed files and + outside the project's history: its archive, its journal, its changelog. + +## Do Not Apply When + +- None beyond the human's decision. + +## Observable Gaps + +1. **The glue.** Signal: `.agents/project.md` names the Crewmate. Rename + it in the prose; the project's answers stay as they are. + Done when: `git grep -i crewmate -- .agents/project.md` finds nothing. +2. **Open task documents.** Signal: an open spec or work document, in the + tasks directory the task workspace section of the glue names, names the + Crewmate. Rename the role. + Done when: no open task document names the Crewmate. +3. **The project's own instructions and skills.** Signal: `AGENTS.md` + outside the chisel markers, `CLAUDE.md`, or a skill chisel does not ship + names the Crewmate. These are the project's own files: show the human + each occurrence and rename it on their word. A "crewmate" that names + something else, such as a harness's own session, stays. + Done when: every occurrence is renamed, or kept on the human's word. + +## Out of Scope + +- The archive, the journal and the changelog: history keeps its words. +- Past tracker events that carry the `crewmate` actor; new ones carry + `mason`. +- The intention ids recorded in `.agents/.chisel.json`. + +## Reference Paths + +- `.agents/workflow.md` β€” **copy**, by the update. +- `.agents/skills/chisel-beads/SKILL.md` β€” **copy**, by the update. + +## Validation + +- `git grep -il crewmate` lists only the managed files the closing update + will replace, the project's history, and the files where the human kept + an occurrence. +- `git diff --stat` on the archive is empty. + +## Record Result + +`chisel record unreleased/crewmate-becomes-mason --applied`, or +`--skipped ""` after the human's word. +```` + +### The tick-rule intention, exact text + +`socle/intentions/unreleased/typist-ticks-what-ran.md`, listed in +`src/socle-files.ts` right after the rename intention's line, as +`"intentions/unreleased/typist-ticks-what-ran.md",` (Architect's ruling 3; +it ships in commit 2, with its change). + +````markdown +--- +id: unreleased/typist-ticks-what-ran +classification: informational +--- + +# The Typist ticks only what really ran + +## Goal + +The human knows that "The Typist brief" of `.agents/workflow.md` now says +a box is ticked only for what really ran, on the real target, and that a +dry run or a run on a copy is written in the worklog with its box left +open. + +## Why + +A project equipped with chisel saw a Typist tick "run the script for real" +after running it only on a throw-away test base. The work document's +checkboxes are where a fresh session resumes, so a false tick skips a step +without anyone seeing it. + +## Applies When + +- The repo is updated from a version whose "The Typist brief" in + `.agents/workflow.md` carries no tick rule. + +## Do Not Apply When + +- Never: there is nothing to apply. `workflow.md` is a managed file and + the copy `chisel update` makes carries the change; the session only + reads it to the human. + +## Observable Gaps + +1. **What the human knows.** Signal: none in the repo. Say it to the + human in one sentence: a Typist ticks a box only for what really ran, + on the real target; a dry run or a run on a copy goes in the worklog + and leaves its box open. A team whose own briefs say otherwise + reconciles them. + Done when: the human has read it. + +## Out of Scope + +- The project's own instructions outside the chisel markers of + `AGENTS.md`. + +## Reference Paths + +- `.agents/workflow.md` β€” **copy**, by the update. + +## Validation + +- Nothing to check in the repo: the closing update carries the change. + +## Record Result + +The closing `chisel update` records it, with the other informational +intentions. +```` + +### Commit order + +Commit with explicit paths, conventional commits, each message ending with +`Co-Authored-By: Claude Opus 5.5 `. No push. + +1. `feat(socle): the crewmate becomes the mason` β€” every rename, the rename + intention and its `src/socle-files.ts` line, plus the spec (status + change) and this work document. Gates green before it. +2. `feat(socle): the typist ticks only what really ran` β€” the bullet in + both `workflow.md`, the tick-rule intention and its + `src/socle-files.ts` line, plus this work document. Gates green before it. +3. At the close: `docs(tasks): close the crewmate-becomes-mason task` β€” + spec ticked, both task documents archived, the journal entry. + +Typist tier: *cheap* β€” every change is named down to its file and its +text. + +## Worklog + +- 2026-11-03 β€” Plan written; stopped for the Architect's reading. +- 2026-11-03 β€” Plan approved with three rulings; the exact texts of the + two rewrites and both intentions written above so the Typist types + without choosing. +- 2026-11-03 β€” Typist, commit 1: rename applied across the planned files; + PHILOSOPHY.md paragraph re-wrapped for the longer sentence; `diff -r + .agents socle/agents` shows only the four known differences; templates + identical to their copies; `deno task check` and `deno task test` green + (76 tests). Nothing in the plan went unanswered. + +## Implementation Checkboxes + +- [x] The rename in the socle (`socle/agents/`, `socle/templates/`) +- [x] The same edits in the copies (`.agents/`, `project-management/` templates, `AGENTS.md`) +- [x] The rename in `CHARTER.md`, `README.md`, `PHILOSOPHY.md`, with the two rewrites +- [x] The rename intention and its `src/socle-files.ts` line +- [x] Gates green, commit 1 +- [ ] The Typist line, the tick-rule intention and its `src/socle-files.ts` line +- [ ] Gates green, commit 2 +- [ ] Criteria greps and the `diff -r` run +- [ ] `code-review`, findings recorded +- [ ] Close: criteria ticked, documents archived, journal entry, retro, commit 3 + +## Notes & Snippets + +- Precedent: the 0.3.0 change "typist by default" (commit `12ec6d2`) touched + the same socle files, their copies, `CHARTER.md`, `README.md`, + `PHILOSOPHY.md`, and added one intention. +- `.agents/.chisel.json` holds managed-file hashes; `12ec6d2` changed + `.agents/workflow.md` without refreshing them, and this plan follows that + precedent. + +## Questions for the Architect (answered on the Plan line) + +1. **`PHILOSOPHY.md`'s past run.** "eleven Crewmates each wrote a plan" + tells history in a living doc. Options: rewrite to "eleven planning + sub-agents" (recommended: no old word, no anachronism); swap to "eleven + Masons"; keep it as history. The first two pass criterion + no-crewmate-outside-history; the third fails it. +2. **The intention touches the project's own skills and instructions**, + which `chisel-update` "never touches". Options: keep gap 3, explicit and + human-validated per occurrence (recommended, as the spec asks); or drop + the skills and say so in Out of Scope. +3. **The tick rule has no intention of its own.** The intention gate is + satisfied by the rename's intention, but a repo's human would not hear of + the new rule. Options: a second, `informational` intention + `typist-ticks-what-ran`, like `0.3.0/crewmate-cleans-up`, in commit 2 + (recommended); a paragraph in the rename intention (two changes in one + intention); or nothing, the managed copy carries it silently. + +## Diff-Review Findings diff --git a/socle/agents/methodology.md b/socle/agents/methodology.md index 69c509c..e847c17 100644 --- a/socle/agents/methodology.md +++ b/socle/agents/methodology.md @@ -90,7 +90,7 @@ is that the expensive-to-reverse decisions are made, not that it is small. **Program design** β€” the target shape inside the agreed architecture: files, seam signatures, test order β€” is deliberately NOT written with the spec. Designing slice 6's files before slices 1–3 have taught anything produces -stale guesses. The Crewmate writes it at the plan step, with the real code +stale guesses. The Mason writes it at the plan step, with the real code in view, and **persists it in the work document** before any code; the Architect reads and approves it there. Three reasons to persist it: @@ -105,7 +105,7 @@ Architect reads and approves it there. Three reasons to persist it: The delegation boundary is the **system design**: above it the *what* β€” architecture, scope, seams β€” settled in the spec; below it the *how*, -designed and typed by the session that implements. A Crewmate asked to +designed and typed by the session that implements. A Mason asked to "figure out" something the *what* left open is a specification failure, and it goes back to the spec. An open *how* is not a hole: it is what the plan step is for. @@ -113,7 +113,7 @@ step is for. Once the plan is approved it is a complete brief, which is what makes a Typist possible: a cheaper model types a settled plan, and the frontier tier is kept for judgement β€” the spec, the plan, the review. So the -Crewmate hands the typing to a Typist by default. A Crewmate that types its +Mason hands the typing to a Typist by default. A Mason that types its own plan pays the frontier price for typing: on 2026-11-03 one of chisel's own tasks ran 383 calls, all at the frontier tier, none of them a Typist's. The brief is **artifacts diff --git a/socle/agents/reference.md b/socle/agents/reference.md index b43dd3c..dee8ea5 100644 --- a/socle/agents/reference.md +++ b/socle/agents/reference.md @@ -12,7 +12,7 @@ for every session are `.agents/discipline.md`. |---|---| | **Task** | The unit of work. Its spec document lives in the task workspace declared in `.agents/project.md` (default `/project-management/tasks/`), named `-.spec.md`, whatever tracker also carries it; once planned it has a matching `-.work.md` beside it. | | **Spec document** | The review surface and the requirement: intent, acceptance criteria, seams, system design, decisions, testing strategy, slices, deliverables, references, pre-plan Notes and retrospective. It carries the task's status line and the reading gradient's two πŸ§‘ zones. | -| **Work document** | The Crewmate's companion file, created at the plan step beside the spec document. It carries the program design and its approval line, the worklog, the implementation checkboxes, Notes & Snippets and the review findings. No zone marker. | +| **Work document** | The Mason's companion file, created at the plan step beside the spec document. It carries the program design and its approval line, the worklog, the implementation checkboxes, Notes & Snippets and the review findings. No zone marker. | | **Slice** | A child task produced by cutting a large task: a tracer-bullet vertical cut through every layer, demoable on its own, sized for one fresh context window. Lives as `tasks/-/-.spec.md`. A small task IS its own single slice. | | **Seam** | The public boundary where a feature is tested β€” named in the spec BEFORE implementation. Tests live at seams, never against internals. Fewer is better (ideal: one). | | **Reading gradient** | The ordering of the spec document by review criticality: πŸ§‘ REVIEW CAREFULLY (short, decision-rich) β†’ πŸ§‘ REVIEW IF RELEVANT. Detail is never cut, it is ordered. | @@ -22,7 +22,7 @@ for every session are `.agents/discipline.md`. | **Expand–contract** | The sequencing for wide mechanical refactors (rename a column, retype a shared symbol): add the new form beside the old β†’ migrate call sites in batches β†’ delete the old form. The exception to vertical slicing. | | **One-shot** | Work done without a task artifact. The discipline still applies; only the file bookkeeping is skipped. | -The roles β€” Architect, Crewmate, Typist, reviewers β€” are defined in "The +The roles β€” Architect, Mason, Typist, reviewers β€” are defined in "The roles" of `.agents/workflow.md`. We do NOT use the word "ticket" for local work. It is reserved for items in an @@ -36,7 +36,7 @@ decision tickets and resolves them one at a time). A πŸ§‘ zone belongs to whoever **approved** it. The human approves a spec that carries decisions the task did not state; the Architect approves one written from a clear task, and then the zones carry the task's own decisions, which -are the human's. The work document has no zone: it belongs to the Crewmate +are the human's. The work document has no zone: it belongs to the Mason that wrote it. A πŸ§‘ zone is never overridden silently β€” a conflict with one is surfaced, never edited sideways. @@ -47,7 +47,7 @@ the work β€” how much judgement it needs. | Tier | What it is for | Roles | |---|---|---| -| **frontier** | Thinking and reviewing β€” where a wrong judgement is expensive and caught late | Architect, Crewmate, reviewers | +| **frontier** | Thinking and reviewing β€” where a wrong judgement is expensive and caught late | Architect, Mason, reviewers | | **mid** | Ordinary work that needs competence but not judgement | The Typist, by default | | **cheap** | Typing a mechanical plan: every change named down to its file and place, nothing left to choose | The Typist, when the plan is mechanical | diff --git a/socle/agents/skills/chisel-beads/SKILL.md b/socle/agents/skills/chisel-beads/SKILL.md index 7991706..d11a67d 100644 --- a/socle/agents/skills/chisel-beads/SKILL.md +++ b/socle/agents/skills/chisel-beads/SKILL.md @@ -28,7 +28,7 @@ bd list --status draft # any other status is a filter ```sh bd create "" --type task --priority <0-4> \ --spec-id "" \ - --actor --silent + --actor --silent ``` `--spec-id` is the whole link; the work document's path follows from it. diff --git a/socle/agents/skills/retro/SKILL.md b/socle/agents/skills/retro/SKILL.md index f9f8b72..d88d18a 100644 --- a/socle/agents/skills/retro/SKILL.md +++ b/socle/agents/skills/retro/SKILL.md @@ -104,7 +104,7 @@ discussed: ### Implementation vs review All work goes through two stages: implementation and review. The -implementation session (the Crewmate writing its program design at the plan +implementation session (the Mason writing its program design at the plan step, then typing it) carries the most context pressure β€” exploration, writing code, debugging failures. The review sub-agents carry the least β€” it receives a diff, no exploration needed. This is why coding standards diff --git a/socle/agents/skills/slice-task/SKILL.md b/socle/agents/skills/slice-task/SKILL.md index f0acd76..6f033c6 100644 --- a/socle/agents/skills/slice-task/SKILL.md +++ b/socle/agents/skills/slice-task/SKILL.md @@ -89,7 +89,7 @@ where `` comes from `scripts/task-id.sh` and `` numbers the slices from `01` in dependency order (blockers first). The parent spec document (if one exists) stays in place and links to the slice folder. -No work document is created here. The Crewmate that implements a slice creates +No work document is created here. The Mason that implements a slice creates the matching `-.work.md` beside it at its `plan` step, from the work template declared in Β§A Β· Task workspace of `.agents/project.md`. @@ -122,7 +122,7 @@ user's perspective β€” not a layer-by-layer implementation list. ## Notes _A question or a blocker met before the plan β€” only what is written into -this document before its work document exists. Not the Crewmate's working +this document before its work document exists. Not the Mason's working space: its notes, snippets and worklog live in the work document._ diff --git a/socle/agents/workflow.md b/socle/agents/workflow.md index a4353ab..d4d2cea 100644 --- a/socle/agents/workflow.md +++ b/socle/agents/workflow.md @@ -18,9 +18,9 @@ or a script. | Role | Who plays it | What it does | |---|---|---| -| **Architect** | The agent a human, or an orchestrator, talks to. This is its default role. | Reads the task, writes or sharpens the spec, launches a Crewmate and talks with it, reads and corrects the plan, rules on what the Crewmate reports, brings the key questions to the human. | -| **Crewmate** | A sub-agent launched by the Architect. | Writes the plan in the work document and stops for the Architect's reading. Then launches a Typist to code it, runs `code-review`, and closes the task. | -| **Typist** | A sub-agent launched by the Crewmate once the plan is approved. | Types code from the approved plan and decides nothing, at a cheaper tier than the Crewmate's (`.agents/reference.md`, "Model tiers"). | +| **Architect** | The agent a human, or an orchestrator, talks to. This is its default role. | Reads the task, writes or sharpens the spec, launches a Mason and talks with it, reads and corrects the plan, rules on what the Mason reports, brings the key questions to the human. | +| **Mason** | A sub-agent launched by the Architect. | Writes the plan in the work document and stops for the Architect's reading. Then launches a Typist to code it, runs `code-review`, and closes the task. | +| **Typist** | A sub-agent launched by the Mason once the plan is approved. | Types code from the approved plan and decides nothing, at a cheaper tier than the Mason's (`.agents/reference.md`, "Model tiers"). | | **Reviewers** | Sub-agents launched by the `code-review` skill. | Read the diff with no context from the session that wrote it. | **The human** owns the intent and the decisions that shape the task. The @@ -29,7 +29,7 @@ made goes back to the human, with the question stated. The Architect's thread can be one long thread that compacts and serves as the entry point to a project, or one thread per piece of work. In a long -thread the Architect can run several Crewmates, one per task or slice. +thread the Architect can run several Masons, one per task or slice. ## The steps @@ -52,8 +52,8 @@ The human approves the spec when it carries decisions the task did not state; otherwise the Architect moves it to `ready` itself. Commit the spec. Status: `draft`, then `ready`. -**3. Plan β€” Crewmate.** The Architect launches a Crewmate with the brief -below. The Crewmate reads the spec document and what it links to, creates +**3. Plan β€” Mason.** The Architect launches a Mason with the brief +below. The Mason reads the spec document and what it links to, creates the work document beside it from the work template, and persists its program design there: files, seam signatures, test order, the decisions the spec left to the implementation. Then it stops and reports. No code before @@ -61,13 +61,13 @@ the plan is approved. Status: `in-progress`, written by the Architect at launch. **4. Read the plan β€” Architect.** Read the spec and the work document, -nothing else. Correct the plan with the Crewmate, then approve it: the +nothing else. Correct the plan with the Mason, then approve it: the approval is written on the work document's `**Plan:**` line, with who and when. A plan that departs from a decision the human made goes to the human first. -**5. Code β€” a Typist the Crewmate launches.** Once the plan is approved, -the Crewmate launches a Typist with the brief below. The Crewmate types +**5. Code β€” a Typist the Mason launches.** Once the plan is approved, +the Mason launches a Typist with the brief below. The Mason types itself only a retouch of a few lines, or while the plan is not settled, and writes which exception applies and why in the work document's worklog. The Typist executes the approved plan in vertical steps, test-first at the @@ -77,12 +77,12 @@ and commit at each green step. Run the gate commands declared in `.agents/project.md`. Reality that contradicts the plan is fixed in the plan, in writing; reality that contradicts the spec is reported. -**6. Review β€” Crewmate.** Run the `code-review` skill on the full diff of +**6. Review β€” Mason.** Run the `code-review` skill on the full diff of the task. Its reviewers are fresh sub-agents that never saw the session that wrote the code β€” never skip this step, even for a small retouch. Write the findings in the work document; fix each one or answer it there. -**7. Close β€” Crewmate.** Tick the spec's acceptance criteria against +**7. Close β€” Mason.** Tick the spec's acceptance criteria against reality. Promote evergreen material into the living docs declared in `.agents/project.md`, the glossary and the ADRs among them. Archive the spec and work documents together. Add the dated journal entry. Run the `retro` skill and put its proposals in the @@ -102,8 +102,8 @@ explicit word on that very action is the only go. | Who stops | For whom | When | |---|---|---| -| Crewmate | Architect | After the plan; after the close, with its report; on a blocker it cannot rule on | -| Typist | Crewmate | After its part of the plan; on anything the plan does not answer | +| Mason | Architect | After the plan; after the close, with its report; on a blocker it cannot rule on | +| Typist | Mason | After its part of the plan; on anything the plan does not answer | | Architect | Human | On an unclear intent; on a spec that carries decisions the task did not state; on a plan that departs from the human's decisions; on a blocker above what it owns | | Architect | Human | Before a merge or a publish, unless the project lets the agent do it | @@ -126,7 +126,7 @@ A task has one status. The thread doing a step writes the status it leaves. |---|---|---| | `draft` | The spec is being written, or waits for the human's approval | step 2 | | `ready` | The spec is approved and nothing holds the task | step 2 | -| `in-progress` | A Crewmate is planning, coding, reviewing or closing it | step 3 | +| `in-progress` | A Mason is planning, coding, reviewing or closing it | step 3 | | `done` | Criteria ticked, documents archived | step 7 | | `blocked` | Held by a named dependency, written after the value | whoever meets the block | | `deferred` | Postponed on purpose | the human | @@ -143,21 +143,21 @@ Launch one only for a context that must stay clean, for work that runs in parallel, or for a cheaper model. Each one costs tokens and a brief to write. Three earn it: -- **The Crewmate** keeps the Architect's context clean for reading the plan +- **The Mason** keeps the Architect's context clean for reading the plan and ruling on reports. - **The Typist** types the approved plan on a cheaper tier than the - Crewmate's. + Mason's. - **The reviewers** bring fresh eyes to the diff. A brief is artifacts and paths, never the conversation: whatever the sub-agent needs must already be in the repo. Reviewers are always fresh. A -Crewmate is reused within a live thread β€” the one that wrote the plan +Mason is reused within a live thread β€” the one that wrote the plan launches its Typist and runs the review β€” and a resumed task starts fresh from the spec and work documents. -## The Crewmate brief +## The Mason brief -What the Architect writes when it launches a Crewmate: +What the Architect writes when it launches a Mason: - the spec document's path, and the work template's; - the branch to work on, and how to commit (explicit paths, no push); @@ -169,7 +169,7 @@ What the Architect writes when it launches a Crewmate: ## The Typist brief -What the Crewmate writes when it launches a Typist: +What the Mason writes when it launches a Typist: - the approved work document's path, and the part of the plan to type; - its tier: *cheap* when the plan is mechanical, *mid* otherwise diff --git a/socle/intentions/unreleased/crewmate-becomes-mason.md b/socle/intentions/unreleased/crewmate-becomes-mason.md new file mode 100644 index 0000000..6f36ceb --- /dev/null +++ b/socle/intentions/unreleased/crewmate-becomes-mason.md @@ -0,0 +1,70 @@ +--- +id: unreleased/crewmate-becomes-mason +classification: migration +--- + +# The Crewmate becomes the Mason + +## Goal + +The project's own files call the sub-agent the Architect launches to plan, +have a Typist code, review and close a task the **Mason**, as the managed +files of chisel now do. + +## Why + +In the Harness that runs chisel's projects, "crewmate" names the per-task +session that plays chisel's Architect. Chisel used the same word for the +sub-agent that Architect launches, and one word for two roles made a plan +reading get skipped. The Owner renamed the role: Architect, Mason, Typist. +A repo whose own files still say "Crewmate" while `.agents/workflow.md` +says "Mason" hands its agents a role the workflow no longer defines. + +## Applies When + +- `git grep -il crewmate` lists a file outside the managed files and + outside the project's history: its archive, its journal, its changelog. + +## Do Not Apply When + +- None beyond the human's decision. + +## Observable Gaps + +1. **The glue.** Signal: `.agents/project.md` names the Crewmate. Rename + it in the prose; the project's answers stay as they are. + Done when: `git grep -i crewmate -- .agents/project.md` finds nothing. +2. **Open task documents.** Signal: an open spec or work document, in the + tasks directory the task workspace section of the glue names, names the + Crewmate. Rename the role. + Done when: no open task document names the Crewmate. +3. **The project's own instructions and skills.** Signal: `AGENTS.md` + outside the chisel markers, `CLAUDE.md`, or a skill chisel does not ship + names the Crewmate. These are the project's own files: show the human + each occurrence and rename it on their word. A "crewmate" that names + something else, such as a harness's own session, stays. + Done when: every occurrence is renamed, or kept on the human's word. + +## Out of Scope + +- The archive, the journal and the changelog: history keeps its words. +- Past tracker events that carry the `crewmate` actor; new ones carry + `mason`. +- The intention ids recorded in `.agents/.chisel.json`. + +## Reference Paths + +- `.agents/workflow.md` β€” **copy**, by the update. +- `.agents/skills/chisel-beads/SKILL.md` β€” **copy**, by the update. + +## Validation + +- `git grep -il crewmate` lists only the managed files the closing update + will replace, the project's history, and the files where the human kept + an occurrence. +- `git diff --stat` on the archive is empty. + +## Record Result + +`chisel record unreleased/crewmate-becomes-mason --applied`, or +`--skipped ""` after the human's word. diff --git a/socle/templates/000-template.spec.md b/socle/templates/000-template.spec.md index 48a20d2..ccf219f 100644 --- a/socle/templates/000-template.spec.md +++ b/socle/templates/000-template.spec.md @@ -14,7 +14,7 @@ cannot be read without is not. The rule is the writing rule of The spec document is the human review surface, the requirement against which a diff is judged, and the archive record of what was asked. It contains no program design, pseudo-code, worklog or implementation checkboxes: these are -in the work document, created at the plan step by the Crewmate. +in the work document, created at the plan step by the Mason. A spec written from a clear task stays short and links the task rather than copying it. A spec with no work document beside it has never been planned. @@ -32,7 +32,7 @@ copying it. A spec with no work document beside it has never been planned. [reference.md](/.agents/reference.md): whoever approved it. - The πŸ§‘ zones carry their owner's decisions. Surface a conflict; never silently contradict one. -- There is no agent zone here. The Crewmate's working space is the work +- There is no agent zone here. The Mason's working space is the work document, a different file. ## The two documents @@ -140,7 +140,7 @@ belongs wholly to the work document. ## Notes Only material written into this file before a work document exists. The -Crewmate's notes, snippets and worklog belong in the work document's +Mason's notes, snippets and worklog belong in the work document's **Notes & Snippets**. ## Retrospective @@ -176,7 +176,7 @@ the `**Status:**` line: 3. Fill both πŸ§‘ zones carefully. 4. Keep the top short; order detail rather than deleting it. 5. At the close, tick acceptance criteria against reality. -6. The Crewmate creates the work document at the plan step, never before. +6. The Mason creates the work document at the plan step, never before. ## When Reviewing Tasks (human) diff --git a/socle/templates/000-template.work.md b/socle/templates/000-template.work.md index e6dcbd9..f1bebf0 100644 --- a/socle/templates/000-template.work.md +++ b/socle/templates/000-template.work.md @@ -9,14 +9,14 @@ and its section title β€” never a line number, which is wrong by the next edit β€” and says in one sentence what the reader finds there. The rule is the writing rule of `.agents/discipline.md`. -The work document is the Crewmate's own file: its program design and the +The work document is the Mason's own file: its program design and the line that records its approval, its worklog, its implementation checkboxes, its Notes & Snippets, and the findings of the review. No zone marker: the reading gradient does not apply to working material. The reasoning behind the split is "The two designs β€” and why they do not happen at the same moment" of [methodology.md](/.agents/methodology.md). -**Who creates it, when, where, under what name.** The Crewmate creates it at +**Who creates it, when, where, under what name.** The Mason creates it at the plan step, never earlier. It lives beside its spec, named by replacing the spec's `.spec.md` suffix with `.work.md`: same time id (or slice number), same directory. A spec with no work document beside it has never @@ -30,11 +30,11 @@ system has. A parent spec of a sliced task never gets a work document of its own β€” only its slices do. **The Architect reads it and approves the plan.** It corrects the plan with -the Crewmate, then the approval goes on the `**Plan:**` line. Plan approval +the Mason, then the approval goes on the `**Plan:**` line. Plan approval is that line, not a status. **The review writes into it.** `code-review` reports its findings, and the -Crewmate records each one in the Diff-Review Findings section with its fix +Mason records each one in the Diff-Review Findings section with its fix or its answer. ## Work Document Template @@ -44,7 +44,7 @@ All work documents MUST follow this structure: ```markdown # β€” work -Created by the Crewmate at the plan step, . Spec: +Created by the Mason at the plan step, . Spec: `/.spec.md`. **Plan:** waiting for the Architect's reading. @@ -86,7 +86,7 @@ The findings of `code-review`, judged against the spec document with this file as evidence, each with its fix or its answer. ``` -## When Creating a Work Document (the Crewmate) +## When Creating a Work Document (the Mason) 1. Create it at the plan step, never before β€” an open question about the *what* at this point means the spec is unfinished; report it rather than @@ -102,7 +102,7 @@ file as evidence, each with its fix or its answer. ## When Reading a Work Document - The Architect reads the Program Design at the plan step, corrects it with - the Crewmate, and records the approval on the `**Plan:**` line. + the Mason, and records the approval on the `**Plan:**` line. - The reviewers read the spec document as the requirement and this file as evidence. - A fresh session resuming the work reads the implementation checkboxes and diff --git a/socle/templates/AGENTS-block.md b/socle/templates/AGENTS-block.md index 204a184..c7e3d4a 100644 --- a/socle/templates/AGENTS-block.md +++ b/socle/templates/AGENTS-block.md @@ -20,9 +20,9 @@ takes one task from its intent to its commit and pull request, in prose: the roles, the steps, where the work stops, the tracker and the statuses. - By default you are the **Architect**: you read the task, write or sharpen - the spec, launch a Crewmate, read its plan, and bring the key questions to + the spec, launch a Mason, read its plan, and bring the key questions to the human. -- Launched as a **Crewmate** or a **Typist**, follow the brief you were +- Launched as a **Mason** or a **Typist**, follow the brief you were given and the matching steps of `.agents/workflow.md`. - Merging and publishing follow the merge and publish section of `.agents/project.md`. By default they wait for the human's explicit word diff --git a/src/socle-files.ts b/src/socle-files.ts index 915a071..72b18ac 100644 --- a/src/socle-files.ts +++ b/src/socle-files.ts @@ -51,6 +51,7 @@ export const SOCLE_FILES: readonly string[] = [ "intentions/0.3.0/01-crewmate-cleans-up.md", "intentions/0.3.0/02-manifest-records-intentions.md", "intentions/0.3.0/03-typist-by-default.md", + "intentions/unreleased/crewmate-becomes-mason.md", "intentions/TEMPLATE.md", "intentions/baseline.md", "scripts/sync-upstream.sh", From cf130933badf4b0ef4dffe20402bddafa3a074bf Mon Sep 17 00:00:00 2001 From: Pierrick Bignet Date: Tue, 3 Nov 2026 23:44:44 +0100 Subject: [PATCH 3/5] feat(socle): the typist ticks only what really ran A Typist once ticked "run the script for real" after running it only on a throw-away test base. A box is the mark a fresh session resumes from, so the brief now says a box is ticked only for what really ran, on the real target; a dry run or a run on a copy is written in the worklog instead. Co-Authored-By: Claude Opus 5.5 --- .agents/workflow.md | 3 + ...261103-2338-crewmate-becomes-mason.work.md | 7 ++- socle/agents/workflow.md | 3 + .../unreleased/typist-ticks-what-ran.md | 58 +++++++++++++++++++ src/socle-files.ts | 1 + 5 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 socle/intentions/unreleased/typist-ticks-what-ran.md diff --git a/.agents/workflow.md b/.agents/workflow.md index d4d2cea..e7a4045 100644 --- a/.agents/workflow.md +++ b/.agents/workflow.md @@ -177,6 +177,9 @@ What the Mason writes when it launches a Typist: - the branch, the gate commands, the commit rule; - type the plan and decide nothing: anything the plan does not answer is reported, not guessed. +- tick a box only for what really ran, on the real target; a dry run, or + a run on a copy or a test base, is written in the worklog and leaves + its box open. ## Blockers and questions diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md b/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md index 2bb60ea..26b8652 100644 --- a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md +++ b/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md @@ -253,6 +253,9 @@ text. .agents socle/agents` shows only the four known differences; templates identical to their copies; `deno task check` and `deno task test` green (76 tests). Nothing in the plan went unanswered. +- 2026-11-03 β€” Typist, commit 2: the Typist bullet added to both + `workflow.md` files; tick-rule intention added and listed in + `src/socle-files.ts`; gates green again (76 tests). ## Implementation Checkboxes @@ -261,8 +264,8 @@ text. - [x] The rename in `CHARTER.md`, `README.md`, `PHILOSOPHY.md`, with the two rewrites - [x] The rename intention and its `src/socle-files.ts` line - [x] Gates green, commit 1 -- [ ] The Typist line, the tick-rule intention and its `src/socle-files.ts` line -- [ ] Gates green, commit 2 +- [x] The Typist line, the tick-rule intention and its `src/socle-files.ts` line +- [x] Gates green, commit 2 - [ ] Criteria greps and the `diff -r` run - [ ] `code-review`, findings recorded - [ ] Close: criteria ticked, documents archived, journal entry, retro, commit 3 diff --git a/socle/agents/workflow.md b/socle/agents/workflow.md index d4d2cea..e7a4045 100644 --- a/socle/agents/workflow.md +++ b/socle/agents/workflow.md @@ -177,6 +177,9 @@ What the Mason writes when it launches a Typist: - the branch, the gate commands, the commit rule; - type the plan and decide nothing: anything the plan does not answer is reported, not guessed. +- tick a box only for what really ran, on the real target; a dry run, or + a run on a copy or a test base, is written in the worklog and leaves + its box open. ## Blockers and questions diff --git a/socle/intentions/unreleased/typist-ticks-what-ran.md b/socle/intentions/unreleased/typist-ticks-what-ran.md new file mode 100644 index 0000000..2023c6c --- /dev/null +++ b/socle/intentions/unreleased/typist-ticks-what-ran.md @@ -0,0 +1,58 @@ +--- +id: unreleased/typist-ticks-what-ran +classification: informational +--- + +# The Typist ticks only what really ran + +## Goal + +The human knows that "The Typist brief" of `.agents/workflow.md` now says +a box is ticked only for what really ran, on the real target, and that a +dry run or a run on a copy is written in the worklog with its box left +open. + +## Why + +A project equipped with chisel saw a Typist tick "run the script for real" +after running it only on a throw-away test base. The work document's +checkboxes are where a fresh session resumes, so a false tick skips a step +without anyone seeing it. + +## Applies When + +- The repo is updated from a version whose "The Typist brief" in + `.agents/workflow.md` carries no tick rule. + +## Do Not Apply When + +- Never: there is nothing to apply. `workflow.md` is a managed file and + the copy `chisel update` makes carries the change; the session only + reads it to the human. + +## Observable Gaps + +1. **What the human knows.** Signal: none in the repo. Say it to the + human in one sentence: a Typist ticks a box only for what really ran, + on the real target; a dry run or a run on a copy goes in the worklog + and leaves its box open. A team whose own briefs say otherwise + reconciles them. + Done when: the human has read it. + +## Out of Scope + +- The project's own instructions outside the chisel markers of + `AGENTS.md`. + +## Reference Paths + +- `.agents/workflow.md` β€” **copy**, by the update. + +## Validation + +- Nothing to check in the repo: the closing update carries the change. + +## Record Result + +The closing `chisel update` records it, with the other informational +intentions. diff --git a/src/socle-files.ts b/src/socle-files.ts index 72b18ac..5d98ec3 100644 --- a/src/socle-files.ts +++ b/src/socle-files.ts @@ -52,6 +52,7 @@ export const SOCLE_FILES: readonly string[] = [ "intentions/0.3.0/02-manifest-records-intentions.md", "intentions/0.3.0/03-typist-by-default.md", "intentions/unreleased/crewmate-becomes-mason.md", + "intentions/unreleased/typist-ticks-what-ran.md", "intentions/TEMPLATE.md", "intentions/baseline.md", "scripts/sync-upstream.sh", From b4816a10db9f7ea4131f0d8a238cd70fd6b2fe61 Mon Sep 17 00:00:00 2001 From: Pierrick Bignet Date: Tue, 3 Nov 2026 23:46:57 +0100 Subject: [PATCH 4/5] fix(socle): answer the review of the mason rename The rename intention leaves the archive to chisel-update, says why its third gap reaches the project's own files, and names the manifest in its check. The Typist brief reads as one list. Co-Authored-By: Claude Opus 5.5 --- .agents/workflow.md | 2 +- ...261103-2338-crewmate-becomes-mason.work.md | 50 ++++++++++++++++++- socle/agents/workflow.md | 2 +- .../unreleased/crewmate-becomes-mason.md | 15 +++--- .../unreleased/typist-ticks-what-ran.md | 2 +- 5 files changed, 59 insertions(+), 12 deletions(-) diff --git a/.agents/workflow.md b/.agents/workflow.md index e7a4045..5dd1f75 100644 --- a/.agents/workflow.md +++ b/.agents/workflow.md @@ -176,7 +176,7 @@ What the Mason writes when it launches a Typist: (`.agents/reference.md`, "Model tiers", which also resolves the model); - the branch, the gate commands, the commit rule; - type the plan and decide nothing: anything the plan does not answer is - reported, not guessed. + reported, not guessed; - tick a box only for what really ran, on the real target; a dry run, or a run on a copy or a test base, is written in the worklog and leaves its box open. diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md b/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md index 26b8652..e75adaa 100644 --- a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md +++ b/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md @@ -256,6 +256,10 @@ text. - 2026-11-03 β€” Typist, commit 2: the Typist bullet added to both `workflow.md` files; tick-rule intention added and listed in `src/socle-files.ts`; gates green again (76 tests). +- 2026-11-03 β€” Mason: criteria greps and `diff -r` run, all as expected + (the one `AGENTS.md` occurrence is the approved gloss). `code-review` + run on `origin/main...HEAD`; the fixes below typed by the Mason itself, + under the retouch exception (a few lines in three files); gates green. ## Implementation Checkboxes @@ -266,8 +270,8 @@ text. - [x] Gates green, commit 1 - [x] The Typist line, the tick-rule intention and its `src/socle-files.ts` line - [x] Gates green, commit 2 -- [ ] Criteria greps and the `diff -r` run -- [ ] `code-review`, findings recorded +- [x] Criteria greps and the `diff -r` run +- [x] `code-review`, findings recorded - [ ] Close: criteria ticked, documents archived, journal entry, retro, commit 3 ## Notes & Snippets @@ -298,3 +302,45 @@ text. intention); or nothing, the managed copy carries it silently. ## Diff-Review Findings + +Run 2026-11-03 on `origin/main...HEAD`, two fresh reviewers. + +**Standards axis** + +- *The rename intention's Out of Scope lists the archive*, already on + `chisel-update`'s "What is never touched" list (`TEMPLATE.md`, "Its + sections"). Fixed: only the journal and the changelog remain. +- *"Harness" capitalised and undefined in the rename intention's Why.* + Fixed: "the harness that runs chisel's own projects", lower case, as + `CHARTER.md` writes it. The commit body of the rename keeps the word; + history is not rewritten. +- *The tick-rule intention says a team reconciles its briefs, while Out of + Scope excludes the project's own instructions.* Answered and sharpened: + the human reconciles, not the update agent; the gap now reads + "reconciles them itself", the pattern of `0.3.0/typist-by-default`. +- *The tick rule lives only in the Typist brief; a Mason typing a retouch + never reads it.* Answered: the spec's Implementation Decisions place it + there and keep step 5 unrepeated. Worth a later look if a Mason's retouch + ever ticks falsely. +- *The new bullet followed one ending with "."* Fixed: the previous + bullet now ends with ";", the list reads as one. +- *Shotgun Surgery: the role table lives in `CHARTER.md` and + `workflow.md`.* Answered: pre-existing, and the charter is the Owner's + page; out of this task's scope. +- *`PHILOSOPHY.md` drops the role name where `AGENTS.md` maps it.* + Answered: Architect's ruling 1, a past run told without the old word. + +**Spec axis** + +- All six criteria re-run and passing; `AGENTS.md`'s kept "Crewmate" is the + approved gloss pointing at the decisions record. Answered: the + criterion is ticked with that exception named. +- *The second intention is beyond the spec's one.* Answered: Architect's + ruling 3. +- *Out of Scope lists the archive.* Fixed, as above. +- *Gap 3 conflicts with `chisel-update`'s "never touched" without saying + so.* Fixed: the gap now says it names those files on purpose, each + rename on the human's word. +- *Validation misses the manifest, which carries `crewmate` ids.* Fixed: + `.agents/.chisel.json` is named in the check. +- *Punctuation of the new bullet.* Fixed, as above. diff --git a/socle/agents/workflow.md b/socle/agents/workflow.md index e7a4045..5dd1f75 100644 --- a/socle/agents/workflow.md +++ b/socle/agents/workflow.md @@ -176,7 +176,7 @@ What the Mason writes when it launches a Typist: (`.agents/reference.md`, "Model tiers", which also resolves the model); - the branch, the gate commands, the commit rule; - type the plan and decide nothing: anything the plan does not answer is - reported, not guessed. + reported, not guessed; - tick a box only for what really ran, on the real target; a dry run, or a run on a copy or a test base, is written in the worklog and leaves its box open. diff --git a/socle/intentions/unreleased/crewmate-becomes-mason.md b/socle/intentions/unreleased/crewmate-becomes-mason.md index 6f36ceb..aa83199 100644 --- a/socle/intentions/unreleased/crewmate-becomes-mason.md +++ b/socle/intentions/unreleased/crewmate-becomes-mason.md @@ -13,8 +13,8 @@ files of chisel now do. ## Why -In the Harness that runs chisel's projects, "crewmate" names the per-task -session that plays chisel's Architect. Chisel used the same word for the +In the harness that runs chisel's own projects, "crewmate" names the +per-task session that plays chisel's Architect. Chisel used the same word for the sub-agent that Architect launches, and one word for two roles made a plan reading get skipped. The Owner renamed the role: Architect, Mason, Typist. A repo whose own files still say "Crewmate" while `.agents/workflow.md` @@ -40,14 +40,15 @@ says "Mason" hands its agents a role the workflow no longer defines. Done when: no open task document names the Crewmate. 3. **The project's own instructions and skills.** Signal: `AGENTS.md` outside the chisel markers, `CLAUDE.md`, or a skill chisel does not ship - names the Crewmate. These are the project's own files: show the human - each occurrence and rename it on their word. A "crewmate" that names + names the Crewmate. These are the project's own files, beyond what + `chisel-update` touches on its own: this intention names them on + purpose, so show the human each occurrence and rename it on their word. A "crewmate" that names something else, such as a harness's own session, stays. Done when: every occurrence is renamed, or kept on the human's word. ## Out of Scope -- The archive, the journal and the changelog: history keeps its words. +- The journal and the changelog: history keeps its words. - Past tracker events that carry the `crewmate` actor; new ones carry `mason`. - The intention ids recorded in `.agents/.chisel.json`. @@ -60,8 +61,8 @@ says "Mason" hands its agents a role the workflow no longer defines. ## Validation - `git grep -il crewmate` lists only the managed files the closing update - will replace, the project's history, and the files where the human kept - an occurrence. + will replace, the manifest `.agents/.chisel.json`, the project's + history, and the files where the human kept an occurrence. - `git diff --stat` on the archive is empty. ## Record Result diff --git a/socle/intentions/unreleased/typist-ticks-what-ran.md b/socle/intentions/unreleased/typist-ticks-what-ran.md index 2023c6c..a11486b 100644 --- a/socle/intentions/unreleased/typist-ticks-what-ran.md +++ b/socle/intentions/unreleased/typist-ticks-what-ran.md @@ -36,7 +36,7 @@ without anyone seeing it. human in one sentence: a Typist ticks a box only for what really ran, on the real target; a dry run or a run on a copy goes in the worklog and leaves its box open. A team whose own briefs say otherwise - reconciles them. + reconciles them itself. Done when: the human has read it. ## Out of Scope From f8fc86d6e197be875885536c8cb2a65834afd24f Mon Sep 17 00:00:00 2001 From: Pierrick Bignet Date: Tue, 3 Nov 2026 23:47:41 +0100 Subject: [PATCH 5/5] docs(tasks): close the crewmate-becomes-mason task Criteria ticked, spec and work document archived, the journal entry and the Owner's ruling in the decisions record. Co-Authored-By: Claude Opus 5.5 --- project-management/JOURNAL.md | 24 ++++++++++++++ ...261103-2338-crewmate-becomes-mason.spec.md | 33 ++++++++++++------- ...261103-2338-crewmate-becomes-mason.work.md | 7 +++- project-management/review-360-decisions.md | 14 ++++++++ 4 files changed, 65 insertions(+), 13 deletions(-) rename project-management/{tasks => archive}/20261103-2338-crewmate-becomes-mason.spec.md (79%) rename project-management/{tasks => archive}/20261103-2338-crewmate-becomes-mason.work.md (97%) diff --git a/project-management/JOURNAL.md b/project-management/JOURNAL.md index 7ef53e1..9082887 100644 --- a/project-management/JOURNAL.md +++ b/project-management/JOURNAL.md @@ -5,6 +5,30 @@ ships. --- +## 51. 2026-11-03 β€” The Crewmate becomes the Mason, and the Typist ticks only what really ran + +In the Harness that runs chisel's projects, "crewmate" names the per-task +session that plays chisel's Architect, and chisel used the same word for +the sub-agent that Architect launches: one word for two roles made a plan +reading get skipped on chisel-intentions. On the Owner's word, "Architect β†’ +Mason β†’ Typist": the role is renamed everywhere outside history, in the +socle and its copy, the templates, the charter, the README and the +philosophy, and the `chisel-beads` actor becomes `mason`. The migration +intention `unreleased/crewmate-becomes-mason` has an update session rename +the word in a project's own files, each rename in its own instructions and +skills on the human's word. History keeps its words. + +A project equipped with chisel saw a Typist tick "run it for real" after a +run on a throw-away test base. "The Typist brief" now says a box is ticked +only for what really ran, on the real target; a dry run or a run on a copy +goes in the worklog and leaves its box open. The informational intention +`unreleased/typist-ticks-what-ran` tells updated repos. + +The Mason wrote every edit and both intentions as exact text, a Haiku +Typist typed them, gates green. Two fresh reviewers found the archive +listed twice in the intention's Out of Scope, the manifest missing from its +check, and an undefined "Harness"; all fixed by the Mason as retouches. + ## 50. 2026-11-03 β€” The Crewmate hands the typing to a Typist Chisel's own task on intentions ran 383 calls, all at the frontier tier, diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md b/project-management/archive/20261103-2338-crewmate-becomes-mason.spec.md similarity index 79% rename from project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md rename to project-management/archive/20261103-2338-crewmate-becomes-mason.spec.md index 15be3cd..3e1045c 100644 --- a/project-management/tasks/20261103-2338-crewmate-becomes-mason.spec.md +++ b/project-management/archive/20261103-2338-crewmate-becomes-mason.spec.md @@ -1,6 +1,6 @@ # The Crewmate becomes the Mason, and the Typist ticks only what really ran -**Status:** in-progress +**Status:** done --- @@ -51,20 +51,26 @@ seeing it. ## Acceptance Criteria -- [ ] **no-crewmate-outside-history** β€” `git grep -il crewmate` lists only +- [x] **no-crewmate-outside-history** β€” `git grep -il crewmate` lists only the history files of "Not Included", the new intention (it names the old word to find it), and this task's own documents. -- [ ] **no-crewmate-idea-left** β€” a case-insensitive `git grep -w crew` + Met, with two named extras: `AGENTS.md` keeps "the Mason (named the + Crewmate in the record)" on the Architect's ruling, so the G16 citation + still leads to its ruling; `.agents/.chisel.json` and + `src/socle-files.ts` carry intention ids and 0.3.0 file names, which + "Not Included" keeps. +- [x] **no-crewmate-idea-left** β€” a case-insensitive `git grep -w crew` outside history finds nothing that names the role. -- [ ] **typist-ticks-what-ran** β€” "The Typist brief" of +- [x] **typist-ticks-what-ran** β€” "The Typist brief" of `socle/agents/workflow.md` carries the tick rule: real run, real target, dry run or copy in the worklog. -- [ ] **socle-copy-identical** β€” `diff -r .agents socle/agents` shows only +- [x] **socle-copy-identical** β€” `diff -r .agents socle/agents` shows only `.chisel.json`, `project.md`/`project.md.tpl` and `skills/chisel-release`. -- [ ] **intention-ships** β€” `socle/intentions/unreleased/crewmate-becomes-mason.md` +- [x] **intention-ships** β€” `socle/intentions/unreleased/crewmate-becomes-mason.md` follows `socle/intentions/TEMPLATE.md`, classification `migration`, and - is listed in `src/socle-files.ts`. -- [ ] **gates-green** β€” `deno task check` and `deno task test` pass. + is listed in `src/socle-files.ts`. A second, informational intention, + `unreleased/typist-ticks-what-ran`, ships beside it (Architect's ruling). +- [x] **gates-green** β€” `deno task check` and `deno task test` pass. ## Seams @@ -109,10 +115,11 @@ and is kept byte-identical for the shared files. ## Deliverables -- [ ] The renamed socle and its copy, the docs and templates -- [ ] The Typist line -- [ ] The intention -- [ ] A pull request in conventional commits +- [x] The renamed socle and its copy, the docs and templates +- [x] The Typist line +- [x] The intention +- [ ] A pull request in conventional commits β€” the commits are conventional; + opening the pull request is the Architect's, after the close ## References @@ -124,3 +131,5 @@ and is kept byte-identical for the shared files. ## Notes ## Retrospective + +The Mason's `retro` proposals went to the Architect in its close report. diff --git a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md b/project-management/archive/20261103-2338-crewmate-becomes-mason.work.md similarity index 97% rename from project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md rename to project-management/archive/20261103-2338-crewmate-becomes-mason.work.md index e75adaa..29971e8 100644 --- a/project-management/tasks/20261103-2338-crewmate-becomes-mason.work.md +++ b/project-management/archive/20261103-2338-crewmate-becomes-mason.work.md @@ -260,6 +260,11 @@ text. (the one `AGENTS.md` occurrence is the approved gloss). `code-review` run on `origin/main...HEAD`; the fixes below typed by the Mason itself, under the retouch exception (a few lines in three files); gates green. +- 2026-11-03 β€” Mason, close: spec criteria ticked, status `done`; nothing + to promote (the living docs, glossary and ADR paths the glue names do + not exist in this repo); the Owner's ruling recorded as Addendum 19 of + the decisions record; journal entry 51; both documents archived. Nothing + started that needs stopping: no container, server or background process. ## Implementation Checkboxes @@ -272,7 +277,7 @@ text. - [x] Gates green, commit 2 - [x] Criteria greps and the `diff -r` run - [x] `code-review`, findings recorded -- [ ] Close: criteria ticked, documents archived, journal entry, retro, commit 3 +- [x] Close: criteria ticked, documents archived, journal entry, retro, commit 3 ## Notes & Snippets diff --git a/project-management/review-360-decisions.md b/project-management/review-360-decisions.md index c945288..fc7d7ac 100644 --- a/project-management/review-360-decisions.md +++ b/project-management/review-360-decisions.md @@ -1401,3 +1401,17 @@ part. Ce qui remplace Β« Le Typist est optionnel Β» de l'Addendum 15 : tant que le plan n'est pas arrΓͺtΓ©, et il le dit dans le worklog du document de travail. - βœ… **Les reviewers restent *frontier*.** + +## Addendum 19 (2026-11-03) β€” le Crewmate devient le Mason + +Dans le Harness, Β« crewmate Β» nomme la session par tΓ’che lancΓ©e par un +secondmate, qui joue l'Architect de chisel. Un mΓͺme mot pour deux rΓ΄les a +fait sauter une lecture de plan (tΓ’che chisel-intentions). L'Owner : +Β« Chisel ne doit pas parler de crewmate. Architect β†’ Mason β†’ Typist. Β» + +- βœ… **Le rΓ΄le s'appelle le Mason** partout hors historique ; l'acteur de + `chisel-beads` devient `mason`. Ce qu'il fait ne change pas. Les addenda + prΓ©cΓ©dents gardent Β« Crewmate Β». +- βœ… **Le Typist ne coche que ce qui a vraiment tournΓ©**, sur la vraie + cible ; un essai Γ  blanc ou sur une copie va dans le worklog, la case + reste ouverte (retour d'un projet Γ©quipΓ©, tΓ’che id-by-rivoli).