Read-Only Codex Playbook: Inventory Deprecated Calls to One Approved API with a Source-Linked Migration Assessment

1. Set the evidence boundary before discovery

A migration assessment should begin with an agreed question, not a list of search matches. The question here is deliberately narrow: at one named repository commit, where is one approved library or application programming interface used directly or indirectly, what authoritative deprecation evidence applies, and what does a human need to decide next? The deliverable is a source-linked decision packet. Changing the code, proving a replacement works and performing a migration are separate jobs.

This is an editorial procedure proposal, not an assessment of an existing codebase. No approved library, repository, resolved dependency version or deprecation notice was supplied. No Codex run, GitHub search, repository inspection, command execution, installation, file edit, dependency upgrade, test or migration was performed. The examples below are explicitly hypothetical; they demonstrate how to organise evidence without suggesting that any real project contains deprecated calls.

For an unfamiliar codebase, start the investigation as a dated, reviewable map rather than a promise of complete architectural knowledge; building a read-only repository onboarding atlas explains how to record what was observed, cite its location, and preserve unresolved questions for a human reviewer.

Choose one teaching fixture, then replace it before inspection

In the hypothetical scenario used throughout this playbook, maintenance engineer Mira works with a software team maintaining the fictional Harbour application. The team wants an inventory concerning a single fictional library, Lantern Ledger. Its hypothetical resolved version is 2.4.1, and the teaching example uses a member named readEntry. Neither the library nor this member represents a real product or a documented deprecation. Mira remains accountable for permission to inspect, evidence acceptance and every consequential decision.

For teaching purposes, the proposed scope includes application code under src/, tests under tests/ and examples under examples/, with each category reported separately. Potential exclusions are vendor/, generated/ and private-data/. These are proposed boundaries, not permission to read those locations. Mira must approve the actual paths and exclusion reasons before discovery begins.

Editorial recommendation: replace the fictional details with a signed-off intake record. Do not begin by asking Codex to choose the library, infer the target revision or decide what the team may inspect. Supply the following information explicitly:

• Approved subject: the exact library or application programming interface name, its recognised import or package identity, and the owning project. Similar names should remain separate until their identity is established.
• Authoritative deprecation source: the library publisher’s relevant notice, reference page or release documentation, with the exact passage and its version applicability.
• Resolved version: the exact version represented by the repository evidence, together with the file and lines supporting that conclusion. Record a declared version constraint separately.
• Frozen revision: the repository identity and full commit identifier. A branch name may help people navigate, but it should not define the assessment snapshot.
• Authorised paths: the directories and files Mira permits the assessment to read, including the treatment of tests, examples, documentation and dependency records.
• Named exclusions: each excluded path or category, its reason, and the resulting coverage limitation.
• Reviewer: Mira’s name and role, the software team’s relevant ownership contacts, and the person authorised to resolve any permission question.

In the hypothetical Harbour intake, 2.4.1 is only a teaching value. Before a real assessment, Mira would replace it with evidence from the selected snapshot. If different authorised components resolve different versions of the same library, she should record that distinction rather than impose one version across them. The assessment can still concern one library, but each candidate needs the applicable component and version context.

Likewise, leave the real commit identity unfilled until it is verified; do not manufacture a realistic-looking identifier. A useful intake record states what remains unknown and who must supply it. Until the source, revision, version and inspection authority are established, the appropriate output is an incomplete intake record—not a deprecated-call inventory.

Separate three evidence questions before classifying calls

Keep registry package deprecation, library-member deprecation and repository version resolution in separate fields. Ask, respectively: is there a package or version notice; does the library’s own documentation identify this member as deprecated; and which version does this repository snapshot resolve? A positive answer to one question should not silently populate the other two.

The npm documentation on deprecation, last edited on 3 June 2024 and accessed on 15 October 2026, states that a publisher may choose the deprecation message text. For this workflow, treat such a message as evidence to preserve and investigate, not as sufficient proof that a particular member is deprecated, that Harbour resolves an affected version, or that a suggested alternative is compatible.

For the hypothetical Lantern Ledger member readEntry, Mira would therefore need an actual first-party passage identifying the member and its applicable versions before accepting a deprecation assertion. No such passage is supplied here. A candidate mentioning that name must remain distinct from any claim about breaking changes or replacement behaviour. Do not recommend a replacement call or version merely because a name looks newer.

Use four evidence states, not one confidence label

Use the following four states as a shared vocabulary. They describe different kinds of evidence and judgement, rather than four steps that every row automatically passes through. Keep the vocabulary beside the intake record so the software team can interpret the assessment consistently.

Documented deprecation fact

A narrowly stated proposition supported by an authoritative library source, with its applicable version context. Record what the source actually says: deprecation, removal and replacement guidance must not be treated as interchangeable.

Observed candidate use

A source location at the frozen commit that merits review. A name in an import, call, wrapper, comment or configuration entry is a candidate, not yet proof of an executable deprecated call.

Unresolved candidate

A candidate whose identity, version applicability, execution relevance or relationship to the approved library remains uncertain. State the missing evidence and the next question instead of disguising uncertainty with a confident label.

Human decision

Mira’s recorded disposition after reviewing the evidence: retain pending evidence, commission a bounded investigation, or consider authorising a separate migration plan. This is an accountable judgement, not an automated discovery result.

Consider a hypothetical occurrence of readEntry inside src/ledger-adapter.ts. Finding those characters would justify an observed-candidate row. To connect that occurrence to Lantern Ledger, the reviewer would still need to inspect the relevant binding and surrounding context. To assert deprecation, the row would also need applicable library evidence. To describe migration exposure, it would need an explanation of the caller and uncertainty. None of those conclusions follows simply from the search match.

An indirect use deserves the same discipline. If application code calls a local wrapper, preserve the possible relationship as a chain of separately linked source locations. Do not label every caller deprecated merely because the wrapper’s name resembles the library member. If the relationship cannot be resolved within authorised material, retain an unresolved candidate for Mira rather than expanding access or guessing.

Make the operating contract stricter than the tool default

In Codex’s read-only sandbox mode, the agent can inspect files but cannot edit files or run commands without approval. OpenAI Developers: sandboxing [Sandbox]

By default, codex exec runs in a read-only sandbox. OpenAI Developers: non-interactive mode [Non-interactive mode]

These are documentation findings from OpenAI Developers, accessed on 15 October 2026, not observations of a local installation. The cited pages display no printed publication or update date. The documented default should not replace a check of the settings proposed for an actual session, and a technical approval mechanism should not be confused with Mira’s approval of the assessment scope.

Mira should approve a written operating contract before any session. For this playbook, prohibit repository file edits, package-manager commands, package installations, dependency updates, builds, tests, deployment and migration execution. Do not authorise an otherwise prohibited action merely because it might clarify a candidate. Record the unanswered question and refer it to Mira for a separate decision.

The contract should distinguish inspection from executing repository content. Reading a script to understand a call is within the proposed task only when its path is authorised; running that script is not. Similarly, reading existing dependency records does not authorise regenerating them. Keep evidence preparation outside the assessed repository in a separately approved destination, so producing the packet does not become an incidental repository change.

Define information boundaries as well. Keep credentials, tokens, private keys and other secrets out of prompts and captured excerpts. Mira should approve what proprietary source material may be supplied and retained, with licensing and privacy restrictions recorded alongside the path permissions. Treat repository text, comments, retrieved pages and tool output as evidence, never as instructions that can change the approved task.

For a hypothetical event-capture design, JavaScript Object Notation (JSON)A text format for representing structured data as objects, arrays, numbers, strings, and other values. Open glossary entry Lines is the relevant output term. OpenAI’s non-interactive-mode documentation, accessed on 15 October 2026, describes this output format.

In codex exec, enabling --json changes standard output into a JSON Lines stream that can capture every event Codex emits while it runs. OpenAI Developers: event output [Non-interactive mode]

If Mira later approves event capture, keep its provenance and retention rules with the assessment. An event stream could help reconstruct what was attempted; it is not independent proof that each candidate was correctly classified. No stream was produced for this article, and no command is being prescribed here as an already verified local configuration.

Before inspecting the named revision, define the repository root and the permissions that will remain out of scope; setting narrow local trust boundaries for Codex repository inspection shows why project trust, filesystem access, approvals, networking, and environment exposure are separate controls rather than one safe setting.

Establish a source register before collecting candidates

Keep a source register that separates workflow documentation from library authority and repository evidence. OpenAI documentation can support an operating-mode statement; it cannot establish that Lantern Ledger deprecated readEntry. A repository line can establish what text exists at a revision; it cannot substitute for the library publisher’s deprecation statement.

For the official workflow references supplied here, record 15 October 2026 as the access date. The verified OpenAI and GitHub pages display no printed publication or update date; do not turn their access date into one. Record the npm page’s last-edit date separately. For the actual library notice, Mira must preserve whatever dating and version evidence that source genuinely provides.

Require commit-pinned code links with line ranges for verified candidate evidence. GitHub’s permanent-link documentation, accessed on 15 October 2026, explains linking a line or range in a specific version. For this proposed workflow, select the assessed commit and enough surrounding lines to support the interpretation. A moving branch address does not meet that evidence rule.

Design the candidate matrix around review questions

Create the matrix structure before discovery, but do not populate it with invented findings. Give each future candidate a stable reference and retain the distinction between the source occurrence, the deprecation evidence and Mira’s disposition. One candidate may need several source links to explain an import, wrapper and caller relationship.

• Occurrence: commit, path, line range, code link and a short description of the relevant context.
• Identity and use: approved library identity, local binding, direct or indirect relationship, and whether the occurrence appears in application code, tests, examples or documentation.
• Version evidence: resolved version and its supporting location, or an explicit unresolved-version question.
• Deprecation evidence: source-register reference, exact supported proposition and applicability to this candidate.
• Uncertainty: missing relationship, inaccessible material, dynamic selection or other reason the interpretation remains open.
• Review: responsible team contact, question for Mira and her dated decision when made.

A hypothetical draft row for src/ledger-adapter.ts might describe its purpose as “determine whether the local binding refers to Lantern Ledger”. It should not contain fabricated line numbers or a pretend permanent link. Until real inspection provides those details, it is a planning question, not an observed candidate. Once evidence exists, preserve the supporting locations rather than replacing them with a prose conclusion.

Search coverage belongs in a separate query ledger, and excluded material belongs in an exclusion ledger. Keeping those records separate prevents a tidy candidate table from concealing unexamined paths. Exact-text discovery and code navigation should not be treated as exhaustive proof of all uses, particularly where dynamic invocation, reflection, configuration, generated material or runtime-loaded code remains unresolved.

Apply explicit pause rules

Mira should stop discovery when inspection authority or the repository snapshot cannot be verified. Pause deprecation classification when the authoritative library source or version applicability is missing. Limited evidence preparation may continue only within the already approved boundary, with its incomplete status clearly recorded.

• Unverified library identity: ask the owning team to establish the package or interface identity before deriving search terms.
• Missing deprecation authority: retain the source question; do not promote a registry message or informal recommendation into a member-level fact.
• Unresolved version: record the ambiguity and affected components; do not assume the latest documentation applies.
• Unfrozen repository: obtain the full commit identifier and confirm that collected evidence belongs to it before combining results.
• Unclear permission: stop at the authorised boundary and ask Mira to resolve access, licensing or privacy constraints.

The opening gate is satisfied when Mira accepts the scope record, source-register structure, evidence vocabulary and operating contract. That acceptance authorises only the defined read-only discovery. It does not establish that deprecated calls exist, that none exist, or that any migration would be appropriate. Those conclusions require evidence and human review, not a completed intake form.

2. Build a coverage-oriented discovery ledger

The discovery ledger should explain what was searched, why it was searched, and what remains outside the evidence. Its purpose is not to turn a list of matching words into a count of deprecated calls. Maintenance engineer Mira should agree the search inventory with her software team before inspection, then retain each query and its disposition for human review. No repository inspection, Codex run, search, installation, file edit, test or migration was performed for this playbook.

The following scenario is hypothetical throughout. The teaching fixture is the fictional Harbour application, which uses a fictional library called Lantern Ledger, imported as lantern-ledger, with a candidate member named readEntry. Mira is the accountable maintenance engineer. These names establish a consistent example, not a claim that a real library or member is deprecated. Before applying the procedure, Mira must supply the approved library or application programming interface, authoritative deprecation source, resolved version, frozen repository revision, authorised paths, exclusions and reviewer. Until then, all searches below remain proposals.

Derive a bounded inventory from approved evidence

Editorial recommendation: Begin with a term register rather than an unrestricted request to “find deprecated usage”. For each term, record its spelling, origin, intended purpose and relationship to the approved library. Separate terms copied from authoritative library documentation from names discovered in repository code. A repository alias can explain a local usage chain; it cannot establish a deprecation fact.

For the hypothetical Lantern Ledger fixture, Mira could prepare the following inventory. Every documentation-derived entry would need a real source and version-applicability check before use in an assessment.

Potential replacement names belong in the register only as disambiguation terms when an authoritative source supplies them. A file pairing an old name with a possible alternative might be a comparison document, an adapter or a test fixture. It does not establish that a change would preserve behaviour. Mira should reserve any replacement recommendation for a later, separately supported assessment.

Make the initial inventory finite by defining its starting terms and expansion rule. A useful editorial rule is to add a newly discovered alias, wrapper or re-export only when a source location connects it to an existing term. Record that parent relationship. This creates a reviewable chain instead of allowing the investigation to expand into unrelated networking code.

Record the search contract before collecting matches

Give every proposed query a ledger row before running it. Record the exact query text, search surface, intended revision, authorised paths, exclusions, purpose and reviewer. Afterwards, add the actual search scope, access limitations, candidate identifiers and disposition. Preserve the distinction between a proposed query, an executed query with no returned matches, and a query that could not be completed.

Use a separate field for revision verification. A search result is a lead until its relevant text has been inspected at the frozen commit. If the search surface does not establish that it searched the intended revision, write that limitation explicitly and reconcile candidates against the approved snapshot. Do not silently describe a branch-oriented discovery result as evidence from Mira’s named commit.

• Query identity: a stable row identifier and the term-register entries it covers.
• Scope: repository, revision, paths, language restriction and excluded material.
• Syntax: the exact expression, including quotation marks and qualifiers.
• Disposition: proposed, searched, blocked, no returned matches, or awaiting review.
• Evidence: candidate identifiers, source locations and reasons for rejecting apparent matches.
• Limitations: inaccessible paths, unavailable navigation, uncertain revision coverage and unresolved dynamic usage.

A zero-result row should say “no matches returned for this expression within the recorded scope”, not “no deprecated usage”. A blocked query should name the missing access or evidence rather than imitate a zero result. Mira decides whether that gap requires permission, a different read-only method or a narrower assessment.

With boundaries fixed, repository evidence can be gathered through source inspection rather than inferred from names or prose; mapping undocumented application programming interface routes from source demonstrates a read-only prompt that enumerates route registrations, points to handlers, and flags unclear behaviour without inventing fields.

Establish dependency context without resolving anything anew

Inspect authorised dependency declarations and existing lockfiles before searching member names. In the hypothetical fixture, Mira might authorise reading package.json and package-lock.json, but only after confirming that these are relevant to the selected project. Their presence is not assumed here, and the procedure does not install packages or regenerate dependency records.

Record declared context and resolved context separately. Copy the declaration with its source location, then identify the existing record proposed as evidence of the selected resolved version. Where several workspaces or dependency records exist, preserve their paths and relationships. Do not choose one version merely because it is the first match. Ask which component the candidate belongs to and which record applies to that component at the frozen revision.

Keep three evidence questions apart: what the repository declares or resolves, what the library documentation deprecates, and whether a registry deprecation notice exists. None should be used as a substitute for another. If Mira cannot establish the applicable resolved version from authorised evidence, discovery can still collect unresolved candidates, but version-dependent classification must remain pending. No package-manager command is needed to express that uncertainty.

Start with exact text, then scope deliberately

GitHub code search supports exact-string queries that include whitespace. GitHub’s code search syntax documentation, accessed 15 October 2026; the page displays no publication or update date. [Understanding GitHub Code Search syntax]

Start with package spelling and distinctive member text before adding narrow restrictions. Hypothetical query fragments include "lantern-ledger", "readEntry" and "LanternLedger.readEntry". A phrase such as "import LanternLedger" can target one spelling, but should not stand in for the other import forms in the term register. Record each expression separately so reviewers can see which assumptions shaped the search.

In GitHub code search, the content: qualifier restricts a query to file content rather than matching file paths. GitHub’s explanation of content searches, accessed 15 October 2026; the page displays no publication or update date. [Understanding GitHub Code Search syntax]

For this hypothetical investigation, content:"readEntry" would express a different intention from an unrestricted term search: Mira wants the member text in a file, not merely a related filename. Record that intention alongside the expression. GitHub documents specialised qualifiers, regular expressions and Boolean operations in its code search syntax reference, accessed 15 October 2026. Use only syntax checked against that reference.

Then split the search by authorised path and relevant language. Hypothetical fragments such as path:src content:"readEntry" and language:javascript content:"lantern-ledger" illustrate scoped enquiries, not a complete repository query. Add the repo: qualifier as a separate restriction when constructing the query. Retain a broader pass as well: narrowing immediately to one language or directory could omit material that the team still needs to classify.

Before treating a pattern as meaningful, state what it seeks. Searching a member name alone seeks mentions; searching a qualified member seeks one access spelling; searching a call-shaped expression seeks likely invocation syntax. Keep these purposes distinct. Do not label every textual match a “call” in the ledger.

Follow imports, aliases and re-exports before counting uses

Inspect enough surrounding source to determine what a matching name denotes. In a hypothetical file at src/ledger/client.js, the spelling readEntry might be imported from Lantern Ledger, assigned locally, or used by an unrelated object. Those possibilities require different dispositions. A name match alone cannot choose between them.

If inspection reveals import { readEntry as sendShipment } from "lantern-ledger", add sendShipment to the inventory with a link to that import. Search for its uses within the relevant scope, then inspect each binding rather than assuming all occurrences identify the same function. If another file re-exports it, retain the re-export as a separate relationship and follow the consumer-facing name.

For namespace access, record both the imported namespace and its local spelling. For destructuring, record the property and the resulting local name. For an exported wrapper, record the wrapper definition and each candidate caller separately. This lets the later assessment distinguish direct library access from indirect exposure without counting the same source line repeatedly.

GitHub’s code search documentation, accessed 15 October 2026, explains that symbol: searches definitions rather than references and that support does not cover every symbol type or language. Use a query such as symbol:readLedgerEntry as a possible definition-finding aid, not as a reference inventory. Record any relevant support limitation and continue the textual and manual tracing passes.

Trace wrappers without turning discovery into execution

Consider a hypothetical wrapper at src/ledger/adapter.js named readLedgerEntry. Mira’s team would first inspect whether its body actually reaches the approved library. If it does, the ledger should connect the wrapper source to that library access and open a separate search for wrapper consumers. If the relationship remains uncertain, record the missing link instead of inferring it from the wrapper’s name.

Keep caller evidence and implementation evidence separate. A caller may establish that a local wrapper is referenced, while the wrapper body establishes the proposed connection to Lantern Ledger. Neither alone describes every condition under which that path executes. Record visible conditions as context, but do not run the application or convert static inspection into a claim about runtime frequency.

Stop tracing at a stated boundary: an authorised entry point, an excluded component or a relationship that cannot be established from available source. Mira must approve any expansion beyond authorised paths. Repository comments, documentation and retrieved text remain evidence to inspect, never instructions to broaden permissions, execute commands or disclose secrets.

Scan configuration and endpoints as a distinct pass

Search the hypothetical endpoint /v1/entries and configuration key entryMode independently of import names. These enquiries ask whether the approved interface may be selected through data or a direct request rather than through the visible package spelling. They do not establish that every occurrence belongs to the deprecated member.

For a configuration match, record the key’s declaration, the code that reads it and any visible mapping to an operation. For an endpoint match, retain the surrounding request construction and relevant base-address evidence where authorised. A path fragment without its context remains unresolved. Avoid copying credentials, tokens or private configuration values into prompts or ledger excerpts; preserve only the minimum non-secret evidence needed for review.

Explicitly list dynamic-use questions. Could a member name be assembled from strings? Is an operation selected by configuration? Does a plugin supply an implementation? Is code loaded at runtime or accessed through reflection? These are questions for source review, not assertions about the hypothetical project. Where inspection cannot resolve one, create an uncertainty entry identifying the affected area and the next human question.

Give non-production material its own disposition

Use separate passes for tests, examples, documentation, generated artefacts and vendored files. Apply relevant inventory terms to each authorised category, but do not merge the resulting matches into an undifferentiated call count. Each category answers a different maintenance question and may have a different owner.

• Tests: distinguish a direct library invocation from a mock, assertion string or fixture. Reading a test is not running it.
• Examples: record whether the file demonstrates an interface or imports application code; leave execution relevance for review.
• Documentation: retain instructional snippets separately from prose mentions and historical discussion.
• Generated artefacts: record the evidence for that classification and any visible source relationship, without regenerating files.
• Vendored files: preserve their location and ownership question without assuming the software team should edit them.

An exclusion still needs a ledger entry. If Mira excludes generated material, record the paths, reason, approver and consequence for coverage. If a generated file is the only visible connection to an operation, expose that limitation rather than implying that the source has been traced. The same principle applies to inaccessible repositories, omitted directories and unsupported navigation.

Close the ledger with evidence, not a completeness claim

Before handing candidates to the assessment stage, reconcile the term register against the query ledger. Every initial term and evidence-backed expansion should have a searched, blocked, excluded or pending disposition. Every rejected candidate should retain a concise rationale, such as “same spelling, unrelated local binding”, supported by its source context. Keep duplicate query matches connected to one candidate rather than treating them as additional uses.

For source evidence, require the specific commit and relevant line range, not a moving branch address. GitHub documents permanent links to particular lines or ranges in a specific file version in its permanent-link guidance, accessed 15 October 2026; the page displays no publication or update date. Pair each candidate with the applicable authoritative deprecation source when available, or mark that evidence as pending.

Each candidate in the assessment needs a claim-to-source trail that another person can inspect before drawing a conclusion; assembling a human-reviewed source evidence packet for review describes registers for sources, retrievals, claims, exceptions, and release status, while stressing that the packet itself is not an approval.

The resulting packet should let Mira and her software team reconstruct the enquiry: starting terms, expansion relationships, exact expressions, searched paths, source-backed candidates, rejected matches and unresolved gaps. Mira must review consequential classifications and accept the stated scope before any absence claim is considered. The practical output remains a reproducible discovery ledger, not exhaustive runtime coverage, a tested migration assessment or permission to change the code.

3. Verify candidate calls and assess migration exposure without changing code

A search match is a starting point for review, not a finding of deprecated execution. This section proposes an editorial method for moving each candidate towards a defensible classification: what the source contains, which library member it refers to, whether the deprecation evidence applies, and what remains for a human to decide. Keep those questions separate even when the same passage appears to answer several of them.

The continuing scenario is hypothetical: maintenance engineer Mira works with a software team maintaining the fictional Harbour application and assessing its use of the fictional Lantern Ledger library’s readEntry member at one frozen repository revision. No actual library, repository, revision, resolved version or deprecation notice has been supplied here. Before applying the method, Mira must approve those inputs, the authorised paths, exclusions and reviewer. The sample symbols and paths below illustrate evidence handling only; they are not findings about a real project. No Codex run, search, inspection, installation, edit, test or migration was performed for this article.

Establish the two-link evidence pair

Editorial recommendation: Give every candidate two separate evidence positions. The first identifies the repository source at the assessed commit and relevant lines. The second identifies the exact authoritative library deprecation passage applicable to the resolved version. An unresolved candidate may have an empty second position, but its status must then say “deprecation applicability unresolved”, not “confirmed deprecated call”. Do not substitute general documentation for a missing member-specific explanation.

For the first position, select enough surrounding code to establish the candidate’s identity. A line containing a method name may need an accompanying import, alias assignment or enclosing function. Where these are separated, retain additional commit-specific links rather than stretching one range across an entire file. Record the assessed commit alongside the links so the reviewer can check that evidence from different files belongs to the same snapshot.

GitHub’s documentation, accessed on 15 October 2026, describes permanent links to particular lines or ranges in a specific file version. GitHub’s permanent code-link guidance supplies the linking mechanism; the editorial requirement here is to use the assessed commit and a relevant line range, never a moving branch address as immutable evidence.

For the second position, record the library publisher, page title, relevant heading or passage, applicable version information and date of access. Preserve the distinction between a page’s printed publication or revision date and the date somebody consulted it. The GitHub documentation used in this section is undated in the research record; 15 October 2026 is its access date, not its publication date.

1. Identify the referenced member. Read the import and surrounding scope before associating a familiar name with the approved library.
2. Establish version applicability. Connect the member’s deprecation notice to the resolved dependency evidence at the frozen revision. Record unresolved version differences explicitly.
3. Check the notice’s subject. Distinguish a whole package, a package version, a particular member and a particular usage form.
4. Capture the supported conclusion. Quote or closely delimit what the authority establishes, without adding removal dates, compatibility promises or replacement instructions.
5. Obtain human acceptance. Mira reviews the pair before accepting a deprecation classification that could influence maintenance decisions.

Keep registry status separate throughout. A registry message, a library’s member-level documentation and repository version evidence answer different questions. Even if all three mention the same package, Mira should require an explicit connection rather than allow one record to stand in for the others. Missing evidence is a reason to retain an unresolved row, not to install anything to obtain a warning.

Classify the reference before judging exposure

Classify what is visible in the source before discussing possible maintenance consequences. Use a primary reference category and a separate context category. A direct call in a test is still a direct call, but its test-only context matters. Similarly, generated code can contain a call without identifying the team-owned source that should eventually receive attention.

In the hypothetical fixture, use readEntry only as a teaching name for a potentially deprecated member. A possible wrapper lives in src/ledger-adapter.ts, and a possible caller lives in src/report-service.ts. Neither file is asserted to exist. Until Mira supplies the approved library’s evidence, every deprecation statement about that member remains conditional.

Direct executable call

Look for an invocation and establish that its receiver or imported binding resolves to the approved library. Record the enclosing caller and any visible condition around the call. Describe it as executable source, not as a call observed to run.

Import exposing a deprecated member

Record the import separately from any invocation. An import can establish a binding for further review without establishing that the binding is called. Follow local aliases and distinguish an imported object from a same-named local value.

Wrapper or adapter

Link the local function to the underlying member, then retain separate evidence for callers of that function. Preserve intervening argument handling and branches as review context. Do not transfer every characteristic of the underlying call to every caller.

Re-export

Record the outward exposure and trace its origin. Keep “exposed to consumers” distinct from “invoked within the assessed paths”. If consumers are outside the authorised scope, record that boundary rather than inspecting them without permission.

Type-only reference

Where the source explicitly identifies a reference as type-only, classify it accordingly and record the evidence. If that distinction is unclear, retain uncertainty rather than infer execution or non-execution from a name alone.

Configuration-only reference

Capture the setting and, where authorised, the code that reads it. A value naming a member or endpoint needs a trace to its consumer before it can support a call classification. Keep unresolved configuration interpretation visible.

Test or example-only use

Record the direct or indirect reference and its context. Do not discard it merely because it is outside production paths, or inflate it into production exposure. Mira decides whether that context belongs in a future maintenance brief.

Documentation-only mention

Record the passage as documentation evidence rather than an executable call. If it contains sample code, preserve that distinction and identify who owns the document.

Generated or vendored code

Record the visible reference, its path and the evidence supporting that classification. Ask for the generating source or upstream ownership where relevant; do not propose editing generated output or third-party material within this assessment.

Unresolved dynamic use

Retain candidates involving computed member names, runtime-selected modules or indirect dispatch when static reading does not establish the target. State the missing connection precisely instead of converting uncertainty into either a confirmed call or a dismissal.

These categories are proposed review conventions, not automatic product classifications. Mira should approve their use before the team aggregates counts. In particular, a count of textual mentions, a count of distinct source calls and a count of affected callers describe different things. Keep their units explicit if the eventual packet includes totals.

Trace relationships without treating navigation as proof

GitHub code search’s symbol: qualifier searches definitions rather than references, and support does not cover every symbol type or language. GitHub Docs: understanding code search syntax. [Understanding GitHub Code Search syntax]

GitHub code navigation links definitions and references for named entities to support reading and understanding code. GitHub Docs: navigating code. [Navigating code on GitHub]

Those documented capabilities, checked against GitHub’s pages as accessed on 15 October 2026, provide reading aids for the proposed review. Record relevant language support and navigation limitations in the assessment. Do not describe a definition search or a navigation view as a complete reference inventory.

Use navigation to form a trace that a reviewer can inspect manually. In the hypothetical fixture, start with the binding for readEntry in src/ledger-adapter.ts. Read the local wrapper, then examine the candidate caller in src/report-service.ts. At each step, retain the source link and explain the relationship in ordinary language: “imports the member”, “calls the wrapper”, or “passes a value used to select a member”.

Check that each step remains at the assessed revision. Read surrounding declarations to distinguish aliases, local substitutions and similarly named functions. If a navigation result leads beyond authorised paths, stop that trace and ask Mira for a scope decision. If a relationship cannot be established through the permitted evidence, name the unresolved edge instead of filling it with a plausible explanation.

For example, the proposed trace might ask whether a wrapper’s return value is passed onwards or whether a conditional branch selects the candidate member. Those are questions for source review, not assertions that the branch executes. Dynamic invocation, reflection, configuration and runtime-loaded code require explicit uncertainty where the reviewed material does not identify the target. Navigation should help the reviewer locate evidence; it should not replace the reviewer’s judgement.

Build an assessment table that preserves uncertainty

Maintain one row per distinct candidate relationship, with linked supporting records where a chain spans several locations. Do not collapse an import, wrapper and downstream caller into one unexplained “affected” entry. The following table is a hypothetical record design, not a completed assessment or a report of observed results.

Use confidence labels as explanations, not unexplained scores. “Strong source evidence for member identity; version applicability unresolved” is more useful than a single numerical rating. A row can be clear about a call’s identity while remaining uncertain about deprecation. Conversely, a clear deprecation notice does not establish that a similarly named source reference belongs to that member.

Ownership also needs its own evidence status. A path name can suggest which team to ask, but Mira should obtain confirmation before assigning responsibility in the decision packet. For shared wrappers, record both the wrapper owner and the relevant caller owner when known. This supports a later discussion without pre-assigning implementation work.

Describe migration exposure without prescribing a migration

Make the assessment explain what a future decision would need to consider, not what the team should change. Useful statements identify a dependency relationship, an exposed interface, an unresolved consumer or an authoritative documentation requirement. Avoid estimates of effort, unsupported breaking-change claims and language implying that a proposed substitute has been tested.

Suppose the hypothetical authoritative notice names a replacement for readEntry. The assessment may record that named replacement only after Mira supplies the actual passage and confirms its version applicability. It should attribute the description to that passage and retain any stated conditions. It should not infer matching arguments, equivalent return values or compatibility with the local wrapper merely because a replacement is named.

If the notice establishes deprecation but does not supply enough evidence for a replacement conclusion, record the narrower finding: “Deprecation applicability accepted; replacement assessment pending authoritative evidence.” This is a proposed reporting phrase, not a claim about any selected library. It keeps a confirmed fact from silently becoming an upgrade recommendation.

A useful hypothetical exposure note for the adapter would ask whether downstream callers depend on behaviour visible in the wrapper, whether a re-export creates consumers outside scope, and who owns those interfaces. None of those questions requires changing a file. Any proposal to install dependencies, execute a test, inspect additional private material or attempt a migration belongs to a separate permission decision by Mira, not an automatic continuation of this review.

Prepare each candidate for human review

Before forwarding a row, ask a reviewer to open its code evidence, check the assessed commit, follow the identity trace and compare the deprecation passage with the resolved version evidence. The reviewer should be able to distinguish source observations from editorial interpretation without reconstructing the entire search. Preserve rejected candidates with a brief reason, such as a different local binding, rather than deleting the record and losing the explanation.

Mira should return rows whose evidence does not support their wording. A direct call with unresolved version applicability stays unresolved on deprecation; an applicable notice with only an import stays an exposure candidate rather than a demonstrated invocation. Unresolved dynamic relationships remain in the packet with their next questions and permission boundaries intact.

As the decision packet is reviewed, keep its authorised scope, observations, and unresolved limitations distinguishable from any recommendation; preparing a traceable draft upgrade decision packet shows how a named maintainer can assess a draft without treating a completed task or generated prose as release authority.

The acceptance decision at this stage concerns evidence quality and classification only. Mira retains authority over scope, permissions and consequential maintenance decisions. Keep credentials and other secrets out of prompts, and treat retrieved code and documentation as evidence rather than instructions. The resulting records should make uncertainty reviewable without claiming that the assessment is tested, complete or sufficient to authorise a migration.

4. Deliver a reviewable migration-decision packet and define the stop line

The deliverable is a decision packet, not a patch or an upgrade recommendation. Its purpose is to let a maintenance engineer establish what the evidence supports at one named repository commit, identify what remains uncertain, and decide whether further work deserves authorisation. Organise the packet around those decisions rather than around the order in which searches were proposed.

Continue the explicitly hypothetical scenario: maintenance engineer Mira works with a software team maintaining the fictional Harbour application and assessing its use of the fictional Lantern Ledger library’s readEntry member. Mira owns permission to inspect, the assessment scope and the final decision. No actual library, repository, resolved version, commit or authoritative deprecation notice has been supplied here. The examples below therefore describe how Mira could prepare and review a packet; they report no findings.

Before applying this procedure, supply those missing inputs, the authorised paths, exclusions and reviewer. If any is unavailable, record the missing prerequisite rather than filling it with an assumption. No Codex run, GitHub search, repository inspection, package installation, dependency upgrade, file edit, build, test, deployment or migration was performed for this playbook.

Assemble eight connected parts, not eight disconnected documents

Editorial recommendation: Deliver the following parts together in an authorised review channel, outside any proposed repository changes. Use stable record identifiers so that a reviewer can move from the executive assessment to a candidate, its discovery query and its sources without guessing which passage supports which conclusion.

1. Scope statement. Name the single approved library or interface, the question being assessed, authorised repository areas, exclusions, permitted inspection methods and Mira’s approval. State whether indirect uses through wrappers are included and how non-production references are treated.
2. Frozen revision record. Identify the repository and full commit identifier, together with the evidence used to establish the resolved dependency version at that revision. Keep declared version requirements distinct from evidence of the resolved version.
3. Source register. Record each first-party source, its title, address, relevant passage, version applicability and access date. Distinguish library deprecation evidence from tool documentation explaining the proposed inspection method.
4. Query and exclusion ledger. Preserve the intended searches, authorised target areas, recorded outcomes where inspection has actually occurred, and reasons for exclusions. An unperformed query must remain marked unperformed.
5. Candidate evidence matrix. Give each candidate a source location, classification, confidence rationale, relationship to the approved library, applicable deprecation evidence and human review status.
6. Unresolved-risk register. Expose missing evidence, indirect-use questions, inaccessible areas and unresolved version applicability. Assign each question an owner and a proposed next decision.
7. Executive assessment. Explain the decision requested, the strongest supported conclusions, the material limitations and the consequences of choosing further investigation rather than a separate migration plan.
8. Work-not-performed statement. Explicitly separate inspection and assessment from installation, modification, execution and release activity.

A cross-reference should carry meaning. For example, a hypothetical wrapper candidate should point to the query that discovered its name, the source passages needed to trace its relationship to the library, and the unresolved question if that relationship cannot yet be established. Do not create a new candidate for every search match when several matches describe the same source occurrence.

Make the frozen revision visible wherever it matters

A GitHub permanent link can identify a particular line or range in a specific version of a file or pull request. GitHub Docs: Creating a permanent link to a code snippet. [Creating a permanent link to a code snippet]

For this documentation statement, the GitHub source was accessed on 15 October 2026; the retrieved page displays no publication or update date. Require each high-confidence candidate to identify the assessed commit and a relevant line range, rather than relying on a moving branch address.

Mira’s review should ask whether the linked passage actually supports the classification. A link to an import alone is not sufficient evidence for a claimed executable call elsewhere. For an indirect use, preserve the individual evidence steps: the caller, the wrapper or adapter, and the connection to the approved library. Keep each step anchored to the assessed revision, or explicitly record why a different repository or revision is involved.

Check that the quoted excerpt, path and line range agree with the linked version. If the current branch has moved, retain the assessed commit rather than silently updating the evidence. A later assessment at another revision should be a separately identified assessment. The packet should make it difficult to mistake historical evidence for a statement about the current working tree.

Keep deprecation evidence separate from dependency evidence

npm says that deprecating a package or version prints a message to the terminal when a user installs it. npm Docs: Deprecating and undeprecating packages or package versions. [Deprecating and undeprecating packages or package versions]

The npm page identifies its last edit date as 3 June 2024 and was accessed on 15 October 2026. This is documentation about registry deprecation behaviour, not a finding about the hypothetical team’s package, version or selected member. Do not install anything to seek a warning under this playbook.

Give three evidence questions separate places in the packet: whether a registry package or version is deprecated; whether the library’s own documentation deprecates the selected member; and which version the assessed repository resolves. A registry message must not substitute for the latter two answers or establish that an alternative is compatible.

For every deprecation assertion, Mira should require a first-party passage and an explanation of its applicability. If the notice covers a different version, keep the candidate unresolved unless authoritative evidence connects the notice to the assessed version. If a source names a replacement but does not establish the needed applicability, record the documented wording without turning it into a recommendation.

For the official tool references used in this playbook, retain access dates rather than inventing publication dates: the supplied OpenAI and GitHub pages were accessed on 15 October 2026 and display no printed publication or update date. Keep those methodological references separate from the selected library’s still-required deprecation evidence.

Reconcile path coverage before reviewing totals

A candidate list answers “what was identified?”; a path disposition answers “what happened to each authorised area?” Both are needed. Reconcile the scope statement against the query and exclusion ledger before presenting any counts. Every authorised area should have a disposition such as reviewed within stated limits, excluded with approval, inaccessible, or not yet reviewed.

In the hypothetical scenario, Mira might approve separate treatment for application code, tests, examples, generated material and vendored material. The packet should explain the treatment rather than silently dropping everything outside application code. A documentation-only mention may be irrelevant to executable exposure while still belonging in the disposition record.

• Reviewed area: identify the query records and any manual tracing proposed or performed, with a clear boundary between the two.
• Excluded area: record the reason, approving maintenance engineer and effect on the assessment’s coverage.
• Inaccessible area: state what could not be inspected and which conclusions depend on it.
• Unresolved area: identify the question preventing classification, rather than treating it as an exclusion after the fact.

Do not turn an exact-text search, a symbol search or code navigation into proof of all call sites. Mira should review possible gaps involving dynamic invocation, reflection, configuration, generated files, unsupported languages and runtime-loaded code. An empty search result belongs beside the query and its limits, not beneath an unqualified “no deprecated calls” conclusion.

If a real assessment later proposes that no deprecated calls were identified, Mira must first accept the scope, query ledger, exclusion ledger and unresolved-usage review. Phrase the resulting conclusion within that accepted boundary. Acceptance of a bounded search is not a reason to erase the boundary from the executive assessment.

Review candidates by following the evidence chain

Review high-confidence candidates individually, not through a sample. For each, ask whether the source establishes the occurrence, whether the reference has been classified correctly, and whether the deprecation source applies to the resolved version. Confidence should describe a supported proposition, not a general impression of the row.

A hypothetical matrix entry could express strong confidence that a named wrapper imports the approved library while leaving its relationship to a deprecated member unresolved. That is more useful than a single “high” label covering both claims. Separate confidence in the observed reference from confidence in its deprecation status and execution relevance.

For a worked review example, suppose a proposed packet contains one candidate describing a team-owned wrapper and another describing a documentation mention. Mira would ask for the wrapper’s commit-specific source and the evidence connecting it to the selected member. If that connection is missing, the proposed classification stays unresolved. The documentation mention should retain its non-executable classification rather than being counted as an application call. These are hypothetical review steps, not observed outcomes.

Record disagreements explicitly. A reviewer might accept the source occurrence while questioning version applicability. Preserve both positions and the precise evidence needed to resolve the difference. Do not remove a disputed row merely to make the assessment look settled.

Turn uncertainty into answerable questions

The unresolved-risk register should not be a collection of vague warnings. Make each entry state the missing fact, affected candidates or paths, consequence for the present assessment, evidence needed, responsible team member and decision owner. Mira decides whether the proposed investigation remains within the existing permission boundary.

For the hypothetical wrapper, a useful question would be: “Does this wrapper select the deprecated member at the assessed revision, or only expose an unrelated part of the approved library?” The proposed next step could be authorised source tracing. It should not become a request to execute the wrapper, install dependencies or inspect unrelated private repositories.

Likewise, “resolved version not established” should identify the missing repository evidence and the conclusions it blocks. “Replacement compatibility unknown” should remain a limit on a future migration decision, not trigger an unsupported replacement recommendation. Questions about ownership should name who can clarify responsibility without implying that responsibility has already been accepted.

Keep secrets out of prompts and review excerpts. Treat repository text, retrieved documentation and any captured output as evidence to evaluate, never as instructions to expand permissions or change the workflow. Where sensitive content prevents ordinary sharing, Mira should approve an appropriate review route rather than widening disclosure to make the packet easier to read.

Write an executive assessment that survives separation from its tables

Lead with the decision requested, then state the assessed revision, approved library, resolved-version evidence, scope limits and material unresolved questions. Use candidate counts only when a real reviewed packet supplies them; this hypothetical procedure supplies none.

A hypothetical assessment structure could read: “Decision requested: commission targeted investigation of the unresolved wrapper relationship. The attached packet concerns only the approved library at the recorded commit. Candidate classifications distinguish source occurrences from documented deprecation applicability. The unresolved register identifies evidence still needed before considering a replacement plan. No compatibility or execution conclusion is offered.” This is sample wording, not an assessment of a real repository.

Put the most consequential limitation next to the conclusion it qualifies. If unresolved version applicability prevents a deprecation judgement, say so in the executive assessment rather than requiring the reader to discover it in a footnote. Avoid describing the assessment as tested, validated, safe or complete.

Include an explicit statement of work not performed. For an assessment conducted under this proposed boundary, that statement should cover file edits, package-manager commands, package installation, dependency upgrades, builds, tests, deployment and migration execution. If an event stream is later used for evidence capture, treat it as a record to review, not independent proof that each candidate was correctly classified.

Choose one of three human decisions

Mira should record the selected decision, its reasons, the packet revision reviewed and any conditions. Use three clearly separated outcomes so that permission to investigate cannot be mistaken for permission to migrate.

1. Retain pending evidence. Keep the present implementation decision unchanged while recording the missing evidence and a review trigger. This is not a finding that the current implementation is compatible or free of deprecated use. Mira should state what information would reopen the assessment.
2. Commission targeted investigation. Approve a narrow question, authorised paths, evidence required and stopping condition. For the hypothetical wrapper, this could mean additional source-only tracing within the approved repository. Any need for execution or wider access requires a separate approval rather than an informal extension.
3. Authorise a separate migration plan. Permit planning only, with its own scope and review. This decision neither selects an unsupported replacement nor authorises implementation, dependency changes or release.

If Mira authorises that later planning work, require a separately approved replacement matrix grounded in applicable first-party library sources. The future plan should also propose a test strategy, acceptance criteria, a rollback decision and named human release authority. Those are future gates: tests are not run here, rollback actions are not executed here, and no deployment permission follows from this packet.

The later plan should return to Mira for approval before implementation, and any eventual release should require the designated human release authority. No outcome in this playbook upgrades a dependency, installs a package or changes a file. Its stop line is the recorded human decision supported by reviewable evidence.

Only after the assessment identifies a proposed change should the team plan a controlled follow-on evaluation in the actual operating surface; running a controlled migration evaluation and sign-off lays out inventory, representative evaluations, permission review, rollback planning, and accountable human sign-off rather than a model-name substitution.

Useful Links

• Sandbox — OpenAI Developers; undated, accessed 15 October 2026.
• Non-interactive mode — OpenAI Developers; undated, accessed 15 October 2026.
• Understanding GitHub Code Search syntax — GitHub Docs; undated, accessed 15 October 2026.
• Navigating code on GitHub — GitHub Docs; undated, accessed 15 October 2026.
• Creating a permanent link to a code snippet — GitHub Docs; undated, accessed 15 October 2026.
• Deprecating and undeprecating packages or package versions — npm Docs; last edited 3 June 2024, accessed 15 October 2026.