docs(agent): a pull request is reported as its link plus its title, never a bare number

"#54" made Frank go hunting: numbers are per-repository across the forges this fleet uses, and a number carries no hint of which work is being reported. Every mention of a PR now pairs its web URL with its title — gitea.franksdank.cloud for the Dankclaw Gitea, the equivalent for any other forge. Refs the AGENTS.md convention that an open PR gets opened in Frank's browser: the rule covers prose, where the browser tab does not help.
docs(agent): commit the point-of-use documentation doctrine that has been live for a day
2026-10-20 21:22:35 -07:00 · 2026-10-20 21:20:04 -07:00
3 changed files with 21 additions and 33 deletions
@@ -54,13 +54,20 @@ Suggest these tools or languages as possible solutions to problems if they are a

 ### 1. Maintain your projects source of truth.

-The knowledge base at `docs/` is the source of truth for your project. Your training is out of date. Default to the documentation and the code before you assume anything. Maintain a work log of actions taken and their result. Refer to the work log to remember the progress of your tasks.
+Documentation exists for ONE reason: **point of use**. A page earns its bytes only if it helps you perform a task at the moment you perform it — the shape to deploy, the flag that must be passed, the failure mode to recognise, the rollback to run. It is NOT a museum, NOT a lab notebook, and NOT a place to keep track of numbers.
+
+**THE PURPOSE TEST — apply it before you write, and again before you keep:**
+- Would an agent or Frank, doing a real task tomorrow, read this line and act differently because of it? If no: **delete it.**
+- Is this a measured number (t/s, tokens, ms, MiB, %, bench ladder, acceptance rate) for a model, runtime, or hardware configuration that is NOT currently deployed and NOT currently being compared? Then it is **dead weight — destroy it**, do not archive it, do not "preserve it in an Eras row", do not cite it. AI advances make such a figure wrong within weeks, and a wrong number in a runbook is worse than no number: it gets believed.
+- "It is the only copy of that fact" is NOT a reason to keep it. Sole custody of a useless fact is still useless. Losing information is an acceptable — often correct — outcome; do not hesitate to lose it.
+- What survives the test: live configuration and its exact numbers, the procedure that must be followed, the law/causal story that prevents a repeat failure, security posture, and the interface contract a consumer depends on. Qualitative laws outlive the measurement that taught them — keep the law, drop the numbers.
+- Never let a tool's "this is duplicated / this is the only record" census decide what to keep. That is a question of USEFULNESS, which only the operator answers.

 1. Read the relevant `index.md` before you touch a topic.
 2. Follow `omp-docs/references/okf-spec.md` for every doc you create or edit.
 3. Read the target file completely before you edit it.
-4. Always update the documentation when you've completed a task.
-5. Compact the work log when necessary.
+4. Always update the documentation when you've completed a task — and when updating means deleting a page or a paragraph, delete it.
+5. Compact the work log when necessary; a work log holds laws and incidents, never bookkeeping.

 #### USE PROGRESSIVE DISCLOSURE.
 Always ensure that all produced documentation is laid out in files following WIKI conventions: start with a top level README.md index file that provides a brief, concise introduction to the item being documented, and then SPLIT OFF individual aspects, features, or arguments into their own interlinked pages so that future agents can read the documentation in a piecewise fashion, only taking in the details they need. Where relevant, crosslink any created documentation with other relevant documentation. This structure may also be nested, if necessary.
@@ -90,6 +97,7 @@ Never assume the user reports correct information. He is human, and humans make
 - Before starting new work, `git pull` from the remote, and start a new branch in a separate worktree using `master` or `main` as the base branch.
 - Commit atomically: after every change that forms a complete functional unit, commit. Do so early and often.
 - When the work is complete, ask the user if they would like to open a pull request.
+- **Report a pull request as link AND title, every time.** A bare `#54` is not a reference: numbers are per-repository, so a number alone does not say which work, in which repo, is being reported. Give the PR's web URL on that forge — on the Dankclaw Gitea that is `https://gitea.franksdank.cloud/<owner>/<repo>/pulls/N` — together with the PR's title. Applies everywhere a PR is mentioned: chat replies, status summaries, issue and commit bodies, alerts. Another forge (GitHub, GitLab, …): the equivalent URL its web UI serves, same pairing.

 ### 5. Test Driven Development

@@ -42,27 +42,17 @@ gen() {
  echo "> GENERATED by \`scripts/gen-keybinds.sh\` from \`$(basename "$KBD")\` — do not edit by hand."
  echo
  awk '
-    # Section marker: a comment decorated with box-drawing dashes on both sides,
-    # `// ─── Name ───`. The dash is matched as a LITERAL and removed with gsub — never
-    # with a quantifier on the multibyte character. Under LC_ALL=C (cron, systemd units,
-    # agent shells) gawk works byte-wise, `─+` then means "the last byte of ─, repeated",
-    # and every header vanishes while the script still exits 0. Plain comments stay
-    # comments: only a dash-decorated one opens a section.
-    /^[[:space:]]*\/\/[[:space:]]*─/ {
+    # section header: // ─── Name ───
+    /^[[:space:]]*\/\/[[:space:]]*─+ (.+) ─+[[:space:]]*$/ {
      s = $0
-      sub(/^[[:space:]]*\/\/[[:space:]]*/, "", s)
-      sub(/[[:space:]]+$/, "", s)
-      if (s ~ /─ .*─/) {
-        gsub(/─/, "", s)
-        gsub(/[[:space:]]+/, " ", s)
-        sub(/^ /, "", s); sub(/ $/, "", s)
-        if (in_table) print ""
-        print "## " s
-        print ""
-        print "| Key | Action |"
-        print "|-----|--------|"
-        in_table = 1
-      }
+      sub(/^[[:space:]]*\/\/[[:space:]]*─+ /, "", s)
+      sub(/ ─+[[:space:]]*$/, "", s)
+      if (in_table) print ""
+      print "## " s
+      print ""
+      print "| Key | Action |"
+      print "|-----|--------|"
+      in_table = 1
      next
    }
    # bind line: KEY [flags] [hotkey-overlay-title="..."] { action; }
@@ -48,16 +48,6 @@ teardown() {
  [[ "$output" != *"a plain comment"* ]]
 }

-@test "section headers survive a C locale, where awk reads bytes instead of characters" {
-  # Cron, systemd units and agent shells get LC_ALL=C while Frank's terminal does not.
-  # A matcher that puts a quantifier on a multibyte character then loses EVERY section
-  # header and prints a sheet with no sections at all — silently, exit status 0.
-  run env LC_ALL=C "$GEN" "$TMP/keybinds.kdl"
-  [[ "$output" == *"## Applications"* ]]
-  [[ "$output" == *"## Screenshots"* ]]
-  [[ "$output" != *"a plain comment"* ]]
-}
-
@test "row count matches bind count" {
  run "$GEN" "$TMP/keybinds.kdl"
  local rows