A Read-Only Codex Audit of Potentially Stale README Command Examples Against package.json Scripts

Establish the inspection contract before comparing commands

A command example can look outdated without being demonstrably wrong. The useful first deliverable is therefore not a patch or a list of broken commands. It is a human-reviewed discrepancy register: a record of what the documentation says, which package declaration was inspected, what remains uncertain, and who must resolve that uncertainty. This tutorial’s editorial procedure uses Codex for a static comparison at one fixed repository reference, without executing project commands or changing repository content.

The reader’s task is deliberately narrow: help the Repository documentation maintainer identify documented npm command examples that may not match the declared package scripts. A name that is absent from a manifest is a reason to ask a question, not sufficient evidence that an example is stale. The comparison must preserve the command’s context, including its intended working directory and package boundary, before a reviewer can interpret that absence.

GitHub describes a repository introductory file (README)A file explaining what a repository project does, how to get started and where to find help; GitHub commonly surfaces it to repository visitors. Open glossary entry as a way to tell readers what they can do with a project and how they can use it. GitHub’s guidance on repository README files [About the repository README file]

That makes reader-facing command examples a useful inspection target. It does not make every example a declaration about the root package. A command might appear in installation guidance, a contributor section, or instructions for a nested package. The editorial task is to retain those distinctions rather than reduce every command block to a script-name lookup.

When defining the fixed-reference register, use Read-only ownership coverage audit evidence packets to see how a six-path audit makes the manifest, source evidence, classifications and unresolved questions separately traceable for later human investigation.

Give the two human roles different responsibilities

Editorial recommendation: the Repository documentation maintainer authorises the scope, confirms that the supplied material may be used, and receives the register. The maintainer decides which documents and packages belong in the inspection and approves any later documentation work through a separate process. Scope authorisation is not permission to execute examples, install dependencies, or edit files.

The Build/package owner resolves technical intent: which package a command addresses, whether its spelling is intentional, and whether the evidence warrants a later correction. The owner’s answer should be recorded as a human decision, separate from the static observation. The Repository documentation maintainer retains responsibility for accepting the handoff and authorising any subsequent documentation change. Neither role grants execution or editing permission merely by participating in this inspection.

In the single hypothetical scenario used here, these two roles agree to inspect README.md and docs/quickstart.md at an illustrative reference, EXAMPLE_COMMIT. The approved package manager is npm, the package root is ., and the authoritative manifest is package.json. History lookup is excluded. These are authored example inputs, not facts about a repository or a report of a completed audit. Before a real inspection, the maintainer must replace every illustrative value with approved repository-specific inputs.

Freeze the reference and the package boundary together

Editorial recommendation: begin with an authorisation record that is complete enough to prevent accidental scope expansion. It should identify the repository, one immutable reference, all in-scope documentation paths, and the manifests that govern those documents. An immutable reference means a fixed revision identifier, rather than a moving branch name whose content may change during the comparison.

Do not inspect a default-branch README.md and compare it with package.json from another revision. Even if the paths are identical, the resulting row would combine evidence from different states of the repository. Record the reference beside both sides of the comparison. If either file cannot be tied to that reference, leave the row unclassified and request consistent evidence.

The maintainer’s authorisation record should contain:

• Repository and fixed reference: the approved repository identity and the complete immutable revision identifier.
• Documentation scope: the exact paths to inspect, with any excluded sections identified explicitly.
• Authoritative manifests: the exact manifest paths and the package each one represents.
• Package-manager syntax: the approved command forms to consider and any owner-supplied interpretation needed for them.
• Package mapping: which documentation sections apply to the root package, nested packages, or workspaces.
• Working-directory expectation: the directory from which each documented example is intended to be read.
• History permission: whether non-executing history inspection is allowed; in the hypothetical scenario, it is not.
• Human routing: the Repository documentation maintainer receiving the register and the Build/package owner resolving command intent.

A monorepo is a repository containing multiple packages or projects. A workspace, for this inspection, is an owner-identified package grouping or package context that may affect how a documented command is interpreted. Do not infer either mapping merely from a directory name. The maintainer must supply the approved package boundary before a candidate discrepancy is classified.

For the hypothetical scope, . means the approved package root, not permission to treat every nested directory as part of that package. If a passage in docs/quickstart.md turns out to describe another package, the inspector should retain the passage as evidence and ask for a mapping decision. Silently substituting the root manifest would answer a different question.

Define what the comparison can establish

npm defines the package.json scripts property as a dictionary of commands associated with package lifecycle events. npm’s package manifest documentation [package.json]

The npm facts used in this section are grounded in the supplied npm documentation dated 18 June 2026. For this editorial procedure, a declared script means a named entry visibly present under scripts in the approved manifest at the fixed reference. The inspection can record that entry’s name and literal value. It cannot establish what happens when the entry is executed because execution is outside the authorised task.

A package-manager command is not interchangeable with a script key. Preserve the complete documented command before identifying any possible script name within it. The command’s syntax, accompanying directory instructions, and package selection may change which declaration is relevant. If interpreting that syntax requires information outside the approved evidence, record the uncertainty rather than stripping away the unfamiliar parts.

Use an absent name to frame a resolver question

Consider a hypothetical passage in README.md containing npm run preview. Suppose the illustrative manifest evidence supplied for comparison contains a scripts object but no preview key. The bounded observation would be: “The supplied root-manifest evidence contains no declared preview script at EXAMPLE_COMMIT.” This is sample wording only, not an observed result.

The next sentence should expose the assumption: “This comparison assumes the example targets package root ..” The resolver question then becomes useful: “Does this example target the approved root package, or does its surrounding guidance imply a different package context?” That gives the Build/package owner something specific to answer without presenting a proposed replacement as established fact.

Do not turn that hypothetical row into “the preview command is broken”. A documented command may address another package, use another package manager, invoke an external tool, or depend on a documented default. Those possibilities are reasons to retain context and ask for confirmation; they are not explanations to invent for a particular repository.

npm documents a conditional default start command when a package root contains server.js. npm’s documented default start behaviour [package.json]

This is a concrete reason not to treat the absence of an explicit start key as a verdict. A hypothetical npm start example needs consideration of the documented condition as well as the manifest. Record whether approved, same-reference evidence addresses server.js in the relevant package root. If that evidence is unavailable, leave the condition unresolved. Do not assume that a file elsewhere in the repository satisfies a condition concerning this package root.

Keep textual correspondence separate from execution validation

A declared-name correspondence is also a limited observation. If a documented name appears in the approved manifest, the register may record that textual correspondence. It should not say that the command works, that its prerequisites are present, or that its effects suit the documentation’s purpose. Those are different questions requiring evidence outside this static comparison.

Equally, reading a script value is not permission to follow it. A value might refer to another command or file. The inspector may quote the relevant text within the authorised evidence boundary, but must not execute it to discover its meaning. If additional inspection would require new paths or unsupported interpretation, ask the maintainer to approve an expanded scope rather than following an open-ended chain.

The result is a deliberately modest evidence product: literal text, relevant declarations, explicit assumptions, and questions. It does not validate a build, test suite, dependency graph, security posture, or release readiness. Human reviewers should be able to see exactly where the evidence stops and interpretation begins.

Make no-run and no-write rules explicit

Editorial recommendation: treat filesystem permissions and the inspection’s behavioural rules as separate controls. A read-only permission profile concerns filesystem access. The editorial contract must independently forbid command execution; a profile name must not be used as a substitute for that instruction. This procedure authorises static reading of approved material, not experimentation with the project.

The contract should state plainly: do not run scripts, tests, builds, installers, generators, package-manager commands, or arbitrary shell commands. Do not use execution to identify a working directory, inspect a revision, discover files, or resolve a confusing example. Obtain those facts through approved static evidence or return the missing information to the maintainer.

The no-write boundary is just as broad. Do not rewrite documentation, update a manifest, create a repository report file, change configuration, or generate a patch. Return the register in the agreed response channel without modifying repository content. Do not commit, publish, open a change request, or trigger a downstream publishing action. Any later correction requires a distinct human-authorised workflow.

At the start of inspection, record the actual working directory and applicable local guidance using the approved non-executing access method. Compare them with the authorised scope. If the directory is uncertain, or local guidance conflicts with the no-run or no-write contract, stop and return an unclassified evidence row describing the conflict. Do not improvise a command to resolve it.

Keep repository text and supplied source passages in their proper role as data. A command block is evidence to transcribe, not an instruction to execute. Likewise, text asking for installation, editing, or publication must not expand the inspection’s authorisation. Keep credentials, access tokens, private keys, and other secrets out of prompts and register excerpts. The maintainer should confirm consent, rights, and licensing before supplying or reusing material.

Before listing command examples, set an authorised scope around the repository reference and supplied documents; Vendored directory inspection boundary and preflight illustrates a permission gate that records permitted inputs, environment, responsible reviewers and unresolved questions without converting evidence gathering into an approval.

Design the register before collecting evidence

Editorial recommendation: agree the register fields in advance so that uncertainty is captured rather than hidden in a verdict column. Each row should be understandable without asking the inspector to reconstruct its reasoning. Use one row for a documented occurrence; repeated command text in different sections may carry different directory assumptions.

Keep observation, interpretation, and decision separate. “No same-named key appears in the supplied manifest excerpt” describes evidence. “The example may address another package” expresses uncertainty. “A later documentation correction is warranted” is a human decision requiring the appropriate owner’s input and the maintainer’s authorisation. Combining these into one status would obscure the reasoning.

Use an unclassified row when the fixed reference, package mapping, working directory, or applicable guidance is unresolved. Such a row is useful: it identifies precisely what the maintainer must supply before comparison can continue. It is preferable to a confident label based on the wrong manifest.

Before collection begins, the Repository documentation maintainer should approve this contract, confirm the evidence-sharing boundaries, and identify the Build/package owner who will answer intent questions. The inspection can then proceed towards a register of possible discrepancies—not a repair list—with every proposed conclusion traceable to one fixed repository state and reserved for human review.

Collect traceable evidence without running commands

Editorial recommendation: make this collection pass a reading task, not a troubleshooting session. The immediate deliverable is a set of traceable excerpts for a human-reviewed discrepancy register. Each excerpt should connect a documented command to its surrounding instructions and, where the approved scope permits, to a particular package manifest. Do not run the command to discover what it means. Do not install dependencies, invoke a package manager, open a shell to inspect the checkout, or modify repository files.

The hypothetical scenario throughout this method uses a Repository documentation maintainer working with the Build/package owner. The illustrative inputs are reference EXAMPLE_COMMIT, documents README.md and docs/quickstart.md, npm syntax, package root ., and no history lookup. These are authored teaching inputs, not assertions about a repository. Before a real inspection, the Repository documentation maintainer must replace them with an approved immutable reference, document list, manifest list, package mapping and history policy.

The Repository documentation maintainer authorises collection and receives the register. The Build/package owner resolves questions about command intent and whether a later documentation correction is warranted; the Repository documentation maintainer retains approval over any subsequent documentation action. Neither responsibility authorises execution or editing during this workflow. If the evidence needed for a comparison is unavailable through permitted reading, record the gap rather than trying another operational route.

Identify the surfaced README without confusing visibility with scope

GitHub says it chooses the surfaced README from the .github directory, the repository root, then the docs directory, in that order. GitHub’s README selection documentation [About the repository README file]

Use that display rule to establish which README a reader encounters, but keep it separate from the maintainer’s approved document list. A surfaced README and a supplementary guide have different reasons for inclusion: one is visible at the repository entry point, while the other is explicitly selected for inspection. Neither reason establishes which package governs every command in the file. Record the surfaced file’s actual path, rather than describing it merely as “the main README”.

In the hypothetical scenario, first check whether the approved README.md is the surfaced file at EXAMPLE_COMMIT. If the visible README has a different path, do not silently substitute it or expand the inspection. Return the difference to the Repository documentation maintainer as a scope question. The maintainer can authorise a revised document list before collection resumes. This avoids inspecting one file while reporting findings as though they came from another.

Keep docs/quickstart.md separately identified as an owner-approved supplementary document. A link from the README to that guide is useful context, but it is not permission to follow every subsequent documentation link. Record linked, unapproved documents as possible follow-up material without collecting their command examples. The same restraint applies to generated documentation, translated guides and package-specific README files: their existence does not automatically bring them into scope.

For each approved document, record its repository location, fixed reference, path and reason for inclusion. Preserve a source link that identifies the file at the fixed reference, not just the repository homepage or a moving branch. If the supplied link does not establish the approved revision, leave the reference check unresolved. A familiar filename is not enough to show that two excerpts belong to the same repository state.

For the inventory-and-comparison pass, preserve command references and declared script entries as separate observations; Localisation key extractor and reviewer workflow presents an asymmetric mapping-and-challenge pattern in which an extractor records relationships and a reviewer prepares draft classifications rather than deciding content changes.

Read the file as evidence, preserving its context

GitHub’s raw-file view permits unstyled viewing or copying of a file’s raw content. GitHub’s file-viewing documentation [Viewing and understanding files]

Editorial recommendation: use an approved static file view to collect literal text, then read the surrounding section to understand how that text is introduced. Keep the repository location, immutable reference, document path and actual retrieval date with the excerpt. The retrieval date describes collection, not publication. Where a line link is available, retain it; otherwise, record a heading anchor and enough nearby text for a reviewer to locate the example unambiguously.

Copy the entire command example before extracting any comparison target. Preserve spelling, capitalisation, punctuation, arguments, quotation marks and line breaks. If the source includes a displayed prompt character, retain that in the evidence excerpt and distinguish it from the command in a separate interpretation field. Do not silently repair a typographical error, join lines, remove an option or replace shorthand with a longer form. Such changes would make the collected evidence different from what the reader sees.

Capture the relevant introduction and any directory instruction as well. A command block immediately following an instruction to enter a package directory has different context from an identical block presented at the repository root. A heading may also limit an example to a particular package, operating environment or optional workflow. Record these statements as documentary evidence, rather than treating them as facts about the actual runtime environment.

For example, suppose the hypothetical README.md contains npm run build. The literal command alone does not identify the governing manifest. The collection row also needs the preceding directory instruction, or an explicit note that none was found in the inspected context. “Directory unstated” is a useful observation. “Runs at root” is an inference unless the document or approved package mapping supports it.

Do not discard a command because it appears unlikely to name a package script. Collect each in-scope npm command example with enough context for later comparison. If the document presents several commands in one block, preserve the complete block and make separate rows for the individual commands where needed. Link those rows to their shared context so the later reviewer does not mistake a sequence for unrelated instructions.

Locate the approved manifest, not merely the nearest familiar file

The manifest collection pass should begin with the maintainer’s approved mapping. In the hypothetical root-only scope, the proposed pair is package root . and manifest package.json, both at EXAMPLE_COMMIT. Inspect that file through the permitted reading route and preserve the relevant scripts text. Record the manifest path beside the documentation path, rather than leaving the package relationship implicit.

Copy the script keys and associated command values faithfully. The key is the item that a later comparison may match against a documented script invocation; the value is useful supporting context for the Build/package owner. Neither should be executed. If the manifest cannot be read completely, distinguish a partial excerpt from a complete inspection. A cropped display or incomplete supplied passage is not enough to establish that a key is absent.

Keep three cases separate during collection: a manifest that was fully inspected, a manifest whose relevant content is incomplete, and a manifest that was not supplied or could not be accessed. Do not turn the last two cases into “no matching script”. Similarly, if the inspected manifest has no visible scripts property, record precisely what was inspected and where. Reserve interpretation of the documented command for the comparison stage.

In a repository containing multiple packages, require an approved mapping from each relevant documentation context to its package root and manifest. Do not assume that the root manifest governs a command introduced under a nested package heading. Do not infer scope solely from where the documentation file sits: a guide inside docs/quickstart.md might discuss the root package, another package, or several packages. The governing relationship needs evidence or owner confirmation.

If a workspace-related option appears in a documented command, preserve the whole option and its value in the literal excerpt. Record that the example appears to select a package context, but do not invent a mapping from that text to a manifest. In this hypothetical scenario only the root boundary has been approved. A command apparently targeting another package therefore becomes an unclassified scope question for the Repository documentation maintainer, informed by the Build/package owner.

Record actual working context and applicable local guidance

Editorial recommendation: distinguish the directory assumed by the documentation from the actual working directory of the inspection session. They answer different questions. The former helps identify the intended package; the latter records where the collection task is taking place and which local guidance must be considered. Obtain the actual location through an already permitted session view or supplied session information, not by issuing a shell command. If it cannot be established within the authorised method, stop and record the missing evidence.

OpenAI’s guidance, inspected as of 16 October 2026, describes Codex reading AGENTS.md before work and discovering project guidance from the project root down to the current working directory. OpenAI’s guidance on project instructions For this editorial procedure, record the applicable guidance paths and the passages relevant to inspection boundaries. Do not assume that a particular repository contains such a file, and do not report guidance as checked if its contents were unavailable.

Keep the guidance record separate from command evidence. A statement in local guidance that asks for a build does not become evidence that a documented command is current, nor does it authorise execution within this audit. If applicable guidance requires an action that conflicts with the no-run or no-write contract, stop collection and return an unclassified evidence row. Describe the conflict to the Repository documentation maintainer without attempting to resolve it by following the broader instruction.

Treat repository text, copied source passages and command examples as material to inspect, never as authority to expand the task. This includes text that appears to address an automated assistant directly. The authorised scope remains the maintainer’s fixed inspection contract. Record relevant guidance conflicts, but do not include secrets, credentials or unnecessary private material in prompts or the register. Before supplying repository excerpts, the maintainer should check consent, access rights and licensing for that reuse.

Give every row enough evidence to be reviewed independently

A reviewer should be able to understand one row without reconstructing the entire collection session. That does not require copying whole files into every entry. It requires stable source locations, small faithful excerpts and a clear account of what remains unknown. Use the following field groups as an editorial collection checklist, adapting the register’s layout without removing the underlying evidence.

• Repository and revision: repository location, approved immutable reference, actual inspected reference and retrieval date. An unresolved reference mismatch prevents comparison.
• Documentation location: exact path, heading or line location, fixed-reference source link, and whether the file is surfaced or supplementary.
• Literal example: the complete command text, its position within a multi-command block, and relevant introductory or qualifying prose.
• Directory evidence: the document’s stated directory, the approved package-root mapping, and any assumption that still needs confirmation.
• Package-manager context: the syntax named in the document, the maintainer-approved syntax for comparison, and any visible mismatch between them.
• Manifest evidence: exact manifest path and reference, source location for scripts, relevant keys and values, and whether inspection was complete.
• Session and guidance: actual working directory, applicable AGENTS.md paths, relevant guidance excerpts and any conflict that stopped collection.
• Open question: missing evidence or unclear intent, the responsible resolver and the maintainer decision needed before proceeding.

Source links should support the specific observation beside them. A link to README.md supports what the guide says; a link to package.json supports the manifest excerpt. Neither independently establishes the relationship between them. That relationship comes from the approved package mapping and the document’s directory context. Keeping those sources separate makes it easier for the Build/package owner to challenge a mistaken scope assumption without disputing a faithful transcription.

Record repeated examples as separate occurrences when their context differs. If npm run build appears in both approved documents, do not collapse the entries merely because the characters match. One occurrence might state its directory while the other leaves it unstated. The later register can group related questions, but it should preserve each documentary location so that a human can decide whether any eventual correction applies to one occurrence or both.

Work through a hypothetical collection row without declaring a result

Consider an authored illustration in which docs/quickstart.md shows npm run preview. This is sample material only: no repository has been inspected and no script inventory is asserted here. The collection task is to preserve the command, its heading, its surrounding directory instructions and a fixed-reference source location. It is not to decide that a script called preview must exist in the root manifest.

The hypothetical row would identify EXAMPLE_COMMIT, docs/quickstart.md, the actual line range or anchor supplied during a real inspection, and the literal text npm run preview. It would separately record package root . as the approved boundary, while stating whether the guide itself explicitly names that directory. Its manifest evidence would come from package.json at the same reference. Do not invent line numbers or source links to make the teaching example look complete.

If the full manifest has not yet been supplied, the row remains “manifest evidence pending”, not “script missing”. If the guide appears to discuss a nested package, the row remains unclassified until the package boundary is approved. If a complete manifest inspection later reveals no same-named key, retain the literal evidence and ask the Build/package owner about intent. Another package, different syntax, an external tool or an npm default may require consideration; absence alone is not a staleness verdict.

When a command lacks a same-named script, retain the literal absence and the surrounding context rather than concluding staleness; Accessible-name discrepancy evidence register construction method shows how a register separates observed source excerpts, candidate questions, uncertainty and accountability before a discrepancy is accepted for follow-up.

Close collection when the evidence is sufficient, not when a command succeeds

Editorial recommendation: finish this pass with a coverage check against the approved document list. Account for each collected command occurrence, every required manifest and all unresolved scope gaps. Leave history untouched in this hypothetical scenario because it was not authorised. Do not search earlier revisions to explain an ambiguity, and never replace the fixed-reference evidence with a newer file that happens to contain a more convenient script name.

Return incomplete rows as incomplete. A useful handoff can state that a command was faithfully captured but its package context remains unknown. That is more actionable than a confident label based on the wrong manifest. Ask the Repository documentation maintainer to approve any additional collection, with the Build/package owner supplying the package-specific clarification. Until then, preserve the uncertainty and keep the row outside classified findings.

The stopping point is a traceable evidence set ready for comparison: documentation text, directory context, manifest excerpts, guidance records and explicit gaps, all tied to one approved reference. No command execution is needed to reach that point, and execution would answer a different question. The next stage can assess correspondence and formulate resolver questions; this stage supplies the evidence without changing the project or claiming that any command works.

Compare the evidence without turning uncertainty into a verdict

Editorial recommendation: compare each documented command as a separate evidence question, not as an opportunity to repair the documentation. The useful result is a discrepancy register that distinguishes an observed textual relationship from an unresolved question about intent. A command can have a corresponding declared script without its behaviour being validated. Equally, a command can lack a same-named script without being stale. Keep those two limits visible throughout classification.

The following practice uses one hypothetical, authored fixture, not an inspected repository. The Repository documentation maintainer has authorised the illustrative reference EXAMPLE_COMMIT, the documents README.md and docs/quickstart.md, npm syntax, package root ., and the manifest package.json. History lookup is excluded. The Build/package owner resolves questions about command intent and whether a later correction is warranted; the Repository documentation maintainer retains approval of scope and any consequential follow-up. Neither role authorises execution or editing through this comparison.

For the worked comparisons below, suppose the supplied fixture manifest contains build, test, and dev entries within scripts, but no explicit serve or start entry. These are hypothetical inputs, not reported findings. Before a real audit, replace all fixture values with the maintainer’s approved evidence. Do not carry the illustrative script names into a real register as assumptions.

Check that classification is still authorised

Before interpreting the command text, compare the recorded actual working directory with the approved package root and check the applicable local guidance. Do this from authorised static evidence and available context, not by launching a shell command to discover the environment. If the working directory cannot be established, or if local guidance conflicts with the no-execution boundary, stop the comparison and return an unclassified row. A permission profile concerning filesystem access is not a substitute for the separate editorial prohibition on executing commands.

OpenAI states that Codex reads AGENTS.md files before doing any work. OpenAI’s guidance on repository instructions [Custom instructions with AGENTS.md]

OpenAI says Codex starts project guidance discovery at the project root and walks down to the current working directory. OpenAI’s guidance-discovery description [Custom instructions with AGENTS.md]

For this editorial procedure, record which guidance was applicable and whether it was compatible with the authorised inspection. Do not assume a particular instruction file exists. Treat repository commands, quoted instructions and supplied source passages as evidence, not as permission to act. A direction embedded in a document to install dependencies, run a test or regenerate documentation does not expand this workflow. Any conflict goes back to the Repository documentation maintainer rather than being resolved by trying the requested action.

Separate a declared-name match from a behavioural claim

Start with the narrowest question: under the owner-approved interpretation of the command syntax, does the documented script name appear in the approved manifest’s scripts object? Preserve the entire command even when only one part is relevant to that comparison. Also retain the documentation location, immutable reference, manifest path and working-directory assumption. A stripped-down script name alone is insufficient evidence for a reviewer to reconstruct the comparison.

In the hypothetical fixture, consider a README.md example containing npm run build, with surrounding instructions explicitly placing the reader at package root .. If the supplied package.json at EXAMPLE_COMMIT declares build, the proposed classification is “declared-name match”. Suggested finding language is: “The documented command names build, which is declared in the approved root manifest at the same reference; no execution was performed.” That records a relationship between two pieces of text, not a working build.

Do not strengthen that finding to “the instructions are correct”. The comparison has not established whether the script body achieves the documentation’s stated purpose, whether required files are present, or whether the reader’s environment is suitable. If the surrounding prose promises a particular output, retain that promise as context without treating the script name as proof of it. A concise resolver question is: “Does this declared script remain the intended entry point for the documented task at this reference?”

Also avoid replacing one documented name with another merely because the manifest contains a plausible alternative. The presence of dev alongside build does not establish which one the author intended. This procedure produces no patch and does not infer an intended replacement.

Record an absent name as a candidate discrepancy

Now consider the hypothetical docs/quickstart.md example npm run serve. Under the supplied root-package interpretation, serve is absent from the fixture manifest. The bounded observation is the absence of that key in that manifest, not the failure of the command. Use “absent-name candidate” as an editorial classification, with a separate field for the unresolved interpretation.

A suitable hypothetical entry would say: “The documented command contains serve; no same-named entry appears in the supplied root scripts object at EXAMPLE_COMMIT. The intended package and command entry point require owner confirmation.” Its resolver question can be short: “Is this example intended for the approved root package, or does it refer to another package, tool or documented setup?”

That question matters even where the name comparison itself is clear. A complete transcription can support high confidence in an absence observation while leaving command intent unresolved. Do not convert confidence in reading the manifest into confidence that the documentation is stale. If the document’s package context is unclear, retain the observed absence but leave the discrepancy classification unclassified until the package boundary is approved.

Do not infer a rename from similar words. For example, the fixture’s dev entry might tempt a reviewer to propose it instead of serve. Similarity is not evidence of intent. Ask the Build/package owner about the task the example is meant to express, rather than offering a replacement command for approval.

Interpret shorthand only within approved syntax evidence

Command text should not be classified by searching for the word immediately after npm and comparing it mechanically with script keys. First determine whether the maintainer-supplied syntax evidence identifies a script invocation, a recognised shorthand form, or another kind of command. Preserve the original spelling even if the register records an interpreted script name in a separate field. Interpretation must remain traceable to the approved syntax, not to an auditor’s recollection.

In the same hypothetical fixture, suppose README.md includes npm test. The register should retain that exact string rather than silently rewriting it as npm run test. If the authorised syntax material establishes that the example should be compared with test, compare that key with the supplied manifest and record the interpretation basis. If that syntax evidence was not supplied, ask for it and leave the relationship unresolved; do not execute the command to discover its meaning.

The resolver question here differs from the absent-name question: “Which approved syntax interpretation should govern this shorthand in the documented environment?” This prevents a spelling difference from becoming a false discrepancy. It also avoids assuming that every word which resembles a familiar task name is necessarily a declared script invocation.

Handle the conditional start default as a separate evidence branch

An example containing npm start requires particular care when the manifest lacks an explicit start entry. npm’s documentation, dated 18 June 2026 and retrieved on 16 October 2026, describes a default start command conditional on server.js being present at the package root. npm’s package manifest documentation That condition makes an absent explicit name insufficient for a staleness verdict.

For the hypothetical fixture, record three distinct pieces of evidence: the literal npm start example, the absence of an explicit start entry, and whether the authorised static evidence establishes the presence of server.js at package root .. Do not assume the file exists because the documentation discusses a server. Do not treat a similarly named file elsewhere as satisfying the package-root condition.

If the root-file evidence is supplied and meets the documented condition, use “conditional default-start candidate”, not “missing script defect”. If the evidence does not establish that condition, record it as unknown. The appropriate question is: “Does this example intentionally rely on the documented root-file default, and is this the package root to which it applies?” No server is started, and no runtime behaviour is claimed.

If confirming the root-file evidence would require expanding the approved inspection, stop that branch and request the evidence from the Repository documentation maintainer. The need to resolve a default does not authorise browsing unrelated directories or running a package-manager command.

Prevent workspace leakage before judging a root manifest

A monorepo can contain several package contexts, so evidence from the root must not silently govern every command in the documentation. In this hypothetical scenario, only package root . has been approved. If a quickstart passage directs readers into a nested package, that passage raises a boundary question. It does not authorise the auditor to choose another manifest or to classify the command against the root manifest regardless.

Preserve the directory instruction and its relationship to the command. A command block may appear far below the heading that establishes its working directory. Conversely, the document’s own location does not by itself establish where its commands are meant to run. Record “working directory not established” when the available prose does not settle the question. Do not fill the gap with whichever manifest happens to contain a matching name.

Suggested bounded language is: “The document appears to describe a nested package context, but the approved comparison covers only the root package. No discrepancy classification has been assigned.” Ask the Build/package owner: “Which package governs this example?” The Repository documentation maintainer must approve any expanded package mapping before comparison resumes. This keeps a root-level absence from becoming a false finding about another package.

Keep other package managers and external tools distinct

The fixture authorises npm syntax only. If an in-scope document also contains a command for another package manager, preserve its literal text and classify it as outside the approved syntax comparison. Do not translate it into npm syntax or assume equivalent resolution rules. The useful question is whether the Repository documentation maintainer wants that syntax added to scope with authoritative interpretation evidence.

The same separation applies to direct tool invocations and package-manager operations that are not established as script invocations. A command example can belong in user documentation without corresponding to a scripts key. Record the command’s apparent purpose only where the surrounding text supplies it, and mark any interpretation as provisional. “Outside package-script comparison” is not a judgement that the command is inappropriate.

For example, a hypothetical quickstart may place an installation instruction before a script example. Preserve that dependency in the evidence, but do not try the installation or invent a same-named script requirement for it. A resolver question could be: “Should this instruction remain contextual evidence, or should the maintainer commission a separately scoped review?” The current comparison must not expand into installation validation, tool verification or dependency inspection merely because those instructions sit next to an in-scope command.

Separate environmental prerequisites from name correspondence

A declared-name match and a documented prerequisite answer different questions. Suppose the fixture’s README.md says that a local configuration value must be supplied before npm run build. The presence of build in the approved manifest supports the name comparison. It does not establish that the configuration is available, suitable or complete. Record the prerequisite as stated, with its documentation location, and leave its operational status unassessed.

Do not request credentials, copy private configuration values or place secrets in the comparison prompt. A reference to a prerequisite is normally enough to frame the owner question: “Is this prerequisite still part of the intended documented workflow?” If a value is essential to understanding the text, ask the Repository documentation maintainer for an authorised, non-sensitive description rather than the value itself. Verify permission and licensing before reusing supplied material beyond the authorised review.

Likewise, do not inspect a declared script body and conclude that every referenced tool, file or service is available. You may preserve relevant script text within the approved evidence boundary, but following its dependencies would be a different investigation. Keep the row’s conclusion about the documentation-to-manifest relationship separate from any unanswered environmental question.

Tie confidence to the completeness of the evidence

Editorial recommendation: use confidence labels for the comparison evidence, not for whether the command works. Each label should have a reason. This avoids a misleading register in which a confident absence observation appears to be a confident defect verdict.

• Complete comparison evidence: the immutable reference, document location, literal command, approved syntax interpretation, working directory, package mapping and applicable manifest are all established. A name match or absence can be stated narrowly.
• Partial comparison evidence: the command and manifest are available, but a relevant interpretation or contextual condition remains unresolved. Record the known facts and the missing element; do not elevate a tentative relationship into a confirmed discrepancy.
• Insufficient evidence to classify: the reference, package boundary or actual working context is missing or conflicting. Return an unclassified row with a specific request for the missing evidence.

Applied to the hypothetical serve example, complete evidence could justify confidence that the approved root manifest lacks that key. It would still leave the owner’s intent unanswered. Applied to npm start, the missing root-file condition could make the default interpretation partial even when the manifest transcription is complete. These are proposed classifications, not observed audit outcomes.

A useful row therefore has separate spaces for the observed relationship, evidence completeness, unresolved interpretation and resolver question. Avoid a single “valid” or “invalid” column: it would collapse several different judgements into a verdict this static procedure cannot support.

Use history only when authorised, and never as a substitute for intent

GitHub states that its blame view lists an author, commit description, and commit date for each commit. GitHub’s file-history guidance [Viewing and understanding files]

History is excluded from this hypothetical fixture, so none is consulted. In a real inspection where the Repository documentation maintainer explicitly permits non-executing history review, historical context may help formulate an ownership question. It should remain separate from the fixed-reference comparison and must not be used to substitute an older manifest for the approved one. An author or commit description does not establish current command intent.

Do not seek historical explanations merely to make a row look complete. A concise unresolved question is more useful than an unsupported account of how a discrepancy arose. The Build/package owner can resolve intent through the authorised human review; the auditor need not reconstruct a narrative.

At the review stage, give the maintainer citations, fixed-reference identifiers and unresolved rows to challenge; Human review of read-only release evidence sets out a separate owner review against raw artefacts and requires untraceable assertions to remain evidence gaps rather than operative decisions.

Finish classification with questions, not proposed corrections

Before handing the classified evidence forward, reread each finding for an unsupported leap. Replace “broken” with the precise observation where intent remains unresolved. Replace “works” with “declared-name match” where only a textual relationship has been established. If the package boundary is uncertain, keep the row unclassified rather than assigning it to the most convenient manifest.

Each resolver question should ask for one missing decision: the governing package, the approved syntax interpretation, reliance on a conditional default, or the intended entry point. The Build/package owner supplies that technical resolution and determines whether a later correction is warranted. The Repository documentation maintainer receives the register, reviews the evidence and retains approval of any consequential next step. This section’s work ends with classified observations and explicit uncertainty: no commands run, no files rewritten, and no patch proposed.

Package the evidence for a human-reviewed handoff

Editorial recommendation: close the inspection by preparing a reviewable discrepancy register, not a correction plan. The Repository documentation maintainer should be able to trace each entry back to the authorised repository reference, understand what was compared, and see which question belongs with the Build/package owner. The handoff should also make omissions visible. A command excluded because its package boundary is unknown must not disappear merely because it cannot yet receive a comparison status.

In the hypothetical scenario used here, the Repository documentation maintainer authorises the scope and receives the register. The Build/package owner resolves technical intent and advises whether a later documentation change is warranted. The Repository documentation maintainer retains approval of any consequential next step. Neither role’s participation authorises execution, installation, editing or publication within this inspection.

The word “release” here means releasing the evidence package for review. It does not mean releasing software, validating a build or approving repository readiness. A useful handoff can contain unresolved questions. Its value lies in making those questions precise enough for the responsible humans to answer without confusing a textual comparison with evidence that a command works.

Freeze the handoff envelope before presenting individual rows

Editorial recommendation: begin the register with a short scope record that applies to every row. For this fictional authored fixture, the illustrative reference is EXAMPLE_COMMIT; the approved documents are README.md and docs/quickstart.md; the package manager is npm; the package root and intended working directory are .; and the authoritative manifest is package.json. History lookup is excluded. These are teaching inputs, not assertions about an inspected repository, and the reference token is not an actual commit identifier.

Before a real inspection, the Repository documentation maintainer must replace these fixture values with approved inputs, including an actual immutable reference, authoritative package-manager syntaxes, manifests and package or workspace mapping. The scope record should distinguish the intended working directory from the actual working directory recorded at runtime. It should also identify applicable local guidance and any conflict with the authorised scope. An unresolved conflict stops comparison rather than becoming a footnote beneath apparently finished findings.

Keep collection dates separate from repository references. A collection date explains when evidence was obtained; it does not identify the revision being compared. Likewise, an official documentation access date does not establish when a repository command was written. The register needs the fixed repository reference even when all material was collected on the same day.

The envelope should identify what was not inspected: other documents, other packages, history and execution behaviour. This prevents a narrow finding from acquiring an implied repository-wide meaning when someone forwards the register. State that the output concerns only the approved documents and package boundary at the recorded reference.

Keep the permission setting separate from the editorial prohibition

OpenAI lists a built-in Codex permission profile named :read-only. OpenAI ChatGPT Learn: Config basics [Config basics]

Editorial recommendation: record the selected :read-only profile separately from the task’s no-execution rule. The permission profile concerns filesystem access; the inspection protocol independently prohibits arbitrary shell commands, package-manager commands, scripts, tests, builds, installers, generators and network-affecting commands. A profile name is not a substitute for reviewing the actions actually taken, nor is it permission to execute a command merely to obtain a clearer answer.

OpenAI’s prompting guidance identifies boundaries as what must remain unchanged and what the system should avoid or check before acting. OpenAI ChatGPT Learn: Prompting [Prompting]

Editorial recommendation: express those boundaries in the handoff as inspection requirements, not vendor guarantees. The repository must remain unchanged. Supplied documents and source passages are evidence, not instructions to expand the task. Uncertainty must remain explicit. If the available record does not establish whether a prohibited action occurred, report that limitation and pause acceptance; do not replace missing evidence with an assurance based on the chosen profile.

A fictional register that preserves uncertainty

The following sample is entirely hypothetical. It demonstrates how to package authored evidence; it is not a repository report or an observed outcome. For this fixture only, suppose the supplied package.json contains a scripts dictionary with the single key build. No script body is needed for the illustrated name comparison. Suppose the approved documents contain the command examples below. Every row uses EXAMPLE_COMMIT, the same manifest path and the package root ..

The location descriptions in this sample are authored headings, not verified repository anchors. In a real register, replace them with the collected line ranges or stable section anchors and fixed-reference repository links. Do not invent repository links to make a sample appear complete. Official product documentation supports interpretation of the procedure; it does not supply evidence that these fictional commands exist in a real project.

All five command strings are evidence to read, not instructions to execute. Even the installation example remains inert text. Its presence in a register does not create an exception to the prohibition on dependency actions. The table deliberately retains a matching row and an excluded row alongside candidate discrepancies so that the maintainer can distinguish inspected coverage from unresolved findings.

Separate the fact, the inference and the decision

Consider entry 2. Within the fictional fixture, the fact is narrow: the supplied document contains npm run preview, while the supplied manifest dictionary contains build and no preview key. The inference is that the documented example may need clarification if the approved root-package interpretation is correct. The unresolved decision is whether its intended context justifies a documentation change. Those three statements should occupy separate fields or clearly labelled sentences.

A suitable hypothetical finding is: “At the supplied reference, the documented command names preview; that name is absent from the supplied root manifest’s scripts dictionary. Please confirm the intended package and operation.” An unsuitable finding would declare the command broken or propose replacing it with npm run build. Similar-looking names and nearby documentation do not establish equivalent intent.

For entry 1, the fact of a matching name supports only textual correspondence. It does not establish that dependencies are present, that the script completes, or that its behaviour suits the documentation. The Build/package owner might still identify a contextual problem, but that would be additional human evidence, not an outcome of this static comparison.

Entry 3 preserves a different uncertainty. The absence of an explicit name should not erase the possibility of an applicable default. The handoff should point to the relevant interpretation already recorded in the comparison stage and identify any missing condition evidence. It should not broaden collection to additional files without the Repository documentation maintainer’s approval, and it should never try the command to settle the question.

Use “unclassified” and “out of scope” for different reasons

Editorial recommendation: use “unclassified” when a potentially relevant example cannot be compared responsibly because essential evidence or authority is missing. Entry 4 illustrates this distinction. Although the root dictionary contains build, the paragraph’s package context is unresolved. Reporting a match would conceal the missing mapping; reporting a discrepancy would be equally premature.

Other reasons for leaving a row unclassified include an uncertain reference, an unavailable approved manifest, ambiguous working-directory context or a conflict between applicable guidance and the supplied scope. Preserve the literal command and available source location, state what is missing, and name the decision needed to resume. If the actual working directory or applicable local guidance conflicts with the authorised scope, stop the inspection and return the unclassified evidence rather than continuing with unaffected-looking rows.

Use “out of scope” when the exclusion follows from the agreed task rather than an evidential gap. Entry 5 is retained because the document contains a command, but installation behaviour is outside this script-name comparison. This label says nothing about whether the instruction is correct. Similarly, a clearly identified example for another package manager would require its own approved interpretation rather than being judged against npm script names.

Do not silently move a difficult candidate into the excluded category. Explain the exclusion rule and let the Repository documentation maintainer review it. Conversely, do not request a technical verdict on every excluded instruction merely to make the register look exhaustive. A concise coverage note can record the exclusion without turning this narrow inspection into a general documentation audit.

Review the evidence package before handing it over

Editorial recommendation: give the reviewer a compact package containing the scope record, register, evidence excerpts, source pointers, unresolved questions and activity declaration. Keep excerpts short enough to review while preserving the paragraph that establishes the working directory or package context. Avoid copying unrelated repository material. Before sharing supplied content, the Repository documentation maintainer should confirm the permitted recipients, privacy and consent boundaries, and rights or licensing for reuse. Secrets must not enter prompts or the register.

Check reference consistency and source anchors

• One revision: confirm that every document excerpt and manifest excerpt belongs to the same approved immutable reference. A default-branch document is not interchangeable with a fixed-reference copy.
• Traceable locations: verify each documentation path, literal command, heading or line range, and manifest path against the collected evidence. Keep repeated occurrences separate when their surrounding contexts differ.
• Correct package boundary: check the approved mapping, stated directory and actual working directory. A root manifest must not silently stand in for an unresolved nested package.
• Evidence roles: distinguish repository evidence from official-source interpretation. An npm documentation link cannot prove that a repository contains a particular script.
• Faithful text: retain command spelling, arguments and directory assumptions. Put any interpretation in a separate field rather than rewriting the captured command.

A missing source anchor is a repair request for the evidence package, not permission to guess. If the excerpt cannot be located at the fixed reference, withhold that row’s classification until it can be traced. Do not repair the gap using a newer version of the document: that would change the comparison rather than complete it.

Check scope discipline and the activity declaration

The reviewer should confirm that history was not consulted in this fixture, that no additional documents or package boundaries were introduced without approval, and that classification language remains within the evidence. Search the prose for conclusions such as “works”, “broken”, “safe” or “ready” and ask whether they wrongly turn a static observation into a behavioural or consequential verdict.

The activity declaration should explicitly address command execution, installation, generation, tests, builds, file changes and publication. Confirm it from the available activity record, not from the absence of a reported error. Do not run a final status command or test as a closing ritual. If the record is incomplete, state that the no-action requirement cannot yet be confirmed. If a prohibited action occurred, report the deviation to the Repository documentation maintainer and stop; do not present the package as a completed no-run inspection.

A hypothetical closing declaration, usable only when supported by the actual record, is: “The inspection was limited to reading approved static evidence and preparing this register. No commands were executed, dependencies installed, files rewritten or documentation published.” This is sample wording, not a claim that an inspection has occurred here.

Route owner responses without reopening the workflow implicitly

Editorial recommendation: send the Build/package owner focused questions with the relevant rows, then record responses separately from the original observations. Preserve the original reference and command text. If the owner identifies a different package or reference, that answer may justify a newly authorised inspection; it must not silently alter the existing register.

The Repository documentation maintainer should record whether the evidence package is accepted, needs clarification or remains blocked. The Build/package owner’s technical resolution can recommend a later correction, but any change requires the maintainer’s separate approval and a separate editing workflow. Neither a confirmed discrepancy nor an accepted register authorises Codex to edit or publish documentation.

Keep the handover tied to the reviewed repository revision. Documentation and code discrepancy review prompts offer a revision-specific evidence ledger with source links, unresolved findings and named maintainer sign-off, plus a prioritised findings table. Adapt that structure to this discrepancy register; the maintainer still decides what should change.

Close with unresolved rows still visible, exclusions explained and the human decision boundary intact. The stop condition is explicit: the workflow delivers evidence only, and no documentation is changed.

Useful Links

• package.json — npm Docs.
• About the repository README file — GitHub Docs.
• Viewing and understanding files — GitHub Docs.
• Custom instructions with AGENTS.md — OpenAI ChatGPT Learn.
• Config basics — OpenAI ChatGPT Learn.
• Prompting — OpenAI ChatGPT Learn.