generated from coulomb/repo-seed
Add Claude Code support, credential routing polish, and CYA-WP-0006
Mirror sibling-repo Claude setup (CLAUDE.md + .claude/rules/*), align AGENTS.md with fleet credential-routing template, and close housekeeping gaps (WP-0002-T05 done, WP-0005 status note). Draft CYA-WP-0006 for Profile 1 production hardening as the proposed next slice.
This commit is contained in:
32
.claude/rules/agents.md
Normal file
32
.claude/rules/agents.md
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
## Agent entry points
|
||||||
|
|
||||||
|
| Runtime | Canonical instructions |
|
||||||
|
| --- | --- |
|
||||||
|
| **Grok / Codex** (shell) | `AGENTS.md` at repo root |
|
||||||
|
| **Claude Code** | This file tree via `CLAUDE.md` |
|
||||||
|
|
||||||
|
`AGENTS.md` and `.claude/rules/` are kept in sync for repo-specific content.
|
||||||
|
Fleet-wide credential routing is mirrored in `credential-routing.md` and the
|
||||||
|
matching section of `AGENTS.md` — re-sync from `~/ops-warden/wiki/CredentialRouting.md`
|
||||||
|
when the catalog changes.
|
||||||
|
|
||||||
|
## Kaizen Agents
|
||||||
|
|
||||||
|
Specialized agent personas available on demand via the state-hub MCP.
|
||||||
|
|
||||||
|
**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
|
||||||
|
**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
|
||||||
|
|
||||||
|
Common agents:
|
||||||
|
|
||||||
|
| Agent | Category | When to use |
|
||||||
|
|-------|----------|-------------|
|
||||||
|
| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
|
||||||
|
| `code-refactoring` | quality | Code quality analysis and safe refactoring |
|
||||||
|
| `test-maintenance` | testing | Diagnose and fix failing tests |
|
||||||
|
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
|
||||||
|
| `keepaTodofile` | process | Maintain TODO.md during work |
|
||||||
|
| `project-management` | process | Track status, determine next steps |
|
||||||
|
| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
|
||||||
|
|
||||||
|
All 17 agents: call `list_kaizen_agents()` for the full list.
|
||||||
23
.claude/rules/architecture.md
Normal file
23
.claude/rules/architecture.md
Normal file
@@ -0,0 +1,23 @@
|
|||||||
|
## Architecture
|
||||||
|
|
||||||
|
**Request pipeline** (`src/cya/orchestrator.py`):
|
||||||
|
1. Collect local context (`context/collector.py`)
|
||||||
|
2. Recall memory via phase-memory ports (`memory/__init__.py`)
|
||||||
|
3. Classify risk (`safety/risk.py`) — rule-based; memory signals add caution only
|
||||||
|
4. Call LLM via `LLMAdapter` Protocol (`llm/adapter.py`) — FakeLLMAdapter today
|
||||||
|
5. Render explainable response (Rich)
|
||||||
|
|
||||||
|
**Memory (Profile 0 + Profile 1 spike):**
|
||||||
|
- User-controlled local JSON behind explicit ports (`remember`, `recall`, `forget`, `export`)
|
||||||
|
- Kinds: `preference`, `retrospection`, `interaction_goal`, `reflection`
|
||||||
|
- Directory/project-bound activation via `activation_context`
|
||||||
|
- `cya retrospect` feeds higher-order memory; optional verbal lesson capture (Profile 1)
|
||||||
|
|
||||||
|
**Boundaries:** See `repo-boundary.md`. No production path bypasses the adapter or memory ports.
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
- Memory contract: `MemoryVision.md`
|
||||||
|
- Activation/retrospection concept: `docs/cya-memory-activation-and-retrospection-concept.md`
|
||||||
|
- phase-memory feedback: `docs/phase-memory-optimization-suggestions.md`
|
||||||
|
- `~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
|
||||||
54
.claude/rules/credential-routing.md
Normal file
54
.claude/rules/credential-routing.md
Normal file
@@ -0,0 +1,54 @@
|
|||||||
|
# Credential and access routing
|
||||||
|
|
||||||
|
> Fleet template mirrored in `AGENTS.md` (Credential and access routing section).
|
||||||
|
> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes.
|
||||||
|
|
||||||
|
**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`.
|
||||||
|
|
||||||
|
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
||||||
|
other credential need belongs to another subsystem. **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` (`uv tool install .` or `uv run warden`).
|
||||||
|
|
||||||
|
| Agent runtime | How to orient |
|
||||||
|
| --- | --- |
|
||||||
|
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=can-you-assist` is for coordination, not secret vending |
|
||||||
|
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **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` |
|
||||||
|
|
||||||
|
### Quick routing table
|
||||||
|
|
||||||
|
Prefer `warden route find` for repo-specific needs. Common routes:
|
||||||
|
|
||||||
|
| I need… | Owner | ops-warden executes? |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||||
|
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
||||||
|
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
||||||
|
| Authorization decision | flex-auth | No — route only |
|
||||||
|
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
||||||
|
|
||||||
|
### Anti-patterns (do not do these)
|
||||||
|
|
||||||
|
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
||||||
|
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
||||||
|
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||||
|
|
||||||
|
### Other capabilities (reuse-surface)
|
||||||
|
|
||||||
|
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
||||||
|
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
||||||
|
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||||
|
get wrong.
|
||||||
|
|
||||||
|
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||||
37
.claude/rules/first-session.md
Normal file
37
.claude/rules/first-session.md
Normal file
@@ -0,0 +1,37 @@
|
|||||||
|
## First Session Protocol
|
||||||
|
|
||||||
|
Triggered when `get_domain_summary("capabilities")` shows **no workstreams**.
|
||||||
|
The project is registered but work has not yet been structured.
|
||||||
|
|
||||||
|
**Step 1 — Read, don't write**
|
||||||
|
- `INTENT.md`, `README.md`, `SCOPE.md`, `AGENTS.md`, `MemoryVision.md`
|
||||||
|
- Scan repo root: `src/cya/`, `workplans/`, `tests/`
|
||||||
|
|
||||||
|
**Step 2 — Survey in-progress work**
|
||||||
|
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
|
||||||
|
|
||||||
|
**Step 3 — Propose workstreams to Bernd**
|
||||||
|
Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to
|
||||||
|
INTENT/SCOPE. **Wait for approval before creating.**
|
||||||
|
|
||||||
|
**Step 4 — Create workplan file first, then DB record (ADR-001)**
|
||||||
|
```
|
||||||
|
workplans/CYA-WP-NNNN-<slug>.md ← write this first
|
||||||
|
```
|
||||||
|
Then register in the hub:
|
||||||
|
```
|
||||||
|
create_workstream(topic_id="64418556-3206-457a-ba29-6884b5b12cf3", title="...", owner="...", description="...")
|
||||||
|
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 5 — Record the setup**
|
||||||
|
```
|
||||||
|
add_progress_event(
|
||||||
|
summary="First session: structured capabilities/can-you-assist into N workstreams, M tasks",
|
||||||
|
event_type="milestone",
|
||||||
|
topic_id="64418556-3206-457a-ba29-6884b5b12cf3",
|
||||||
|
detail={"workstreams": [...], "tasks_created": M}
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
<!-- Past first session for this repo — retained for fleet consistency -->
|
||||||
11
.claude/rules/repo-boundary.md
Normal file
11
.claude/rules/repo-boundary.md
Normal file
@@ -0,0 +1,11 @@
|
|||||||
|
## Repo boundary
|
||||||
|
|
||||||
|
This repo owns **can-you-assist** (`cya`) only. It does not own:
|
||||||
|
|
||||||
|
- LLM provider access, API clients, or model hosting → `llm-connect`
|
||||||
|
- Durable memory storage, profile planners, graph/event stores, or lifecycle algorithms → `phase-memory`
|
||||||
|
- Global work tracking, decisions, or cross-repo coordination → State Hub / custodian
|
||||||
|
- Credential custody (API keys, DB passwords, OIDC) → OpenBao / key-cape / operator paths (route via `warden route`)
|
||||||
|
- SSH certificate issuance → `ops-warden` (`warden sign` only)
|
||||||
|
|
||||||
|
`cya` integrates via stable seams (`LLMAdapter` Protocol, memory ports). State Hub is non-runtime.
|
||||||
7
.claude/rules/repo-identity.md
Normal file
7
.claude/rules/repo-identity.md
Normal file
@@ -0,0 +1,7 @@
|
|||||||
|
**Purpose:** Console-native, backend-agnostic LLM assistant (`cya`) for practical local work from the shell, using user-controlled context, memory, and provider configuration.
|
||||||
|
|
||||||
|
**Domain:** capabilities
|
||||||
|
**Repo slug:** can-you-assist
|
||||||
|
**Topic ID:** 64418556-3206-457a-ba29-6884b5b12cf3
|
||||||
|
**Workplan prefix:** CYA-WP-
|
||||||
|
**Command name:** cya
|
||||||
90
.claude/rules/session-protocol.md
Normal file
90
.claude/rules/session-protocol.md
Normal file
@@ -0,0 +1,90 @@
|
|||||||
|
## Session Protocol
|
||||||
|
|
||||||
|
State Hub: http://127.0.0.1:8000 (remote tunnel: http://127.0.0.1:18000)
|
||||||
|
|
||||||
|
**Step 1 — Orient**
|
||||||
|
|
||||||
|
Read the offline-safe brief first — it works without a live hub connection:
|
||||||
|
```bash
|
||||||
|
cat .custodian-brief.md
|
||||||
|
```
|
||||||
|
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
|
||||||
|
```
|
||||||
|
get_domain_summary("capabilities")
|
||||||
|
```
|
||||||
|
If MCP tools are unavailable in the current agent session, use the REST API:
|
||||||
|
```bash
|
||||||
|
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \
|
||||||
|
| python3 -m json.tool
|
||||||
|
```
|
||||||
|
If the hub is offline: `cd ~/state-hub && make api`
|
||||||
|
|
||||||
|
**Step 2 — Check inbox**
|
||||||
|
With MCP tools:
|
||||||
|
```
|
||||||
|
get_messages(to_agent="can-you-assist", 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=can-you-assist&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 '{}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 3 — Scan workplans**
|
||||||
|
```bash
|
||||||
|
ls workplans/
|
||||||
|
```
|
||||||
|
For each file with `status: ready`, `active`, or `blocked`, note pending
|
||||||
|
`todo`/`in_progress` tasks.
|
||||||
|
|
||||||
|
**Step 4 — Present brief**
|
||||||
|
|
||||||
|
1. **Active workstreams** for `capabilities` — title, task counts, blocking decisions
|
||||||
|
2. **Pending tasks** from `workplans/` + any `[repo:can-you-assist]` 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
|
||||||
|
4. **Suggested next action** — highest-priority open item
|
||||||
|
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
|
||||||
|
|
||||||
|
If no workstreams: follow First Session Protocol (`first-session.md`).
|
||||||
|
|
||||||
|
**During work:**
|
||||||
|
- Keep changes small and inspectable.
|
||||||
|
- Treat command execution safety as product behavior: explain destructive commands and require explicit confirmation before suggesting execution.
|
||||||
|
- Do not commit secrets, API keys, local transcripts, private notes, or hidden memory contents.
|
||||||
|
- Before requesting API keys, SSH access, login tokens, or database passwords, run `warden route find` / `warden route show` per `credential-routing.md`.
|
||||||
|
- `record_decision()` · `add_progress_event()` · `resolve_decision()`
|
||||||
|
|
||||||
|
> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
|
||||||
|
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
|
||||||
|
|
||||||
|
**Session close:**
|
||||||
|
With MCP tools:
|
||||||
|
```
|
||||||
|
add_progress_event(summary="...", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", workstream_id="<uuid>")
|
||||||
|
```
|
||||||
|
Without MCP tools:
|
||||||
|
```bash
|
||||||
|
curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"topic_id":"64418556-3206-457a-ba29-6884b5b12cf3","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
|
||||||
|
```
|
||||||
|
If workplan files were modified, ensure the local copy is up to date first:
|
||||||
|
```bash
|
||||||
|
git -C <repo_path> pull --ff-only
|
||||||
|
cd ~/state-hub && make fix-consistency REPO=can-you-assist
|
||||||
|
```
|
||||||
|
For repos where implementation runs on a remote machine (e.g. CoulombCore),
|
||||||
|
use the combined target which pulls before fixing:
|
||||||
|
```bash
|
||||||
|
cd ~/state-hub && make fix-consistency-remote REPO=can-you-assist
|
||||||
|
```
|
||||||
|
**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.
|
||||||
38
.claude/rules/stack-and-commands.md
Normal file
38
.claude/rules/stack-and-commands.md
Normal file
@@ -0,0 +1,38 @@
|
|||||||
|
## Stack
|
||||||
|
|
||||||
|
- **Language:** Python 3.11+
|
||||||
|
- **CLI:** Typer + Rich
|
||||||
|
- **Config:** TOML
|
||||||
|
- **Packaging:** setuptools + setuptools_scm (`src/` layout)
|
||||||
|
- **Tests:** pytest
|
||||||
|
|
||||||
|
## Dev Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Recommended: install latest development code
|
||||||
|
make dev-install
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
make test
|
||||||
|
# or: python3 -m pytest tests/ -q
|
||||||
|
|
||||||
|
# Build distribution packages
|
||||||
|
make dist
|
||||||
|
make release-prep
|
||||||
|
make check-dist
|
||||||
|
|
||||||
|
# Run the assistant
|
||||||
|
cya "your natural language request here"
|
||||||
|
cya --help
|
||||||
|
cya --explain-context "show me what context would be collected"
|
||||||
|
cya retrospect
|
||||||
|
|
||||||
|
# Version / inspection
|
||||||
|
make version
|
||||||
|
git status --short
|
||||||
|
rg --files
|
||||||
|
```
|
||||||
|
|
||||||
|
Current memory baseline: **Profile 0** (local JSON + activation + retrospection).
|
||||||
|
Profile 1 verbal reflections shipped as a minimal spike (CYA-WP-0005); production
|
||||||
|
hardening tracked in CYA-WP-0006.
|
||||||
28
.claude/rules/workplan-convention.md
Normal file
28
.claude/rules/workplan-convention.md
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
## Workplan Convention (ADR-001)
|
||||||
|
|
||||||
|
File location: `workplans/CYA-WP-NNNN-<slug>.md`
|
||||||
|
ID prefix: `CYA-WP-`
|
||||||
|
|
||||||
|
Work items originate as files in this repo **before** being registered in the hub.
|
||||||
|
|
||||||
|
Canonical workplan/workstream frontmatter statuses are:
|
||||||
|
`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
|
||||||
|
Use `proposed` for a newly drafted plan, `ready` after review against current
|
||||||
|
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-CYA-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`, workstream 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.
|
||||||
|
|
||||||
|
Ecosystem todos from other agents arrive as `[repo:can-you-assist]` hub tasks —
|
||||||
|
visible at session start. Pick one up by creating the workplan file, then registering
|
||||||
|
the workstream.
|
||||||
|
|
||||||
|
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||||
65
AGENTS.md
65
AGENTS.md
@@ -126,6 +126,8 @@ During work:
|
|||||||
- Treat command execution safety as product behavior: explain destructive or
|
- Treat command execution safety as product behavior: explain destructive or
|
||||||
broad filesystem commands and require explicit confirmation before suggesting
|
broad filesystem commands and require explicit confirmation before suggesting
|
||||||
execution.
|
execution.
|
||||||
|
- Before requesting API keys, SSH access, login tokens, or database passwords,
|
||||||
|
run `warden route find` / `warden route show` per **Credential and access routing**.
|
||||||
- Do not commit secrets, API keys, local transcripts, private notes, or hidden
|
- Do not commit secrets, API keys, local transcripts, private notes, or hidden
|
||||||
memory contents.
|
memory contents.
|
||||||
- Preserve user-controlled memory as a design principle. Prefer explicit,
|
- Preserve user-controlled memory as a design principle. Prefer explicit,
|
||||||
@@ -207,7 +209,68 @@ Current primary entry point: `cya` (after editable install).
|
|||||||
Relevant workplans:
|
Relevant workplans:
|
||||||
- `workplans/CYA-WP-0002-memory-integration-roadmap.md`
|
- `workplans/CYA-WP-0002-memory-integration-roadmap.md`
|
||||||
- `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md`
|
- `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md`
|
||||||
- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md` (current)
|
- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md`
|
||||||
|
- `workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md`
|
||||||
|
- `workplans/CYA-WP-0006-profile-1-production-hardening.md` (proposed — next slice)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Credential and access routing
|
||||||
|
|
||||||
|
> Fleet template mirrored in `.claude/rules/credential-routing.md` for Claude Code.
|
||||||
|
> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes.
|
||||||
|
|
||||||
|
**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`.
|
||||||
|
|
||||||
|
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
||||||
|
other credential need belongs to another subsystem. **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` (`uv tool install .` or `uv run warden`).
|
||||||
|
|
||||||
|
| Agent runtime | How to orient |
|
||||||
|
| --- | --- |
|
||||||
|
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=can-you-assist` is for coordination, not secret vending |
|
||||||
|
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **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` |
|
||||||
|
|
||||||
|
### Quick routing table
|
||||||
|
|
||||||
|
Prefer `warden route find` for repo-specific needs. Common routes:
|
||||||
|
|
||||||
|
| I need… | Owner | ops-warden executes? |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||||
|
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
||||||
|
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
||||||
|
| Authorization decision | flex-auth | No — route only |
|
||||||
|
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
||||||
|
|
||||||
|
### Anti-patterns (do not do these)
|
||||||
|
|
||||||
|
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
||||||
|
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
||||||
|
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||||
|
|
||||||
|
### Other capabilities (reuse-surface)
|
||||||
|
|
||||||
|
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
||||||
|
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
||||||
|
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||||
|
get wrong.
|
||||||
|
|
||||||
|
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Workplan Convention
|
## Workplan Convention
|
||||||
|
|
||||||
|
|||||||
12
CLAUDE.md
Normal file
12
CLAUDE.md
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
# can-you-assist — Claude Code Instructions
|
||||||
|
|
||||||
|
@SCOPE.md
|
||||||
|
@.claude/rules/repo-identity.md
|
||||||
|
@.claude/rules/session-protocol.md
|
||||||
|
@.claude/rules/first-session.md
|
||||||
|
@.claude/rules/workplan-convention.md
|
||||||
|
@.claude/rules/stack-and-commands.md
|
||||||
|
@.claude/rules/architecture.md
|
||||||
|
@.claude/rules/repo-boundary.md
|
||||||
|
@.claude/rules/credential-routing.md
|
||||||
|
@.claude/rules/agents.md
|
||||||
@@ -137,10 +137,11 @@ completed: "2026-05-26"
|
|||||||
|
|
||||||
```task
|
```task
|
||||||
id: CYA-WP-0002-T05
|
id: CYA-WP-0002-T05
|
||||||
status: progress
|
status: done
|
||||||
priority: high
|
priority: high
|
||||||
state_hub_task_id: "d30f159c-3459-4c7b-ba31-990a73deaffb"
|
state_hub_task_id: "d30f159c-3459-4c7b-ba31-990a73deaffb"
|
||||||
started: "2026-05-26 final ralph push"
|
started: "2026-05-26 final ralph push"
|
||||||
|
completed: "2026-05-28"
|
||||||
```
|
```
|
||||||
|
|
||||||
- Expand the test suite (building on T07) with memory-specific tests (in-memory fake phase-memory adapter, profile scenarios, error cases).
|
- Expand the test suite (building on T07) with memory-specific tests (in-memory fake phase-memory adapter, profile scenarios, error cases).
|
||||||
|
|||||||
@@ -254,7 +254,9 @@ When complete:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Status note**: This workplan is created in `proposed` state. It captures a focused, high-leverage planning and feedback slice. Implementation of the profiles (beyond the baseline documentation and optional Profile 1 spike) should be activated only after review and operator go-ahead, following the ralph-workplan discipline used for 0001–0004.
|
**Status note**: Completed 2026-05-28. Profile 0 baseline, Profiles 1–3 definitions, phase-memory
|
||||||
|
feedback artifact, and minimal Profile 1 spike are delivered. Production hardening for Profile 1
|
||||||
|
is tracked in `workplans/CYA-WP-0006-profile-1-production-hardening.md`.
|
||||||
|
|
||||||
**References** (non-exhaustive):
|
**References** (non-exhaustive):
|
||||||
- Research: `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md`
|
- Research: `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md`
|
||||||
|
|||||||
199
workplans/CYA-WP-0006-profile-1-production-hardening.md
Normal file
199
workplans/CYA-WP-0006-profile-1-production-hardening.md
Normal file
@@ -0,0 +1,199 @@
|
|||||||
|
---
|
||||||
|
id: CYA-WP-0006
|
||||||
|
type: workplan
|
||||||
|
title: "Profile 1 Production Hardening: Reflection UX, Compaction, and Surfacing"
|
||||||
|
domain: capabilities
|
||||||
|
repo: can-you-assist
|
||||||
|
status: proposed
|
||||||
|
owner: grok
|
||||||
|
topic_slug: foerster-capabilities
|
||||||
|
created: "2026-06-19"
|
||||||
|
updated: "2026-06-19"
|
||||||
|
---
|
||||||
|
|
||||||
|
# CYA-WP-0006: Profile 1 Production Hardening
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Move the **Profile 1** (Reflexion-style verbal reflections) spike from CYA-WP-0005-T05
|
||||||
|
from "minimal but working" to **production-quality** behavior that users can rely on daily:
|
||||||
|
|
||||||
|
- Clearer capture UX inside `cya retrospect`
|
||||||
|
- Lightweight reflection management (review, edit path, basic compaction)
|
||||||
|
- Stronger surfacing in normal responses and `--explain-context`
|
||||||
|
- Expanded tests and observability
|
||||||
|
|
||||||
|
Preserve all Profile 0 / safety invariants: user-controlled inspectable memory, full
|
||||||
|
provenance, memory signals add caution only (never downgrade risk or bypass confirmation).
|
||||||
|
|
||||||
|
## Background & References
|
||||||
|
|
||||||
|
- **Profile 1 spike (done):** `remember_reflection()`, `KIND_REFLECTION`, optional capture
|
||||||
|
step in `run_retrospection()`, preferential recall by kind, basic output surfacing.
|
||||||
|
- **Gap analysis:** `history/2026-05-28-CYA-Intent-Scope-Gap-Analysis-Post-0005.md` —
|
||||||
|
recommends production-hardening Profile 1 as the highest-leverage next deepening step.
|
||||||
|
- **Profile definitions:** MemoryVision.md — Profile 1 section and Capability Matrix.
|
||||||
|
- **Safety contract:** `src/cya/safety/risk.py` + CYA-WP-0002-T04 invariants.
|
||||||
|
|
||||||
|
## Non-Goals (for this slice)
|
||||||
|
|
||||||
|
- Profile 2 (hierarchical synthesis) or Profile 3 (procedural evolution) implementation.
|
||||||
|
- Real `llm-connect` client wiring (separate future slice).
|
||||||
|
- Deep `phase-memory` graph/planner integration (feedback doc exists; wiring is later).
|
||||||
|
- Automatic background reflection generation without explicit user trigger.
|
||||||
|
- PyPI publishing or CI automation (registered debt from CYA-WP-0004).
|
||||||
|
|
||||||
|
## Task Breakdown
|
||||||
|
|
||||||
|
### T01 — Audit Profile 1 spike gaps vs MemoryVision acceptance
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T01
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
```
|
||||||
|
|
||||||
|
Document the delta between shipped spike behavior and MemoryVision Profile 1 acceptance
|
||||||
|
criteria: capture UX, activation surfacing, compaction, explainability, safety integration.
|
||||||
|
Produce a short checklist in the workplan or `docs/` that gates T02–T05.
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- Gap checklist exists with prioritized items mapped to tasks T02–T05.
|
||||||
|
- No code changes required unless a blocking bug is found (file separately as ADHOC if so).
|
||||||
|
|
||||||
|
### T02 — Improve `cya retrospect` reflection capture UX
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T02
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
```
|
||||||
|
|
||||||
|
Enhance the optional verbal-lesson step in `run_retrospection()`:
|
||||||
|
|
||||||
|
- Guided prompts (what went well / what to remember / what to avoid)
|
||||||
|
- Preview before save; allow skip without storing empty records
|
||||||
|
- Store structured metadata (session date, scope) in provenance
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- Users can capture 1–3 concise lessons with clear prompts and confirmation.
|
||||||
|
- Skipping leaves no orphan/empty reflection records.
|
||||||
|
- Existing retrospection kinds and goals flow unchanged.
|
||||||
|
|
||||||
|
### T03 — Reflection review and lightweight compaction
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T03
|
||||||
|
status: todo
|
||||||
|
priority: medium
|
||||||
|
```
|
||||||
|
|
||||||
|
Add user-visible reflection management without hiding state:
|
||||||
|
|
||||||
|
- `export_memory(..., kinds=["reflection"])` surfaced via CLI helper or documented path
|
||||||
|
- Simple compaction: detect near-duplicate reflections in the same scope (string similarity
|
||||||
|
or normalized key collision) and offer merge/replace in retrospect or a small subcommand
|
||||||
|
- All compaction is explicit — no silent deletion
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- User can list/export reflections for a scope.
|
||||||
|
- Duplicate detection works on a small fixture set; merge/replace is opt-in.
|
||||||
|
- Compaction never bypasses safety or provenance requirements.
|
||||||
|
|
||||||
|
### T04 — Strengthen surfacing in responses and `--explain-context`
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T04
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
```
|
||||||
|
|
||||||
|
Improve how activated reflections appear in `handle_request()` and context explanation:
|
||||||
|
|
||||||
|
- Show count + truncated lesson text in `--explain-context` with provenance
|
||||||
|
- Normal responses include a concise "reflections influenced this" line when relevant
|
||||||
|
- Cap token/line budget to avoid wall-of-text
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- Roundtrip test: stored reflection → recall → visible in explain output.
|
||||||
|
- Output remains readable for 0, 1, and 5+ reflections.
|
||||||
|
|
||||||
|
### T05 — Tests, observability, and safety regression coverage
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T05
|
||||||
|
status: todo
|
||||||
|
priority: high
|
||||||
|
```
|
||||||
|
|
||||||
|
Expand `tests/test_memory.py` and orchestrator tests for:
|
||||||
|
|
||||||
|
- New capture UX paths (prompt/skip/preview)
|
||||||
|
- Compaction opt-in behavior
|
||||||
|
- Surfacing in explain-context
|
||||||
|
- Safety invariant: reflections cannot downgrade destructive-command confirmation
|
||||||
|
|
||||||
|
Add basic observability in `export_memory` (reflection counts by scope).
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- `make test` / `python3 -m pytest tests/ -q` passes cleanly.
|
||||||
|
- At least one test per new behavior path from T02–T04.
|
||||||
|
|
||||||
|
### T06 — Documentation updates
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T06
|
||||||
|
status: todo
|
||||||
|
priority: medium
|
||||||
|
```
|
||||||
|
|
||||||
|
Update README.md (retrospect / Profile 1 section), MemoryVision.md status note, and
|
||||||
|
SCOPE.md if delivered scope changes materially.
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- README documents the hardened Profile 1 flow with an example session.
|
||||||
|
- MemoryVision notes Profile 1 as "production" (not "spike") when T02–T05 complete.
|
||||||
|
|
||||||
|
### T07 — Register, sync, and handoff
|
||||||
|
|
||||||
|
```task
|
||||||
|
id: CYA-WP-0006-T07
|
||||||
|
status: todo
|
||||||
|
priority: medium
|
||||||
|
```
|
||||||
|
|
||||||
|
Register workstream in State Hub via `make fix-consistency REPO=can-you-assist`,
|
||||||
|
log progress event, set workplan to `ready` after review or `active` when implementation
|
||||||
|
starts.
|
||||||
|
|
||||||
|
**Acceptance criteria:**
|
||||||
|
- `state_hub_workstream_id` and task ids written by fix-consistency.
|
||||||
|
- `.custodian-brief.md` regenerated with CYA-WP-0006 visible.
|
||||||
|
|
||||||
|
## Dependencies & Cross-Repo Coordination
|
||||||
|
|
||||||
|
- **phase-memory:** Optional future compaction planner hooks — not required for this slice.
|
||||||
|
See `docs/phase-memory-optimization-suggestions.md` for long-term asks.
|
||||||
|
- **llm-connect:** Not required (reflections are user-authored text in this slice).
|
||||||
|
|
||||||
|
## Debt & Future Work (Registered)
|
||||||
|
|
||||||
|
- Profile 2 synthesis spikes (user-triggered, dry-run first).
|
||||||
|
- Real `llm-connect` adapter implementation slice.
|
||||||
|
- CI gate for `make test` + `make check-dist` (from CYA-WP-0004 debt).
|
||||||
|
- Profile selection UX (`cya memory profile ...`).
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
When complete:
|
||||||
|
|
||||||
|
- Profile 1 is demonstrably production-usable: capture, review, activation, and surfacing
|
||||||
|
are polished and tested.
|
||||||
|
- Safety and explainability invariants from Profile 0 remain intact.
|
||||||
|
- Users reading README + MemoryVision understand Profile 1 as shipped capability, not a spike.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Status note:** Created `proposed` on 2026-06-19 after CYA-WP-0005 completion and gap
|
||||||
|
analysis recommendations. Activate to `ready` after operator review; move to `active` when
|
||||||
|
implementation begins (ralph-workplan or direct session).
|
||||||
Reference in New Issue
Block a user