established rules

This commit is contained in:
2026-06-22 23:06:36 +02:00
parent 63eb431db9
commit 43bea485aa
10 changed files with 242 additions and 39 deletions

View File

@@ -4,50 +4,13 @@
**Purpose:** Iterating towards optimal agentic performance.
**Domain:** helix_forge
**Domain:** infotech
**Repo slug:** agentic-resources
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
**Workplan prefix:** `AGENTIC-WP-`
---
## Dev Workflow
The deliverable code lives in `session_memory/` (the Helix Forge coding-session
memory system). It is **pure-stdlib Python 3.11+**`tomllib`, `sqlite3`,
`dataclasses`; no third-party runtime dependencies and no build step. `pytest` is
the only dev dependency. Run everything from the repo root.
| Need | Command |
|------|---------|
| Python | `python3` (3.11+ required for `tomllib`; developed on 3.12) |
| Install deps | none at runtime; for tests: `pip install pytest` (or `uv pip install pytest`) |
| Test | `python3 -m pytest` (full suite) · `python3 -m pytest tests/test_curate_review.py` (one file) · `-q` for quiet |
| Lint / build | none configured — keep changes matching surrounding style |
| Run: ingest sweep | `python3 -m session_memory.ingest` (`--dry-run`, `--config PATH`) |
| Run: detect | `python3 -m session_memory.detect` (`--json`, `--min-frequency N`) |
| Run: curate | `python3 -m session_memory.curate` (`--auto-approve`, `--json`) |
| Config | `session_memory/config.toml`; local store under `session_memory/.store/` (gitignored) |
**Verify a change before declaring it done:** run `python3 -m pytest` (expect all
green), and for pipeline changes do a live `ingest → detect → curate` pass against
the local store. See `session_memory/README.md` for the full layout and the
detect → curate → distribute flow.
### Editing files — Read before you Edit
**Read a file (or the region you'll touch) before Edit/Write.** The most common
error across our own captured coding sessions was *"File has not been read yet.
Read it first before writing to it"* — 12 of 27 real sessions, 8 repos
(`docs/ASSESSMENT-infra-friction.md`). Two cheap reflexes eliminate it:
- **Read → then Edit/Write.** Don't blind-write a file you haven't read this
session; the edit tools reject it and the retry wastes a turn.
- **On `File has been modified since read`, re-Read then re-Edit.** A stale read
means the file changed under you — refresh before retrying, don't loop.
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
@@ -188,6 +151,11 @@ every repo's agent instructions because it is high-frequency, high-risk, and eas
get wrong.
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention (ADR-001)
@@ -213,7 +181,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
id: AGENTIC-WP-NNNN
type: workplan
title: "..."
domain: helix_forge
domain: infotech
repo: agentic-resources
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex