Correct repo flavor to product; add SCOPE, AGENTS, classification
fix-consistency surfaced that GOAL.md's `repo_flavor: project` was wrong. project-repository-flavor_v0.1.md reserves the prj- flavor for bounded cross-repo coordination efforts and says durable products use INTENT.md and an ordinary category. informed-decision is a durable product, so the C-35 "prj- flavor forbids shipping both INTENT.md and GOAL.md" contradiction was self-inflicted rather than a real conflict. - .repo-classification.yaml: category product, domain infotech. - GOAL.md: drop repo_flavor/project_status, add a flavor note explaining that GOAL.md is retained as the stage statement alongside a stable INTENT.md. - SCOPE.md: honestly empty — states that nothing is implemented and that INFD-WP-0001-T06 rewrites it after the gate-house ruling and the specs. - AGENTS.md: shared State Hub / session / workplan boilerplate, plus the hard rules for this repository — never decide, never own approval state, never invent identity, never let awareness enter view_hash, never let an agent bind, never fork the schema, fail closed. - INFD-WP-0001: T01 records both corrections; T06 now rewrites SCOPE.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V3W1dQG7GFFM9d94jFx7iR Assistant: claude-code Assistant-Model: opus Assistant-Process: 1565372@bnt-lap001 Assistant-Session: 16bb2f25-b34c-49ef-8e94-5fec3567a568
This commit is contained in:
parent
0f5a6c4f59
commit
309bea463e
6 changed files with 461 additions and 10 deletions
296
AGENTS.md
Normal file
296
AGENTS.md
Normal file
|
|
@ -0,0 +1,296 @@
|
|||
# informed-decision — Agent Instructions
|
||||
|
||||
## Repo Identity
|
||||
|
||||
**Purpose:** Presentation and binding surface for decisions — the Decision Memo, and the browser-facing approver UI that approval-engine does not contain.
|
||||
|
||||
**Domain:** infotech
|
||||
**Repo slug:** informed-decision
|
||||
**Topic ID:** `a6c6e745-bf54-4465-9340-1534a2be493e`
|
||||
**Workplan prefix:** `INFD-WP-`
|
||||
**Category:** product (not `prj-` project flavor — see `.repo-classification.yaml`)
|
||||
|
||||
Read in this order: `INTENT.md` (stable purpose) → `GOAL.md` (current stage) →
|
||||
`SCOPE.md` (what actually exists) → `workplans/`.
|
||||
|
||||
`history/20260909-initial-exploration/` is the founding provenance record and is
|
||||
**never edited**. Governed copies of the schema, canonicalizer and vectors live
|
||||
in `schemas/` and the package once `INFD-WP-0001-T06` promotes them.
|
||||
|
||||
---
|
||||
|
||||
## State Hub Integration
|
||||
|
||||
The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and
|
||||
the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge
|
||||
adds severe call latency; the full administrative MCP surface remains available
|
||||
to clients that need it.
|
||||
|
||||
| Context | URL |
|
||||
|---------|-----|
|
||||
| Local workstation | `http://127.0.0.1:8000` |
|
||||
| Remote via tunnel | `http://127.0.0.1:18000` |
|
||||
| Optional local edge relay | http://127.0.0.1:18080 |
|
||||
|
||||
When an operator has enabled the edge relay, set API_BASE to the relay URL.
|
||||
Queueable writes return an explicit queued receipt if the central hub is
|
||||
unreachable. Treat that as pending local evidence, then ask the operator to run
|
||||
statehub outbox status/replay after connectivity returns.
|
||||
|
||||
Codex workspace-write sandboxes need network access enabled to reach the host's
|
||||
loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex`
|
||||
and restart Codex. The canonical REST health endpoint is `/state/health`, not
|
||||
`/health`. If a sandboxed loopback probe fails, retry it with escalated execution
|
||||
before declaring State Hub unavailable; a managed Codex permission profile may
|
||||
still enforce isolated networking. Experimental MCP can be enabled explicitly
|
||||
with `make -C ~/state-hub configure-codex WITH_MCP=1`.
|
||||
|
||||
### Orient at session start
|
||||
|
||||
```bash
|
||||
# Offline brief — works without hub connection
|
||||
cat .custodian-brief.md
|
||||
|
||||
# Active workplans for this domain
|
||||
curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
# Check inbox
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=informed-decision&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
```
|
||||
|
||||
Mark a message read:
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
### Log progress (required at session close)
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"summary": "what was done",
|
||||
"event_type": "note",
|
||||
"author": "codex",
|
||||
"workplan_id": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
Omit `workplan_id` / `task_id` when not applicable.
|
||||
|
||||
### Update task status
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"status": "progress"}'
|
||||
# values: wait | todo | progress | done | cancel
|
||||
```
|
||||
|
||||
### Flag a task for human review
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"needs_human": true, "intervention_note": "reason"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Protocol
|
||||
|
||||
**Start:**
|
||||
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
|
||||
2. Check inbox: `GET /messages/?to_agent=informed-decision&unread_only=true`; mark read
|
||||
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
|
||||
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
|
||||
|
||||
**During work:**
|
||||
- Update task statuses in workplan files as tasks progress
|
||||
- Record significant decisions via `POST /decisions/`
|
||||
|
||||
**Close:**
|
||||
1. Update workplan file task statuses to reflect progress
|
||||
2. If finishing a workplan: hand off **residuals** as live work records first
|
||||
(intake with `origin: residual` + `origin_ref: <WP-id>`, or a next workplan /
|
||||
decision / engagement). Do not park leftovers only in prose or `SCOPE.md`.
|
||||
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
|
||||
3. Log: `POST /progress/` with a summary of what changed (name handoff ids)
|
||||
4. After workplan file changes, run:
|
||||
```bash
|
||||
statehub fix-consistency
|
||||
```
|
||||
Coding agents should run this directly; ask the operator only if the CLI or
|
||||
State Hub API is unavailable. This syncs task status from files into the hub DB.
|
||||
If C-06/C-11 reports that this host is not the identifier registrar, do not
|
||||
retry, export `STATEHUB_REGISTRAR`, or register records by hand. Commit and
|
||||
push the file-backed work first, then run the repo-manager fallback once:
|
||||
```bash
|
||||
uv run --project ~/repo-manager rmgr registrar-reconcile \
|
||||
--path . --confirm-primary --push
|
||||
```
|
||||
If unavailable, send one deduplicated registrar request to `repo-manager`
|
||||
naming the repo and canonical ids; UUID absence does not block local work.
|
||||
|
||||
---
|
||||
|
||||
## Credential and access routing
|
||||
|
||||
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
||||
for inference. Run this check **before** requesting secrets, API keys, SSH access,
|
||||
login tokens, or database passwords — in any repo, not only `ops-warden`.
|
||||
|
||||
The companion (`net-kingdom/SECURITY-COMPANION.md`) says what the rules are;
|
||||
`ops-warden` stewards the paths through them. **Do not** message `ops-warden`
|
||||
on State Hub expecting a secret value; the reply is a pointer, not a key.
|
||||
|
||||
### Lookup (do this first)
|
||||
|
||||
```bash
|
||||
warden route find "<describe your need>" --json
|
||||
warden route show <catalog-id> --json
|
||||
```
|
||||
|
||||
Requires the `warden` CLI from `~/ops-warden`.
|
||||
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route`; inbox `to_agent=informed-decision` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | domain summary for workplans; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** | Never put secret retrieval in prompts |
|
||||
|
||||
### Quick routing table
|
||||
|
||||
| I need… | Owner | ops-warden executes? |
|
||||
| --- | --- | --- |
|
||||
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||
| API key, DB password, provider token | OpenBao | No — route only |
|
||||
| Login / OIDC / MFA | key-cape | No — route only |
|
||||
| Authorization decision | access-engine (`flex-auth`) | No — route only |
|
||||
| Approval current-state | **this engine** (not yet implemented) | No |
|
||||
| SSH tunnel | ops-bridge | No — route only |
|
||||
|
||||
### Anti-patterns
|
||||
|
||||
- Asking State Hub or `ops-warden` to vend a secret
|
||||
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||
- Treating a callable tool as permission (companion §7)
|
||||
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md`
|
||||
|
||||
<!-- REPO-AGENTS-EXTENSIONS -->
|
||||
<!-- Append repo-specific agent instructions below this marker.
|
||||
The state-hub template sync preserves content after this line. -->
|
||||
## This repository's layer
|
||||
|
||||
**Provisional: PEP-shaped**, statute §6.4 / companion §5. Not ratified — the
|
||||
catalog row does not exist and `layer.yaml` is not written yet.
|
||||
`INFD-WP-0001-T02` takes the placement to `gate-house`; the ruling wins over
|
||||
anything asserted in `INTENT.md` or here.
|
||||
|
||||
Hard rules, regardless of how the ruling lands:
|
||||
|
||||
- **Never decide.** No endpoint in this repository answers "may this actor do
|
||||
X". That is `access-engine`, always and only (statute §6). This surface
|
||||
renders a question and records a human's answer; a disposition is evidence of
|
||||
an act, not an authorization verdict.
|
||||
- **Never own approval state.** `approval-engine` is the sole mutator. Do not
|
||||
cache validity, do not infer consumption from a decision record, and do not
|
||||
request scope `approval:consume` — the engine refuses it for human principals
|
||||
and consumption belongs to the PEP that causes the side effect
|
||||
(`GH-DEC-2026-003`).
|
||||
- **Never invent identity.** Every principal is authenticated by `key-cape`.
|
||||
No local credential, no self-issued assurance level.
|
||||
- **Never let awareness enter the signature.** `view_hash` covers only what the
|
||||
person committed to. Proposed roles, other-tenant orientation and last-session
|
||||
summaries are hashed separately and are unsigned unless explicitly promoted
|
||||
into `awareness_promoted`.
|
||||
- **Never let an agent bind.** An agent may assemble a memo; only a human
|
||||
completes a disposition.
|
||||
- **Never fork the schema.** A field added for approvals must be expressible for
|
||||
an L0 login banner, or it does not go in the shared object.
|
||||
- **Fail closed.** Degrading into showing a memo that cannot be bound is
|
||||
acceptable. Degrading into binding without evidence is not.
|
||||
- Remote hub: this host reaches State Hub on `http://127.0.0.1:8000` (primary
|
||||
on railiance01). Do not use `127.0.0.1:18000` — that reverse tunnel is being
|
||||
retired (`CUST-WP-0067`).
|
||||
|
||||
---
|
||||
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
Work items originate as files in this repo — not in the hub. The hub is a
|
||||
read/cache/index layer that rebuilds from files.
|
||||
|
||||
**File location:** `workplans/INFD-WP-NNNN-<slug>.md`
|
||||
|
||||
**Archived location:** finished workplans may move to
|
||||
`workplans/archived/YYMMDD-INFD-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
|
||||
the completion/archive date; the frontmatter `id` does not change.
|
||||
|
||||
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
|
||||
`workplans/ADHOC-YYYY-MM-DD.md`, workplan id
|
||||
`INFD-WP-ADHOC-YYYY-MM-DD`, and task ids
|
||||
`INFD-WP-ADHOC-YYYY-MM-DD-T01`, etc. `APPROVAL-WP` includes its final `-WP`
|
||||
token. Unqualified historic `ADHOC-*` ids are grandfathered and must not be
|
||||
copied into new records. Use this only for low-risk work completed directly;
|
||||
create a normal workplan for anything needing analysis, design, approval,
|
||||
dependencies, or multiple phases.
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: INFD-WP-NNNN
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: infotech
|
||||
repo: approval-engine
|
||||
status: proposed | ready | active | blocked | backlog | finished | archived
|
||||
owner: codex
|
||||
topic_slug: ...
|
||||
created: "YYYY-MM-DD"
|
||||
updated: "YYYY-MM-DD"
|
||||
state_hub_workstream_id: "<uuid>" # fix-consistency — do not edit (legacy field name; workplan UUID)
|
||||
---
|
||||
```
|
||||
|
||||
Use `proposed` for a new draft, `ready` after review against current repo
|
||||
state, and `finished` after implementation. `stalled` and `needs_review` are
|
||||
derived health labels, not frontmatter statuses.
|
||||
|
||||
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
|
||||
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
|
||||
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
|
||||
|
||||
**Task block format** (one per `##` section):
|
||||
|
||||
```
|
||||
## Task Title
|
||||
|
||||
` ` `task
|
||||
id: INFD-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
|
||||
` ` `
|
||||
|
||||
Task description text.
|
||||
```
|
||||
|
||||
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
|
||||
|
||||
**Residuals when finishing:** actionable leftovers become live work records
|
||||
before `status: finished` — usually an intake (`origin: residual`,
|
||||
`origin_ref: INFD-WP-NNNN`) or a spawned workplan. Residual is a *role*,
|
||||
not a kind. Fleet list lives on State Hub, not in `SCOPE.md`.
|
||||
|
||||
To create a new workplan:
|
||||
1. Write the file following the format above
|
||||
2. Run `statehub fix-consistency` locally.
|
||||
3. On a non-registrar C-06/C-11 skip, use the repo-manager fallback documented
|
||||
above exactly once; never set registrar authority directly.
|
||||
Loading…
Add table
Add a link
Reference in a new issue