Skip to content

docs: clarify public contributor guidance - #351

Closed
kevintseng wants to merge 1 commit into
mainfrom
docs/public-agent-guidance
Closed

kevintseng wants to merge 1 commit into
mainfrom
docs/public-agent-guidance

Conversation

@kevintseng

@kevintseng kevintseng commented Sep 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Clarifies the public contributor entry point: AGENTS.md directs repository contributors to CLAUDE.md while preserving its product instructions. CLAUDE.md retains actionable safeguards and canonical links, removing internal history and duplicated explanations. The top-of-file pointer is separate from the section removal proposed in #341.

Verification

npm run verify exited 0, including isolated tests, packaged CLI checks and the packaged dashboard browser journey:

Dashboard packaged e2e smoke passed
[verify] ok dashboard-e2e (26s)
[verify] tree d73a299bca46e25cf62a3d6c4a564e9afc256435 (full)
[verify] GREEN. Receipt for tree d73a299bca46 written to .verify/receipt.json.

Existing harness evals exited 0: no-plan-no-build and verify-before-done, 2/2 passed, 0 failed, 0 skipped. No evaluator or test changed. Initial sandboxed process launches failed; the unchanged candidate passed with the required OS permissions.

Independent read-only review: PASS_WITH_CONCERNS. The pointer's required-plan wording may sound universal; CLAUDE.md explicitly limits plans to non-trivial changes. No disclosure finding in the reviewed documents.

Hosted eval run 34781277221 failed: no-plan-no-build reported read plan docs: true; answer names docs/plans and Proof: false; verify-before-done passed. Thus the local result has not reproduced with the CI default model. This remains an open finding; no rerun or evaluator modification was used to hide it. Other CI checks and merge remain pending.

Coverage

Item QA Simplification Notes
CLAUDE.md Full-file review; local links checked; verify exit=0, receipt tree d73a299bca46e25cf62a3d6c4a564e9afc256435 Consolidated guidance Isolation, receipt, Proof and review retained
AGENTS.md Full-file review; original body byte-identical after removing pointer One conditional pointer Product instructions preserved
Contributor discovery Both existing evals exit=0 Evaluator unchanged One local replay
Public disclosure Full-file review found no credentials or private host identifiers Internal history removed No private transcripts or working notes included

@github-actions

Copy link
Copy Markdown

SDLC review (REVIEW.md, three passes; codex:default)

FAIL

Bugs

No findings.

Security

No findings.

Compliance

  • [Compliance] Important — .sdlc-run/review-351.diff:3 (request body): The required “Docs synced” checklist is missing. CONTRIBUTING.md:37 explicitly treats an unfilled checklist as not-ready-for-review. Restore the PR template checklist and complete applicable entries; the Coverage table does not replace it.

Verification limitation: the quoted receipt matches HEAD’s tree, d73a299bca46e25cf62a3d6c4a564e9afc256435, and Coverage includes both changed files. GitHub API access failed, so CI’s Golden journeys result and tree comparison remain unverified.

No change-specific plan or spec exists; this documentation-only diff touches none of the configured source prefixes.

Files read in full: 2/2 changed files.

@kevintseng

Copy link
Copy Markdown
Contributor Author

Closing without merging.

This branch is 53 commits behind main and now has a real merge conflict (not just a fast-forward gap). More importantly, its content has drifted out of sync with a change that landed on main on 2026-09-20 (54c3fb21, #364/#365): REVIEW.md, docs/sdlc/LOOP.md and sdlc/config.json — all three referenced by this PR's target CLAUDE.md as live, universal requirements — are now git-ignored, maintainer-local files, not present in any fresh clone. Merging this as written would put dead links and a misleading "every change needs a plan with a Proof section" claim into the file every contributor is told to read first, and would also drop several still-accurate, hard-won notes from the current CLAUDE.md (the audit/mutation-testing discipline, the reviewer-scoping rule, coverage caveats) in favor of pointers to docs that no longer ship publicly.

The PR's own description also disclosed an unresolved finding from its one CI review pass ("This remains an open finding... Other CI checks and merge remain pending"), so it was not marked ready even when opened.

If a single, clear public contributor entry point is still wanted, it should be a new PR built from the current CLAUDE.md (already a clean pointer file post-#365), not from this branch's base. #341's AGENTS.md top-of-file pointer idea can still work, worded to match what a public clone actually has.

@kevintseng kevintseng closed this Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant