Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Task] Align adoption instructions and publish dated evidence boundaries

Open
  • Is something wrong?
#33 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github, python
Domain
devtools, documentation, testing

Research direction

Start by reading the installed and public README.md, the payload README, and the evidence and parity pages named in the plan; then inspect the listed integrity checks and focused conformance tests. The scope spans 14 owned paths and requires preserving historical evidence, payload integrity, and seed behavior. Done means the planned documentation and bindings are aligned, focused regressions and both production gates pass, and the exact candidate’s CI and independent review are recorded; live behavior and owner acceptance remain out of scope.

Written by the indexing model from the issue text.

Description

Problem and expected behavior

The public README requires the ChatGPT Codex desktop app, but the installed README still advertises an available client and CLI/IDE invocation, and incorrectly says all installers never stage. The first-Task feature example also conflicts with the installed onboarding procedure for existing codebases, which calls for characterization tests first. Evidence documentation mixes a retained Pending checkpoint with a later accepted bounded exercise, making the supported claims difficult to find.

Align the adopter instructions with the existing product contract and provide one dated entry point that separates baseline CI, synthetic conformance, historical bounded E01 acceptance, and unmeasured behavior. This is not a new compatibility, runtime, release, or live-measurement claim.

Plan, scope and ownership

  • Base: 9fdbf91d9980b5c632e0f3483c97098358ce519f (tree 455adcd64ef2af0e19d5899dfa3c5d56f08c6dd4). Branch: codex/adoption-evidence-polish.
  • One active writer: the current coordinating Codex session, in one isolated public-source checkout. Bounded documentation-task exemption: supervision and implementation are combined; no implementation worker is dispatched. Read-only independent reviewers may inspect the result without editing it.
  • Human approval covers this bounded polish and an unmerged PR. Final acceptance and merge require a separate owner decision.
  • Read and record this plan before edits. Align the installed README with desktop requirements, project primary-folder/specification preparation, entry-specific staging, explicit Skill loading, and preservation of existing seed READMEs. Align the first existing-codebase Task with characterization testing.
  • Add a dated evidence page and clarify historical checkpoint labels and later acceptance without rewriting historical results. Use the existing public acceptance links in the parity page; no private evidence is accessed or republished.
  • Preserve all 47 payload paths/classes/modes and 46 other payload contents. README remains seed. Bind this one current README adaptation independently from the immutable original export and preserve all historical seals/baselines.
  • Synchronize current-target inventory/provenance hashes and add focused negative regressions for the one-file adaptation and documentation boundaries. No installer/update/helper/workflow behavior changes.

Owned paths (14):

  1. README.md
  2. .github/distribution/payload/README.md
  3. docs/evidence-status.md (new)
  4. docs/parity-status.md
  5. docs/known-limitations.md
  6. docs/provenance.md
  7. .github/distribution/payload.v1.tsv
  8. .github/distribution/source-parity.v1.json
  9. .github/distribution/adopter-ci.v1.json
  10. .github/distribution/ongoing-improvement.v1.json
  11. .github/distribution/pr-monitor.v1.json
  12. .github/scripts/check-product.py (closed README adaptation, documentation/test inventory, current record bindings only)
  13. .github/scripts/check-installer.py (current digest constants only)
  14. tests/conformance/test_adoption_evidence.py (new focused regressions)

Excluded: Skill changes, application behavior, held Task 23 A01-A06 work, E01 reruns, live adopters/Projects/Rulesets, service or permission changes, model/API experiments, workflow/receiver/schedule activation, T12/runtime, release, merge/close, application or support-program claims.

Acceptance and verification

  1. Public and installed entry instructions consistently require desktop and explicit loading, describe project/specification preparation, and distinguish staging entry points. Existing-codebase first Task protects observed behavior before feature work.
  2. A dated evidence matrix links baseline CI at the exact base and the existing dated public E01 acceptance section; it distinguishes synthetic conformance, historical accepted evidence, later unmeasured live behavior and remaining exclusions. Historical Pending checkpoint and release limitations remain intact.
  3. Only payload README content changes; its seed class/mode, all other payload bytes and original export/history/baselines are unchanged. Fresh delivery uses the new bytes; custom/existing seed README bytes and modes survive install/update.
  4. Current integrity bindings pass both production gates. Focused regressions reject altered original export rows, unreviewed README bytes, and an additional resealed path exemption. The new page participates in navigation validation; receipt exceptions do not expand.
  5. Publish exact candidate HEAD/tree, verification results and independent review in this Task/PR. Baseline CI is not candidate evidence. No live model-compliance result, owner acceptance or merge is inferred.

Planned checks: both product/installer gates; focused adoption/evidence tests; existing fresh-install, seed preservation, upgrade roundtrip, kickoff provenance/boundary and export/navigation/receipt tests; git diff --check; required PR quality and conformance CI for the exact candidate. Local missing PowerShell, if any, remains an explicit coverage limit until CI supplies its required real host. No live E01 or adopter operations.

Risk: documentation can overstate compatibility/evidence or overwrite the historical meaning of receipts; a broad export exception could weaken integrity. Mitigations are closed single-path/original/current bindings, negative tests, seed-preservation checks, independent review and dated claim boundaries. Remaining model behavior, onboarding/Project execution and Windows behavior are not measured by this change.

Dominant language
Python
Stars
5
Forks
0
Avg merge
3h 45m
Merged PRs (30d)
29

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mochan-tk/agentic-dev-kit-for-codex

All issues in mochan-tk/agentic-dev-kit-for-codex

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.