coilyco-flight-deck/ward

Fork 0

Substrate ships an auto-generated repo catalog (full_name + description + topics) as the read-these-first manifest #594

New issue

Closed

opened 2026-07-04 04:39:39 +00:00 by coilysiren · 3 comments

coilysiren commented

2026-07-04 04:39:39 +00:00

Owner

Problem

The substrate mounts a pile of reference repos (/substrate/<name>) but ships no index of what they are. An agent in a design/ops session has no addressable map of "which repo holds what," so it either spelunks or - the failure that motivated this - interrogates the operator for facts that were readable on disk the whole time (see #593). A second failure in the same session: with no canonical repo list, the agent guessed an owner (coilysiren/ward) off ambient naming and only discovered the canonical coilyco-flight-deck/ward when a mutating write refused to follow forgejo's rename-redirect.

Both failures share a root cause: no catalog. The agent has no first-class, canonical list of the repos, their owners, and what each is for.

Proposal

Ship an auto-generated repo catalog into the substrate seed. Per repo:

canonical full_name (owner/name, straight from forgejo - no alias, no guess)
description
topics
the reference-surface path (/substrate/<name>) when mounted

Consumed as the "read these first" manifest at session start, and the natural backing data for WARD_CONTEXT_REPOS (#593).

Why auto-generated, not hand-maintained

A hand-written list is the point-in-time artifact the AGENTS doctrine warns rots ("a fact true when written goes stale and then silently anchors a wrong picture"). Derived-from-forgejo-on-a-trigger never drifts. Forgejo stays the single source of truth - the catalog is never a hand-duplicated prose copy.

The source data already exists and is good

Sampled today via ward ops forgejo user-repo list coilyco-flight-deck. Descriptions are populated and first-class, e.g.:

coilyco-flight-deck/infrastructure -> "k3s cluster, systemd units, and invoke tasks that run kai-server - the host behind my personal apps and sites"
coilyco-flight-deck/ward -> "Harness driver: sends an AI agent harness ... into ephemeral containers to carry Forgejo issues end to end..."
coilyco-flight-deck/eco-mcp-app -> "Inline Claude Desktop widget ... a hand-rolled MCP Apps reference implementation in Python"

The infrastructure line alone would have short-circuited the low-context interrogation in #593. Caveat: descriptions are the strong axis, topics look sparse - topics are a cheap backfill, and the feature's value should not hang on them.

Placement (config-placement law)

The manifest is container-context config, consumed by ward when it composes a container. Config lives at the layer that consumes it, so:

ward owns the generator (a thin user-repo list / org-repo list query -> manifest) and the manifest lands in the substrate seed (/opt/substrate-seed).
Infra only triggers the regen (push or the seed-refresh cron) - the authoring-vs-rollout split, same as every other rollout.
Forgejo is the single source; the catalog is generated, never hand-edited.

Relationship to #593

This is the data layer under #593. #593 = "label the relevant subset for this session" (WARD_CONTEXT_REPOS). This = the full addressable index that selection reads from. Complementary, different layers. The catalog also independently kills the owner-guessing class of bug by carrying canonical full_names.

Acceptance

A generated catalog file lands in the substrate seed and is present in a fresh container.
Each entry carries canonical full_name, description, topics, and mount path where applicable.
Regeneration is trigger-driven (push or seed-refresh cron), not hand-run.
Filed from the surface session that hit both failures.

## Problem The substrate mounts a pile of reference repos (`/substrate/<name>`) but ships no index of what they are. An agent in a design/ops session has no addressable map of "which repo holds what," so it either spelunks or - the failure that motivated this - interrogates the operator for facts that were readable on disk the whole time (see #593). A second failure in the same session: with no canonical repo list, the agent *guessed* an owner (`coilysiren/ward`) off ambient naming and only discovered the canonical `coilyco-flight-deck/ward` when a mutating write refused to follow forgejo's rename-redirect. Both failures share a root cause: no catalog. The agent has no first-class, canonical list of the repos, their owners, and what each is for. ## Proposal Ship an **auto-generated repo catalog** into the substrate seed. Per repo: - canonical `full_name` (owner/name, straight from forgejo - no alias, no guess) - `description` - `topics` - the reference-surface path (`/substrate/<name>`) when mounted Consumed as the "read these first" manifest at session start, and the natural backing data for `WARD_CONTEXT_REPOS` (#593). ## Why auto-generated, not hand-maintained A hand-written list is the point-in-time artifact the AGENTS doctrine warns rots ("a fact true when written goes stale and then silently anchors a wrong picture"). Derived-from-forgejo-on-a-trigger never drifts. Forgejo stays the single source of truth - the catalog is never a hand-duplicated prose copy. ## The source data already exists and is good Sampled today via `ward ops forgejo user-repo list coilyco-flight-deck`. Descriptions are populated and first-class, e.g.: - `coilyco-flight-deck/infrastructure` -> "k3s cluster, systemd units, and invoke tasks that run kai-server - the host behind my personal apps and sites" - `coilyco-flight-deck/ward` -> "Harness driver: sends an AI agent harness ... into ephemeral containers to carry Forgejo issues end to end..." - `coilyco-flight-deck/eco-mcp-app` -> "Inline Claude Desktop widget ... a hand-rolled MCP Apps reference implementation in Python" The `infrastructure` line alone would have short-circuited the low-context interrogation in #593. Caveat: **descriptions are the strong axis, topics look sparse** - topics are a cheap backfill, and the feature's value should not hang on them. ## Placement (config-placement law) The manifest is container-context config, consumed by ward when it composes a container. Config lives at the layer that consumes it, so: - **ward owns the generator** (a thin `user-repo list` / `org-repo list` query -> manifest) and the manifest lands in the substrate seed (`/opt/substrate-seed`). - **Infra only triggers the regen** (push or the seed-refresh cron) - the authoring-vs-rollout split, same as every other rollout. - Forgejo is the single source; the catalog is generated, never hand-edited. ## Relationship to #593 This is the data layer under #593. #593 = "label the relevant subset for this session" (`WARD_CONTEXT_REPOS`). This = the full addressable index that selection reads from. Complementary, different layers. The catalog also independently kills the owner-guessing class of bug by carrying canonical `full_name`s. ## Acceptance - A generated catalog file lands in the substrate seed and is present in a fresh container. - Each entry carries canonical `full_name`, description, topics, and mount path where applicable. - Regeneration is trigger-driven (push or seed-refresh cron), not hand-run. - Filed from the surface session that hit both failures.

coilyco-ops commented

2026-07-04 04:39:47 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-594 on host KAI-SERVER is carrying this issue (reserved 2026-07-04T04:39:45Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-594` on host `KAI-SERVER` is carrying this issue (reserved 2026-07-04T04:39:45Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh** — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).  — Claude (she/her), via `ward agent`

coilysiren commented

2026-07-04 04:39:52 +00:00

Author

Owner

🔓 Reservation released by ward container reap — container ward (--driver claude) exited without launching the agent (smoke-test death, ward#222/#264), so the hold it took is retracted. A plain ward agent retry no longer needs --force.

— Claude (she/her), via ward agent

🔓 Reservation released by `ward container reap` — container `ward` (`--driver claude`) exited without launching the agent (smoke-test death, ward#222/#264), so the hold it took is retracted. A plain `ward agent` retry no longer needs `--force`.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue

2026-07-04 04:51:01 +00:00

Engineer dispatch smoke-test-dies on KAI-SERVER and a death can orphan the issue - failover re-dispatch is not deterministic #595

coilyco-ops added the

headless

labels

2026-07-04 08:21:26 +00:00

coilyco-ops commented

2026-07-04 08:33:35 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-594 on host KAI-DESKTOP-TOWER is carrying this issue (reserved 2026-07-04T08:33:29Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-594` on host `KAI-DESKTOP-TOWER` is carrying this issue (reserved 2026-07-04T08:33:29Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh** — that is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-04 08:50:45 +00:00

feat(substrate): auto-generate a Forgejo-derived repo catalog for the seed

coilysiren closed this issue

2026-07-04 08:50:45 +00:00

coilysiren referenced this issue

2026-07-04 08:51:25 +00:00

infra: trigger substrate-catalog regen into the seed (follow-up to #594) #602

coilysiren referenced this issue

2026-07-04 17:44:43 +00:00

infra: trigger substrate-catalog regen into the seed (follow-up to #594) #602