Round 44: surface-map-drift smell — hygiene #50 + map-completeness BACKLOG#140
Merged
Round 44: surface-map-drift smell — hygiene #50 + map-completeness BACKLOG#140
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces the “surface-map-drift” hygiene smell and expands the repo’s operational documentation around supply-chain safety, GitHub-surface triage, and loop cadence/fire-history, alongside a backlog entry for proactive map-completeness auditing.
Changes:
- Add new security guidance docs (supply-chain safe patterns, GitHub Actions injection safe patterns) and enrich the incident playbook with additional canonical cases.
- Add/extend factory governance + cadence artifacts (autonomous loop discipline, GitHub surface triage playbook + skill, upstream rhythm) and update several hygiene/debt/vision documents.
- Add issue templates for dual-track workflow (bug/backlog/human-ask) and tighten various doc formatting/consistency.
Reviewed changes
Copilot reviewed 43 out of 43 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/templates/DMAIC-proposal-template.md | Removes stray blank lines in template sections. |
| docs/security/SUPPLY-CHAIN-SAFE-PATTERNS.md | Adds supply-chain “pre-add/pre-bump” checklist and threat-model framing. |
| docs/security/INCIDENT-PLAYBOOK.md | Expands Playbook A with additional canonical cases and cross-refs. |
| docs/security/GITHUB-ACTIONS-SAFE-PATTERNS.md | Introduces workflow-injection safe-patterns checklist and enforcement layers. |
| docs/research/lfg-only-capabilities-scout.md | Adds inventory of LFG-only capabilities and experiment candidates. |
| docs/research/github-surface-map-complete-2026-04-22.md | Adds drift notes + UI-only surfaces + drift log for GitHub surface map. |
| docs/factory-crons.md | Documents a new “every-tick reconcile” lifetime and an autonomous-loop cron row. |
| docs/copilot-wins.md | Adds a log entry capturing prior review findings and calibration notes. |
| docs/VISION.md | Updates long-term vision details (multi-node, tooling stack, crystallization loop framing). |
| docs/UPSTREAM-RHYTHM.md | Adds fork-first/batched upstreaming cadence and concrete gh command recipes. |
| docs/TECH-DEBT.md | Removes extra blank lines in example blocks. |
| docs/SYSTEM-UNDER-TEST-TECH-DEBT.md | Removes extra blank lines in example blocks. |
| docs/SHIPPED-VERIFICATION-CAPABILITIES.md | Removes an MD024 suppression comment near duplicate headings. |
| docs/POST-SETUP-SCRIPT-STACK.md | Wraps a long heading for readability. |
| docs/INTENTIONAL-DEBT.md | Normalizes emphasis markup in “Resolved” placeholder note. |
| docs/HUMAN-BACKLOG.md | Adds HB-002 entry describing backlog restructure decision questions. |
| docs/HARNESS-SURFACES.md | Adjusts formatting around memory references. |
| docs/FACTORY-RESUME.md | Removes a stray blank line in the experience section. |
| docs/FACTORY-METHODOLOGIES.md | Removes a stray blank line in a checklist preface. |
| docs/FACTORY-HYGIENE.md | Adds/expands several hygiene rows including surface-map-drift; updates shipped-summary table. |
| docs/DECISIONS/2026-04-22-backlog-per-row-file-restructure.md | Adds a proposed ADR for backlog per-row-file restructure. |
| docs/CONTRIBUTOR-PERSONAS.md | Adds contributor-persona inventory to guide first-contact UX. |
| docs/CONFLICT-RESOLUTION.md | Updates standing-resolution ADR pointer for claims-vs-complexity pipeline. |
| docs/BACKLOG.md | Adds map-completeness audit row + LFG-only experiment track section. |
| docs/AUTONOMOUS-LOOP.md | Adds a full discipline/spec for the autonomous loop tick + cron behavior. |
| docs/AGENT-ISSUE-WORKFLOW.md | Adds adapter-neutral dual-track + claim/lock protocol doc. |
| docs/AGENT-GITHUB-SURFACES.md | Adds ten-surface GitHub playbook, cadence, shapes, and fire-history paths. |
| .github/ISSUE_TEMPLATE/human_ask.md | Adds “human ask” issue template for sign-off decisions. |
| .github/ISSUE_TEMPLATE/config.yml | Adds issue-template contact links routing to key docs. |
| .github/ISSUE_TEMPLATE/bug_report.md | Replaces default bug template with Zeta-specific fields and dual-track guidance. |
| .github/ISSUE_TEMPLATE/backlog_item.md | Adds backlog-item issue template with category/acceptance guidance. |
| .claude/skills/skill-documentation-standard/SKILL.md | Adds frontmatter provenance fields to the skill doc. |
| .claude/skills/github-surface-triage/SKILL.md | Adds executable checklist skill for GitHub-surface triage. |
| .claude/skills/alignment-observability/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/alignment-auditor/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/algebra-owner/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/alerting-expert/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/ai-researcher/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/ai-jailbreaker/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/ai-evals-expert/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/agent-qol/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/agent-experience-engineer/SKILL.md | Adds frontmatter provenance fields. |
| .claude/skills/activity-schema-expert/SKILL.md | Adds frontmatter provenance fields. |
…CKLOG + map-drift log
Aaron 2026-04-22 flagged two related smells during LFG budget audit:
(1) "i'm supprised you got the url wrong given you mapped it" +
"that should be a smell when that happen to a surface you
already have mapped"
Agent invented /orgs/.../billing/budgets (404) despite
docs/research/github-surface-map-complete-2026-04-22.md
already being the complete mapping. FACTORY-HYGIENE row #50
codifies the smell as:
- Pre-call: grep the map before `gh api <path>`.
- Post-call: 410/301 on a mapped endpoint auto-proposes a
map-update.
- Cadenced: 5-10 round replay of mapped endpoints to catch
silent renames.
(2) "missing map hygene on backlog?"
Complementary proactive audit that row #50 doesn't cover:
"does the map cover all surfaces we actually touch?".
Filed as P1 BACKLOG row under factory/tooling section.
Known gaps surfaced by the triggering incident: GitHub
org spending-budget UI (now mapped as `ui-only`); Copilot
Business per-feature toggle state; coding-agent / internet-
search enablement flags.
Same incident revealed separate map-drift:
/orgs/{org}/settings/billing/actions returned 410 with
documentation_url: https://gh.io/billing-api-updates-org.
Logged in new "Map drift log" section of the research doc;
old-path preserved, successor TBD per GitHub's migration doc.
New "UI-only surfaces" subsection in the research doc
documents surfaces with no REST equivalent (budget management,
audit-log on Team plan) so agents don't waste attempts on
non-existent paths. Budget management stays in the *forbidden*
class per the LFG paid-Copilot memory.
Memory:
- memory/feedback_surface_map_consultation_before_guessing_urls.md
- MEMORY.md index entry added.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
force-pushed
the
surface-map-drift-smell-2026-04-22
branch
from
1d976ad to
7be5235
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7be5235952
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+777
to
+778
| log is the **post-call arm of FACTORY-HYGIENE row #50** | ||
| (surface-map-drift smell). Agents encountering a drift on any |
There was a problem hiding this comment.
This text points the map-drift workflow at FACTORY-HYGIENE row #50, but the same commit actually introduces the surface-map-drift smell as row #60, while related BACKLOG text also mentions a future row #51; those numbers currently map to unrelated hygiene items. In practice, reviewers following these references will inspect/update the wrong rule and miss the intended cadence, so the cross-references should be aligned to the actual row number introduced here.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
docs/FACTORY-HYGIENE.mdrow style🤖 Generated with Claude Code