Codex GitHub Upstream Conformance

Maintainer-facing record of how this pack maps onto the OpenAI Codex GitHub plugin, produced by the final conformance audit. The goal is workflow semantics, not copy-identical text. Any future change to a skill should be checked against this matrix so intentional differences are not accidentally "fixed" back toward Codex, and genuine gaps are not introduced silently.

Baselines (pinned at audit time)

Baseline	Identity
Local installed Codex GitHub plugin	~/.codex/plugins/cache/openai-curated-remote/github/0.1.8-2841cf9749ae/ (cache mtime 2026-07-10)
Public upstream commit	openai/plugins@4c2b32e42cf50cea9599bb8a167c1db759e6ce40 (2026-06-23; latest commit touching plugins/github at audit time)
Local vs public file diff	identical for github/SKILL.md, gh-address-comments/*, gh-fix-ci/*; only yeet/SKILL.md differs (local: branch agent/{desc}, PR title {desc}; public: branch codex/{desc}, PR title [codex] {desc}) — branding only, no workflow-semantic change

The public plugin declares a GitHub MCP server (.mcp.json, bearer_token_env_var: GITHUB_PAT_TOKEN) that the local 0.1.8 install does not carry; neither is relevant to DSH (see Intentional omissions).

Behavior matrices

Verdict legend: equivalent · equivalent via DSH capability · intentionally different · intentionally omitted · GAP.

1. github umbrella

Behavior	Codex local/public	dsh-github-skills	Verdict
Resolve operating context first	yes	yes	equivalent
Identify repo / PR / issue / local branch	yes	yes	equivalent
Classify: triage / review / CI / publish	yes	yes	equivalent
Route immediately once intent is clear	yes	yes	equivalent
Umbrella does not duplicate specialist workflows	yes	yes	equivalent
Structured GitHub capability first	connector app first	best visible DSH GitHub tool first	equivalent via DSH capability
Align connector state with local checkout	yes	yes	equivalent
Never pretend a capability exists	ask for repo, don't invent search	catalog detection, no invented tool names	equivalent
Final output: inspected / state / next	yes	yes	equivalent
Tool-name collisions across providers	n/a (single connector)	match exact full name + signature + description (gh_* shared by ZariaEcho/PerryLink)	DSH-specific addition

2. gh-address-comments

Behavior	Codex	dsh-github-skills	Verdict
Explicit repo + PR	yes	yes	equivalent
PR URL	yes	yes	equivalent
Current-branch PR	head repo via headRepositoryOwner/headRepository	PR canonical URL → target repo	intentionally different (see fork PR note)
Fork / cross-repo PR	"works by reading head repo" — queries head repo	queries the repo that owns the PR (target)	intentionally different (corrected upstream bug)
Three layers: conversation comments / reviews / reviewThreads	yes	yes	equivalent
Thread fields: isResolved, isOutdated, path, line, diffSide, startLine, startDiffSide, originalLine, originalStartLine, resolvedBy, comments, pagination	yes	yes	equivalent
Only unresolved actionable feedback is acted on	yes	yes	equivalent
Explicit thread classification	not hard-coded	7 classes (actionable/informational/approval/resolved/outdated/duplicate/ambiguous)	DSH-specific addition
"Address the review" authorizes local edits	yes	yes, without mechanical re-asking	equivalent
Remote writes (reply/resolve/submit review/push) need explicit ask	yes	yes	equivalent
Comment asking for explanation → draft response, not forced code change	yes	yes	equivalent

Fork PR note (high-priority audit item). Codex fetch_comments.py resolves the current-branch PR from headRepositoryOwner/headRepository and queries repository(owner, name) { pullRequest(number) } with it. For a fork PR the PR object — including its reviewThreads — lives in the target repository, not the fork head; querying the head repo can return null or, worse, an unrelated PR with the same number. gh 2.97 exposes no baseRepository JSON field, but the canonical PR url always identifies the target repo. fetch-review-threads.mjs therefore prefers the URL and falls back to the head repo only for same-repository PRs. This is an intentional correction of upstream behavior.

3. gh-fix-ci / inspect-pr-checks

Robustness behavior	Codex (inspect_pr_checks.py)	dsh (inspect-pr-checks.mjs)	Verdict
gh availability / auth check	yes	yes	equivalent
Current PR resolution	gh pr view --json number	same	equivalent
Explicit PR	yes	yes	equivalent
gh pr checks JSON field drift fallback	"Available fields" retry	same	equivalent
conclusion / state / bucket normalization	failure/cancelled/timed_out/action_required; fail bucket	same sets	equivalent
Actions run id extraction	/actions/runs/(\d+), /runs/(\d+)	same	equivalent
Job id extraction	/actions/runs/\d+/job/(\d+), /job/(\d+)	same	equivalent
External provider detection	no run id → external, report-only	same; never calls run/log APIs	equivalent
Run metadata	gh run view --json …	same fields	equivalent
Run log retrieval	gh run view <id> --log	same	equivalent
Pending logs	marker detection ("still in progress", "log will be available…")	same	equivalent
Job-log fallback	gh api /repos/…/jobs/<id>/logs when run log pending	same	equivalent
Zip payload handling	detects PK → reports error, no fake success	same	equivalent
Failure marker selection	scan from end for error/fail/traceback/…	same markers	equivalent
Bounded context snippet	marker ± context, capped at max-lines	same	equivalent
Log tail	last max-lines	same	equivalent
Malformed JSON handling	explicit error	same	equivalent
Exit code semantics	0 no failures, 1 failures remain	same, plus 2 for blocked/usage	equivalent / intentionally different (DSH adds 2)
Workflow: summary → plan → approval → implement	approval before any fix	local fix allowed when the user explicitly says "fix the CI"; diagnosis-only never edits; push/rerun/comment still need explicit intent	intentional UX adaptation

4. yeet ↔ gh-publish

Behavior	Codex (yeet local/public)	dsh-github-skills	Verdict
Inspect git status first	yes	yes (+ preflight)	equivalent via DSH capability
Inspect diff before staging	yes	yes (+ numstat)	equivalent
Mixed-worktree detection	ask which files	deterministic mixedWorktree flag	equivalent via DSH capability
Never default git add -A on mixed tree	yes	yes (hard rule)	equivalent
Branch strategy	agent/ (local) / codex/ (public) prefix	follow repo conventions; dsh/<desc> only when none	intentionally different
Explicit-file staging	yes	yes, plus partially staged (MM) rule: never blindly re-git add a file with unstaged hunks; git add -p or report ambiguity	equivalent + DSH addition
Untracked files	—	neither auto-included nor auto-excluded; judged against task scope	DSH addition
Commit	terse message	terse, repo conventions, hooks respected	equivalent
Relevant checks	yes	yes, minimal scope	equivalent
Push	git push -u origin	tracked remote first (preflight upstream), never assume origin	intentionally different
Draft PR default	yes	yes	equivalent
Existing PR on branch	not handled	check gh pr view first; never create a duplicate PR	DSH addition (closes gap)
Repo / head / base resolution	connector + gh repo view	preflight + gh repo view --json defaultBranchRef	equivalent via DSH capability
Fork / cross-repo	gh pr create fallback	push to fork remote, gh pr create --head <fork>:<branch> --repo <target>, fail closed when unclear	intentionally different / equivalent
PR body real Markdown + newlines	emphasized, temp file	emphasized; temp file for CLI fallback	equivalent
Final evidence summary	yes	yes	equivalent
codex/ branch / [codex] PR title branding	local yeet drops it; public keeps it	never adopted	intentionally omitted

Intentional omissions from Codex

Codex artifact	Why DSH should not copy it
OpenAI App connector metadata (.app.json)	binds to Codex's connector runtime; DSH has no single connector
GitHub MCP declaration (.mcp.json, GITHUB_PAT_TOKEN)	Codex API-key-session mechanism; DSH auth flows through gh/DSH providers
Codex agent UI metadata (agents/openai.yaml, interface fields)	Codex-specific presentation surface
codex/ branch naming + [codex] PR title prefix	branding; this pack follows target-repo conventions
Python helpers	DSH guarantees Node; zero-dependency .mjs preferred
Resident prompt injection	this pack is progressive disclosure; catalog = name + description only

DSH-specific additions

• Multi-provider capability matrix (references/capability-matrix.md)
• dsh-ci-doctor (ci_diagnose) as preferred CI primitive when visible
• dsh-gitflow tools as the git fallback layer
• DSH approval model: remote writes need explicit intent or the host gate
• ctx.skills bundle shim (lib/index.js) with lazy bodies and directory resourceBase
• publish-preflight.mjs deterministic scope evidence
• Fork-PR target-repo resolution correction (see above)
• Explicit 7-class thread classification
• Partially-staged (MM) staging rules, existing-PR detection, non-origin remote handling

GAP ledger (audit outcome)

All gaps found in this audit were closed in the same audit:

Severity	Gap	Fix
high	fork-PR current-branch resolution queried the head repo for reviewThreads	resolve target repo from the PR canonical URL (helper + fork tests)
medium	partially staged files had no staging rule	SKILL rule (never blindly re-git add an MM file) + preflight MM test + static assertion
medium	existing PR on branch would be blindly re-created	SKILL rule (check gh pr view, never duplicate) + static assertion
medium	push hard-coded origin	SKILL rule (tracked remote first, fail closed) + static assertion
low	fork publish lacked push-to-fork-remote guidance	SKILL rule (git push -u <fork-remote> + --head <fork>:<branch> --repo <target>, fail closed) + static assertion
low	multi-provider tool-name collisions under-specified	umbrella wording (exact full name + signature + description)
low	CLI-fallback PR body newline handling not stated	SKILL rule (temp file preserves newlines)

Remaining known differences are all intentional (matrices above). No critical or high gaps remain.

Post-conformance adversarial hardening

The conformance audit proves workflow-semantic parity; the adversarial hardening pass fixed issues that are NOT Codex-conformance gaps — they are either upstream-equivalent behavior with boundary bugs, DSH-specific helper bugs, security hardening, or release engineering. They are tracked here so they are not re-labeled as conformance regressions later:

Category	Issue	Fix
security	credential-bearing https remote URL leaked to stdout	lib/redact.mjs applied to every helper output path (URL userinfo + token shapes)
security	pasted tokens in remote content (comments, CI logs) and gh/git stderr	same redaction with stable placeholders; safety-model wording corrected
helper bug	unequal pagination re-appended finished collections	per-collection independent paginators with own cursors
helper bug	thread comments >100 silently truncated	explicit commentsTruncated + commentsPageInfo
helper bug	generic /runs/<id> misdetected as Actions	strict /actions/runs/<id> detection (github.com + GHES)
helper bug	run/job queries bound to implicit cwd repo	explicit -R <owner/repo> target context everywhere
helper semantics	mixedWorktree too narrow	objective class signals + redefined conservative flag
mock quality	fake returned pages by call count	protocol-aware fake (cursor matching, -R verification, fail loud)
release eng	no CI, npm-install README overstated	.github/workflows/ci.yml (Node 22.19/24), truthful install sections, metadata, prepublishOnly

Maintaining conformance

• Re-pin the baselines when a new audit runs; record the public commit SHA, not "main".
• Before editing a SKILL.md or helper, check the corresponding matrix row: preserve the verdict unless the change is itself a deliberate, documented divergence.
• New DSH-specific additions belong in this file's addition list, not silently in code.