Complete CommerceCanon rename and declare concept ownership boundary
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a070b5-4994-7271-bd8b-7c3dbcedec4b
This commit is contained in:
parent
40d5792faf
commit
c7002cfcea
18 changed files with 279 additions and 324 deletions
|
|
@ -19,7 +19,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
|
|||
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=identity-canon` is for coordination, not secret vending |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=commerce-canon` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
## First Session Protocol
|
||||
|
||||
Triggered when `get_domain_summary("infotech")` shows **no workplans**.
|
||||
Triggered when `get_domain_summary("financials")` shows **no workplans**.
|
||||
The project is registered but work has not yet been structured.
|
||||
|
||||
**Step 1 — Read, don't write**
|
||||
- `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases
|
||||
- `~/the-custodian/canon/projects/financials/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/financials/roadmap_v0.1.md` — planned phases
|
||||
- Scan repo root: README, directory structure, existing code or docs
|
||||
|
||||
**Step 2 — Survey in-progress work**
|
||||
|
|
@ -15,24 +15,24 @@ Look for TODOs, open branches, half-finished files. Note done vs. started but in
|
|||
Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
|
||||
roadmap phase. **Wait for approval before creating.**
|
||||
|
||||
**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
|
||||
**Step 4 — Write the workplan file; Repo Manager projects it (ADR-001)**
|
||||
```
|
||||
workplans/IDENTITY-WP-NNNN-<slug>.md ← write this, commit it
|
||||
workplans/COMMERCE-WP-NNNN-<slug>.md ← write this, commit it
|
||||
```
|
||||
Then register by running the consistency check — do **not** call
|
||||
`create_workplan`/`create_task` yourself; manual registration duplicates what
|
||||
C-06 creates from the file:
|
||||
Then run the deterministic, forge-derived sync — do **not** call
|
||||
`create_workplan`/`create_task` yourself:
|
||||
```bash
|
||||
statehub fix-consistency --repo identity-canon
|
||||
uv run --project ~/repo-manager rmgr sync --path . --push
|
||||
```
|
||||
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
|
||||
(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
|
||||
back into the file.
|
||||
Repo Manager writes deterministic `state_hub_workstream_id` and
|
||||
`state_hub_task_id` values, pushes the file, verifies `primary/railliance01`,
|
||||
and asks central to derive that exact Forgejo commit. If connectivity is down,
|
||||
the queued receipt is pending evidence; rerun the same command later.
|
||||
|
||||
**Step 5 — Record the setup**
|
||||
```
|
||||
add_progress_event(
|
||||
summary="First session: structured infotech into N workplans, M tasks",
|
||||
summary="First session: structured financials into N workplans, M tasks",
|
||||
event_type="milestone",
|
||||
topic_id="fe2aaa78-9c20-4feb-b3d2-4fe0529572a3",
|
||||
detail={"workplans": [...], "tasks_created": M}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
## Repo boundary
|
||||
|
||||
This repo owns **identity-canon** only. It does not own:
|
||||
This repo owns **commerce-canon** only. It does not own:
|
||||
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
**Purpose:** Othogonal vocabulary and canonical model for identity related concepts.
|
||||
**Purpose:** Counterparty and commercial-relationship semantics, importing shared concepts from InfoTechCanon.
|
||||
|
||||
**Domain:** infotech
|
||||
**Repo slug:** identity-canon
|
||||
**Domain:** financials
|
||||
**Repo slug:** commerce-canon
|
||||
**Topic ID:** fe2aaa78-9c20-4feb-b3d2-4fe0529572a3
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ cat .custodian-brief.md
|
|||
```
|
||||
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
|
||||
```
|
||||
get_domain_summary("infotech")
|
||||
get_domain_summary("financials")
|
||||
```
|
||||
If MCP tools are unavailable in the current agent session, use the REST API:
|
||||
```bash
|
||||
|
|
@ -22,14 +22,14 @@ If the hub is offline: `cd ~/state-hub && make api`
|
|||
**Step 2 — Check inbox**
|
||||
With MCP tools:
|
||||
```
|
||||
get_messages(to_agent="identity-canon", unread_only=True)
|
||||
get_messages(to_agent="commerce-canon", unread_only=True)
|
||||
```
|
||||
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
|
||||
requests before proceeding.
|
||||
|
||||
Without MCP tools:
|
||||
```bash
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=identity-canon&unread_only=true" \
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=commerce-canon&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
|
|
@ -44,8 +44,8 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
|
|||
|
||||
**Step 4 — Present brief**
|
||||
|
||||
1. **Active workplans** for `infotech` — title, task counts, blocking decisions
|
||||
2. **Pending tasks** from `workplans/` + any `[repo:identity-canon]` hub tasks
|
||||
1. **Active workplans** for `financials` — title, task counts, blocking decisions
|
||||
2. **Pending tasks** from `workplans/` + any `[repo:commerce-canon]` hub tasks
|
||||
3. **Goal guidance** — if `goal_guidance` in summary:
|
||||
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
|
||||
- `alignment_warnings`: flag if active work is not aligned with current goal
|
||||
|
|
@ -58,14 +58,24 @@ If no workplans: follow First Session Protocol (`first-session.md`).
|
|||
|
||||
> State Hub is a *read model*. **Never register workplans or tasks by hand**
|
||||
> (`create_workplan`, `create_task`) — write the workplan file in `workplans/`
|
||||
> and run `fix-consistency`; C-06 registers the workplan and tasks and writes
|
||||
> IDs back into the file. Manual registration creates duplicates when
|
||||
> fix-consistency runs. Work structure belongs in repo files (ADR-001).
|
||||
> and run `uv run --project ~/repo-manager rmgr sync --path . --push`.
|
||||
> Repo Manager assigns missing deterministic IDs; central derives the exact
|
||||
> pushed Forgejo commit. Manual registration creates duplicate ownership.
|
||||
> Work structure belongs in repo files (ADR-001).
|
||||
>
|
||||
> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
|
||||
> see `workplan-convention.md` (compatibility footnote).
|
||||
|
||||
**Session close:**
|
||||
1. Update workplan/task statuses in repo files.
|
||||
2. If marking a workplan **finished**: hand off residuals as **live work
|
||||
records** first (intake with `origin: residual` + `origin_ref: <WP-id>`, or
|
||||
a child workplan / decision / engagement). Do not leave actionable leftovers
|
||||
only as prose or in `SCOPE.md`. See work-record-types § Residuals.
|
||||
3. Log progress (below).
|
||||
4. `uv run --project ~/repo-manager rmgr sync --path . --push` when workplan
|
||||
files changed. Use `statehub fix-consistency` separately for a deep audit.
|
||||
|
||||
With MCP tools:
|
||||
```
|
||||
add_progress_event(summary="...", topic_id="fe2aaa78-9c20-4feb-b3d2-4fe0529572a3", workplan_id="<uuid>")
|
||||
|
|
@ -80,13 +90,7 @@ If workplan files were modified, ensure the local copy is up to date first,
|
|||
then sync from the repo checkout:
|
||||
```bash
|
||||
git pull --ff-only
|
||||
statehub fix-consistency
|
||||
uv run --project ~/repo-manager rmgr sync --path . --push
|
||||
```
|
||||
For repos where implementation runs on a remote machine (e.g. CoulombCore),
|
||||
use the pull-before-fix mode from any shell with the State Hub CLI:
|
||||
```bash
|
||||
statehub fix-consistency --repo identity-canon --remote
|
||||
```
|
||||
**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
|
||||
will sync the file to match DB. **C-16** (repo behind remote) blocks all writes
|
||||
until you pull — intentional to prevent clobbering remote progress.
|
||||
The sync refuses uncommitted workplan files and a branch behind its upstream.
|
||||
This prevents a workstation projection from getting ahead of the forge source.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
## Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/IDENTITY-WP-NNNN-<slug>.md`
|
||||
ID prefix: `IDENTITY-WP-`
|
||||
File location: `workplans/COMMERCE-WP-NNNN-<slug>.md`
|
||||
ID prefix: `COMMERCE-WP-`
|
||||
|
||||
Work items originate as files in this repo **before** being registered in the hub.
|
||||
|
||||
|
|
@ -12,24 +12,35 @@ repo state, and `finished` when implementation is complete. `stalled` and
|
|||
`needs_review` are derived health labels, not stored statuses.
|
||||
|
||||
Closed workplans may be moved to `workplans/archived/` with a completion-date
|
||||
prefix: `YYMMDD-IDENTITY-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
prefix: `YYMMDD-COMMERCE-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
unchanged; the prefix is only for quick visual reference.
|
||||
|
||||
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
|
||||
`workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids
|
||||
`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
|
||||
directly. Promote anything requiring analysis, design, approval, dependencies, or
|
||||
multiple planned phases into a normal workplan.
|
||||
`workplans/ADHOC-YYYY-MM-DD.md`, workplan id
|
||||
`COMMERCE-WP-ADHOC-YYYY-MM-DD`, and task ids
|
||||
`COMMERCE-WP-ADHOC-YYYY-MM-DD-T01`, `T02`, etc. `IDENTITY-WP` includes its final
|
||||
`-WP` token. Unqualified historic `ADHOC-*` ids are grandfathered and must not
|
||||
be copied into new records. Use adhocs only for low-risk work completed directly.
|
||||
Promote anything requiring analysis, design, approval, dependencies, or multiple
|
||||
planned phases into a normal workplan.
|
||||
|
||||
Ecosystem todos from other agents arrive as `[repo:identity-canon]` hub tasks —
|
||||
visible at session start. Pick one up by creating the workplan file, committing,
|
||||
and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
|
||||
Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).
|
||||
Ecosystem todos from other agents arrive as `[repo:commerce-canon]` hub tasks —
|
||||
visible at session start. Pick one up by creating the workplan file, then run
|
||||
the fast authoritative projection path:
|
||||
|
||||
```bash
|
||||
uv run --project ~/repo-manager rmgr sync --path . --push
|
||||
```
|
||||
|
||||
Repo Manager assigns only missing deterministic identifiers. Central reads the
|
||||
exact pushed Forgejo commit and updates its replaceable projection. Never
|
||||
register by hand with `create_workplan` or `create_task`. Use
|
||||
`statehub fix-consistency` separately for a deep audit.
|
||||
|
||||
Task blocks use this shape:
|
||||
|
||||
```task
|
||||
id: IDENTITY-WP-NNNN-T01
|
||||
id: COMMERCE-WP-NNNN-T01
|
||||
status: wait | todo | progress | done | cancel
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
|
|
@ -38,6 +49,22 @@ state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
|||
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
|
||||
blocked work and `cancel` for stopped work.
|
||||
|
||||
### Residuals (role, not kind)
|
||||
|
||||
When finishing a workplan, **actionable leftovers must become live work
|
||||
records** before `status: finished`. Residual is not a registered kind and
|
||||
must not be parked only in `SCOPE.md` or finished-file prose.
|
||||
|
||||
| Shape | Capture as | Links |
|
||||
| --- | --- | --- |
|
||||
| Small Green/Blue parkable | intake (queue YAML / `*-IN-*`) | `origin: residual`, `origin_ref: COMMERCE-WP-NNNN` |
|
||||
| Multi-step | next workplan | name parent WP; optional promote from residual intake |
|
||||
| Founder gate / time | decision / engagement | same origin fields when from residual intake |
|
||||
|
||||
Fleet listing of residuals is a State Hub concern (`list_intakes` + origin
|
||||
filters; planned `statehub residuals`). Canon:
|
||||
`the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
|
||||
|
||||
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
|
||||
kept for compatibility; it holds the hub workplan UUID and is written by
|
||||
fix-consistency. Do not edit or rename it.
|
||||
|
|
@ -46,7 +73,7 @@ fix-consistency. Do not edit or rename it.
|
|||
|
||||
**Workplan** is the fleet term — see
|
||||
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
|
||||
**Workplan** is legacy only: some API routes (`/workstreams/`), params
|
||||
**Workstream** is legacy only: some API routes (`/workstreams/`), params
|
||||
(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
|
||||
above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
|
||||
identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue