self-development: add review-derived agent conventions

[kelos-bot]

What type of PR is this?

/kind cleanup

What this PR does / why we need it:

Adds twenty-four evidence-backed conventions and workflow safeguards to the project
instructions and shared Kelos development AgentConfig.

1. Compare forwarded streams exactly. PR Stream agent output through kelos-capture instead of writing to /tmp #1189's
   review comment
   found that per-line substring assertions could not detect dropped, duplicated,
   or reordered output. The printer/formatter test rule now also requires full
   normalized equality for stream-forwarding tests.

2. Scope autonomous triggers to trusted authors and intended subjects. PR
   Add kanon-development TaskSpawners for autonomous kanon development #1241 was corrected because a
   review trigger lacked an author filter
   and a
   PR-only command also matched issue comments.
   The TaskSpawner convention now requires both author allowlists and commentOn
   scoping where applicable.

3. Classify request failures by cause. PR feat: add WebhookGateway CRD for per-channel webhook auth and multi-instance GitHub #1238's reviews found that
   TaskSpawner list errors silently returned success
   and
   all gateway Get errors became 404s.
   PR Support file attachments in Sessions #1630 then showed the broader form of the same mistake:
   message matching mapped server-side storage failures to 400.
   Error-to-status mappings must use typed or sentinel causes, reserve 4xx for
   client-correctable failures, and return 5xx for lookup, RBAC, storage, and
   transport failures.

4. Honor reduced-motion preferences. PRs
   #1481
   and
   #1482
   independently added continuous running-state animation without a reduced-motion
   fallback. New nonessential animation must retain a distinguishable static state
   when motion is disabled.

5. Protect credentials in configuration and transport. PR feat: Add native OpenTelemetry (OTLP) support for metrics and traces #1559's
   review
   found authorization headers rendered from plaintext Helm values, while PR feat: add GitHub App auth to HTTP context sources #1564's
   review
   found that an HTTP endpoint exposed a GitHub App JWT. Credential-bearing values
   must use Secret references, and their endpoints must use HTTPS unless explicitly
   opted into insecure transport.

6. Protect state-dependent transitions from stale work. PR Add section choosers to the Session server #1548's
   review
   found that an old dialog request could mutate a newly opened Session dialog. PR
   Allow Session interruption while draining #1618's
   review
   similarly required an interrupt to be revalidated against the snapped active turn.
   PR Use inline session section selector #1649 then left a
   finding
   because an async failure path rendered a captured pre-request Session after
   polling had refreshed the selected Session. PR Add Session goal and shell commands #1650 exposed the interaction-level
   form of the same problem: a
   stale goal notification could complete a new message,
   interrupt could race goal startup,
   completion used provider-global goal state,
   and
   goal control matched the wrong active turn kind.
   PR Keep kelos logs -f open after empty streams #1654 then exposed the same precedence problem across independently updated
   lifecycle signals: a
   failed Pod was treated as retryable while Task status lagged,
   and a
   non-zero terminated container was also treated as retryable.
   Async completions and controls must re-read current state, bind to the exact
   operation identity and kind, and coordinate startup and handoff so stale work
   cannot render or mutate another operation. When lifecycle signals disagree or
   lag, terminal and failure evidence must be inspected before returning a
   transient or retry decision.

7. Test behavior through the layer that owns it and assert the primary effect.
   PR Add section choosers to the Session server #1548's same
   review
   found that source-fragment assertions did not exercise stateful UI behavior. PR
   feat: Add optional Prometheus Operator PodMonitor to Helm chart #1560's
   review
   found that a render test never exercised the non-default namespace branch it
   claimed to cover. PR Display and manage pending Session messages #1648's
   review
   also found that an exact minified CSS-rule assertion was brittle while failing
   to exclude declarations that would restore the regression. PR Support file attachments in Sessions #1630 had a
   download fake that discarded the requested attachment ID,
   PR Monitor pull request checks in Sessions #1639 had an
   end-to-end fixture that omitted the changed check-rollup response,
   and PR Reduce Session GitHub API usage #1652 had a
   command fixture that accepted any GraphQL query and could not detect duplicate calls.
   PR Add Session goal and shell commands #1650 also had an
   interrupt test that checked journal status without checking process death,
   while PR Reduce Session GitHub API usage #1652 had a
   periodic test whose blocking callback leaked its goroutine.
   PR Keep kelos logs -f open after empty streams #1654's
   test review
   also found that new terminal, transient, and unknown lifecycle branches were
   left unvalidated.
   Tests must execute the owning layer and important non-default branches, assert
   the real routed or lifecycle effect rather than a bookkeeping proxy, and make
   appropriate static assertions on behavior instead of serialization details.
   State-dependent decision tests must cover each relevant terminal, transient,
   and unknown class plus combinations where status sources can lag one another.
   Fakes, fixtures, and command shims must exercise changed response fields,
   validate complete request shapes, reject unexpected calls, and expose call
   counts when batching or request reduction is part of the contract. Background
   goroutines and child processes must also be cancellation-aware and verified
   stopped before the test returns.

8. Keep all documentation surfaces complete and consistent. Recent reviews
   repeatedly found partial documentation updates: PR Show sessions waiting for input #1604
   claimed header styling that was not implemented,
   PR Track sticky issue validity verdicts #1611 left
   per-spawner sections inconsistent with its overview,
   PR Paginate Session terminal history #1613
   removed documentation for still-supported flags,
   and PR Add Session turn duration separator #1616
   omitted newly observable terminal behavior.
   Agents must search related overviews, component sections, tables, setup examples,
   and command/flag references and update all affected mentions together.

9. Separate historical replay from live event handling. PR Paginate Session terminal history #1613's
   review
   found that older terminal pages could be rendered as continuations of the active
   live stream and that duplicate history requests reused a cursor. PR Paginate Session web chat history #1621's
   review
   found that web history replay could emit a false live interruption toast, omit
   independently needed current file state, and leave viewport preservation untested.
   Replay must keep its rendering, state, and side effects separate while preserving
   cursors, request state, current state, order, and viewport behavior.

10. Use lease-protected pushes after rebasing published branches. PR Add full spawner fleet for kelos-dev/open-actions #1622's
    reviews independently found that the
    worker existing-PR path
    and
    PR responder
    rebased already-published branches and then attempted normal pushes, which fail
    as non-fast-forward updates. The shared instructions now require
    git push --force-with-lease, never an unleased force-push, after rebasing a
    published branch.

11. Treat controller-generated Kubernetes names as durable identities. PR
    Bound Session workload names #1629's reviews found that dropping the Session workload prefix would
    collide with legacy workloads
    and
    abandon retained persistent workspaces.
    The independent
    Kelos Claude review
    also found that a 63-character StatefulSet bound still left no room for
    ControllerRevision and Pod-label suffixes. The
    review on PR #1631
    then showed that a Session name valid under DNS-1123 can still be invalid for
    its governing Service under DNS-1035. Name derivation must validate the exact
    grammar of every generated kind and account for all downstream suffix and label
    limits, and controller-owned resources must not be renamed without a
    collision-safe migration that preserves ownership and data.

12. Keep shared feature contracts consistent across clients. PR Support file attachments in Sessions #1630's
    review found that the plain terminal
    did not enforce the TUI's eight-file limit,
    the TUI
    accepted an empty /send that the plain terminal rejected,
    and the plain terminal
    omitted /send from command help.
    The
    independent Kelos Claude review
    also identified the cross-client limit mismatch. Shared web, TUI, and CLI
    features must apply the same limits, empty-input rules, failure semantics, and
    discoverability, with each surface tested explicitly.

13. Preserve prompt contracts when consolidating instructions. PR Simplify session spawner prompts #1641
    removed detailed worker and PR-responder prompts on the assumption that shared
    configuration supplied the same behavior. Reviewers found the same missing-owner
    failure across
    Open Actions workers,
    Agora workers,
    the Kanon responder,
    the Agora responder,
    the Open Actions responder,
    and the Kelos responder.
    Separate comments also found the
    persistent-workspace test contract
    and
    Agora documentation
    out of sync. Before consolidating prompt instructions, agents must map every
    removed requirement to a concrete source the spawned agent actually loads and
    update contract tests and documentation in the same change.

14. Audit responsive rules when changing web controls. Three recent web
    changes independently missed existing phone behavior:
    PR #1630 left the attachment button below the mobile touch-target size,
    PR #1638 resized the composer without resizing its adjacent attachment control,
    and
    PR #1647 omitted its new textarea from the mobile anti-zoom selector.
    Agents must sweep every relevant selector group and breakpoint override for
    new or renamed controls, preserving mobile font sizing, touch targets, and
    sibling alignment.

15. Use production identities and collection cardinality in tests. PR
    Handle rotated CRD CA bundles during install #1656 had a
    multi-certificate review finding
    because singleton-only expected bundles did not exercise whether every
    required certificate was present. PR fix(slack): stop retrying replies rejected with cannot_reply_to_message #1660 then used an empty Task UID in
    a
    keyed-suppression test,
    so the test passed without exercising the production identity path.
    Fixtures must populate identity fields used as keys and use multi-element
    inputs when behavior depends on collection membership or aggregation.

16. Test API mutability through updates. PR Make Session idle policy mutable #1665's
    API review
    and
    general review
    independently found that making Session.spec.idlePolicy mutable was tested
    only for one non-nil replacement. A
    separate inline finding
    also found that create-only negative cases did not prove validation remained
    enforced on updates. Mutability changes must cover the newly allowed presence
    transitions and at least one invalid update.

17. Preserve keyboard operability in dynamic web controls. PR Add per-session actions menu to session server #1663's reviews
    found that keyboard-invoked actions
    lost focus after rerendering their trigger,
    menu items
    removed the visible focus ring,
    and
    Tab left the menu open after focus moved away.
    PR Show Task logs in the Console #1673 was then independently flagged by
    Cubic
    and the
    Kelos Claude reviewer
    because roving tabindex made the inactive Manifest tab unreachable without
    Arrow/Home/End handling. Custom widgets must implement their expected keyboard
    interaction model; dynamic menus and dialogs must also retain a visible focus
    indicator, dismiss on expected keyboard navigation, restore focus after success
    and failure, and test those interactions through the browser behavior layer.

18. Make component renames upgrade-safe. PR Turn the Session server into the Kelos Console #1670's current-head reviews
    found that the Console rename
    dropped the persisted namespace selection
    and
    left legacy installed objects, uninstall RBAC, and Helm values without an upgrade path.
    Component renames must inventory prior deployed identifiers, migrate stored
    state, clean up resources that non-pruning installs leave behind, retain
    uninstall cleanup for old names, and reject unsupported stale configuration
    actionably. Upgrade-state tests are required alongside fresh-install tests.

19. Test every distinct behavior path independently. PR Add Session suspend action to console #1681 reviews found that the suspend tests depended on an earlier test global, omitted a runtime dependency and could not execute, and left the idempotent API branch untested. PR Visualize resource relationships in the console #1682 then had an independent review find that an exact-set relationship test skipped core derivation branches while a dependency edge was missing. Tests must now establish their prerequisites, include runtime dependencies, prove that the intended path is reached, and inventory relevant mapping variants.

20. Centralize behavior that must stay in lockstep. A
    review on PR #1673
    found duplicate authentication and error handling across two request helpers.
    A
    review on PR #1681
    found duplicated suspend and resume bookkeeping that could drift, and a
    review on PR #1683
    found the Console build commands duplicated instead of routed through the
    existing Makefile target. Code paths that intentionally implement the same
    behavior and differ only by an input or action must share the implementation,
    and repeated build or generation commands must use one Makefile target. The
    rule explicitly excludes incidental similarity to avoid unnecessary
    abstraction.

21. Preserve touch-accessible actions across breakpoints. The Claude review on PR #1686 found that the mobile breakpoint hid the only touch-usable path for Session section assignment while drag-and-drop was not reliable on touch devices. An independent inline review also found that the redesigned mobile tabs fell below the established 44px touch target. Responsive changes must keep every supported action available through an equivalent touch-operable path and test that path.

22. Preserve readable contrast across supported themes. A review on PR #1663 found that removing an explicit focus outline left only a weak dark-mode indicator, and PR #1686 reused a light-theme label color that produced roughly 2.5:1 contrast in dark mode. Color and theme changes must verify text, interactive labels, and focus indicators in every supported theme against the applicable WCAG AA contrast requirement.

23. Preserve Unicode semantics in text processing. A review on PR #1673 found that byte-offset truncation could split a multibyte rune and emit invalid UTF-8. A review on PR #1692 then found that len() enforced a documented character threshold in bytes, causing non-ASCII false negatives and misleading diagnostics. Character limits must count Unicode code points, byte-bounded truncation must preserve UTF-8 boundaries, and affected limits must be tested with non-ASCII input.

24. Preserve UI behavior when restructuring web views. PR Make console sidebar controls scrollable #1688 moved
    Console sidebar scrolling to a new container but left
    menu dismissal attached to the old non-scrolling list.
    PR Keep the current request visible in console #1702 later let
    hidden-view geometry updates clear current-request state without recomputing it on reveal.
    Web view restructuring must migrate behavior bindings to the actual
    containers, avoid deriving state from hidden layout geometry, recompute
    derived state when a view becomes visible, and test the affected scroll and
    hide/reveal interactions.

Files updated:

• AGENTS.md
• self-development/agentconfig.yaml

self-development/base-agent.yaml is intentionally unchanged because none of
these changes are an upstream gjkim42/kanon-repo synchronization.

Which issue(s) this PR is related to:

N/A

Special notes for your reviewer:

The existing unassigned configuration PR was reused and was rebased onto current main. make verify and
env -u CODEX_AUTH_JSON -u CODEX_HOME -u KELOS_PLUGIN_DIR make test pass.
The environment overrides keep entrypoint fixtures from inheriting agent host
configuration.

Does this PR introduce a user-facing change?

NONE