docs: generated "Where to file" block routes user reports to the Discussions hub

[Jammy2211]

Overview

A collaborator asked whether AGENTS.md carries a flag telling their agent that user reports belong on the org Discussions hub (https://github.com/orgs/PyAutoLabs/discussions) rather than a repo's Issues. It does not: policy/community_surface.md decides this, but no AGENTS.md/CLAUDE.md mentions Discussions, and the only filing recipe an agent sees is create_issue's gh issue create. This task adds a generated "Where to file" block to every public AGENTS.md, single-sourced from a Mind policy file, and makes create_issue and intake state the same rule.

Plan

1. Add a terse Mind policy file policy/where_to_file.md: the "what" an agent needs at filing time; link to policy/community_surface.md for the why.
2. Generate it into every public AGENTS.md as a <!-- repos_sync:filing:begin/end --> block via scripts/repos_sync.py: one source, N copies, drift-checked, self-inserting under the end-at-deliverable block; a missing block is REPORTED, not skipped (same contract as check_deliverable_blocks).
3. Make skills/create_issue (Mind) and skills/intake (Brain) state the rule for user-facing reports so the Mind flow is not the loophole.
4. Tests mirror tests/test_repos_sync_deliverable_block.py (fictional fixtures, every leg proven to fail).
5. Rollout to the ~48 AGENTS.md copies: extend .github/workflows/session_hook_propagate.yml with a NARROW leg that writes only the filing block (never the map blocks), also triggered on policy/where_to_file.md. Human-approved decision: bot push, not a PR wave. This Mind PR ships first; propagation runs on push to main after merge.

Detailed implementation plan

Affected Repositories

• PyAutoMind (primary)
• PyAutoBrain

Branch Survey

Repository	Current Branch	Dirty?
./organs/PyAutoMind	main	clean
./organs/PyAutoBrain	main	clean

Parallel claim (human-approved 2026-09-27): both repos are also claimed by eyes-organ-order (PyAutoMind#439). Its Mind diff touches repos.yaml organ order, the two hook copies and one 4-line hunk in scripts/repos_sync.py _repo_resolver; its Brain diff touches agents/_pyauto_root.py, bin/_pyauto_root.sh, docs/. This task touches disjoint regions: repos_sync.py block constants/new functions/main wiring, policy/, tests/, skills/create_issue, .github/workflows/session_hook_propagate.yml, and Brain skills/intake/.

Suggested branch: feature/where-to-file-block

Implementation Steps

1. policy/where_to_file.md (~8 lines, ## Where to file): user/collaborator questions, help, ideas, bug reports and results go to the Discussions hub in the matching category (Help & Questions, Ideas & Proposals, Bugs & Errors, Show and tell; Announcements maintainers-only), never repo Issues; an agent never runs gh issue create for such a report — it drafts title/category/body for the human; only the dev flow (Mind prompt → /start_dev → /create_issue → one issue per task → PR) opens issues. Why: policy/community_surface.md.
2. scripts/repos_sync.py: FILING_BEGIN/END, FILING_POLICY_FILE, load_filing_policy, check_filing_blocks (three-state, anchored on the deliverable markers), insert_filing_markers (under DELIVERABLE_END), write_block in the --write loop, check-table row "where-to-file blocks (generated)", --only/--skip plumbing, and a write_filing_blocks(root, repos) helper for the workflow.
3. .github/workflows/session_hook_propagate.yml: add policy/where_to_file.md to the path trigger; call repos_sync.write_filing_blocks beside write_session_hooks; header comment explains the narrow leg; keep dry_run semantics.
4. tests/test_repos_sync_filing_block.py mirroring the deliverable-block tests; assert the workflow references write_filing_blocks and the policy path.
5. Write the block into Mind's and Brain's own AGENTS.md on the branch (other repos get it via propagation).
6. skills/create_issue/SKILL.md: guard before gh issue create for user-facing reports. Brain skills/intake/intake.md: route outsider reports the same way.

Key Files

• policy/where_to_file.md — new single source
• policy/community_surface.md — the why (unchanged)
• scripts/repos_sync.py — generator + drift check
• tests/test_repos_sync_filing_block.py — new tests
• .github/workflows/session_hook_propagate.yml — bot-push rollout leg
• skills/create_issue/SKILL.md, PyAutoBrain skills/intake/intake.md — skill guards

Original Prompt

Click to expand starting prompt

docs: "Where to file" block in every public AGENTS.md — route user reports to the Discussions hub

Type: docs
Target: pyautomind
Repos:

• PyAutoMind
  Difficulty: small
  Autonomy: supervised
  Priority: high
  Lane: any

Request (2026-09-27, from the collaborator Slack)

Jam: All issues for any project should be posted here
https://github.com/orgs/PyAutoLabs/discussions and NOT on their individual
GitHub Issues page. When posts go there we will be notified about it here on
SLACK.

Sam: is there a flag in the agents.md files for this so that if I use Claude
to raise an issue it will automatically see that the issue should go there
and not through GitHub?

There is no such flag. policy/community_surface.md (PyAutoMind#403/#411/#426)
already decides that users go to the one org Discussions hub, and the README
"Community & Support" sections and issue choosers were regenerated from it —
but no AGENTS.md or CLAUDE.md in the workspace mentions Discussions (grep
over the root, every organ, every library, workspace and assistant checkout),
and the only issue-filing recipe an agent sees is create_issue's
gh issue create on the target repo. A contributor's Claude reading their
clone of PyAutoLens today opens a repo issue.

Ask

Add a generated "Where to file" block to every public repo's AGENTS.md,
single-sourced from a Mind policy file exactly like the never-rewrite-history
and end-at-deliverable blocks (scripts/repos_sync.py, one source, N copies,
drift check), stating:

• questions, help with code or analysis, ideas/proposals, bug reports and
  results from users and collaborators — or an agent acting for one — go to
  https://github.com/orgs/PyAutoLabs/discussions in the matching category
  (Help & Questions, Ideas & Proposals, Bugs & Errors, Show and tell;
  Announcements is maintainers-only), not to the repo's Issues;
• an agent never runs gh issue create for a user-facing report: it drafts
  the post (title, category, body) and hands it to the human, since sessions
  have not been able to create Discussions (measured on the policy page);
• the organism's own development flow — Mind prompt → /start_dev →
  /create_issue → one issue per task → PR — is the only thing that opens
  issues on these repos (policy sentence two; unchanged).

Make create_issue and intake state the same rule for user-facing reports so
the Mind flow does not become the loophole.

Constraints

• Terse: the block rides in every repo's AGENTS.md and is paid in context in
  every session. Prohibition + hub link + categories + the dev-flow exemption.
• Keep policy/community_surface.md the source of why; the new policy file
  is the what an agent needs at filing time. Link, don't duplicate.
• The rollout to the ~48 AGENTS.md copies is its own decision: PR wave versus
  extending session_hook_propagate.yml to bot-push this one block.

[Jammy2211]

Parallel claim (human-approved 2026-09-27): where-to-file-block (PyAutoMind#442) also claims PyAutoMind and PyAutoBrain on feature/where-to-file-block. Disjoint from eyes-organ-order (#439): #439 touches Mind repos.yaml organ order, the two hook copies and the 4-line _repo_resolver hunk in scripts/repos_sync.py, plus Brain agents/_pyauto_root.py, bin/_pyauto_root.sh, docs/. #442 touches only repos_sync.py block constants/new functions/main wiring, policy/, tests/, skills/create_issue, .github/workflows/session_hook_propagate.yml and Brain skills/intake/.

[Jammy2211]

Library PR Created

• PyAutoMind: docs: generated "Where to file" block routes user reports to the Discussions hub #443 (merge first)
• PyAutoBrain: docs: where-to-file block in AGENTS.md; intake routes outsider reports to Discussions PyAutoBrain#425 (merge after docs: generated "Where to file" block routes user reports to the Discussions hub #443; the propagation bot writes the identical block to Brain main, so it merges clean either way)

API changes: none. This is docs/policy plus generator tooling (policy/where_to_file.md, a repos_sync:filing block, a narrow write_filing_blocks propagation leg, a filing_pr skip in the firewall gate, filing_block: false for euclid_assistant, and guards in create_issue and intake).

Workspace impact: none. No library API changed, so there are no smoke tests to run.

Heart YELLOW acknowledged: "manifest drift: hub organism blurb (organs present) — 7 mismatch(es) vs PyAutoMind/repos.yaml"; "manifest drift: organism-map blocks (generated) — 1 mismatch(es) vs PyAutoMind/repos.yaml"; "manifest drift: workspace checkouts (manifest ↔ disk) — 1 mismatch(es) vs PyAutoMind/repos.yaml"; "release validation incomplete: no rehearsal for current source"

Next: the human merges both PRs, then /prm. After #443 merges, session_hook_propagate.yml bot-pushes the block to the in-scope sibling repos.

[Jammy2211]

Shipped

• PyAutoMind: docs: generated "Where to file" block routes user reports to the Discussions hub #443 (merge commit bf4f8db)
• PyAutoBrain: docs: where-to-file block in AGENTS.md; intake routes outsider reports to Discussions PyAutoBrain#425 (merge commit 64861372)

What shipped:

• policy/where_to_file.md, generated into every public AGENTS.md as a drift-checked repos_sync:filing block that inserts itself under the deliverable block
• a narrow propagation leg (write_filing_blocks)
• the firewall-gate filing_pr skip
• the filing_block: false exemption for euclid_assistant
• the create_issue guard and the intake rule

Rollout snapshot (16:21Z): the propagation run 36332804243 completed with success on bf4f8db. Its log shows 36 AGENTS.md diffs and no warnings. The post-merge firewall push run 36332804151 on bf4f8db also succeeded.

User and collaborator reports now point at https://github.com/orgs/PyAutoLabs/discussions from every repo's AGENTS.md. This answers the collaborator question from Slack.