Additive/refining entries left uncommitted in the working tree from an earlier
distill session (found during the 2026-07 sweep commit): agent-repos 5-step
plan pattern; ai-parallel-agents cheap-model scope; spec-driven spec-inversion
and caller/callee cross-reference rules.
The previous "Dogfood Failure Path: Branch + Logs Lost" section was wrong
on two counts (verified by M16 Wave B3, 2026-05-08):
1. The agent's branch IS pushed on F70-failure (dispatcher logs "branch
will still push (partial work preserved)"). The earlier "no branch"
claim was a fetch-refspec mistake — both B2 and B3 have task-<id>
branches on the agents fork.
2. The CP task record's logs ARE populated (~50 KB on B3). What's actually
missing is the pytest stdout/stderr from the F70 invocation — only the
high-level "Tests failed" line is logged.
Section retitled "What's Visible, What Isn't" with the corrected picture.
Operator pattern updated: fetch the task branch, apply the diff locally,
run the test — if local passes, cherry-pick to main.
New section "F70 Pytest Can Disagree with Local Pytest" captures the B3
finding: airouter's 15-line MN-14 validator passed 5/5 locally but F70
reported failure twice. Possible causes listed; workaround is
--max-test-iterations 1 + local apply-and-run after failure.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Three additions to agent-repos.md based on the post-A1-incident dogfood
batch (8 successes + 1 operator-induced "failure"):
1. Airouter Qwen3.6 section: pattern reconfirmed across M16 Wave A1/A2/B1
and M25 Waves A1-A5 + B1-B2. Time-to-success bands recorded for cost
calibration (1m30s for git rm; ~5 min for Pydantic regex; ~12 min for
class addition). Default --max-test-iterations 1 for cheap probes.
2. New section: Test Design for AI Agent Dogfood Pipelines. Triggered by
the M16 Wave B2 (MN-4 prompt cap) failure — a 14-minute airouter run
blamed on the agent that was actually an over-strict test asserting on
sanitised 422 body content. CP's RequestValidationError handler strips
Pydantic detail for security; tests asserting body content for that
path are structurally impossible. Rules: verify test passes against a
reference impl before pushing; status-code-only ceiling for validator-
driven 422s; model on previous successes not stricter variants; F70
retries don't recover structurally impossible tests.
3. New section: Dogfood Failure Path: Branch + Logs Lost. When all F70
retries exhaust, the agent's last attempt is not pushed to the agents
fork, the CP task record's logs field is empty, and the pod is gone.
Operator must reproduce locally — until F70 finalize-on-failure pushes
the failed branch.
BESTPRACTICES.md index updated to reflect the new sub-topics.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
D4a (harness.yaml, 1 file) = success
D4b (CLAUDE.md, 1 file) = success
Both succeeded where original D4 (2 files) = silent no-output.
Pattern confirmed: single-file scope is the reliable unit for airouter/Qwen3.6.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Document the kubernetes-py v35 gotcha that bit M22 Phase 8: patch with
force=True against the default merge-patch Content-Type returns 422
silently in mocks but breaks at the apiserver. Workaround is a
dedicated ApiClient with the apply-patch header.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reframe "Cilium Entity Identities for Monitoring Scraping" as
cross-cutting -- the same entity table applies to any pod that
needs to reach cluster infrastructure (apiserver, kubelets,
node-exporter, host services), not just Prometheus.
Add the gotcha that bit M22 Phase 7: standard NetworkPolicy
ipBlock CIDR rules do NOT match cluster node IPs. Nodes carry
the Cilium remote-node/kube-apiserver identity and ipBlock only
matches off-cluster IPs. The misleading symptom is a 30s hang
followed by a generic upstream error like "permission denied"
(seen on OpenBao TokenReview, would also affect ESO+vault k8s
auth, and any controller calling subjectaccessreviews).
Same gotcha applies to namespaceSelector: kube-system -- the
apiserver runs hostNetwork=true and is not selectable that way.
Source incident: agent-runtimes M22 Phase 7 F-OPENBAO-K8S-AUTH-1
(homelab/openbao-deploy@f7bd64d).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Eight practices for writing specs that serve as direct input to
automated test-generation agents, extracted from the M15 Mechanical
Process Nodes milestone review: module layout tables, integration
boundary marking, explicit library semantics, concrete interfaces over
"implementation detail", error messages as test data, pattern tables as
parametric matrices, scenario selection, and pre-dispatch testability
assessment.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Extends api-design.md beyond its security/operations focus with three
new dimensions:
- §0 API-First Design Process — OpenAPI 3.1 as single source of truth,
Spectral governance, dogfooding (UIs consume the public API, no
privileged backdoors), auth-required-by-default as a design stance.
- §7 Documentation and Developer Experience — Scalar/Mintlify,
RFC 9457 Problem Details error envelope, interactive playgrounds,
generated SDKs (Stainless, Speakeasy, Fern), RFC 9745 deprecation
signals and changelog UX.
- §8 Contract Testing and API Quality — schema validation in the
test suite, Pact CDC vs provider verification, Schemathesis
property-based fuzzing, oasdiff drift detection in CI, the API
test pyramid.
Intro, cross-refs in §3.1/§3.3/§4.1, and Sources block reorganised
by topic. Index entry in BESTPRACTICES.md updated. PLAN file included
for traceability.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds 3 new topic files (ai-parallel-agents, api-integration,
python-patterns) and extends 21 existing topic files with new gotchas
and patterns surfaced from memory across tracked projects. Index
updated accordingly.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add 37 new entries and update 7 existing entries across 13 topic files.
Major contributions from agent-runtimes (K8s secrets, CI, Docker gotchas),
cluster-bootstrap (ArgoCD SSA, etcd tuning, DB migrations, Compose networking),
and cluster-apps/octopus-deploy (Helm vs raw manifests, ArgoCD source types).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Learnings from F58 3-way model comparison (Sonnet/MiniMax/Haiku):
- Read-only test gates: filesystem enforcement (chmod a-w) because
prompt instructions are insufficient — MiniMax edited tests 7x,
Haiku rewrote entirely, only Sonnet respected constraints
- Model selection table: Sonnet minimum for constrained implementation,
Haiku/MiniMax viable for review and test-writing
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Registry cache with inline metadata, buildx docker driver for DinD,
dependency layer separation (stub package pattern for setuptools),
pip cache retention, scheduled base image builds. Includes measured
results from Gitea Actions with DinD runners.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Comprehensive guide covering task submission to the agent-runtimes
control plane, available harnesses, monitoring, multi-model workflows,
agent repo forks with workspace layout, and artifact extraction patterns.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two new topic files from research:
- api-design.md: Transport security, OAuth2/JWT/mTLS auth, API patterns
(versioning, pagination, idempotency, rate limiting), input validation,
secrets handling, zero-trust service mesh patterns. Maps to OWASP API
Security Top 10.
- llm-code-security.md: Common vulnerabilities in LLM-generated code
(injection, hardcoded secrets, hallucinated packages, over-permissive
defaults, IaC risks, crypto mistakes). Includes per-technology review
checklists and cites 18 research sources (2024-2026).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Migrated from claude-foundations. Tracks per-project git SHAs for
incremental distillation runs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Migrates 20 topic files from claude-foundations/best-practices/ to this
standalone repo. Adds BESTPRACTICES.md index, CLAUDE.md conventions, and
updated README.md. Container agents clone this repo to /best-practices.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
