[docs] Capture session lessons into pr-workflow / memory-rules / conftest notes

AGENTS.md

@@ -47,6 +47,9 @@ area. Format conventions: `docs/notes/README.md`.
 
 - [CI](docs/notes/ci.md) — what `make check` and `make ci` each cover, and which gates have caught real regressions.
 - [Reviews](docs/notes/reviews.md) — when and how to run multi-lens reviews, and how to triage uplift items between PR-scope and follow-ups.
+- [PR workflow](docs/notes/pr-workflow.md) — body-sync, iterative-review prompt discipline.
+- [Memory rules](docs/notes/memory-rules.md) — reconciling rule collisions with forward-only compliance.
+- [Conftest / OPA rego](docs/notes/conftest.md) — pod-spec guards and non-pod-document evaluation traps.
 
 <!-- Add one line per topic note. Newest entries go to the matching
      note's top, not here; this index is just pointers. -->

docs/notes/conftest.md

@@ -0,0 +1,19 @@
+# Conftest / OPA rego
+
+Lessons specific to the rego policies that gate the Helm chart at
+`install/kubernetes/tracecore/policies/conftest/`. Format conventions:
+`docs/notes/README.md`.
+
+### Guard rego deny rules with `input.spec.template.spec`
+
+Rego rules that reference `pod_spec.<field>` are silently undefined
+when the input is a non-pod document (ConfigMap, ServiceAccount,
+Secret). But `not pod_spec.<field> == true` evaluates to `true` when
+`pod_spec` is undefined, so policies meant to police pods fire on
+every ConfigMap in the rendered chart. Every deny rule that touches
+the pod spec must start with `input.spec.template.spec` to anchor
+evaluation.
+
+Anchor: `install/kubernetes/tracecore/policies/conftest/tracecore.rego` —
+every `deny contains msg if { ... }` block that references
+`pod_spec` or `all_containers`.

docs/notes/memory-rules.md

@@ -0,0 +1,20 @@
+# Memory rules
+
+Lessons about authoring and reconciling the durable memory in
+`/Users/tree/.claude/projects/-Users-tree-Desktop-tracecore/memory/`.
+Format conventions: `docs/notes/README.md`.
+
+### Reconcile colliding memory rules with a governance call, not cleanup
+
+When a memory rule tightens and collides with an existing constraint
+(canonical example: a "no AI attribution" tightening that would
+require rewriting already-pushed commits, blocked by "no history
+rewrites"), naming the resolution as forward-only-compliance prevents
+the next contributor from relitigating. Record the disposition in the
+colliding memory file itself so it surfaces on the next look-up.
+
+Anchor: any memory file under
+`$HOME/.claude/projects/-Users-tree-Desktop-tracecore/memory/`
+that introduces a constraint stricter than the one it replaces — grep
+for `Updated 20` headers and verify the "How to apply" section
+addresses prior-state work.

docs/notes/pr-workflow.md

@@ -0,0 +1,29 @@
+# PR workflow
+
+Repo-resident lessons on opening, iterating on, and merging PRs in
+this codebase. Format conventions: `docs/notes/README.md`.
+
+### Update the PR body each review round, not just at open
+
+When a PR goes through multiple rounds of review-driven fixes, the
+description authored at PR-open often understates what actually
+shipped: new files, new rules, new knobs added in later commits. On
+squash-merge, the body becomes the permanent commit message on
+`main` — a stale body turns into a permanent under-statement of
+scope. CHANGELOG entries can mitigate this, but the commit body is
+what `git log` shows by default.
+
+Anchor: `git log origin/main -1 --format=%B` after every squash-merge
+of an iterative PR; compare against the diff to catch drift.
+
+### Pre-load prior-round findings when running an iterative review
+
+Review prompts that do not enumerate what already shipped in earlier
+rounds re-surface those exact findings as "new." The delta-quality
+output of an iterative review depends on each round explicitly listing
+the artifacts (rules, fixtures, knobs, doc sections) that landed
+previously, so reviewers focus on the residual gap.
+
+Anchor: the prompt body of any Agent tool call dispatching an
+iterative review must include an explicit "what already shipped"
+block; without it, the review repeats itself.