The numbering is the flow: decisions are 02, design is 03
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
This commit is contained in:
@@ -6,7 +6,7 @@ description: Use when a hal-hq design document must change, or when an as-is doc
|
||||
# hal-amend-design
|
||||
|
||||
Changes a design document. **Authoritative playbook:**
|
||||
[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md).
|
||||
[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md).
|
||||
|
||||
## Which layer is being changed
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ description: Use when investigating an open hal-hq issue — finding which compo
|
||||
# hal-diagnose
|
||||
|
||||
Investigates an open issue to the point where its owner is known. **Authoritative playbook:**
|
||||
[`00-GENESIS/process/03-issues.md`](../../../00-GENESIS/process/03-issues.md).
|
||||
[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md).
|
||||
|
||||
## Before forming a hypothesis
|
||||
|
||||
@@ -28,7 +28,7 @@ result is not "nothing to learn" — it is the reason the next person repeats th
|
||||
what was ruled out and how. Archaeology — which commit, which pull request, which date a
|
||||
behaviour changed — is the most valuable content here.
|
||||
3. When the owner is known, set `status: located` and fill `located-in:` with repositories or
|
||||
modules from [`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md).
|
||||
modules from [`00-META/repos.md`](../../../00-META/repos.md).
|
||||
4. On resolution: `status: resolved`, fill `fixed-by:`. If the root cause was a design gap, run
|
||||
`hal-graduate` for the amendment and fill `amended-design:`.
|
||||
|
||||
|
||||
@@ -7,17 +7,17 @@ description: Use when a hal-hq research effort concludes and becomes design, or
|
||||
|
||||
Closes a research effort into a decision and a design, or amends an existing design.
|
||||
**Authoritative playbook:**
|
||||
[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md) — read
|
||||
[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md) — read
|
||||
it; this skill adds only the scaffolding.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Check against GENESIS** — `mission.md`, `context.md`, `effect.md`. If the conclusion
|
||||
conflicts, say which is wrong, in writing, before proceeding.
|
||||
2. **Write the decision record** in `adr/`, next free number, frontmatter per
|
||||
[`adr/README.md`](../../../adr/README.md). `reconstructed: false` — this one is being taken,
|
||||
2. **Write the decision record** in `02-DECISIONS/`, next free number, frontmatter per
|
||||
[`02-DECISIONS/README.md`](../../../02-DECISIONS/README.md). `reconstructed: false` — this one is being taken,
|
||||
not recovered. Record the rejected options.
|
||||
3. **Write the design** under `02-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`,
|
||||
3. **Write the design** under `03-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`,
|
||||
empty `code:`, today's `updated:`, and `decisions:` pointing at the record.
|
||||
4. **Close the effort** — the research `00-overview.md` gets `status: graduated` and `became:`
|
||||
pointing at both.
|
||||
@@ -31,7 +31,7 @@ Then edit the design and set `updated:`.
|
||||
|
||||
## When something ships
|
||||
|
||||
Write or update the matching `02-DESIGN/00-as-is/` document so it describes what now runs,
|
||||
Write or update the matching `03-DESIGN/00-as-is/` document so it describes what now runs,
|
||||
including anything that shipped differently from the intent. Set the to-be document's
|
||||
`status: implemented` and its `code:`. **The to-be document does not move** — both stand.
|
||||
|
||||
|
||||
@@ -6,18 +6,18 @@ description: Use when a hal-hq design is settled and implementation is about to
|
||||
# hal-handoff
|
||||
|
||||
Hands a settled design to a code repository. **Authoritative playbook:**
|
||||
[`00-GENESIS/process/04-build-handoff.md`](../../../00-GENESIS/process/04-build-handoff.md).
|
||||
[`00-META/process/04-build-handoff.md`](../../../00-META/process/04-build-handoff.md).
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Confirm it is settled.** `status: designed`, and every claim traceable to a record in
|
||||
`adr/`. An open question in the text is a reason to run `hal-new-research`, not to build
|
||||
`02-DECISIONS/`. An open question in the text is a reason to run `hal-new-research`, not to build
|
||||
around it.
|
||||
2. **Name the owner.** Set `code:` from
|
||||
[`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md). If the repository does not exist yet,
|
||||
[`00-META/repos.md`](../../../00-META/repos.md). If the repository does not exist yet,
|
||||
add it to `repos.md` in the same change.
|
||||
3. **Read the as-is counterpart.** What is being replaced must be written down in
|
||||
`02-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how
|
||||
`03-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how
|
||||
shipped behaviour gets lost.
|
||||
4. **Flip the status** to `in-progress`, `updated:` today.
|
||||
5. Build in the code repository. hal-hq never carries implementation.
|
||||
|
||||
@@ -6,7 +6,7 @@ description: Use when something is wrong with the HAL mesh at the level of desig
|
||||
# hal-new-issue
|
||||
|
||||
Opens a numbered issue. **Authoritative playbook:**
|
||||
[`00-GENESIS/process/03-issues.md`](../../../00-GENESIS/process/03-issues.md).
|
||||
[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md).
|
||||
|
||||
## First, decide it belongs here
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ description: Use when starting a new research effort in hal-hq — an idea, tech
|
||||
# hal-new-research
|
||||
|
||||
Scaffolds a new research effort. **Authoritative playbook:**
|
||||
[`00-GENESIS/process/01-research.md`](../../../00-GENESIS/process/01-research.md) — read it;
|
||||
[`00-META/process/01-research.md`](../../../00-META/process/01-research.md) — read it;
|
||||
this skill only does the mechanical setup.
|
||||
|
||||
## Steps
|
||||
@@ -33,7 +33,7 @@ this skill only does the mechanical setup.
|
||||
- Do not restate the status in prose. It lives in frontmatter, in one place.
|
||||
- Do not fill `became:` while the effort is open — `hal-graduate` sets it at closure.
|
||||
- Do not skip or reuse a sequence number.
|
||||
- Do not write into `02-DESIGN` from an open effort.
|
||||
- Do not write into `03-DESIGN` from an open effort.
|
||||
- Do not name the mesh being observed. Evidence is required; identification is forbidden.
|
||||
|
||||
## Closing
|
||||
|
||||
@@ -14,8 +14,8 @@ generated on demand and never written back to disk.
|
||||
| Section | Files | Frontmatter |
|
||||
|---|---|---|
|
||||
| Research | `01-RESEARCH/NNN-*/00-overview.md` | `status` (`active` / `graduated` / `abandoned`), `initiated`, `touches`, `became` |
|
||||
| Design | `02-DESIGN/**/*.md` (not READMEs) | `layer` (`as-is` / `to-be`), `status` (`designed` / `in-progress` / `implemented` / `abandoned`), `code`, `updated`, `decisions` |
|
||||
| Decisions | `adr/NNNN-*.md` | `status` (`proposed` / `accepted` / `superseded`), `date`, `deciders`, `reconstructed`, `superseded-by`, `extends` |
|
||||
| Design | `03-DESIGN/**/*.md` (not READMEs) | `layer` (`as-is` / `to-be`), `status` (`designed` / `in-progress` / `implemented` / `abandoned`), `code`, `updated`, `decisions` |
|
||||
| Decisions | `02-DECISIONS/NNNN-*.md` | `status` (`proposed` / `accepted` / `superseded`), `date`, `deciders`, `reconstructed`, `superseded-by`, `extends` |
|
||||
| Issues | `04-ISSUES/NNN-*/00-report.md` | `status` (`open` / `diagnosing` / `located` / `resolved` / `wontfix`), `opened`, `located-in`, `fixed-by`, `amended-design` |
|
||||
|
||||
## Steps
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
name: hal-sync-constitution
|
||||
description: Use after changing a rule in hal-hq's 00-GENESIS/how-we-build.md, to publish the derived constitution page the mesh injects into design sessions. Triggers on "sync the constitution", "publish the rules", "I changed how-we-build", "update the governed page".
|
||||
description: Use after changing a rule in hal-hq's 00-META/how-we-build.md, to publish the derived constitution page the mesh injects into design sessions. Triggers on "sync the constitution", "publish the rules", "I changed how-we-build", "update the governed page".
|
||||
---
|
||||
|
||||
# hal-sync-constitution
|
||||
|
||||
Publishes the derived constitution from its source. **Authoritative playbook:**
|
||||
[`00-GENESIS/process/05-constitution-sync.md`](../../../00-GENESIS/process/05-constitution-sync.md).
|
||||
[`00-META/process/05-constitution-sync.md`](../../../00-META/process/05-constitution-sync.md).
|
||||
|
||||
## What this is
|
||||
|
||||
[`00-GENESIS/how-we-build.md`](../../../00-GENESIS/how-we-build.md) is the **source**. The
|
||||
[`00-META/how-we-build.md`](../../../00-META/how-we-build.md) is the **source**. The
|
||||
knowledge base carries a **derived** page that the mesh injects into every eligible design
|
||||
session, and against which a check phase can block work.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user