fix: telemetry/memory flag mismatches, doc drift; add CI; self-dogfood

Parallel fleet audit (2 background agents) + direct work: - src/commands/memory.mjs: `memory put --allow-secrets` was read as `flags.allowSecrets` (camelCase) but the CLI parser only emits kebab-case keys, so the flag was always undefined/false. Fixed to `flags['allow-secrets']`. - Docs: `lh graph --brief` was referenced 14x across 5 agent.md files, harness.instructions.md, 4 SKILL.md files, onboard.prompt.md, and README, but `lh graph` has no --brief flag (terse output is already the default, --json/--severity are the only flags). Corrected every reference to match actual CLI surface. - .github/workflows/ci.yml: run npm install/validate/test on node 20+22. - Self-dogfooded `lh init --yes` in this repo, producing .agents/ (harness.config.json, architecture.md, conventions.md, memory shards). `lh doctor` now reports all required checks green. - Deduped .gitignore harness block against init's auto-managed block. Verified: 53/53 tests pass, validate 0 errors, doctor all-green. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-09-09 22:50:07 +02:00
parent 383129f571
commit cd36cc0efc
25 changed files with 273 additions and 20 deletions
@@ -0,0 +1,30 @@
+# agents-2026 architecture
+
+<!-- Living document. Update when components, data flow, invariants, or ADR outcomes change. Keep claims concrete and current. -->
+
+## Purpose
+
+Describe what this system exists to do, who uses it, and what success means.
+
+## System context
+
+List upstream callers, downstream services, data stores, queues, files, and trust boundaries.
+
+## Components
+
+- Component: responsibility, owner, key files.
+
+## Data flow
+
+1. Input source.
+2. Validation and transformation.
+3. Persistence or external calls.
+4. Output and observability.
+
+## Key invariants
+
+- Invariant: why it must hold, where enforced, how verified.
+
+## Decision log (ADRs)
+
+<!-- Append ADR links or summaries here. Newest last. -->
@@ -0,0 +1,38 @@
+# agents-2026 conventions
+
+<!-- Living document. Promote repeated review feedback and user corrections here. Keep rules specific, checkable, and current. -->
+
+## Code style
+
+- Prefer simple control flow and explicit names.
+- Keep side effects at boundaries.
+
+## Naming
+
+- Use domain terms consistently.
+- Name files after their primary responsibility.
+
+## Testing
+
+- Cover changed behaviour with the smallest meaningful test.
+- Add regression tests for fixed bugs.
+
+## Error handling
+
+- Fail fast on invalid inputs.
+- Preserve actionable error context without leaking secrets.
+
+## Commit format
+
+- Use concise conventional commits when possible.
+- Explain why in the body when not obvious.
+
+## Directory layout
+
+- Keep generated artifacts out of source directories.
+- Put shared deterministic helpers in library modules.
+
+## Review rules
+
+- Verify scoped files only.
+- Flag correctness, security, and contract drift before style.
@@ -0,0 +1,94 @@
+{
+  "version": 1,
+  "memory": {
+    "root": ".agents",
+    "committed": [
+      "architecture.md",
+      "conventions.md",
+      "memory",
+      "specs",
+      "runs/*/journal.md"
+    ],
+    "ignored": [
+      ".cache",
+      "runs/*/events.ndjson",
+      "runs/*/board.md"
+    ],
+    "tokenBudget": 8000,
+    "compactAtPercent": 85
+  },
+  "artifacts": {
+    "architecture": true,
+    "conventions": true,
+    "adr": true,
+    "journal": true,
+    "spec": true
+  },
+  "index": {
+    "include": [
+      "**/*"
+    ],
+    "exclude": [
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/target/**",
+      "**/vendor/**",
+      "**/*.min.*",
+      "**/.agents/**"
+    ],
+    "depth": 3,
+    "budget": 1200
+  },
+  "models": {
+    "tiers": {
+      "cheap": "claude-haiku-4.5",
+      "mid": "claude-sonnet-5",
+      "strong": "claude-opus-5"
+    },
+    "roles": {
+      "conductor": "strong",
+      "interrogator": "strong",
+      "scout": "cheap",
+      "architect": "strong",
+      "splitter": "mid",
+      "builder": "mid",
+      "verifier": "cheap",
+      "reviewer": "strong",
+      "integrator": "strong",
+      "scribe": "cheap"
+    }
+  },
+  "ralph": {
+    "maxIterations": 4,
+    "exitCriteria": [
+      "verify-commands-exit-zero",
+      "acceptance-criteria-checked",
+      "structural-gate-passes",
+      "reviewer-approves",
+      "no-out-of-scope-files"
+    ],
+    "onMaxIterations": "escalate"
+  },
+  "verify": {
+    "commands": [
+      {
+        "name": "test",
+        "command": "npm run test"
+      }
+    ],
+    "autodetected": true
+  },
+  "concurrency": {
+    "maxWriteLanes": 4,
+    "readOnlyFanOut": 6
+  },
+  "isolation": {
+    "backend": "worktree"
+  },
+  "context7": {
+    "required": true,
+    "envVar": "CONTEXT7_API_KEY"
+  }
+}
@@ -0,0 +1,15 @@
+# Memory index
+
+Only this file is always loaded. Open shard files only when needed.
+
+updated: 2026-09-09T20:49:13.380Z
+total_tokens: 228
+
+| shard | entries | tokens | updated | summary |
+| --- | ---: | ---: | --- | --- |
+| seed | 0 | 35 | 2026-09-09T20:49:13.379Z | Stable repo facts and bootstrap knowledge. |
+| failures | 0 | 38 | 2026-09-09T20:49:13.379Z | Known failures, regressions, and broken approaches. |
+| corrections | 0 | 36 | 2026-09-09T20:49:13.379Z | User corrections and changed assumptions. |
+| insights | 0 | 37 | 2026-09-09T20:49:13.379Z | Reusable discoveries and design observations. |
+| conventions | 0 | 42 | 2026-09-09T20:49:13.379Z | Project-specific conventions not yet promoted to conventions.md. |
+| quirks | 0 | 40 | 2026-09-09T20:49:13.379Z | Sharp edges, environment quirks, and non-obvious constraints. |
@@ -0,0 +1,9 @@
+# conventions memory
+
+Project-specific conventions not yet promoted to conventions.md.
+
+Entries use:
+
+`## <ISO timestamp> — <title>`
+
+Optional next line: `tags: a, b`
@@ -0,0 +1,9 @@
+# corrections memory
+
+User corrections and changed assumptions.
+
+Entries use:
+
+`## <ISO timestamp> — <title>`
+
+Optional next line: `tags: a, b`
@@ -0,0 +1,9 @@
+# failures memory
+
+Known failures, regressions, and broken approaches.
+
+Entries use:
+
+`## <ISO timestamp> — <title>`
+
+Optional next line: `tags: a, b`
@@ -0,0 +1,9 @@
+# insights memory
+
+Reusable discoveries and design observations.
+
+Entries use:
+
+`## <ISO timestamp> — <title>`
+
+Optional next line: `tags: a, b`
@@ -0,0 +1,9 @@
+# quirks memory
+
+Sharp edges, environment quirks, and non-obvious constraints.
+
+Entries use:
+
+`## <ISO timestamp> — <title>`
+
+Optional next line: `tags: a, b`
@@ -0,0 +1,9 @@
+# seed memory
+
+Stable repo facts and bootstrap knowledge.
+
+Entries use:
+
+`## <ISO timestamp> — <title>`
+
+Optional next line: `tags: a, b`
@@ -16,7 +16,7 @@ Write the spec. Make every acceptance criterion checkable.
 1. Read `.agents/specs/<slug>/decisions.md` first.
 2. Stop if decisions are missing or incomplete.
 3. Run `lh index --budget 6000 --focus <relevant-glob>`.
-4. Run `lh graph --brief`.
+4. Run `lh graph`.
 5. Delegate focused read-only reconnaissance to `scout` when needed.
 6. Consult Context7 before using any external library or framework API.
 7. Use `resolve-library-id` before `query-docs`.
@@ -30,7 +30,7 @@ Run the full lean harness pipeline. Edit no product files.
 15. For plan, invoke `architect`.
 16. Require `.agents/specs/<slug>/spec.md`.
 17. Invoke `splitter` to write `.agents/specs/<slug>/plan.dag.json`.
-18. Validate the DAG with `lh graph --brief`.
+18. Validate the DAG with `lh graph`.
 19. Own the dynamic DAG after splitter returns.
 20. For every checkpoint, read lane status and verifier output.
 21. Re-plan at every checkpoint.
@@ -73,7 +73,7 @@ Run the full lean harness pipeline. Edit no product files.
 - Stop when `lh run end` completes and final verify passes.
 - Stop when design answers remain missing.
 - Stop when max Ralph iterations are reached.
- Stop when `lh graph --brief` keeps failing after re-plan.
+- Stop when `lh graph` keeps failing after re-plan.
 - Stop when host strategy forbids required action.

 ## NEVER DO THIS
@@ -16,7 +16,7 @@ Approve or reject. Check every criterion.
 2. Read `.agents/specs/<slug>/spec.md`.
 3. Read `.agents/specs/<slug>/plan.dag.json`.
 4. Read verifier output.
-5. Run `lh graph --brief` unless fresh passing output exists.
+5. Run `lh graph` unless fresh passing output exists.
 6. List assigned acceptance criteria by id.
 7. Check each criterion individually.
 8. Check changed files against declared scope globs.
@@ -34,7 +34,7 @@ Approve or reject. Check every criterion.

 1. All declared verify commands pass.
 2. Every assigned `AC-###` passes.
-3. `lh graph --brief` passes.
+3. `lh graph` passes.
 4. Changed files stay inside declared scope.
 5. Decisions from `.agents/specs/<slug>/decisions.md` are honored.

@@ -14,7 +14,7 @@ Recon the repo. Return facts, not dumps.

 1. Treat the assignment as read-only.
 2. Run `lh index --budget <N> --focus <glob>` before manual reads.
-3. Run `lh graph --brief` before manual reads.
+3. Run `lh graph` before manual reads.
 4. Read `.agents/memory/INDEX.md` only if the assignment needs history.
 5. Pull memory shards only by explicit relevance.
 6. Search by symbol, path, or glob before opening files.
@@ -15,7 +15,7 @@ Emit the lane DAG. Keep write scopes disjoint.
 1. Read `.agents/specs/<slug>/spec.md`.
 2. Read `.agents/architecture.md` when present.
 3. Run `lh index --budget 6000 --focus <relevant-glob>`.
-4. Run `lh graph --brief`.
+4. Run `lh graph`.
 5. Extract every acceptance criterion id.
 6. Group work by independently verifiable outcomes.
 7. Create read lanes for discovery-only work.
@@ -29,7 +29,7 @@ Emit the lane DAG. Keep write scopes disjoint.
 15. Add verify commands when known.
 16. Add checkpoint hints for risky lanes.
 17. Write `.agents/specs/<slug>/plan.dag.json`.
-18. Run `lh graph --brief` after writing.
+18. Run `lh graph` after writing.
 19. If graph fails, revise the DAG until it passes or report blocker.
 20. Return lane count, dependency shape, and risk lanes.

@@ -65,7 +65,7 @@ Emit the lane DAG. Keep write scopes disjoint.
 - Stop when spec is missing.
 - Stop when acceptance criteria are unnumbered.
 - Stop when write scopes overlap and cannot be separated.
- Stop when `lh graph --brief` blocks the DAG.
+- Stop when `lh graph` blocks the DAG.

 ## NEVER DO THIS

@@ -8,7 +8,7 @@ description: Always-on lean harness behavior, token discipline, style, self-docu
 ## Token discipline

 1. Prefer `lh index --budget <N>` over raw tree reads.
-2. Prefer `lh graph --brief` over verbose diagnostics.
+2. Prefer `lh graph` over verbose diagnostics.
 3. Load only `.agents/memory/INDEX.md` by default.
 4. Pull memory shards only on demand with `lh memory get`.
 5. Return summaries, tables, and paths instead of file dumps.
@@ -6,6 +6,6 @@ description: Produce a concise lean harness onboarding summary from doctor, inde

 Invoke the `onboard` skill.

-Run `lh doctor`, `lh index --stats --budget 4000`, and `lh graph --brief`.
+Run `lh doctor`, `lh index --stats --budget 4000`, and `lh graph`.
 Read only `.agents/memory/INDEX.md` by default.
 If VS Code cannot fan out scouts, inspect sequentially.
@@ -7,7 +7,7 @@ description: Use when checking harness environment, configuration, host capabili

 1. Run `lh doctor`.
 2. Run `lh host` when orchestration capability matters.
-3. Run `lh graph --brief` when repository structure matters.
+3. Run `lh graph` when repository structure matters.
 4. Report failures with exact commands and exit status.
 5. Suggest the smallest next fix.

@@ -8,7 +8,7 @@ description: Use when needing repository understanding under a token budget befo
 1. Run `lh index --budget <N> --focus <glob>`.
 2. Add `--stats` when onboarding or sizing work.
 3. Prefer index output before raw reads.
-4. Follow with `lh graph --brief` when structure matters.
+4. Follow with `lh graph` when structure matters.
 5. Read files by hand only after narrowing scope.

 Return paths and facts, not dumps.
@@ -8,7 +8,7 @@ description: Use when a new contributor or agent needs a concise map of harness
 1. Run `lh doctor`.
 2. Run `lh index --stats --budget 4000`.
 3. Read `.agents/memory/INDEX.md` only.
-4. Run `lh graph --brief`.
+4. Run `lh graph`.
 5. Summarize commands, state paths, conventions, and blockers.

 Pull shards only when the user asks for deeper history.
@@ -8,7 +8,7 @@ description: Use when decisions are complete and the harness must produce a spec
 1. Read `.agents/specs/<slug>/decisions.md`.
 2. Invoke `.github/agents/architect.agent.md` for `.agents/specs/<slug>/spec.md`.
 3. Invoke `.github/agents/splitter.agent.md` for `.agents/specs/<slug>/plan.dag.json`.
-4. Run `lh graph --brief`.
+4. Run `lh graph`.
 5. Report spec path, DAG path, acceptance ids, and blockers.

 Do not build before the DAG passes structural gates.
@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['20', '22']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run validate
+      - run: npm test
@@ -3,9 +3,10 @@ dist/
 *.log
 .DS_Store
 report.*.json
+tests/.tmp/

-# Harness runtime artifacts (per-consumer-repo; here only for fixtures)
-.agents/.cache/
+# redsen-lean-harness
+.agents/.cache
 .agents/runs/*/events.ndjson
 .agents/runs/*/board.md
-tests/.tmp/
+# /redsen-lean-harness
@@ -155,7 +155,7 @@ exploration is deliberately pushed onto the cheap tier; only summaries return to
 | --- | --- |
 | `lh init` | First-run wizard → `.agents/harness.config.json` |
 | `lh index [--budget N] [--focus g] [--fetch]` | Token-budgeted tree-sitter repo map |
-| `lh graph [--brief]` | Structural gate. **Exit 1 on violations** |
+| `lh graph` | Structural gate, terse output by default. **Exit 1 on violations** |
 | `lh lane create\|list\|status\|merge\|drop` | Worktree lanes + file-scope leases |
 | `lh run start\|event\|end` | NDJSON telemetry + live board |
 | `lh memory get\|put\|compact\|scan\|list` | Memory shards, compaction, secret scanning |
@@ -83,7 +83,7 @@ export default async function memory({ flags, positional }) {
        title: flags.title,
        body,
        tags: flags.tags ?? [],
-        allowSecrets: Boolean(flags.allowSecrets),
+        allowSecrets: Boolean(flags['allow-secrets']),
      });
      if (!result.ok) {
        if (json) asJson({ ok: false, findings: result.findings });