{ "meta": { "source": "atlas_v13_current.html", "snapshot": "2026-10-18", "site_version": "13.2", "count": 84, "note": "Materialized view of the current audited graph; complete node fields retained. Source inspection and publication status are recorded per item. The builder performs no new empirical validation." }, "records": [ { "id": "PAT:001", "label": "Plan-Then-Execute", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Separate an authorized objective from the agent's replaceable execution plan. Before changing code, identify the result, constraints, evidence and stopping conditions; then execute a bounded step and revise the plan from observations. Replanning can change the route, while changes to the intended behavior require an explicit, authorized delta.", "limitation": "A coherent plan does not establish correct requirements, executable permissions or acceptance; unexpected information can invalidate its assumptions.", "url": "", "authors": "", "year": "", "attributes": { "label": "Plan-Then-Execute", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Recompose the mechanism", "required_revision": "The plan is replaceable; intention can change only through an authorized delta.", "occurrences": "[\"AGENT:01\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A coherent plan does not establish correct requirements, executable permissions or acceptance; unexpected information can invalidate its assumptions.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make progress inspectable without letting implementation discoveries silently redefine what the requester approved.", "when_to_use": [ "A change spans several dependent actions that need a visible order.", "An agent must resume work without reconstructing its objective from scattered conversation." ], "when_not_to_use": [ "A single reversible action is already unambiguous and a separate planning document would add no useful decision.", "The intended behavior is disputed; resolve that question before planning its implementation." ], "prerequisites": [ "A versioned task envelope naming scope, owner, permissions and accepted obligations.", "A usable check for the next increment and an explicit time, action or cost budget." ], "steps": [ "Record the intended outcome, exclusions and acceptance owner separately from implementation choices and working hypotheses.", "Break the route into meaningful increments, identifying dependencies, uncertain assumptions and the observation needed after each increment.", "Execute the next permitted increment; attach the changed candidate and observed result to the task record.", "Revise remaining steps when observations warrant it, preserving the prior plan and the reason for changing direction.", "Stop and request a decision when success would require a new obligation, broader effects, an unavailable permission or exhausted budget." ], "example": "Illustrative example: An agent plans to add a read-only export endpoint, then discovers that the existing data service has no stable paging order. It may replace its query strategy and run ordering checks. It records that a proposed change to retention policy would alter the authorized objective and leaves that separate decision to the owner before proceeding.", "verification": [ "Each completed step points to observable evidence rather than the agent's assertion that it is done.", "The current candidate still satisfies the same approved objective after any replanning.", "The stop record distinguishes an unresolved decision from a technical failure or acceptance." ], "outputs": [ "Versioned objective and replaceable plan with a short change history.", "Increment evidence and any decision needed from the owner." ], "risks": [ "A detailed plan can create false confidence when its assumptions were never checked.", "Repeated replanning can hide lack of progress unless attempts and remaining budget stay visible." ], "related_practices": [ "PAT:043", "PAT:046", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:001", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:01" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:002", "label": "Swarm Migration (Map-Reduce for Agents)", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C05", "C:C13" ], "printed": false, "summary": "Partition a migration into independently owned units, let workers propose bounded transformations, and integrate them against shared behavior checks. This optional companion variant is useful only when dependencies are understood and review capacity exists. Its value must be assessed from accepted migration outcomes, including coordination and integration work, rather than assumed parallel speedups.", "limitation": "Parallel execution does not make coupled changes independent or guarantee a faster migration; shared semantic errors can affect every worker.", "url": "", "authors": "", "year": "", "attributes": { "label": "Swarm Migration (Map-Reduce for Agents)", "kind": "practice_descriptor", "collection": "PAT", "family": "F05", "chapter": 5, "disposition": "Companion variant", "required_revision": "Optional exploration for independent migrations; remove unverified generic speedup claims.", "occurrences": "[\"AGENT:02\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Parallel execution does not make coupled changes independent or guarantee a faster migration; shared semantic errors can affect every worker.", "historical_structural_chapters": [ "C:C05" ], "family_name": "Architecture, Evolution and Maintenance", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Explore whether a repetitive migration can be distributed without losing behavioral consistency, ownership or a recoverable integration path.", "when_to_use": [ "Many components need the same bounded transformation and can be checked separately.", "A pilot can establish whether partitioning and review save meaningful end-to-end effort." ], "when_not_to_use": [ "The change depends on one unresolved architecture or policy decision shared by all components.", "One maintainer cannot inspect or integrate the proposed work within the available time." ], "prerequisites": [ "An explicit partition map, common migration contract and compatibility checks.", "Isolated write areas with one owner per target and a named integration owner." ], "steps": [ "Run a representative unit first to expose hidden coupling, oracle gaps and the actual review burden.", "Define worker inputs, permitted targets, expected artifacts and stop conditions; reserve shared interfaces for a designated owner.", "Dispatch only independent units up to the capacity of checking and integration, recording assignments and leases.", "Collect each candidate with baseline identity, changed paths, compatibility evidence and unresolved exceptions.", "Integrate incrementally, rerun cross-unit behavior checks and suspend further dispatch if the pilot assumptions fail." ], "example": "Illustrative example: A team considers migrating several isolated configuration readers to a common representation. Two readers form a pilot with stored behavior cases. One exposes a shared parser assumption, so its dependent readers remain serial. Independent readers can proceed in separate workspaces, while an integrator compares their accepted outputs and records the extra review time before expanding the batch.", "verification": [ "No two active assignments can change the same logical target or silently diverge on the migration contract.", "Per-unit checks and integration checks preserve the required old and new behavior.", "The comparison includes rejected patches, coordination, review, elapsed time and follow-up work." ], "outputs": [ "Partition and dependency map with per-unit evidence bundles.", "Integrated candidate, exceptions and an observed pilot cost record." ], "risks": [ "Duplicating an incorrect transformation multiplies rework across the batch.", "A large arrival rate can overload reviewers and increase the time to an accepted migration." ], "related_practices": [ "PAT:019", "PAT:031", "PAT:056" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 5's thematic guidance. The historical family is F05. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:002", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C05", "file": "EN/chapters/chapter05.tex", "line": 3, "sha256": "f6e123ae06931297b82554424c5b9b9c4b6bdb00e897814d515d11203e684075", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C05", "title": "Quality, Architecture and Maintainability", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:02" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Architecture and modularity", "K:Code reuse and duplication", "K:Technical debt and complexity" ], "volumes": [ "V06" ], "families": [ "FAMILY:F05" ] }, { "id": "PAT:003", "label": "Background Agent CI", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Run a bounded agent task in a background continuous-integration context and publish a candidate with traceable checks. The task may prepare or repair work within its assigned scope, but a successful job is only evidence from that environment. Background execution, merge authority, production access and release approval remain separate decisions.", "limitation": "A green CI job covers its configured checks and environment; it does not establish release readiness or authorize production effects.", "url": "", "authors": "", "year": "", "attributes": { "label": "Background Agent CI", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Companion variant", "required_revision": "Treat CI and background execution as variants; CI is not production and green does not mean release.", "occurrences": "[\"AGENT:03\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A green CI job covers its configured checks and environment; it does not establish release readiness or authorize production effects.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Use unattended execution where its trigger, permissions, artifacts and termination can be made explicit and reviewed later.", "when_to_use": [ "A repeatable maintenance task can produce a reviewable patch without interactive clarification.", "Existing CI can capture candidate identity, execution logs and scoped verification results." ], "when_not_to_use": [ "The task requires a product decision or access that cannot safely be delegated to that job.", "The workflow would merge or release solely because the agent reports success." ], "prerequisites": [ "A trusted trigger, fixed input revision and restricted execution identity.", "A task contract with budgets, allowed writes and an artifact retention policy." ], "steps": [ "Specify the trigger and deduplicate repeated events so the same request does not start competing work.", "Create an isolated candidate workspace and supply only the credentials and operations needed for the permitted task.", "Execute the bounded change while retaining tool failures, attempts, checks and the final candidate identity.", "Publish a patch and evidence as review artifacts, with unresolved issues clearly separated from completed obligations.", "Route the result to the named reviewer; let a distinct authorized workflow decide merge, deployment or cancellation." ], "example": "Illustrative example: A nightly job is allowed to refresh generated API examples from the current schema. It creates a branch, runs the example validator and uploads the diff. If the schema requires a change to the public contract, it stops with that question. Passing validation permits the reviewer to inspect the candidate; it does not cause the service to deploy.", "verification": [ "The displayed checks belong to the exact candidate revision being offered for review.", "A duplicate trigger, timeout or restart does not produce uncontrolled concurrent writes.", "The job cannot acquire release permission from the contents of a repository file or model response." ], "outputs": [ "Reviewable candidate and checks tied to the triggering event.", "Completion, hold or failure record with remaining obligations." ], "risks": [ "Logs and artifacts can retain sensitive input beyond the intended task boundary.", "An apparently healthy background job can create an unnoticed backlog of unreviewed candidates." ], "related_practices": [ "PAT:009", "PAT:039", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 11's thematic guidance. The historical family is F11. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:003", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:03" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:004", "label": "Initializer-Maintainer Dual Agent Architecture", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Distinguish initial setup from continued maintenance when the two activities require different context or permissions. An initializer establishes a reviewable starting state; a maintainer works from that accepted state under a narrower task contract. These are functional configurations that may share one agent implementation, not a requirement to deploy two autonomous agents.", "limitation": "Role names provide no isolation by themselves, and a maintainer can inherit mistakes or overbroad access from setup.", "url": "", "authors": "", "year": "", "attributes": { "label": "Initializer-Maintainer Dual Agent Architecture", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Brief thematic reference", "required_revision": "Present two configurations, not two mandatory agents or broad permissions by default.", "occurrences": "[\"AGENT:04\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Role names provide no isolation by themselves, and a maintainer can inherit mistakes or overbroad access from setup.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RINVIO_BREVE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent one-time scaffolding decisions and privileges from becoming an invisible permanent operating mode.", "when_to_use": [ "Bootstrapping and routine changes have materially different write domains or information needs.", "A long-running project needs a deliberate handoff from initial construction to maintenance." ], "when_not_to_use": [ "A single restricted workflow already handles setup and later work clearly.", "The proposed split merely duplicates agents without changing permissions, evidence or ownership." ], "prerequisites": [ "An owner-approved definition of the initialized state and its verification.", "Separate permission profiles and a handoff artifact tied to a concrete revision." ], "steps": [ "Identify what belongs to setup: initial files, assumptions, dependencies, configuration and checks, with explicit limits on external effects.", "Run initialization with only the additional access it actually needs and record every resulting artifact and unresolved assumption.", "Check the initialized state independently of the initializer's completion list, then have the responsible owner accept or hold it.", "Remove temporary capabilities and provide the maintainer with current state, authoritative constraints and open questions.", "Treat any later need to repeat initialization as a new scoped request, preserving maintenance history and rechecking affected obligations." ], "example": "Illustrative example: A starter workflow may create a repository skeleton and propose a dependency file. After review, a maintenance workflow receives permission to edit a feature directory and run local checks. It receives no package-publishing access. If a later task requires changing the build system, that becomes a separately reviewed scope change instead of quietly restoring the initializer's privileges.", "verification": [ "The maintainer's effective permissions match its declared configuration after handoff.", "The accepted initial revision and remaining uncertainties are recoverable without replaying chat history.", "Setup checks cannot be substituted for evidence about a later maintenance candidate." ], "outputs": [ "Accepted setup manifest and explicit maintenance profile.", "Handoff record containing current state, ownership and unresolved assumptions." ], "risks": [ "A ceremonial two-agent design can increase coordination without reducing uncertainty.", "Unreviewed setup defaults can become entrenched dependencies that later work treats as authoritative." ], "related_practices": [ "PAT:001", "PAT:072", "PAT:073" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:004", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:04" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:005", "label": "Feature List as Immutable Contract", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Represent approved feature obligations as a versioned contract that the implementation process can consult but cannot silently rewrite. The contract is stable within a review revision, while approved changes create a new revision and impact assessment. A maker-maintained status field records progress; it is not independent acceptance evidence for the feature.", "limitation": "Immutability preserves a revision, not the correctness or completeness of its requirements; legitimate changes still require an accountable path.", "url": "", "authors": "", "year": "", "attributes": { "label": "Feature List as Immutable Contract", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Apply the critical qualification", "required_revision": "The contract is immutable for a review revision; a maker's passes field does not attest acceptance.", "occurrences": "[\"AGENT:05\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Immutability preserves a revision, not the correctness or completeness of its requirements; legitimate changes still require an accountable path.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep generated code, tests and progress reporting anchored to the same approved behavioral obligations.", "when_to_use": [ "Several implementation attempts must be compared against one stable feature definition.", "A team needs to distinguish proposed requirements, accepted obligations and delivered evidence." ], "when_not_to_use": [ "The feature's decisive behavior is still unresolved and a frozen checklist would conceal the question.", "The list is used as a substitute for scenarios, constraints or review judgment." ], "prerequisites": [ "Stable obligation identifiers with an owner, revision and approval record.", "Scenarios or other independent expectations that explain what fulfilling each obligation means." ], "steps": [ "State obligations in observable terms and separate them from suggested implementation steps, optional ideas and unresolved questions.", "Protect the approved revision from routine implementation writes; retain a readable source of authority and change process.", "Link candidate changes and checks to obligation identifiers, allowing incomplete or blocked states without rewriting the obligation.", "When scope legitimately changes, obtain the authorized delta and identify affected scenarios, code, evidence and earlier decisions.", "Present the completed candidate with its contract revision and evidence; let the designated acceptance authority make the final disposition." ], "example": "Illustrative example: A feature list requires an export to omit archived records and preserve a stable ordering. The maker marks both items as implemented and links its checks. A reviewer discovers that archived records still appear under one filter. The contract stays unchanged, the first item returns to an unresolved state, and the candidate requires repair before acceptance.", "verification": [ "Every completion claim identifies both the obligation revision and the evidence supporting it.", "A status toggle cannot alter the approved expected behavior or overwrite a failed check.", "Authorized deltas have an owner and an impact set, including previously accepted evidence that needs renewal." ], "outputs": [ "Versioned feature contract and approved change history.", "Trace from each obligation to candidate evidence and acceptance disposition." ], "risks": [ "Checkbox completion can hide interactions and nonfunctional obligations absent from the list.", "Freezing a mistaken requirement indefinitely can turn traceability into resistance to necessary correction." ], "related_practices": [ "PAT:043", "PAT:061", "PAT:076" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 4's thematic guidance. The historical family is F04. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:005", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:05" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:006", "label": "Context Window Anxiety Management", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Manage finite conversation context through explicit task state, selective retrieval and checked compaction. Observe practical symptoms such as lost constraints, repeated investigation or stale assumptions rather than diagnosing an agent's feelings. A smaller context is useful only if the resumed process retains the current objective, evidence, remaining work and permission boundaries.", "limitation": "Compaction is lossy and a persistent file can be stale or incorrect; neither token reduction nor fluent continuation proves faithful state recovery.", "url": "", "authors": "", "year": "", "attributes": { "label": "Context Window Anxiety Management", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Retain with explicit qualifications", "required_revision": "Avoid anthropomorphic diagnosis; make compaction measurable and preserve task state.", "occurrences": "[\"AGENT:06\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Compaction is lossy and a persistent file can be stale or incorrect; neither token reduction nor fluent continuation proves faithful state recovery.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep a long task resumable without relying on every prior conversation turn remaining available to the model.", "when_to_use": [ "Work spans long sessions or repeated agent restarts with significant intermediate decisions.", "Repeated rediscovery or forgotten constraints suggest the current context strategy is failing." ], "when_not_to_use": [ "A short task has little state and a checkpoint system would exceed its useful complexity.", "The proposed summary omits unresolved questions merely to make the record appear complete." ], "prerequisites": [ "A typed state record separating approved intent, observations, candidate work and assumptions.", "Versioned source locators and an owner who can resolve uncertain authority or stale information." ], "steps": [ "Identify the minimum resume state: current revision, objective, limits, observations, unresolved questions, spent budget and next decision.", "Write a checkpoint before compaction, retaining links to fuller evidence instead of copying every log into the summary.", "Compare the checkpoint against authoritative task records and explicitly label uncertain or historical material.", "Resume from the checkpoint and retrieve detailed evidence only when the next action requires it.", "Check for repeated work, missed constraints and stale claims; revise the checkpoint format when a concrete information loss is found." ], "example": "Illustrative example: A migration pauses after two of five modules pass compatibility checks. Its checkpoint names the source revision, completed modules, one unresolved parser assumption and the remaining budget. On restart, the agent reopens the parser evidence before changing the third module. It does not infer permission to widen the migration from a shortened summary saying only that work is unfinished.", "verification": [ "A resumed worker can identify the next permitted action and outstanding decision without reconstructing the whole conversation.", "Sampled evidence and current constraints survive compaction with their provenance and status intact.", "Restarted work preserves spent budget and does not silently redo or contradict accepted increments." ], "outputs": [ "Compact resume record with versioned evidence links.", "Observed compaction defects and a corrected state format." ], "risks": [ "A polished summary can launder a tentative assumption into an apparent instruction.", "Overcompaction can remove the counterexample or failed attempt needed to avoid repeating a mistake." ], "related_practices": [ "PAT:020", "PAT:029", "PAT:072" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:006", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:06" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:007", "label": "Compounding Engineering", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Turn experience from completed work into candidate reusable guidance, retaining the event, evidence, applicability and review history behind each lesson. Future tasks retrieve and evaluate that guidance in their own context. This is an operational memory practice; adding notes to a repository does not train model weights or guarantee that engineering performance improves.", "limitation": "A lesson may be locally useful and still fail elsewhere; repeated retrieval can amplify an outdated or poorly supported conclusion.", "url": "", "authors": "", "year": "", "attributes": { "label": "Compounding Engineering", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Retain with explicit qualifications", "required_revision": "Retain candidate lessons with provenance; memory reuse is neither training nor guaranteed improvement.", "occurrences": "[\"AGENT:07\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A lesson may be locally useful and still fail elsewhere; repeated retrieval can amplify an outdated or poorly supported conclusion.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make useful engineering experience available for later decisions without treating every past workaround as a permanent rule.", "when_to_use": [ "Teams repeatedly encounter a diagnosable failure that could be prevented by a reusable check or instruction.", "A completed change reveals an assumption worth preserving for maintainers." ], "when_not_to_use": [ "The task produced no verified observation beyond a plausible model explanation.", "A temporary exception would be recorded as a universal instruction without review." ], "prerequisites": [ "An event record containing the attempted change, observed outcome and relevant versions.", "An owner and review process for admitting, revising, invalidating or retiring guidance." ], "steps": [ "Capture the specific situation, failed expectation and evidence before summarizing a proposed lesson.", "Separate the observation from the inferred recommendation, naming the conditions under which that recommendation might apply.", "Test the candidate guidance on a relevant case or obtain informed review; retain uncertainty when no evaluation is available.", "Publish approved guidance with its owner, scope, source links and triggers for renewal or invalidation.", "When reused, record whether it helped the new task and correct or retire it if the assumptions no longer hold." ], "example": "Illustrative example: A team finds that a data export's nondeterministic ordering caused an intermittent comparison failure. It records the evidence and adds a scoped recommendation to make ordering expectations explicit in export tests. The note identifies the affected component and version. When another service retrieves the lesson, its maintainer checks the actual ordering contract before adopting the recommendation.", "verification": [ "A reader can trace each recommendation to an observation and distinguish evidence from editorial inference.", "The guidance states where it applies and how a later policy or dependency change could invalidate it.", "Any claimed improvement uses observed accepted outcomes and includes maintenance cost and unsuccessful reuse." ], "outputs": [ "Reviewed lesson records with applicability and provenance.", "Reuse observations and a visible retirement or correction history." ], "risks": [ "A memorable anecdote may be mistaken for evidence of a generally effective method.", "An accumulating rule set can increase context conflicts and maintenance burden instead of reducing them." ], "related_practices": [ "PAT:016", "PAT:028", "PAT:059" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:007", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:07" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:008", "label": "Agent-Powered Codebase Q&A and Onboarding", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Use an agent to answer repository questions through identifiable code, tests, design decisions and current policy records. Answers should expose their evidence, uncertainty and version scope, then support a concrete understanding task. Retrieving the right passage and helping a maintainer predict or change behavior are separate outcomes that need different checks.", "limitation": "A plausible answer with relevant citations can still omit a decisive dependency; retrieval quality alone does not establish codebase comprehension.", "url": "", "authors": "", "year": "", "attributes": { "label": "Agent-Powered Codebase Q&A and Onboarding", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Recompose the mechanism", "required_revision": "Make answers traceable and distinguish comprehension tasks from retrieval tasks.", "occurrences": "[\"AGENT:08\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A plausible answer with relevant citations can still omit a decisive dependency; retrieval quality alone does not establish codebase comprehension.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Reduce the cost of finding relevant knowledge while retaining a maintainer's ability to challenge the explanation and act on it.", "when_to_use": [ "A newcomer needs a guided route through unfamiliar behavior and its ownership.", "A maintainer must answer a bounded question about an existing implementation before proposing a change." ], "when_not_to_use": [ "The agent has no access to the current revision or the source needed for the question.", "An answer would decide intended policy from observed legacy behavior without the policy owner's input." ], "prerequisites": [ "A known repository revision and accessible authoritative design or intention records.", "A question with observable scope, plus a maintainer able to resolve missing context." ], "steps": [ "State the question precisely, separating current behavior, intended behavior, historical rationale and how to make a change.", "Retrieve the smallest relevant set of code paths, tests and decisions, recording locators and applicable revisions.", "Construct an explanation that follows the behavior across boundaries and labels any unverified inference or missing source.", "Ask the learner to predict an outcome, locate a counterexample or explain an invariant using the retrieved evidence.", "Check that task against the code and contract, correct the explanation and preserve useful source links for future onboarding." ], "example": "Illustrative example: A newcomer asks why a replayed request returns an older policy decision. The agent identifies the storage lookup, identity rule and approved replay invariant. The newcomer then predicts what happens for the same key with a changed payload and traces the conflict path. Finding those files is a retrieval success; making the correct prediction tests a different aspect of understanding.", "verification": [ "Every material factual assertion has a locator that matches the revision under discussion.", "The answer distinguishes a code observation from a requirement and states meaningful gaps.", "The learner completes a behavior prediction or small change without merely repeating the agent's explanation." ], "outputs": [ "Code-anchored answer or short tour with uncertainty and ownership notes.", "Separate retrieval and comprehension observations, plus any corrected explanation." ], "risks": [ "Fluent summaries can conceal a missing call path or normalize an inherited defect.", "Immediate confidence or successful copying can be mistaken for durable independent understanding." ], "related_practices": [ "PAT:029", "PAT:048", "PAT:053" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:008", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:08" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:009", "label": "CI-as-Backpressure", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Use continuous-integration failures as a signal to limit further admission or repair within an existing task. A failed check can identify a concrete diagnostic and stop a branch from advancing until the relevant obligation is addressed. It does not enlarge the agent's scope, convert unrelated failures into assigned work or authorize changing the expected result.", "limitation": "CI only supplies the signals its checks can observe; a failing job may reflect infrastructure or stale expectations rather than a defect in the candidate.", "url": "", "authors": "", "year": "", "attributes": { "label": "CI-as-Backpressure", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 8, "disposition": "Recompose the mechanism", "required_revision": "A CI failure blocks a branch within scope and policy; it does not authorize unrelated repairs.", "occurrences": "[\"AGENT:09\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "CI only supplies the signals its checks can observe; a failing job may reflect infrastructure or stale expectations rather than a defect in the candidate.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent a stream of unchecked candidates from overwhelming verification and review while keeping repair decisions tied to evidence.", "when_to_use": [ "Agents produce candidates faster than the team can verify or review them.", "A required check supplies a concrete failure that can guide a bounded correction." ], "when_not_to_use": [ "The proposed response is to keep retrying an unexplained failure until one run passes.", "The job failure concerns a separate component outside the authorized task." ], "prerequisites": [ "Explicit required checks and branch-progression rules owned by the project.", "An attempt record linking candidate revision, failure diagnostic, scope and remaining budget." ], "steps": [ "Capture the failing command, environment, candidate identity and relevant diagnostic before modifying anything.", "Classify whether the failure is introduced, pre-existing, environmental, uncertain or based on superseded expectations.", "For an in-scope defect, return a narrowly described repair request with the unchanged contract and protected oracle.", "Hold admission or progression according to the established policy while the required evidence is missing.", "Escalate unrelated or unexplained failures to their owner, preserving the failed result and the reason further work stopped." ], "example": "Illustrative example: A documentation-generation agent produces a candidate whose required example validator fails on one changed code sample. The agent may repair that sample and rerun its checks. A separate database integration job also fails because its service is unavailable. The record classifies the infrastructure failure and holds the required status; it does not rewrite database code to make the dashboard green.", "verification": [ "A retry follows a named diagnostic and is charged to the same persistent budget.", "The branch cannot advance using a passing result from a different revision or a removed required check.", "The hold identifies the missing evidence and the role able to resolve it." ], "outputs": [ "Failure classification with a bounded repair or escalation record.", "Current verification status and admission or progression decision." ], "risks": [ "Optimizing for a green dashboard can encourage weakening checks or hiding failures.", "An unchecked inflow of candidates can move the bottleneck into review despite fast local repairs." ], "related_practices": [ "PAT:003", "PAT:026", "PAT:036" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 11's thematic guidance. The historical family is F11. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:009", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:09" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:010", "label": "Inference-Healed Code Review", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Productivity", "T:Verification & review" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Turn a review finding into a bounded repair only after identifying the affected behavior and checking the finding's basis. The maker proposes a correction, reruns relevant evidence and returns the changed candidate for review. The loop treats AI comments as testable hypotheses, retaining dismissed findings and unresolved uncertainty instead of assuming the reviewer is correct.", "limitation": "A repair can satisfy a mistaken review comment while introducing a real defect; agreement between maker and reviewer is not independent evidence.", "url": "", "authors": "", "year": "", "attributes": { "label": "Inference-Healed Code Review", "kind": "practice_descriptor", "collection": "PAT", "family": "F08", "chapter": 7, "disposition": "Retain with explicit qualifications", "required_revision": "Repair from concrete feedback; do not place blind trust in an AI reviewer.", "occurrences": "[\"AGENT:10\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A repair can satisfy a mistaken review comment while introducing a real defect; agreement between maker and reviewer is not independent evidence.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Critique, Review and Trust", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make review feedback actionable without letting comment generation become an unexamined source of new requirements.", "when_to_use": [ "A reviewer identifies a reproducible defect, contradicted invariant or concrete gap in the candidate's evidence.", "A bounded repair can be evaluated under the existing approved task." ], "when_not_to_use": [ "The comment is a stylistic preference with no applicable project rule or meaningful consequence.", "The proposed fix changes intended behavior and requires a decision from a different authority." ], "prerequisites": [ "The exact reviewed candidate and a finding with a locator, rationale and confidence boundary.", "Protected acceptance expectations and a named reviewer responsible for the returned candidate." ], "steps": [ "Reproduce the finding or identify the evidence that could distinguish a real defect from a mistaken hypothesis.", "Classify the comment as confirmed, disputed, informational or requiring an authority decision; record the reason.", "For a confirmed in-scope defect, create a narrow repair that preserves the approved behavior and unrelated code.", "Run the focused counterexample and the relevant regression checks against the new candidate.", "Return the diff and fresh evidence, linking the original finding and any remaining dispute for an explicit review disposition." ], "example": "Illustrative example: An AI reviewer warns that replay reads the current policy threshold. The maintainer traces the path and reproduces a failure with a stored older decision. The maker repairs that path and reruns the replay and new-request checks. A separate comment about a possible duplicate transaction is dismissed with the documented conflict behavior, preserving the rationale instead of silently accepting every suggestion.", "verification": [ "A substantive fix has a diagnostic that fails on the defective candidate and is addressed by the repaired one.", "The reviewed revision and supporting evidence are current after the repair.", "Dismissed or unresolved findings retain reasons so apparent silence is not mistaken for verification." ], "outputs": [ "Finding-to-repair trace with reproduction evidence and a bounded diff.", "Fresh review bundle and disposition of each material finding." ], "risks": [ "Repeated self-consistent explanations can reinforce the same incorrect interpretation.", "Repairing low-value comments indiscriminately can consume the attention needed for consequential defects." ], "related_practices": [ "PAT:027", "PAT:052", "PAT:074" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 8's thematic guidance. The historical family is F08. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:010", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:10" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:AI as reviewer", "K:Automation bias and trust", "K:Review capacity and maintainers" ], "volumes": [ "V06" ], "families": [ "FAMILY:F08" ] }, { "id": "PAT:011", "label": "Reward Shaping for Tool Use", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Distinguish training-time reward design from the feedback an operating agent receives after a tool action. This retained conceptual entry helps teams identify what intervention they are actually proposing and what evidence it would require. It is outside the book's execution procedure: ordinary test failures and retry instructions are operational feedback, not proof that model parameters are being trained.", "limitation": "An operational trace cannot establish how training rewards affected a model, and optimizing a proxy reward may not improve the intended engineering outcome.", "url": "", "authors": "", "year": "", "attributes": { "label": "Reward Shaping for Tool Use", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Outside the core execution scope", "required_revision": "Distinguish training rewards from execution feedback; the manual contains no training program.", "occurrences": "[\"AGENT:11\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An operational trace cannot establish how training rewards affected a model, and optimizing a proxy reward may not improve the intended engineering outcome.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "FUORI_CORPO", "practice_scope": "Conceptual entry; outside the core execution scope", "practice": { "schema_version": 1, "language": "en", "purpose": "Avoid applying the language of reward optimization to a workflow change that only changes prompts, tools, checks or retries.", "when_to_use": [ "A proposal claims that rewarding tool use will improve the agent and needs a precise intervention definition.", "A reviewer must compare a training proposal with a simpler runtime correction." ], "when_not_to_use": [ "The immediate task is an ordinary bounded repair that an existing diagnostic can guide.", "There is no controlled training capability, data governance or credible evaluation plan." ], "prerequisites": [ "A clear statement of whether parameters, runtime instructions or orchestration behavior would change.", "A separately governed evaluation plan with relevant outcomes and a credible comparison condition." ], "steps": [ "Classify the proposed mechanism before designing a solution: training update, reward-model evaluation or runtime feedback.", "Define the actual desired outcome, such as a correctly completed permitted task, separately from a proxy like tool-call count.", "Identify how the proxy could be satisfied while the engineering outcome fails, including unnecessary calls or suppressed errors.", "Require evidence that evaluates unseen relevant tasks, permitted effects and full workflow cost before adopting a training claim.", "Keep any training experiment under a separate owner and process; use the book's bounded execution controls for the operational workflow regardless." ], "example": "Illustrative example: A team proposes to reward an agent whenever a test passes. Inspection shows that its current setup merely inserts the test result into the next prompt; no training process exists. The proposal is renamed an execution-feedback loop. If the team later considers training, it must independently test whether the signal encourages correct behavior rather than editing expectations or avoiding difficult cases.", "verification": [ "The intervention description correctly identifies what changes and what remains fixed.", "The evaluation distinguishes the desired outcome from the proxy and includes plausible ways to exploit that proxy.", "Any claimed improvement has evidence beyond the examples used to construct the intervention." ], "outputs": [ "Intervention classification and decision to use runtime feedback or assess a separately governed training proposal.", "Evaluation questions and explicit evidence gaps." ], "risks": [ "Calling all positive feedback a reward can hide the absence of a training mechanism.", "A convenient scoring signal can favor behavior that looks successful while missing scope, correctness or authority." ], "related_practices": [ "PAT:013", "PAT:026", "PAT:059" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study. This conceptual entry remains outside the book body and supplies no model-training implementation.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:011", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:11" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:012", "label": "AI-Accelerated Learning and Skill Development", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Jobs & roles", "T:Skills & learning" ], "actual": [], "mapped": [ "C:C10", "C:C13" ], "printed": false, "summary": "Use AI assistance within a deliberate learning task that preserves the learner's own prediction, explanation, diagnosis and repair. A mentor can adjust the assistance and inspect reasoning, while later unaided work tests transfer. Faster completion of the assisted task is recorded separately from learning; no general gain in skill or retention follows from the practice name.", "limitation": "Immediate task success and perceived clarity do not establish retained competence; assistance can also remove the practice that a learner needs.", "url": "", "authors": "", "year": "", "attributes": { "label": "AI-Accelerated Learning and Skill Development", "kind": "practice_descriptor", "collection": "PAT", "family": "F10", "chapter": 10, "disposition": "Recompose the mechanism", "required_revision": "Describe mentoring mechanisms, not generalized gains in learning.", "occurrences": "[\"AGENT:12\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Immediate task success and perceived clarity do not establish retained competence; assistance can also remove the practice that a learner needs.", "historical_structural_chapters": [ "C:C10" ], "family_name": "Competence, Learning and Mentoring", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make assistance serve a stated learning objective while keeping evidence of independent reasoning visible to the learner and mentor.", "when_to_use": [ "A newcomer needs to understand an invariant or unfamiliar subsystem before owning changes.", "A team wants to evaluate whether its assisted workflow preserves opportunities for skill development." ], "when_not_to_use": [ "The learner only copies a completed answer and no independent reasoning task is planned.", "An urgent delivery task cannot accommodate teaching; record that limitation rather than claiming it as training." ], "prerequisites": [ "A specific competence target and a mentor able to evaluate the reasoning.", "A suitable exercise and a distinct later task for checking unaided transfer." ], "steps": [ "Ask the learner to predict behavior or propose a diagnostic before revealing an assisted answer.", "Provide limited help appropriate to the observed difficulty, such as a code locator, explanation or counterexample.", "Have the learner repair or extend the candidate and explain the governing invariant in their own terms.", "Review the reasoning and the software result separately, recording what help was used and what remains uncertain.", "Return later with a different unaided task that needs the same underlying concept, then adjust the mentoring approach from the observation." ], "example": "Illustrative example: A learner predicts how an old request should replay after a policy change. The assistant locates the storage code, and a senior asks the learner to identify a deliberately wrong implementation. The learner constructs a failing example and repairs it. On a later task with a different state transition, the mentor checks whether the learner can apply the same reasoning without the earlier hints.", "verification": [ "The learner's prediction, explanation or diagnostic exists separately from the assistant's generated text.", "Correct code is checked against the contract independently of the educational assessment.", "The record distinguishes immediate assisted success, unaided performance and any later follow-up that is still unknown." ], "outputs": [ "Learning objective, assistance record and mentor feedback.", "Independent-task observations with explicit limits on retention claims." ], "risks": [ "A fluent explanation may create confidence without a transferable mental model.", "Comparing unmatched exercises or learners can falsely attribute improvement to the assistant." ], "related_practices": [ "PAT:048", "PAT:050", "PAT:055" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 10's thematic guidance. The historical family is F10. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:012", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C10", "file": "EN/chapters/chapter10.tex", "line": 3, "sha256": "8c1523efe9ff14e391995db26334a679c629258003f891389e55b9183e57f36f", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C10", "title": "Developer Learning, Mentoring and Comprehension Debt", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:12" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Cognitive offloading and skill debt", "K:Human cognitive load", "K:Onboarding and developer fluency", "K:Remote work and apprenticeship", "K:Skills formation and teaching" ], "volumes": [ "V06" ], "families": [ "FAMILY:F10" ] }, { "id": "PAT:013", "label": "Agent Reinforcement Fine-Tuning", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Treat reinforcement fine-tuning for an agent as a separate model-development proposal, outside the book's operational execution scope. Before considering it, define the observed failure, identify whether context or orchestration can address it, and specify an independent evaluation. A new model variant still needs the same external permissions, budgets, protected expectations and accountable acceptance process.", "limitation": "Training a model does not confer authorization, reliable tool use or general task competence; an evaluation can support only the tested setting and outcomes.", "url": "", "authors": "", "year": "", "attributes": { "label": "Agent Reinforcement Fine-Tuning", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 0, "disposition": "Outside the core execution scope", "required_revision": "RFT is outside the execution scope; retain a note on model limits without provider-specific instructions.", "occurrences": "[\"AGENT:13\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Training a model does not confer authorization, reliable tool use or general task competence; an evaluation can support only the tested setting and outcomes.", "historical_structural_chapters": [], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "FUORI_CORPO", "practice_scope": "Conceptual entry; outside the core execution scope", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep a specialized training decision from becoming an assumed prerequisite for solving ordinary engineering workflow problems.", "when_to_use": [ "A model-development team proposes fine-tuning as a response to a recurring, well-characterized agent failure.", "A reviewer needs to compare that proposal with simpler changes to context, tools or verification." ], "when_not_to_use": [ "The failure is caused by missing authority, stale data or an inadequate oracle.", "There is no separately authorized model-development process or relevant independent evaluation data." ], "prerequisites": [ "A reproducible failure description and baseline model or workflow version.", "Named ownership for training data, evaluation, cost, access and any deployment decision." ], "steps": [ "Describe the failed engineering outcome and separate model behavior from failures of inputs, permissions or surrounding systems.", "Evaluate whether a scoped runtime intervention can answer the problem before proposing a change to model parameters.", "For a genuine training proposal, require an explicit objective, data provenance and a held-out evaluation appropriate to the task.", "Compare candidates under the same authorized tasks and controls, retaining failures, review effort, costs and uncertainty.", "Adopt, hold or reject the proposal through its own governance process; retain the external execution and acceptance boundaries for any deployed variant." ], "example": "Illustrative example: An agent repeatedly chooses an outdated API and the team considers fine-tuning. Investigation finds that its retrieved documentation comes from an obsolete dependency revision. The team corrects retrieval and reevaluates the workflow first. A later training proposal, if still warranted, must demonstrate value on distinct relevant tasks and cannot use the proposed model's own judgments as the sole acceptance evidence.", "verification": [ "The diagnosed failure remains after correcting obvious context or orchestration defects.", "The comparison separates training examples from independent evaluation and states what has not been established.", "The deployed model cannot override tool permissions or declare its own changes accepted." ], "outputs": [ "Training-proposal decision with alternative interventions and evidence gaps.", "Evaluation and deployment requirements owned outside the ordinary task loop." ], "risks": [ "A training investment can mask an unresolved contract or poor information supply.", "Narrow evaluation gains can be overgeneralized to different repositories, task classes or operational consequences." ], "related_practices": [ "PAT:011", "PAT:030", "PAT:065" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study. This conceptual entry remains outside the book body and supplies no model-training implementation.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:013", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Model-limit context; this training variant remains outside core execution; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Model-limit context; this training variant remains outside core execution" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:13" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:014", "label": "Deterministic Failure Harness", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Verification & review", "T:What agents can do" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Build a repeatable failure harness around a concrete behavioral obligation, fixing the relevant candidate, inputs, expected results and environment. The harness makes a selected defect inspectable and supports bounded repair. Its repeatability is conditional on controlled dependencies and the oracle's quality; it is not evidence that all defects are captured or that the system is generally deterministic.", "limitation": "A harness can reliably reproduce the wrong expectation, and uncontrolled time, concurrency or external dependencies may still make runs vary.", "url": "", "authors": "", "year": "", "attributes": { "label": "Deterministic Failure Harness", "kind": "practice_descriptor", "collection": "PAT", "family": "F07", "chapter": 7, "disposition": "Apply the critical qualification", "required_revision": "Repeatability is conditional on environment and oracle; do not claim completeness or guaranteed defect detection.", "occurrences": "[\"AGENT:14\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A harness can reliably reproduce the wrong expectation, and uncontrolled time, concurrency or external dependencies may still make runs vary.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Tests, Oracles and Acceptance Evidence", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Turn an ambiguous failure report into a diagnostic that another reviewer can reproduce and use to assess a repair.", "when_to_use": [ "A candidate violates a known invariant and the failure can be isolated without changing the required behavior.", "A repair loop needs a stable diagnostic instead of vague reviewer disapproval." ], "when_not_to_use": [ "The intended outcome is unresolved and the harness would freeze an unapproved assumption.", "The test arrangement removes the boundary or timing condition responsible for the actual defect." ], "prerequisites": [ "Expected behavior derived from an authorized source independently of the faulty candidate.", "Versioned fixtures, commands and environment details sufficient to explain the run." ], "steps": [ "Name the obligation and select a minimal counterexample that distinguishes required behavior from the observed defect.", "Control relevant state, clocks, randomness and dependency versions where the test permits it, recording remaining variability.", "Verify that the defective candidate fails for the intended reason, not because setup or infrastructure is broken.", "Apply a bounded repair and run the same protected expectations against the new candidate.", "Retain the old failure, new result and environment record, then add wider checks for affected behavior without claiming exhaustive coverage." ], "example": "Illustrative example: A replay bug appears only after reopening a service under a new policy. The harness stores a first decision, closes the service, reopens it with the new policy and checks the original response identity. The faulty candidate fails that invariant. A repaired candidate must pass the same expectation, while a separate new-request case checks that current policy still applies where intended.", "verification": [ "A known defective candidate is rejected by the intended assertion, providing a meaningful negative control.", "Repeated runs under the documented conditions have explainable outcomes and expose unresolved sources of variation.", "Passing the harness leaves untested behavior and any production-environment differences explicitly visible." ], "outputs": [ "Reproducible failure fixture and protected expectation with provenance.", "Candidate-bound run records and a statement of remaining coverage limits." ], "risks": [ "Over-mocking can remove the interaction that causes the defect in the real system.", "Changing expected results during repair can produce a repeatable but circular demonstration of success." ], "related_practices": [ "PAT:015", "PAT:027", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 7's thematic guidance. The historical family is F07. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:014", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:14" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dataset provenance and dependency", "K:Independent verification and oracles" ], "volumes": [ "V06" ], "families": [ "FAMILY:F07" ] }, { "id": "PAT:015", "label": "Regression Safety Net", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Verification & review", "T:What agents can do" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Maintain a regression set that checks both the newly authorized behavior and existing obligations left unchanged by the task. Identify each expectation's applicable revision and record the baseline result before interpreting a failure. Pre-existing defects remain visible and require classification; discovering them does not automatically authorize repairs outside the current scope.", "limitation": "A passing regression suite covers its chosen assertions and environment; missing cases and mistaken expectations can leave consequential defects undetected.", "url": "", "authors": "", "year": "", "attributes": { "label": "Regression Safety Net", "kind": "practice_descriptor", "collection": "PAT", "family": "F07", "chapter": 7, "disposition": "Retain with explicit qualifications", "required_revision": "Require regressions and impact analysis; classify pre-existing failures without automatically expanding scope.", "occurrences": "[\"AGENT:15\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A passing regression suite covers its chosen assertions and environment; missing cases and mistaken expectations can leave consequential defects undetected.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Tests, Oracles and Acceptance Evidence", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Show that a bounded change satisfies its new obligation without silently breaking behavior the owner expected to preserve.", "when_to_use": [ "A maintenance change affects behavior with existing users, stored history or compatibility obligations.", "An authorized policy delta changes some expected results while leaving other invariants intact." ], "when_not_to_use": [ "The suite simply mirrors the implementation and has no independently justified expectations.", "Historical failures are being removed or rewritten solely to make the current candidate appear healthy." ], "prerequisites": [ "An identified baseline and a record of the current suite's results.", "Versioned obligations and a candidate impact map that a maintainer can challenge." ], "steps": [ "Run or inspect the baseline checks and preserve failures, skipped coverage and environment limitations.", "Classify expectations as unchanged invariants, revised behavior, historical behavior or uncertain requirements.", "Add targeted cases for the authorized delta and its boundaries while protecting expectations that should remain unchanged.", "Run the required regression suite on the candidate, investigating unexpected failures without assuming every failure was introduced by the patch.", "Present baseline and candidate outcomes with failure classifications, impact reasoning and unresolved decisions for acceptance review." ], "example": "Illustrative example: A policy change lowers a limit for new requests. The regression set checks the new threshold, unchanged high-risk handling and replay of an older stored decision. One unrelated formatting test was already failing on the baseline. The maintainer records that separately and applies the project's progression policy; the agent cannot silently reformat an unrelated module simply because it encountered the failure.", "verification": [ "Each changed expected result traces to an authorized delta rather than the candidate's observed output.", "Both newly required behavior and unaffected invariants have relevant checks.", "The report preserves pre-existing and unexplained failures, including whether they block the current decision." ], "outputs": [ "Version-scoped regression matrix and baseline comparison.", "Candidate results, impact assessment and classified outstanding failures." ], "risks": [ "A narrow impact map can omit a hidden consumer, so selected checks may need broader regression evidence.", "Treating old behavior as inherently correct can preserve a bug as a permanent contractual expectation." ], "related_practices": [ "PAT:014", "PAT:044", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 7's thematic guidance. The historical family is F07. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:015", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:15" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dataset provenance and dependency", "K:Independent verification and oracles" ], "volumes": [ "V06" ], "families": [ "FAMILY:F07" ] }, { "id": "PAT:016", "label": "Structured Drift Detection", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Detect when a retained instruction, assumption, test expectation or knowledge record no longer applies to current work. Compare explicit versions and validity scopes, assign an owner to resolve the difference, and trace affected decisions. Superseded material remains available for historical explanation while being excluded from decisions that require the current rule.", "limitation": "Change detection can identify differing bytes or known dependencies, but it cannot by itself determine semantic impact, authority or a complete invalidation set.", "url": "", "authors": "", "year": "", "attributes": { "label": "Structured Drift Detection", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Recompose the mechanism", "required_revision": "Track drift with a version and owner; retain obsolete rules as history rather than current guidance.", "occurrences": "[\"AGENT:16\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Change detection can identify differing bytes or known dependencies, but it cannot by itself determine semantic impact, authority or a complete invalidation set.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent a resumed task from treating yesterday's valid information as today's governing instruction.", "when_to_use": [ "Policy, dependencies or interfaces have changed since a memory card or instruction file was written.", "Several artifacts describe the same obligation and may have diverged in meaning or effective revision." ], "when_not_to_use": [ "The system discards old facts even when historical behavior still depends on them.", "A simple textual mismatch is treated as sufficient authority to rewrite code or approved expectations." ], "prerequisites": [ "Records with source, revision, owner, validity scope and known renewal triggers.", "A current authoritative reference and a way to record disputed or unknown status." ], "steps": [ "Compare the task's current contract and environment against the applicability recorded on instructions, evidence and memory.", "Mark suspected drift explicitly, distinguishing superseded current guidance from historically valid observations.", "Trace candidate impacts through consumers, tests, decisions and handoffs; ask the responsible owner to challenge missing relationships.", "Refresh only the affected guidance and evidence under the authorized revision, retaining the prior record and reason for invalidation.", "Before resumed execution, verify that the selected context no longer presents stale or disputed material as current authority." ], "example": "Illustrative example: A memory card says that new requests use an earlier approval threshold. A policy delta changes that threshold, but older stored decisions must still replay unchanged. The steward marks the card superseded for new requests, retains it for historical explanation and identifies tests needing renewal. The agent cannot solve the drift by deleting every reference to the former rule.", "verification": [ "Current, historical, disputed and unknown claims are distinguishable in the retrieved context.", "Each semantic correction has an accountable owner and an applicable revision.", "Affected checks are renewed against the current candidate, while historical evidence remains traceable." ], "outputs": [ "Drift and invalidation register with owners and candidate impacts.", "Refreshed context or expectations plus preserved superseded records." ], "risks": [ "A dependency graph can miss a consumer and give an incomplete appearance of impact coverage.", "Automatically selecting the newest text can privilege an unauthorized edit over an older authoritative decision." ], "related_practices": [ "PAT:007", "PAT:029", "PAT:072" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:016", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:16" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:017", "label": "Blast Radius Containment", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Limit the consequences of an agent mistake by enforcing permitted reads, writes, external operations, resource use and duration outside the model's own requests. Design containment for the actual task and test representative denials. The result is a constrained execution profile whose residual weaknesses remain explicit, not a claim of absolute security or complete isolation.", "limitation": "An allowlist or teaching broker is not proof of operating-system isolation; shared services, credentials, race conditions and indirect effects need deployment-specific controls.", "url": "", "authors": "", "year": "", "attributes": { "label": "Blast Radius Containment", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Recompose the mechanism", "required_revision": "Limit writes, effects and duration outside the model; do not claim absolute safety.", "occurrences": "[\"AGENT:17\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An allowlist or teaching broker is not proof of operating-system isolation; shared services, credentials, race conditions and indirect effects need deployment-specific controls.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep a plausible but incorrect action from reaching assets or effects that the task has no authority to change.", "when_to_use": [ "A tool-using agent can write files, access sensitive resources or call external services.", "Different work phases require different capabilities and should not share every possible privilege." ], "when_not_to_use": [ "A prompt is the only barrier protecting a consequential resource.", "The proposed isolation claim is based solely on a local simulation rather than the effective deployment controls." ], "prerequisites": [ "A task-specific threat and effect map naming protected assets and accountable owners.", "An execution layer able to enforce and revoke the selected permissions independently of generated text." ], "steps": [ "Identify the exact targets, operations, data and duration needed for the task, including indirect effects through tools.", "Configure the narrowest adequate execution profile, separating read-only discovery, candidate writes and any separately authorized external action.", "Protect the contract, expected results and credentials from the maker's write domain.", "Exercise representative permitted and forbidden actions, retaining denial evidence and any enforcement gaps.", "Monitor actual effects and stop or revoke access when a request crosses scope, expires or exposes an unresolved boundary." ], "example": "Illustrative example: An agent may inspect source files, write a candidate in a dedicated workspace and run checks against synthetic data. A request to rewrite protected expected results is denied by the execution layer, even if the agent says the change is needed to finish. The operator verifies the actual filesystem and credential controls separately from the demonstration that the broker rejects a sample request.", "verification": [ "Effective permissions match the declared task profile, including inherited credentials and network access.", "Negative tests cover meaningful forbidden reads, writes or operations and record the enforcement component.", "Timeout, cancellation and revocation stop new effects without resetting or broadening the original authority." ], "outputs": [ "Execution profile with tested allowed and denied operations.", "Effect and denial log with residual enforcement limitations." ], "risks": [ "A permitted tool can expose a broader operation than its harmless-looking name suggests.", "Isolation of files alone can leave shared databases, services or cost-bearing operations outside the containment boundary." ], "related_practices": [ "PAT:030", "PAT:034", "PAT:077" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 6's thematic guidance. The historical family is F06. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:017", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:17" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:018", "label": "PII and Secret Scrubbing", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Reduce unnecessary exposure of personal information and secrets before material enters an agent's context, logs, artifacts or external destination. Combine data minimization, scoped detection, controlled replacement and handling rules. Scrubbing is an imperfect transformation: a clean scan does not authorize sharing, and retained logs or re-identification clues can still cross the original data boundary.", "limitation": "Detectors and redaction rules can miss sensitive content or damage useful context; masking selected fields does not guarantee anonymity or permitted disclosure.", "url": "", "authors": "", "year": "", "attributes": { "label": "PII and Secret Scrubbing", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Retain with explicit qualifications", "required_revision": "Partial scrubbing does not authorize sharing; logs and retention must respect the data boundaries.", "occurrences": "[\"AGENT:18\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Detectors and redaction rules can miss sensitive content or damage useful context; masking selected fields does not guarantee anonymity or permitted disclosure.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Give the task the least sensitive adequate input while preserving the permissions and retention rules that apply to the source data.", "when_to_use": [ "A debugging or documentation task can use synthetic or minimized examples instead of raw production records.", "Potentially sensitive text would otherwise be copied into prompts, diagnostics or shared artifacts." ], "when_not_to_use": [ "The destination or operation is not authorized even if selected values are removed.", "The task requires identifying information but its access and retention conditions have not been established." ], "prerequisites": [ "A classification of the relevant data and the allowed destinations, purposes and retention periods.", "A controlled transformation path that does not leak originals into temporary files or logs." ], "steps": [ "Map where input may travel, including model context, tool arguments, failures, caches and exported evidence.", "Prefer synthetic or reduced data when it can answer the same engineering question.", "Apply appropriate detection and transformation rules, preserving relationships only when they are needed and permitted.", "Review the transformed result for missed sensitive content and for distortions that would invalidate the task's conclusions.", "Use the approved destination and handling process; retain or remove intermediates according to the source's actual rules." ], "example": "Illustrative example: A maintainer needs an example request that reproduces a parser defect. They construct a synthetic record with the same problematic structure instead of uploading a customer log. A checker confirms that the defect still reproduces. The remaining diagnostic is reviewed for embedded credentials and retained only in the approved task record; passing the scanner does not authorize posting it to an unrelated service.", "verification": [ "The minimized input still reproduces the behavior relevant to the task.", "Checks cover the output and incidental artifacts, with known detector limitations recorded.", "The data owner or applicable authorization permits the destination and use independently of the scrub result." ], "outputs": [ "Minimized or synthetic task input with a transformation record.", "Handling decision and residual sensitivity or fidelity limitations." ], "risks": [ "Rare values and combinations can reveal information even after obvious identifiers are removed.", "A debugging trace or exception can reintroduce an original value after the input was successfully scrubbed." ], "related_practices": [ "PAT:017", "PAT:030", "PAT:058" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 6's thematic guidance. The historical family is F06. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:018", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:18" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:019", "label": "Subagent Spawning and Fan-Out", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Delegate bounded, genuinely independent subtasks when their outputs can be integrated and checked within available capacity. Each subagent receives a clear target, contract revision, permissions, evidence requirements and stopping rule. Fan-out is a conditional coordination choice; the right concurrency follows dependencies and reviewer load, not a fixed or maximized worker count.", "limitation": "More workers can increase duplicate effort, conflicting assumptions and integration load; independent execution does not imply independent evidence or faster delivery.", "url": "", "authors": "", "year": "", "attributes": { "label": "Subagent Spawning and Fan-Out", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Recompose the mechanism", "required_revision": "Condition fan-out on dependencies and capacity, not a fixed number of workers.", "occurrences": "[\"AGENT:19\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "More workers can increase duplicate effort, conflicting assumptions and integration load; independent execution does not imply independent evidence or faster delivery.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Use concurrency to address a real partitionable workload while preserving ownership and a coherent final result.", "when_to_use": [ "Read-only investigations or implementation units have distinct questions and explicit integration points.", "The coordinator can review and reconcile the expected outputs without creating a larger bottleneck." ], "when_not_to_use": [ "Several workers would need to resolve the same open policy decision.", "The subtasks share an uncontrolled mutable target or exceed the available checking capacity." ], "prerequisites": [ "A dependency and ownership map with a named coordinator.", "A shared authorized objective and bounded per-worker access, budget and expected output." ], "steps": [ "Identify which work is independent and what must remain serial, including shared interfaces and authority decisions.", "Assign each worker a distinct deliverable, required source revision and criteria for returning evidence or escalating uncertainty.", "Limit concurrency according to execution and review capacity, reserving time to integrate and verify results.", "Track progress and reassignment explicitly; cancel or hold affected workers if the contract changes or a dependency is invalidated.", "Integrate the outputs against the common objective and rerun checks that cross worker boundaries before presenting the final candidate." ], "example": "Illustrative example: One worker inventories a public API, another inspects its tests, and a third investigates a separate documentation gap. Their tasks are read-only and each returns source locators and uncertainties. The coordinator uses those findings to assign one implementation owner. It does not dispatch three competing edits to the same API merely because three agents are available.", "verification": [ "Each active worker can name its unique target, input revision and exit condition.", "The coordinator detects duplicate logical work and invalidates stale assignments after a relevant change.", "The integrated result has cross-boundary evidence beyond the individual workers' completion claims." ], "outputs": [ "Assignment and dependency record with bounded worker outputs.", "Integrated evidence and a decision on whether concurrency was worth its coordination cost." ], "risks": [ "Workers can agree on an incorrect shared assumption and make that error appear corroborated.", "Unbounded fan-out can spend budget and reviewer attention before useful intermediate findings are available." ], "related_practices": [ "PAT:031", "PAT:032", "PAT:056" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 11's thematic guidance. The historical family is F11. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:019", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:19" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:020", "label": "File-System as State Machine", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Represent long-running task state in explicit durable artifacts with validated transitions, controlled writes and recoverable history. The filesystem is a storage substrate, not the state machine's authority. Correct operation also requires ownership, schema validation, concurrency handling and a clear account of what was committed before interruption or restart.", "limitation": "Files alone do not provide transactional atomicity, authenticated decisions or safe concurrent updates; those guarantees depend on the implemented storage and execution controls.", "url": "", "authors": "", "year": "", "attributes": { "label": "File-System as State Machine", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Retain with explicit qualifications", "required_revision": "Persist state through controlled writes; the filesystem alone provides neither atomicity nor authenticity.", "occurrences": "[\"AGENT:20\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Files alone do not provide transactional atomicity, authenticated decisions or safe concurrent updates; those guarantees depend on the implemented storage and execution controls.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make a task's current state and legal next action reconstructable without trusting a conversational claim that a stage completed.", "when_to_use": [ "A task must pause, resume or hand off while preserving attempts, evidence and remaining budget.", "Several processing stages need explicit input, output and completion identities." ], "when_not_to_use": [ "Multiple writers overwrite the same status file without a concurrency or ownership protocol.", "The mere presence of a file is interpreted as proof of approval or successful execution." ], "prerequisites": [ "A state schema with named transitions, required evidence and a responsible writer.", "A write and recovery mechanism appropriate to the storage system and concurrency model." ], "steps": [ "Define states such as active, waiting for evidence, held and ready for review, separating them from acceptance decisions.", "Associate each transition with the task, candidate revision, prior state, event identity and required supporting artifacts.", "Validate proposed updates and commit them through the controlled writer, retaining enough history to identify partial or repeated events.", "On restart, reconcile the durable state with actual artifacts and execution results; preserve spent budget rather than starting a new allowance.", "Reject stale, conflicting or unsupported transitions and route uncertain recovery to the designated owner." ], "example": "Illustrative example: A task writes a candidate and begins a check, then the process stops before recording the result. On restart, the state reader finds no completed evidence event for that candidate. It does not mark the task ready merely because a log file exists. The controller verifies the artifacts, records the interrupted attempt and reruns the required check within the remaining budget.", "verification": [ "Interrupted updates and duplicate events leave an explainable state rather than a false completion marker.", "Only the intended writer can change protected state or authoritative records.", "A resumed task can recover candidate identity, unresolved work, prior failures and cumulative budget." ], "outputs": [ "Versioned state and event records with artifact references.", "Recovery procedure and explicit unsupported or disputed transitions." ], "risks": [ "A compact status file can drift from the actual files unless transitions bind their identities.", "A homemade journal can appear robust in sequential tests while failing under concurrent or interrupted writes." ], "related_practices": [ "PAT:006", "PAT:032", "PAT:072" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:020", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:20" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:021", "label": "Tool Call Budget", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Cap tool use as one dimension of a bounded agent task and enforce the counter outside the model. Record consumed calls across retries, subprocesses and restarts, and check the remaining allowance before dispatch. A call limit controls activity, but calls differ in cost, duration and external effects, so it is not a complete spending or authority limit.", "limitation": "One expensive or consequential call can exceed the practical risk or cost of many harmless calls; a count alone does not bound money, time or effects.", "url": "", "authors": "", "year": "", "attributes": { "label": "Tool Call Budget", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Recompose the mechanism", "required_revision": "The tool-call limit is one dimension of Budget-Gated Autonomy (PAT:083; historical alias SDD2:D3), not a synonym for maximum cost.", "occurrences": "[\"AGENT:21\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "One expensive or consequential call can exceed the practical risk or cost of many harmless calls; a count alone does not bound money, time or effects.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent unnoticed repeated tool activity and make the decision to spend another attempt explicit and inspectable.", "when_to_use": [ "An autonomous task can repeatedly retrieve, test or invoke tools without a person deciding each step.", "Several workers or restarts must share one cumulative task allowance." ], "when_not_to_use": [ "A call counter is being used as the only control over external writes or high-cost operations.", "The task cannot observe tool usage reliably enough to enforce its stated cap." ], "prerequisites": [ "A controller-visible accounting rule for attempted, failed and delegated calls.", "Separate task limits for time, cost, resource use or effects where those dimensions matter." ], "steps": [ "Set the task's permitted call allowance and record how nested operations, retries and failures consume it.", "Before dispatch, check the action's authorization and reserve its budget through the execution controller.", "Record the call identity, purpose, outcome and actual resource information that the tool exposes.", "Preserve the cumulative counter across handoffs and restarts, reconciling uncertain or in-flight actions conservatively.", "Stop before exceeding the allowance and return the best available evidence, unresolved obligation and owner decision needed." ], "example": "Illustrative example: An agent has a bounded allowance for investigating and repairing one test failure. Repeated failed retrievals still consume calls, and a delegated inspection shares the same task accounting. Before starting a long test command, the controller also checks the remaining time allowance. Reaching the call cap produces a hold with the diagnostic history; it does not permit skipping required evidence to claim completion.", "verification": [ "The task cannot reset its usage by restarting, spawning a worker or renaming an attempt.", "A rejected or failed operation follows the documented accounting rule.", "The final record separates call count from monetary cost, duration and permitted effects." ], "outputs": [ "Persistent per-task call ledger and remaining allowance.", "Budget-stop record with completed evidence and unresolved work." ], "risks": [ "A restrictive counter can encourage oversized calls or hide many actions inside one tool invocation.", "Counting only successful calls can reward uncontrolled retries and understate the work actually consumed." ], "related_practices": [ "PAT:033", "PAT:083", "PAT:084" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:021", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:21" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:022", "label": "Trust Calibration", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Productivity", "T:Verification & review" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Compare expressed confidence or reliance with independently assessed performance in a defined task class, then adjust how recommendations are used. Make evidence and uncertainty visible before the acceptance decision. Trust calibration is an evaluation and decision practice; a persuasive tone, a second agreeing model or a label such as high confidence does not establish calibrated correctness.", "limitation": "Calibration depends on the claims, task population, outcomes and observation period assessed; a small or selected sample cannot justify broad trust in other work.", "url": "", "authors": "", "year": "", "attributes": { "label": "Trust Calibration", "kind": "practice_descriptor", "collection": "PAT", "family": "F08", "chapter": 8, "disposition": "Retain with explicit qualifications", "required_revision": "Calibration requires comparison between confidence and performance; the pattern's name is not enough.", "occurrences": "[\"AGENT:22\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Calibration depends on the claims, task population, outcomes and observation period assessed; a small or selected sample cannot justify broad trust in other work.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Critique, Review and Trust", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Help reviewers rely on useful assistance without confusing fluency, familiarity or model agreement with evidence of correctness.", "when_to_use": [ "AI-generated findings influence whether reviewers investigate, accept or dismiss a candidate.", "A team wants to understand when its confidence in a tool matches observed results." ], "when_not_to_use": [ "There is no independent outcome assessment against which confidence can be compared.", "A confidence label would bypass required evidence or the responsible owner's decision." ], "prerequisites": [ "A defined unit of assessment, such as a review finding or behavior prediction.", "Independent outcome criteria and a record of confidence or reliance before the result is known." ], "steps": [ "Specify the claim being assessed and what would count as correct, incorrect or unresolved in the relevant setting.", "Record the recommendation, its evidence and uncertainty before inspecting the independent outcome, avoiding retrospective confidence labels.", "Evaluate the outcome using sources or checks that do not merely repeat the recommendation's assumptions.", "Compare confidence and actual results by meaningful task or risk group, retaining false positives, misses and unresolved cases.", "Adjust review routing or presentation from the observed mismatch, then reassess when the tool, task mix or evidence changes." ], "example": "Illustrative example: A team records whether reviewers initially rate a model's defect claims as strong, tentative or unsupported. Maintainers then investigate the claims against the code and approved behavior. Some confident claims prove false and some tentative ones reveal real defects. The team changes how evidence is shown and tracks later decisions; it does not turn those observations into a universal accuracy rating for the model.", "verification": [ "Confidence or reliance is recorded before outcomes and linked to a clearly defined claim.", "Outcome assessment is independent enough to expose confident errors rather than rubber-stamp recommendations.", "Reported conclusions state the task scope, unresolved cases and consequences of mistaken reliance." ], "outputs": [ "Confidence-versus-outcome record with task and evidence context.", "Revised review guidance and a trigger for renewed assessment." ], "risks": [ "Selective investigation of only confident findings can bias the apparent performance.", "A numerical score can appear calibrated while hiding a dangerous error in a rare but consequential category." ], "related_practices": [ "PAT:010", "PAT:052", "PAT:075" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 8's thematic guidance. The historical family is F08. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:022", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:22" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:AI as reviewer", "K:Automation bias and trust", "K:Review capacity and maintainers" ], "volumes": [ "V06" ], "families": [ "FAMILY:F08" ] }, { "id": "PAT:023", "label": "The External Bash Loop", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Use an external shell-driven controller as one possible implementation of a bounded propose, act and observe loop. The controller maintains explicit task state, enforces permissions and budgets, and interprets typed results before another attempt. This optional companion variant describes responsibilities; it is not a production-ready Bash script or a guarantee that shell orchestration is adequate for every environment.", "limitation": "Shell orchestration inherits command, quoting, process and recovery hazards; an illustrative loop does not establish secure isolation or reliable production operation.", "url": "", "authors": "", "year": "", "attributes": { "label": "The External Bash Loop", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Companion variant", "required_revision": "Treat an external Bash loop as a variant with persistent budget and explicit state; do not copy unverified production-ready code.", "occurrences": "[\"LOOP:R1\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Shell orchestration inherits command, quoting, process and recovery hazards; an illustrative loop does not establish secure isolation or reliable production operation.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Make repetition controlled by an inspectable process instead of allowing an agent's completion text to determine whether it runs forever.", "when_to_use": [ "A local task has simple stages whose exit conditions and artifacts can be interpreted reliably.", "A team can evaluate whether an external controller is a sufficient and maintainable implementation route." ], "when_not_to_use": [ "The workflow needs complex concurrent recovery or external effects that the proposed controller cannot enforce safely.", "A loop would parse free-form model text as commands or as acceptance authority." ], "prerequisites": [ "Structured task state and result statuses with persistent accounting.", "A restricted execution environment, controlled command construction and an owner for failure recovery." ], "steps": [ "Define the input revision, permitted operations, protected artifacts and typed exits before implementing repetition.", "Run one bounded attempt and collect its candidate, diagnostic, usage and outcome through a documented interface.", "Persist the result and remaining budget before deciding whether another attempt is eligible.", "Retry only for a concrete in-scope diagnostic; route ambiguity, denied authority or unsupported state to the relevant owner.", "Test interruption, malformed output, command failure and exhausted budget, then stop at review readiness rather than implicit acceptance." ], "example": "Illustrative example: A local controller asks an agent to repair one failing example and expects a result file naming the candidate and check outcome. When the process exits without that file, the controller records an interrupted attempt and does not treat terminal text saying done as success. A later retry uses the remaining allowance and the same protected expectation; a reviewer still decides whether the candidate is acceptable.", "verification": [ "Free-form output cannot become an unchecked shell command or a success transition.", "Restarts, failed commands and malformed results preserve state and cumulative usage.", "The controller's stop conditions can be demonstrated independently of a cooperative model response." ], "outputs": [ "Controller interface, explicit state transitions and tested failure behavior.", "Per-attempt evidence with a final review, hold or failure status." ], "risks": [ "Fragile parsing and quoting can turn ordinary model text or filenames into unintended operations.", "A wrapper can give a false sense of control when the invoked tool retains broader permissions than the wrapper checks." ], "related_practices": [ "PAT:020", "PAT:026", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:023", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:R1" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:024", "label": "The Stop-Hook Loop", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Use a stop hook to inspect an agent's proposed exit and decide whether the current task has eligible next work. The hook consults durable state, evidence and remaining budget; it can allow a stop, return a bounded diagnostic or require escalation. Re-entry continues the same contract and accounting rather than granting a fresh objective or unlimited retries.", "limitation": "A stop hook is only an integration point; its presence does not prove that all exits, subprocesses or tool effects are controlled.", "url": "", "authors": "", "year": "", "attributes": { "label": "The Stop-Hook Loop", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Companion variant", "required_revision": "Treat a stop hook as a variant; re-entry must not erase budgets or permit changing the oracle.", "occurrences": "[\"LOOP:R2\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A stop hook is only an integration point; its presence does not prove that all exits, subprocesses or tool effects are controlled.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Avoid premature completion claims while retaining an explicit way to stop when further autonomous work is unjustified.", "when_to_use": [ "An existing agent runtime provides a reliable exit callback and the task has machine-checkable completion prerequisites.", "A bounded diagnostic can legitimately guide one more attempt under the same objective." ], "when_not_to_use": [ "The hook rejects every stop until the agent asserts success more convincingly.", "A missing owner decision or permission is being treated as something another generation attempt can resolve." ], "prerequisites": [ "An understood runtime hook contract and a durable task ledger.", "Protected expectations plus explicit retry, hold, cancellation and review-readiness outcomes." ], "steps": [ "Define which evidence must be present for the proposed exit and which gaps require an owner rather than another attempt.", "At the hook, read the exact candidate state and cumulative budget instead of relying on a prose completion summary.", "If an in-scope diagnostic remains and budget permits, return one bounded instruction identifying the failed obligation.", "Preserve the same contract and oracle on re-entry, recording the hook decision and charging all work to the existing task.", "Allow a typed stop for exhaustion, cancellation, unclear intention or unavailable authority, retaining the unfinished obligations for handoff." ], "example": "Illustrative example: An agent proposes to stop after changing a replay function. The hook finds that its required independent replay result is missing and requests that check within the remaining budget. The check reveals an unresolved policy question, so the next hook decision is a hold for the policy owner. It does not force the agent to rewrite the expected result until the exit appears green.", "verification": [ "Each re-entry has a recorded diagnostic, eligibility decision and remaining allowance.", "Cancellation and exhausted-budget exits are possible even when the task is incomplete.", "The hook cannot modify protected expectations or convert a review-ready state into acceptance." ], "outputs": [ "Hook decision log and persistent continuation state.", "Current candidate evidence or a clear hold with the required owner decision." ], "risks": [ "Repeated automatic re-entry can conceal a loop with no new information.", "A runtime-specific hook may miss alternate termination paths unless those paths are explicitly tested." ], "related_practices": [ "PAT:023", "PAT:026", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:024", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:R2" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:025", "label": "The Editor-Native Manual Loop", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Use a human-guided editor session as a complete and legitimate execution route: select one scoped action, inspect its result, obtain relevant evidence and decide what happens next. The engineer controls progression while the assistant contributes drafts, explanations or diagnostics. Manual guidance is suitable when its observed overhead is lower than maintaining an additional autonomous controller.", "limitation": "Human presence does not guarantee correct review or safe tool use; the session still needs appropriate scope, evidence and decision rights.", "url": "", "authors": "", "year": "", "attributes": { "label": "The Editor-Native Manual Loop", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Brief thematic reference", "required_revision": "A manually guided session is a legitimate alternative, not a compulsory lower stage of maturity.", "occurrences": "[\"LOOP:R3\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Human presence does not guarantee correct review or safe tool use; the session still needs appropriate scope, evidence and decision rights.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RINVIO_BREVE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep simple or judgment-heavy changes manageable without adding coordination machinery that does not resolve a concrete uncertainty.", "when_to_use": [ "A small change has a clear diff and a direct verification step.", "Frequent interpretation decisions make interactive guidance useful and affordable." ], "when_not_to_use": [ "A long task loses critical state whenever the editor session closes.", "The engineer is expected to rubber-stamp every tool action without inspecting the consequential decisions." ], "prerequisites": [ "A clear authorized objective and the existing repository permission boundaries.", "A practical way to inspect the diff, run relevant checks and retain the final decision." ], "steps": [ "Choose the next meaningful increment and identify what the assistant may inspect or change.", "Ask for a candidate or diagnostic with its assumptions visible, keeping the approved behavior separate from the proposed implementation.", "Inspect the changed code or artifact and run the check appropriate to its actual consequence.", "Use the observation to continue, revise the approach or stop for clarification; do not repeat suggestions without a new reason.", "Retain a short record of the final revision, evidence, unresolved issues and responsible acceptance decision." ], "example": "Illustrative example: A maintainer corrects a non-authoritative help heading with assistance in the editor. They inspect the one-file diff and render the page to confirm its appearance and links. No parallel coordinator is needed. If the edit unexpectedly changes executable routing text, they pause to clarify the newly affected behavior instead of assuming the same lightweight route remains adequate.", "verification": [ "The final diff stays within the agreed scope or records an authorized change to it.", "The check answers the actual obligation, such as rendered wording or runtime behavior, rather than merely confirming that the file saved.", "The maintainer can explain the result and what would require a stronger review route." ], "outputs": [ "Scoped candidate with proportionate verification evidence.", "Short decision record and any trigger for reconsidering the execution route." ], "risks": [ "Interactive convenience can make unrecorded assumptions difficult to recover later.", "A confident human can still accept a plausible generated change without checking its consequential behavior." ], "related_practices": [ "PAT:001", "PAT:046", "PAT:048" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:025", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:R3" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:026", "label": "Run Until Done: Retry Against Reality", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Retry a bounded task only when a concrete observation provides a reason to expect the next attempt to address an identified failure. Preserve the authorized objective and protected expectations, record the attempted remedy and recheck the candidate. Done means reaching the appropriate reviewed state or a named stop, not an assumption that enough retries must eventually converge.", "limitation": "Repeated attempts can remain correlated, consume budget or introduce new defects; neither a loop nor a model change guarantees convergence to an acceptable result.", "url": "", "authors": "", "year": "", "attributes": { "label": "Run Until Done: Retry Against Reality", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Recompose the mechanism", "required_revision": "Retry only against a verifiable diagnosis with a stopping rule; convergence is not guaranteed.", "occurrences": "[\"LOOP:T01\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Repeated attempts can remain correlated, consume budget or introduce new defects; neither a loop nor a model change guarantees convergence to an acceptable result.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Replace indefinite regeneration with a sequence of explainable repairs whose eligibility can be checked by someone outside the maker.", "when_to_use": [ "A test, reproduction or concrete review finding identifies an in-scope defect.", "The next attempt has a plausible targeted remedy and sufficient remaining budget." ], "when_not_to_use": [ "The only feedback is that the answer is unsatisfactory, with no actionable observation.", "The disagreement concerns intended behavior, unavailable authority or a prohibited operation." ], "prerequisites": [ "A persistent task and attempt record with explicit budgets and exits.", "An oracle or other evidence source that the maker cannot rewrite to achieve a pass." ], "steps": [ "Capture the failed obligation, exact candidate, diagnostic and relevant environment before proposing another attempt.", "Decide whether the failure is repairable within the current contract or needs a named owner to clarify scope.", "State the narrow change expected to address the diagnostic and check that it is permitted and affordable.", "Apply the repair, rerun the protected check and examine relevant regressions for unintended effects.", "Continue only if new evidence supports another eligible attempt; otherwise retain the history and stop as review-ready, exhausted, blocked or escalated." ], "example": "Illustrative example: A checker shows that a revised export drops one allowed status value. The maker corrects that mapping and reruns the status cases. The next review raises an unresolved question about whether that status should exist for a different customer class. This is no longer a mechanical retry: the task stops for a requirement decision, preserving the previous failure and the repaired candidate.", "verification": [ "Each retry names both the prior diagnostic and the remedy it is testing.", "The objective, protected expectation and cumulative budget remain intact across attempts.", "The exit explains whether evidence is sufficient for review or which unresolved issue prevents further action." ], "outputs": [ "Attempt ledger linking diagnostics, remedies, candidates and results.", "Review-ready evidence or an explicit stop with the required next decision." ], "risks": [ "An agent can overfit a visible failure while missing adjacent behavior.", "Repeated rejection without useful diagnostics can consume resources and encourage unauthorized changes to the success criterion." ], "related_practices": [ "PAT:014", "PAT:065", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 3's thematic guidance. The historical family is F03. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:026", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T01" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:027", "label": "Maker–Checker: Separate Production from Acceptance", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Verification & review", "T:What agents can do" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Separate the responsibility for producing a candidate from the responsibility for checking its claims, while protecting the approved objective and expected results from both inappropriate edits and self-approval. Evaluate independence through the origin of expectations, available evidence and effective permissions. Two roles or two models can still share the same mistake and cannot replace accountable acceptance.", "limitation": "Role separation reduces one source of self-review but does not make errors independent; shared assumptions or editable oracles can undermine both roles.", "url": "", "authors": "", "year": "", "attributes": { "label": "Maker–Checker: Separate Production from Acceptance", "kind": "practice_descriptor", "collection": "PAT", "family": "F07", "chapter": 7, "disposition": "Recompose the mechanism", "required_revision": "Compare with Adversarial Agent Pattern (PAT:080; historical alias SDD2:C5); separating roles does not automatically make their errors independent.", "occurrences": "[\"LOOP:T02\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Role separation reduces one source of self-review but does not make errors independent; shared assumptions or editable oracles can undermine both roles.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Tests, Oracles and Acceptance Evidence", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Give a candidate a meaningful opportunity to fail against evidence the maker did not define merely by observing its own output.", "when_to_use": [ "A wrong-but-green candidate would have a material consequence or be difficult for a reviewer to spot.", "The workflow can separate candidate production, independent findings and final acceptance authority." ], "when_not_to_use": [ "The checker simply repeats the maker's explanation or uses expectations generated from the candidate.", "A second role adds ceremony while the maker can still rewrite the protected oracle." ], "prerequisites": [ "Expected behavior derived from an authorized source with a protected revision.", "Distinct effective permissions and result channels for maker, checker and acceptance owner." ], "steps": [ "Define what the maker may change and exclude the approved contract and protected expected results from its write scope.", "Give the checker the actual candidate, relevant authority and independently justified cases rather than only the maker's summary.", "Have the checker seek discrepancies and report reproducible findings with locators, assumptions and uncertainty.", "Return confirmed in-scope failures as bounded repair requests; send ambiguous requirements to their owner.", "Present the renewed candidate and current evidence to the accountable reviewer, preserving the distinction between checked and accepted." ], "example": "Illustrative example: The maker changes how stored decisions replay. A checker runs an independently specified case requiring the original response to survive a policy update. It reports a concrete mismatch but cannot edit the candidate. The maker repairs the implementation without changing that expectation. The final reviewer inspects current results and decides whether the candidate can advance; no checker status alone grants release approval.", "verification": [ "The expected answer has an origin independent of the candidate's observed output.", "Neither role can silently alter protected authority or convert its own claim into acceptance.", "A known wrong candidate is rejected, and evidence is renewed after a relevant repair." ], "outputs": [ "Role and permission map plus independently grounded findings.", "Candidate-bound evidence and a separate acceptance disposition." ], "risks": [ "Different model names can mask shared context gaps or the same faulty requirement.", "A read-only checker cannot protect an expectation that the maker remains able to edit." ], "related_practices": [ "PAT:044", "PAT:080", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 7's thematic guidance. The historical family is F07. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:027", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T02" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dataset provenance and dependency", "K:Independent verification and oracles" ], "volumes": [ "V06" ], "families": [ "FAMILY:F07" ] }, { "id": "PAT:028", "label": "Skills and Context Engineering: Remove Intent Debt", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Package recurring work instructions as a maintained, versioned skill or context aid with an owner, applicability and source references. Separate procedural guidance from retrieved evidence, task state and tool permissions. The aim is to make missing or ambiguous intent visible and reduce repeated clarification where justified, without claiming that a larger instruction file removes all intent debt.", "limitation": "A reusable instruction can be stale, contradictory or inapplicable; more context does not guarantee better understanding and cannot grant authority or tool access.", "url": "", "authors": "", "year": "", "attributes": { "label": "Skills and Context Engineering: Remove Intent Debt", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Recompose the mechanism", "required_revision": "Version skills with an owner and separate permissions; context cannot eliminate every form of intent debt.", "occurrences": "[\"LOOP:T03\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A reusable instruction can be stale, contradictory or inapplicable; more context does not guarantee better understanding and cannot grant authority or tool access.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make recurring procedural knowledge reusable while preserving a clear path to the current authorized objective and its unresolved questions.", "when_to_use": [ "A repeated task has stable procedural steps that workers otherwise reconstruct inconsistently.", "Recurring misunderstandings can be traced to omitted context or unclear precedence." ], "when_not_to_use": [ "A one-off instruction would be generalized without evidence of reuse.", "The proposed skill mixes tool credentials, authority decisions and unverified repository claims into one trusted block." ], "prerequisites": [ "A named maintainer and a versioned source for the procedure.", "Applicability conditions, required inputs, expected outputs and independently enforced permission boundaries." ], "steps": [ "Identify the recurring failure and write only the procedural guidance needed to address it.", "State scope, input requirements, evidence requirements and stop conditions, linking authoritative sources instead of copying mutable rules everywhere.", "Version and review the guidance, separating stable instructions from task-specific state and retrieved material.", "At use time, verify applicability and freshness against the current task and permissions; keep unresolved intent visible.", "Record concrete failures or maintenance changes, then revise or retire the skill when it no longer provides useful guidance." ], "example": "Illustrative example: A team writes a release-note drafting skill that requires a defined revision range, source links and explicit exclusions. The skill explains the workflow but grants no publishing access and contains no permanent claim about which features are released. Each run obtains its current approved inputs. When the release process changes, the owner updates the version and records which old instructions should no longer be used.", "verification": [ "The skill identifies its owner, version, applicable tasks and renewal triggers.", "A worker can distinguish procedural advice from evidence and authoritative decisions.", "A useful trial checks the actual deliverable and exposes missing context rather than merely confirming the skill file was loaded." ], "outputs": [ "Versioned, owned procedural guidance with source links.", "Applicability and renewal record from actual uses." ], "risks": [ "Accumulated instructions can conflict or crowd out the evidence needed for the present task.", "An apparently official skill can launder an old assumption into a current requirement unless its authority and scope are checked." ], "related_practices": [ "PAT:007", "PAT:016", "PAT:047" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:028", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T03" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:029", "label": "Memory and Retrieval: Read What the Model Could Not Know", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Retrieve task-relevant information that is absent from the model's immediate context, preserving source, revision, validity and authority. Memory can contain past actions, semantic summaries, instructions or approved decisions, and those types are not interchangeable. A useful system can abstain when evidence is missing or conflicting instead of turning retrieved plausibility into approved knowledge.", "limitation": "Retrieval can return relevant but stale, incomplete or misleading material; ranking similarity does not establish truth, comprehension or permission to act.", "url": "", "authors": "", "year": "", "attributes": { "label": "Memory and Retrieval: Read What the Model Could Not Know", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Recompose the mechanism", "required_revision": "Use retrieval with abstention, sources and validity; memory is not approved knowledge by definition.", "occurrences": "[\"LOOP:T04\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Retrieval can return relevant but stale, incomplete or misleading material; ranking similarity does not establish truth, comprehension or permission to act.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Ground a task in the information it actually needs while keeping uncertainty and conflicting sources available for review.", "when_to_use": [ "Repository-specific decisions, recent changes or task history are needed to answer the next question.", "A long-running task needs selective access to evidence beyond a compact resume record." ], "when_not_to_use": [ "The system treats the top-ranked passage as authoritative without checking its provenance.", "A missing decision is being filled by a plausible historical analogy instead of being raised with its owner." ], "prerequisites": [ "Source records with stable locators, revisions and validity scopes.", "A distinction between instructions, evidence, task state and authoritative decisions." ], "steps": [ "Define the information need and the type of claim required: observation, current rule, past event or procedural instruction.", "Retrieve candidate sources and retain their identities, scope and dates or versions relevant to the task.", "Check applicability and authority, consulting original records when a derived summary cannot resolve a consequential claim.", "Present supported facts separately from inferences, conflicts and omissions; abstain on unresolved questions that affect acceptance.", "Bind useful retrieved evidence to the task record and set renewal triggers for any derived memory reused later." ], "example": "Illustrative example: A resumed agent finds two cards describing different policy thresholds. It checks the source revisions and discovers that one governs historical decisions while the other governs new requests. It retrieves the approved delta and preserves both scoped facts. If the relevant approval record is unavailable, it reports that gap instead of choosing the newer-looking card as authority.", "verification": [ "Material claims can be traced from a summary back to the source used.", "Current applicability and authority are checked independently of retrieval rank or recency.", "Missing or contradictory evidence produces an explicit uncertainty or owner question rather than a fabricated answer." ], "outputs": [ "Task-specific evidence set with provenance and applicability.", "Derived memory or answer that distinguishes supported claims, inference and unresolved gaps." ], "risks": [ "Retrieved instructions embedded in untrusted material can attempt to cross the tool-permission boundary.", "A compressed memory card may omit the qualifier that determines whether a fact applies to the present task." ], "related_practices": [ "PAT:008", "PAT:016", "PAT:062" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:029", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T04" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:030", "label": "Connectors and Tools: Move Exact Work Outside the Weights", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Delegate exact retrieval, computation or controlled operations to tools whose interfaces and outputs can be checked. The model selects or explains work while the executor performs the specified operation within an enforced permission envelope. Deterministic arithmetic or successful API execution establishes only that operation's result; it does not authorize the external effect or validate the task's underlying assumptions.", "limitation": "An exact executor can faithfully perform the wrong request against stale data; tool success is not proof of business correctness, appropriate access or authorized effects.", "url": "", "authors": "", "year": "", "attributes": { "label": "Connectors and Tools: Move Exact Work Outside the Weights", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Recompose the mechanism", "required_revision": "Use exact executors with explicit interfaces and permissions; exact calculation does not authorize external effects.", "occurrences": "[\"LOOP:T05\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An exact executor can faithfully perform the wrong request against stale data; tool success is not proof of business correctness, appropriate access or authorized effects.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Move operations requiring precise execution into inspectable tools while keeping interpretation and authority decisions explicit.", "when_to_use": [ "A task needs reproducible calculations, repository queries or structured transformations.", "A supported connector can perform a clearly authorized operation more reliably than manual transcription." ], "when_not_to_use": [ "The requested operation or destination exceeds the task's authority.", "The interface cannot identify what data or external resource the operation will affect." ], "prerequisites": [ "A documented input and output contract with the relevant data or resource identity.", "An external enforcement point for access, effect scope and applicable budgets." ], "steps": [ "Define the operation precisely, including units, source version, target resource and any side effects.", "Check input assumptions and authorization before dispatch; use a read-only or preview operation when that answers the task.", "Execute through the controlled interface and capture the actual status, output and relevant provenance.", "Validate the result against the expected shape and meaning, distinguishing executor errors from incorrect assumptions in the request.", "Use the result only for its supported purpose and require any separate authority needed for a consequential follow-on action." ], "example": "Illustrative example: An agent calculates the changed and added files between two website packages using a script over file hashes. The script can determine exact byte differences for those inputs. The agent still checks that the chosen baseline is the published package. Producing a correct delta does not grant permission to upload it to the public site or to alter unrelated repository settings.", "verification": [ "Inputs identify the intended source, target, units and revision unambiguously.", "The recorded tool result concerns the operation actually requested, with failures preserved.", "A precise output is not used to infer an approval or effect outside the operation's authority." ], "outputs": [ "Structured operation record with inputs, output and source identity.", "Validated result and any separate decision required for its use." ], "risks": [ "A broadly scoped connector can turn a small interpretation error into a consequential external write.", "Silent coercion, stale resource selection or missing units can produce a precise but misleading result." ], "related_practices": [ "PAT:017", "PAT:034", "PAT:079" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 6's thematic guidance. The historical family is F06. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:030", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T05" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:031", "label": "Worktrees: Isolate the Write Domains", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Use separate worktrees or equivalent isolated checkouts so concurrent workers produce changes in distinct write domains. Tie each workspace to an input revision and a named task, then integrate deliberately with fresh evidence. Filesystem separation prevents some edit collisions, but ownership of the logical outcome and shared external resources still require explicit coordination.", "limitation": "Worktrees isolate working files, not necessarily credentials, services or task meaning; two isolated workers can still duplicate or contradict the same logical change.", "url": "", "authors": "", "year": "", "attributes": { "label": "Worktrees: Isolate the Write Domains", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Recompose the mechanism", "required_revision": "Isolate writes, while recognizing that this does not prevent logical duplication of tasks.", "occurrences": "[\"LOOP:T06\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Worktrees isolate working files, not necessarily credentials, services or task meaning; two isolated workers can still duplicate or contradict the same logical change.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep concurrent candidate changes inspectable and recoverable until a designated integration point reconciles them.", "when_to_use": [ "Independent implementation tasks can proceed without sharing mutable working files.", "Alternative candidates need to be compared against the same baseline before selecting one." ], "when_not_to_use": [ "Workers require concurrent uncoordinated access to one shared database or authoritative artifact.", "Creating separate directories is being treated as sufficient protection against overlapping logical responsibilities." ], "prerequisites": [ "A baseline revision and an ownership map for logical targets.", "A named integrator and controls for shared resources outside the working directories." ], "steps": [ "Assign a unique task and target to each workspace, recording the baseline and permitted write scope.", "Create or select the isolated checkout and verify its state before work begins, preserving any existing user work.", "Keep candidate artifacts and checks associated with their workspace and revision rather than a shared mutable status file.", "Review dependencies and integrate selected changes through the owner, resolving semantic conflicts as well as textual conflicts.", "Renew relevant checks on the integrated candidate and retire workspaces only after required artifacts and unresolved work are accounted for." ], "example": "Illustrative example: One worker updates export documentation while another repairs an independent parser test in a separate checkout. The coordinator discovers that both also propose renaming the same public option. That logical overlap is resolved by assigning one owner, even though the files were edited in isolation. After integration, the combined documentation and behavior checks run against the resulting revision.", "verification": [ "Each workspace has the expected baseline, owner and allowed target.", "The coordinator detects duplicate logical changes and shared-resource dependencies before integration.", "The accepted evidence belongs to the integrated candidate, including any resolution of conflicts." ], "outputs": [ "Workspace-to-task map with isolated candidate artifacts.", "Integration record, renewed checks and accounted-for remaining work." ], "risks": [ "Shared credentials or service endpoints can bypass the intended separation of write effects.", "Conflict-free textual merges can still combine incompatible assumptions about behavior or interfaces." ], "related_practices": [ "PAT:019", "PAT:032", "PAT:063" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 11's thematic guidance. The historical family is F11. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:031", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T06" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:032", "label": "Multi-Loop Coordination: One Owner per Target", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Assign one current owner to each logical target across concurrent loops, using bounded work concessions or leases where needed. Ownership names the task, contract revision, validity and generation so stale workers cannot submit as current. Coordination must operate above filenames and preserve decision rights, because separate files can encode the same policy or competing implementations.", "limitation": "A sequential ownership check is not a proof of distributed locking; real concurrency, failures and identity controls require an implementation suited to the environment.", "url": "", "authors": "", "year": "", "attributes": { "label": "Multi-Loop Coordination: One Owner per Target", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Recompose the mechanism", "required_revision": "Own the target above file level and manage leases explicitly.", "occurrences": "[\"LOOP:T07\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A sequential ownership check is not a proof of distributed locking; real concurrency, failures and identity controls require an implementation suited to the environment.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent duplicate or stale work from entering integration under an apparently valid assignment.", "when_to_use": [ "Several agents or repeated triggers can act on the same backlog item or logical component.", "A task can outlive its original contract revision, assignment or coordinator session." ], "when_not_to_use": [ "No shared mutable or duplicate target exists and a lease system would add needless complexity.", "A local example is assumed to provide race-safe distributed ownership without further implementation." ], "prerequisites": [ "Canonical target identities and a coordinator able to grant, renew and revoke assignments.", "A state record containing owner, task, contract revision, expiry and assignment generation." ], "steps": [ "Define logical targets so semantically overlapping changes cannot evade ownership by touching different files.", "Grant a bounded assignment only when the target is available and its prerequisites and review capacity are satisfied.", "Require progress and submissions to carry the current assignment identity, intention revision and candidate evidence.", "On expiry, cancellation or changed intention, invalidate affected concessions and preserve prior work as historical or pending reconciliation.", "Accept a submission for review only after checking its current assignment and evidence, then release or explicitly transfer ownership." ], "example": "Illustrative example: A worker receives the task of updating a pricing rule, while another investigates its documentation. The policy revision changes before the first worker submits. Its old assignment and green tests are retained but rejected as current evidence. The coordinator grants a new generation after the owner resolves the change, preventing the delayed old submission from overwriting the newly assigned work.", "verification": [ "Competing requests for the same logical target cannot both obtain current ownership under the implemented model.", "Stale generations, expired leases and duplicate event identities have explicit outcomes.", "Submission checks use current authority and evidence, not only the state recorded when work started." ], "outputs": [ "Target ownership and concession history with explicit invalidations.", "Current submissions, rejected stale events and unresolved integration decisions." ], "risks": [ "Clock assumptions, race conditions or coordinator failures can undermine a naive lease implementation.", "A poorly defined target map can allow two owners to change the same business rule through different artifacts." ], "related_practices": [ "PAT:019", "PAT:020", "PAT:084" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 11's thematic guidance. The historical family is F11. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:032", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T07" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:033", "label": "Budget and Observability: Price the Next Attempt", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Economics", "T:Jobs & roles" ], "actual": [], "mapped": [ "C:C12", "C:C13" ], "printed": false, "summary": "Before another attempt, estimate its incremental burden and compare that decision with the cumulative task record. Include setup, generation, tools, verification, review, waiting and rejected work without double-counting. Use observations where available and label uncertain inputs. A cheap next call may still be a poor choice when checking capacity, authority or the probability of useful progress is missing.", "limitation": "Cost estimates depend on task mix and uncertain outcomes; benchmark performance or token prices alone cannot establish the return of this local workflow.", "url": "", "authors": "", "year": "", "attributes": { "label": "Budget and Observability: Price the Next Attempt", "kind": "practice_descriptor", "collection": "PAT", "family": "F12", "chapter": 12, "disposition": "Recompose the mechanism", "required_revision": "Track next-step and total cost, including setup and rejected attempts; do not transfer returns from benchmarks.", "occurrences": "[\"LOOP:T08\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Cost estimates depend on task mix and uncertain outcomes; benchmark performance or token prices alone cannot establish the return of this local workflow.", "historical_structural_chapters": [ "C:C12" ], "family_name": "Economics, Infrastructure and Work", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make continuation an explicit engineering and economic decision while preserving required controls as eligibility conditions.", "when_to_use": [ "A loop can spend more time or resources on repeated attempts, extra agents or another review stage.", "A team compares candidate execution routes for the same class of accepted changes." ], "when_not_to_use": [ "The proposed saving comes from omitting a required permission or independent check.", "Only inference cost is available but the result is presented as total delivery cost." ], "prerequisites": [ "A task ledger with stable event identities and distinct cost or time categories.", "An eligible next action and explicit assumptions for unobserved costs or outcomes." ], "steps": [ "Record costs already incurred, including failed attempts and initial setup, with observed and estimated values distinguishable.", "Identify the next permitted action and the diagnostic or uncertainty it is expected to resolve.", "Estimate its marginal execution, checking, reviewer and integration burden, accounting for existing capacity constraints.", "Compare continuing, simplifying, using a human-led route or stopping under the same required controls.", "Authorize the eligible choice through the task's existing budget rules, then record the actual outcome to improve later estimates." ], "example": "Illustrative example: After two unsuccessful repairs, a team considers a third model run or a short maintainer investigation. The ledger includes setup, tool use and the review already spent, while the next-step estimate separates those sunk costs from the new decision. An unresolved policy question makes another generation attempt ineligible regardless of its small token cost; the team routes the question to its owner.", "verification": [ "Cumulative accounting includes abandoned and rejected work as well as accepted results.", "Person-time, elapsed waiting and cash charges are reported distinctly before aggregation.", "The chosen action has both a valid permission path and a plausible information benefit under stated assumptions." ], "outputs": [ "Task cost ledger and next-action decision with assumptions.", "Observed outcome, remaining budget and any revised continuation threshold." ], "risks": [ "Ignoring review and integration can make a low-cost producer appear efficient while total accepted-change cost rises.", "A precise spreadsheet can hide uncertainty about acceptance, correlated retries or rare consequential failures." ], "related_practices": [ "PAT:021", "PAT:059", "PAT:060" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 12's thematic guidance. The historical family is F12. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:033", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C12", "file": "EN/chapters/chapter12.tex", "line": 3, "sha256": "86c0ede476fd2a1b32d32f4ea86297429dd24aad34db3f6c7540431e1190ccbe", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C12", "title": "Economics, Jobs, Risk and Evidence-Based Adoption", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T08" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Economic costs and return", "K:Employment and early-career roles", "K:Evaluation methodology and baselines" ], "volumes": [ "V06" ], "families": [ "FAMILY:F12" ] }, { "id": "PAT:034", "label": "Safety and Guardrails: Verification Is Not Authorization", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Keep three questions separate: whether an operation is permitted, whether its result satisfies a check, and who may accept or publish the change. Enforce the permission envelope before execution and evaluate evidence afterward. A passing test, clean scanner or policy-shaped file supplies only its specific finding; none silently grants the authority of a neighboring decision.", "limitation": "Verification can establish selected predicates without authenticating an approver or covering unmodeled effects; authorization cannot manufacture evidence that was never obtained.", "url": "", "authors": "", "year": "", "attributes": { "label": "Safety and Guardrails: Verification Is Not Authorization", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Retain with explicit qualifications", "required_revision": "Verification, policy and authorization remain distinct decisions.", "occurrences": "[\"LOOP:T09\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Verification can establish selected predicates without authenticating an approver or covering unmodeled effects; authorization cannot manufacture evidence that was never obtained.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent technical success from being used to cross a boundary that requires a different owner's authority.", "when_to_use": [ "A workflow passes from candidate creation through review toward a consequential external action.", "Several checks and actors contribute evidence that could be mistaken for one combined approval." ], "when_not_to_use": [ "An established workflow already separates permissions, checks and acceptance; map the practice to those controls instead of introducing parallel approval stages.", "A small, pre-authorized edit has a clear owner and verification path; retain that path without adding redundant decision stages." ], "prerequisites": [ "Named decision rights for scope, tool access, acceptance and any external publication or release.", "Checks whose supported claims and unverified boundaries are explicit." ], "steps": [ "Map the next operation to the actor, target and existing authority that would permit it.", "Enforce that permission before the tool acts, independently of the model's confidence or expected result.", "Run the relevant checks and record their actual scope, candidate revision and limitations.", "Present the evidence to the role responsible for the next decision, preserving any missing authority or unresolved risk.", "Record that decision separately and recheck applicability if the candidate, contract, destination or permissions change." ], "example": "Illustrative example: An agent creates a patch that passes functional tests and a dependency scan. Those findings support review of the candidate, but the task only authorizes local preparation. The release owner still decides deployment through the established process. Conversely, an owner may authorize a release review, but that permission cannot be described as evidence that an unrun security check passed.", "verification": [ "No successful test or scanner result changes the execution permission profile.", "The acceptance or publication decision identifies the responsible authority and the exact eligible candidate.", "Missing evidence and missing authorization remain distinguishable in the final status." ], "outputs": [ "Decision-rights map and enforced operation outcomes.", "Candidate evidence plus a separate, scoped decision record." ], "risks": [ "Combining all statuses into one green indicator can conceal which obligation remains unmet.", "Repository text or generated metadata can impersonate an approval unless the real identity and authority path are checked." ], "related_practices": [ "PAT:017", "PAT:058", "PAT:076" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 6's thematic guidance. The historical family is F06. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:034", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T09" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:035", "label": "Daily Triage: rank the rare urgent item", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Use a bounded triage pass to identify a small set of potentially urgent items from a larger stream, showing the evidence and uncertainty behind their proposed order. Preserve deferred work and route consequential cases to the right owner. This optional companion workflow proposes priorities; ranking an issue does not authorize a fix, a policy change or a message to an external party.", "limitation": "A triage model can miss a rare urgent case or over-rank persuasive text; usefulness depends on the queue, evidence quality and the owner's review capacity.", "url": "", "authors": "", "year": "", "attributes": { "label": "Daily Triage: rank the rare urgent item", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 8, "disposition": "Companion variant", "required_revision": "An optional triage example; proposed priority is not an authorized change.", "occurrences": "[\"LOOP:T10\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A triage model can miss a rare urgent case or over-rank persuasive text; usefulness depends on the queue, evidence quality and the owner's review capacity.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Focus limited human attention on items whose delay may matter, without converting automated ranking into unattended execution.", "when_to_use": [ "A queue is large enough that manually scanning every item repeatedly imposes a real burden.", "The team can state what makes an item urgent and who decides its disposition." ], "when_not_to_use": [ "The ranking would automatically trigger consequential actions without the queue owner's decision.", "Available item descriptions omit the evidence needed to distinguish urgency from confident wording." ], "prerequisites": [ "A bounded source queue and explicit priority or escalation criteria.", "A named triage owner with capacity to examine the proposed urgent set and a record of deferred items." ], "steps": [ "Capture the queue snapshot and the time window, preserving item identity and current status.", "Apply the stated criteria using linked evidence, separating urgency, impact, uncertainty and age where they mean different things.", "Produce a small ranked proposal with reasons, missing information and any rule-based mandatory escalation.", "Have the owner review uncertain or consequential cases and record a disposition without silently dropping the rest.", "Review outcomes later, including missed urgent items and false alarms, and adjust the triage criteria or assistance only from those observations." ], "example": "Illustrative example: A daily repository queue contains many documentation suggestions and one report of changed replay behavior. The assistant flags the replay report because its linked reproduction may violate a protected invariant, while labeling the evidence incomplete. The owner checks the report and assigns the next action. The assistant's ranking does not permit it to change the replay policy or contact affected customers.", "verification": [ "Each proposed urgent item has a traceable reason tied to the stated criteria.", "Deferred and unassessed items remain visible, including relevant ageing or follow-up needs.", "Evaluation counts false alarms and missed urgent cases rather than only correct top-ranked suggestions." ], "outputs": [ "Ranked triage proposal with evidence, uncertainties and retained backlog.", "Owner dispositions and later outcome observations." ], "risks": [ "Overfitting the criteria to common items can hide the rare event the process was meant to surface.", "Automated urgency labels can consume scarce review capacity and displace quieter but consequential work." ], "related_practices": [ "PAT:039", "PAT:056", "PAT:084" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 11's thematic guidance. The historical family is F11. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:035", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T10" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:036", "label": "CI Sweeper: classify before fixing", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C05", "C:C13" ], "printed": false, "summary": "Inspect failed continuous-integration work and classify the evidence before deciding whether a code repair is warranted. Distinguish a candidate regression, known baseline failure, environmental problem, potentially intermittent behavior and unresolved cause. The optional sweeper creates a routed diagnostic or bounded repair proposal; it does not infer that every red build is a software defect the agent may fix.", "limitation": "A classifier or a later passing rerun cannot reliably establish the cause of intermittent failures; evidence may remain insufficient to distinguish code, test and environment.", "url": "", "authors": "", "year": "", "attributes": { "label": "CI Sweeper: classify before fixing", "kind": "practice_descriptor", "collection": "PAT", "family": "F05", "chapter": 5, "disposition": "Companion variant", "required_revision": "Classify a red build before repairing it; do not guarantee that a classifier can recognize flakiness.", "occurrences": "[\"LOOP:T11\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A classifier or a later passing rerun cannot reliably establish the cause of intermittent failures; evidence may remain insufficient to distinguish code, test and environment.", "historical_structural_chapters": [ "C:C05" ], "family_name": "Architecture, Evolution and Maintenance", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Reduce indiscriminate CI repair by making the failure type, candidate identity and appropriate owner explicit first.", "when_to_use": [ "Many failed jobs require initial diagnosis before maintainers can assign work.", "The same repository has both candidate regressions and infrastructure or pre-existing failures." ], "when_not_to_use": [ "The workflow reruns jobs until green and discards the failed observations.", "The proposed repair crosses the current task scope or weakens a required check." ], "prerequisites": [ "Job logs, exact candidate and baseline identities, and relevant environment information.", "An agreed classification vocabulary that permits unknown and an owner for each route." ], "steps": [ "Capture the failure signature, command, revision, timing and environment details before logs expire or another run replaces them.", "Compare the failure with the baseline and available related runs, avoiding claims unsupported by missing history.", "Classify the evidence with a confidence boundary and list the observation needed to resolve competing explanations.", "For a reproducible in-scope regression, create a bounded repair request; otherwise route the diagnostic to the appropriate maintainer or infrastructure owner.", "Retain reruns and final dispositions so later success does not erase the original failure or create a false causal explanation." ], "example": "Illustrative example: A build fails during package retrieval before any changed code runs. A later rerun succeeds. The sweeper records an environmental candidate explanation and the two run identities, but does not declare the test flaky or alter source code. Another failure reproduces on the patch and not the baseline, providing a stronger basis for a focused repair proposal to the component owner.", "verification": [ "A classification is supported by actual runs and clearly separates observations from inferred causes.", "A passing rerun does not delete the failure or automatically satisfy policies requiring investigation.", "Any proposed repair has a relevant owner, bounded scope and evidence that distinguishes it from unrelated work." ], "outputs": [ "Failure classification with diagnostic evidence and unresolved hypotheses.", "Routed owner decision or scoped repair proposal with retained run history." ], "risks": [ "Grouping failures by similar log text can combine unrelated causes.", "Repeated reruns can hide an unstable environment and consume capacity without yielding a useful diagnosis." ], "related_practices": [ "PAT:009", "PAT:014", "PAT:015" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 5's thematic guidance. The historical family is F05. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:036", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C05", "file": "EN/chapters/chapter05.tex", "line": 3, "sha256": "f6e123ae06931297b82554424c5b9b9c4b6bdb00e897814d515d11203e684075", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C05", "title": "Quality, Architecture and Maintainability", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T11" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Architecture and modularity", "K:Code reuse and duplication", "K:Technical debt and complexity" ], "volumes": [ "V06" ], "families": [ "FAMILY:F05" ] }, { "id": "PAT:037", "label": "Dependency Sweeper: route by risk", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Route dependency updates according to their specific compatibility, provenance and effect risks instead of treating all version changes alike. Establish the package identity and proposed change, inspect relevant evidence, and create a proportionate review path. This optional maintenance workflow produces a candidate and risk record; passing CI does not authorize a dependency's adoption, its permissions or the merge.", "limitation": "Version labels, release notes and passing tests can miss consequential compatibility or supply-chain changes; risk cannot be inferred from a version increment alone.", "url": "", "authors": "", "year": "", "attributes": { "label": "Dependency Sweeper: route by risk", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Companion variant", "required_revision": "Route updates by risk; green CI does not authorize the dependency or the merge.", "occurrences": "[\"LOOP:T12\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Version labels, release notes and passing tests can miss consequential compatibility or supply-chain changes; risk cannot be inferred from a version increment alone.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Make dependency maintenance reviewable by connecting each proposed update to the behavior, trust boundary and owner it affects.", "when_to_use": [ "A repository has recurring dependency updates that require different levels of investigation.", "A maintainer needs to separate routine candidates from updates changing interfaces, build behavior or execution privileges." ], "when_not_to_use": [ "Package identity or provenance is uncertain and the proposed automation would install first and investigate later.", "The route assumes every patch-level version is harmless or every passing update may merge unattended." ], "prerequisites": [ "A known dependency baseline, lock or resolution record, and authorized update scope.", "A dependency owner and access to relevant upstream or repository evidence." ], "steps": [ "Identify the exact package, source, resolved version and proposed version, including transitive changes that affect the candidate.", "Review relevant compatibility notes, provenance and build or runtime effects, retaining unknowns rather than inventing reassurance.", "Route the candidate by the actual affected boundaries and project rules, assigning specialist review when justified.", "Prepare the bounded update and run checks relevant to its use, including behavior that may not be covered by installation success.", "Present the changed resolution, evidence and residual uncertainty for the authorized adoption and integration decision." ], "example": "Illustrative example: A dependency update changes only a declared version in the manifest but also changes the resolved parser used by the application. The sweeper records that transitive difference and proposes compatibility cases for the input formats the service supports. Even if those cases pass, the maintainer still assesses package provenance and the project-specific approval path before accepting the update.", "verification": [ "The candidate's actual resolution matches the package identities and versions in the review record.", "Checks cover the dependency's consequential local use rather than merely a successful install.", "Unknown provenance, new privileges or compatibility gaps remain visible to the responsible approver." ], "outputs": [ "Dependency change inventory and evidence-based routing decision.", "Bounded update candidate with checks, owner and residual risks." ], "risks": [ "A harmless-looking top-level update can alter transitive code or installation behavior.", "Treating vulnerability scanning as a complete safety verdict can miss provenance, licensing or operational questions outside its scope." ], "related_practices": [ "PAT:015", "PAT:077", "PAT:079" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 6's thematic guidance. The historical family is F06. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:037", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T12" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:038", "label": "Duplicate detection", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Use retrieval or similarity analysis to propose records that may describe the same underlying issue, practice or change, then confirm the semantic relationship before consolidation. Preserve stable identifiers, source evidence and historical dispositions. A duplicate candidate may instead be a related topic, a recurrence, a different affected version or a distinct request with similar wording.", "limitation": "Similarity scores cannot establish semantic identity; deduplication can lose meaningful history or merge incompatible obligations if performed without contextual review.", "url": "", "authors": "", "year": "", "attributes": { "label": "Duplicate detection", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Companion variant", "required_revision": "Confirm retrieval-proposed duplicates semantically and preserve historical records.", "occurrences": "[\"LOOP:T13\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Similarity scores cannot establish semantic identity; deduplication can lose meaningful history or merge incompatible obligations if performed without contextual review.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Reduce repeated investigation while retaining distinctions needed for ownership, version history and accountable decisions.", "when_to_use": [ "A catalogue or issue queue contains repeated titles, paraphrases or overlapping reports.", "Maintainers need to locate prior work before deciding whether a new item is genuinely redundant." ], "when_not_to_use": [ "The source records lack enough evidence to determine whether they concern the same behavior.", "The process would delete or close items automatically based only on textual similarity." ], "prerequisites": [ "Stable record identifiers with source links, affected versions and current status.", "A responsible reviewer and a way to represent related, duplicate, recurring and unresolved relationships." ], "steps": [ "Retrieve candidate pairs or groups using labels, content and relevant metadata, retaining the basis for the suggestion.", "Compare the underlying outcome, affected component, version, reproduction and requested action rather than the title alone.", "Classify the relationship explicitly and identify any uncertainty that needs the record owner.", "If consolidation is justified, choose a canonical navigation target while preserving every original record and its provenance.", "Link the records and retain their historical dispositions, ensuring searches can still discover aliases and explain the consolidation." ], "example": "Illustrative example: Two issue titles both say export order is unstable. One concerns the current CSV endpoint; the other concerns historical PDF reports and has a different reproduction. The system proposes them as similar, but the maintainer marks them related rather than duplicate. Two genuinely identical reports can point to one investigation while their original reporters' evidence and affected revisions remain intact.", "verification": [ "Each duplicate decision states the shared underlying behavior and the evidence supporting identity.", "Canonical navigation preserves original identifiers, provenance and any version-specific exceptions.", "A review sample checks false merges and missed duplicates, including records with misleadingly similar titles." ], "outputs": [ "Candidate duplicate report and reviewed relationship decisions.", "Canonical links or aliases with preserved original history." ], "risks": [ "Collapsing separate incidents can hide repeated failures that should inform maintenance priorities.", "Retaining only the most complete-looking record can discard a counterexample that changes the diagnosis." ], "related_practices": [ "PAT:008", "PAT:016", "PAT:062" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:038", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T13" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:039", "label": "PR babysitter", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Productivity", "T:Verification & review" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Monitor a pull request's current candidate, required checks, review findings and unresolved dependencies to propose its next action. Bind every readiness claim to the exact revision and relevant authority. This optional companion workflow helps maintainers follow evidence as a PR changes; it must distinguish a truly eligible review candidate from a false-ready status based on stale or incomplete information.", "limitation": "PR status can lag behind changing code, base branches or policy; a green dashboard and absence of comments do not prove review readiness or acceptance.", "url": "", "authors": "", "year": "", "attributes": { "label": "PR babysitter", "kind": "practice_descriptor", "collection": "PAT", "family": "F08", "chapter": 8, "disposition": "Companion variant", "required_revision": "Base PR status on evidence for the correct revision; record false-ready as a distinct outcome.", "occurrences": "[\"LOOP:T14\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "PR status can lag behind changing code, base branches or policy; a green dashboard and absence of comments do not prove review readiness or acceptance.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Critique, Review and Trust", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Reduce forgotten review obligations without replacing the maintainer's decision with an automated status summary.", "when_to_use": [ "Pull requests wait across multiple revisions, checks and reviewer exchanges.", "Maintainers need a compact view of what specifically blocks the next legitimate stage." ], "when_not_to_use": [ "The monitor would merge because checks appear green or comments have been answered.", "It cannot determine whether a result or review applies to the current candidate." ], "prerequisites": [ "Access to current candidate and base identities, required checks and review dispositions.", "A project-defined readiness policy and a named owner for exceptions or acceptance." ], "steps": [ "Capture the current PR revision, relevant base, contract or requirement revision and mandatory evidence.", "Associate each check and substantive review finding with the candidate it actually concerns.", "Identify stale evidence, unresolved findings, missing decisions and dependency changes rather than flattening them into one status.", "Propose the next bounded action, such as rerunning a check, requesting a clarification or presenting a current bundle to the reviewer.", "Recompute readiness after changes and retain false-ready incidents as an explicit outcome for improving the monitor." ], "example": "Illustrative example: A pull request passed checks, then received a new commit adjusting replay behavior. The monitor finds that the visible approval and independent replay result concern the previous revision. It reports the precise stale evidence and prepares the current diff for review. Answering the earlier comment or seeing one green job does not restore readiness until the applicable evidence is renewed under the repository's policy.", "verification": [ "Every required result and review disposition matches the revision or supported scope claimed.", "A newly pushed commit or relevant base change invalidates only the evidence whose applicability must be renewed.", "The monitor can demonstrate a false-ready case and reports it separately from ordinary waiting." ], "outputs": [ "Revision-specific readiness report with blockers and next actions.", "Evidence renewal and disposition history, including false-ready observations." ], "risks": [ "Automated reminders can add noise or pressure without resolving the actual missing decision.", "A stale approval can look authoritative when its associated candidate identity is hidden." ], "related_practices": [ "PAT:003", "PAT:010", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 8's thematic guidance. The historical family is F08. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:039", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T14" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:AI as reviewer", "K:Automation bias and trust", "K:Review capacity and maintainers" ], "volumes": [ "V06" ], "families": [ "FAMILY:F08" ] }, { "id": "PAT:040", "label": "Post-merge cleanup", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C05", "C:C13" ], "printed": false, "summary": "Inspect the integrated result for justified follow-up maintenance, such as obsolete temporary artifacts, duplicated explanations or incomplete handoff notes. Produce scoped proposals with evidence and ownership before making further changes. Merge is a new baseline for inspection, not standing permission for broad cleanup or proof that every leftover item is safe to remove.", "limitation": "Apparently unused code, files or branches may still support consumers, rollback or historical explanation; cleanup evidence can be incomplete.", "url": "", "authors": "", "year": "", "attributes": { "label": "Post-merge cleanup", "kind": "practice_descriptor", "collection": "PAT", "family": "F05", "chapter": 5, "disposition": "Brief thematic reference", "required_revision": "Use this as a source of maintenance proposals, not automatic authorization to rewrite.", "occurrences": "[\"LOOP:T15\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Apparently unused code, files or branches may still support consumers, rollback or historical explanation; cleanup evidence can be incomplete.", "historical_structural_chapters": [ "C:C05" ], "family_name": "Architecture, Evolution and Maintenance", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RINVIO_BREVE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep integration from leaving avoidable maintenance burden while preserving the obligations and history needed by the next engineer.", "when_to_use": [ "A completed change leaves known temporary scaffolding or an explicitly deferred maintenance item.", "Integration reveals duplicated or outdated material that a maintainer should assess." ], "when_not_to_use": [ "The proposed cleanup has no demonstrated consequence beyond aesthetic preference.", "Deletion could remove user work, recovery evidence or a consumer whose existence has not been checked." ], "prerequisites": [ "An identified integrated baseline and the original task's actual cleanup authorization.", "An owner for each affected target and evidence of the artifact's current purpose or obsolescence." ], "steps": [ "Inspect the integrated diff and deferred-work record for specific follow-up candidates rather than scanning for unrestricted rewrites.", "For each candidate, identify its purpose, consumers, retention needs and the consequence of leaving or changing it.", "Separate cleanup already authorized by the task from new maintenance proposals that need their own scope decision.", "Apply eligible changes in a bounded candidate and verify the relevant behavior, documentation or recovery path.", "Record the outcome and preserve the rationale for retained items or deferred proposals so a later sweeper does not rediscover the same uncertainty." ], "example": "Illustrative example: After an API migration merges, a temporary compatibility note appears outdated. The maintainer checks that the old endpoint still serves one documented client, so the note remains with a revised validity statement. An unused migration scratch file can be removed within the authorized cleanup scope. A broader rewrite of the adapter becomes a separate proposal with its own behavior and review requirements.", "verification": [ "Each removal or rewrite has evidence about its purpose and affected consumers.", "The candidate stays within explicit cleanup authority and preserves required historical or recovery artifacts.", "Relevant checks run on the integrated baseline rather than an obsolete pre-merge workspace." ], "outputs": [ "Scoped maintenance proposal or authorized cleanup candidate.", "Verified result and rationale for items retained, changed or deferred." ], "risks": [ "Broad cleanup can obscure the original change and create unrelated regressions.", "Deleting evidence too early can make later diagnosis or rollback reasoning harder even when the running code is unaffected." ], "related_practices": [ "PAT:015", "PAT:031", "PAT:054" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 5's thematic guidance. The historical family is F05. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:040", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C05", "file": "EN/chapters/chapter05.tex", "line": 3, "sha256": "f6e123ae06931297b82554424c5b9b9c4b6bdb00e897814d515d11203e684075", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C05", "title": "Quality, Architecture and Maintainability", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T15" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Architecture and modularity", "K:Code reuse and duplication", "K:Technical debt and complexity" ], "volumes": [ "V06" ], "families": [ "FAMILY:F05" ] }, { "id": "PAT:041", "label": "Changelog drafter", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Draft a changelog from a defined change range and attributable evidence, separating implemented changes, user-visible effects, unresolved work and actual release status. Preserve links that let a reviewer challenge each material statement. The draft communicates verified scope; it is not itself proof that work completed, was accepted, reached production or produced the claimed benefit.", "limitation": "Commits and PR descriptions can misstate behavior or deployment status; a coherent narrative can still omit breaking effects or promote unfinished work.", "url": "", "authors": "", "year": "", "attributes": { "label": "Changelog drafter", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Companion variant", "required_revision": "Provide a sourced draft for review; release notes are not evidence of completion.", "occurrences": "[\"LOOP:T16\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Commits and PR descriptions can misstate behavior or deployment status; a coherent narrative can still omit breaking effects or promote unfinished work.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "COMPANION", "practice_scope": "Optional companion variant", "practice": { "schema_version": 1, "language": "en", "purpose": "Turn a set of changes into an accurate reader-facing account without letting generated prose enlarge the delivered scope.", "when_to_use": [ "A release or update has a clear baseline and target whose differences need explanation.", "Maintainers need a concise draft that traces claims to the accepted change record." ], "when_not_to_use": [ "The release range or actual publication status is unknown.", "The draft would infer user benefits or completed work from plans, commit messages or unreviewed proposals alone." ], "prerequisites": [ "Identified baseline and target revisions with relevant issue, diff and verification records.", "An editor or release owner who can confirm the audience, terminology and publication status." ], "steps": [ "Establish the exact comparison range and distinguish accepted changes from proposals, reverted work and unrelated commits.", "Inspect the actual diff and supporting records, identifying externally meaningful behavior and any compatibility or migration implications.", "Draft concise claims linked to their evidence, labeling unknown deployment or validation status rather than filling gaps.", "Have the responsible reviewer check completeness, wording, breaking effects and the relationship between code changes and actual release.", "Publish only through the authorized process and preserve the reviewed range and evidence links for future correction." ], "example": "Illustrative example: A website update translates practice descriptions and adds a catalogue collection. The draft points to the changed catalogue data and verified navigation, while distinguishing those completed package changes from deployment to the public site. It does not say the update is live merely because a ZIP exists. A reviewer checks the range and removes a claim about unrelated articles that were not changed in this release.", "verification": [ "Every material statement is supported by the selected change range and relevant evidence.", "The text distinguishes implementation, acceptance, publication and measured outcomes where those statuses differ.", "Known incompatibilities, required user actions and incomplete work are accurately represented." ], "outputs": [ "Reviewed changelog draft with evidence links and defined revision range.", "Publication disposition and any unresolved wording or status questions." ], "risks": [ "An attractive summary can overstate the scope by repeating a PR's original ambition.", "Grouping changes too aggressively can hide an action users must take or an important compatibility boundary." ], "related_practices": [ "PAT:029", "PAT:038", "PAT:062" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 9's thematic guidance. The historical family is F09. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:041", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T16" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:042", "label": "Capstone orchestra", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Economics", "T:Jobs & roles" ], "actual": [], "mapped": [ "C:C12", "C:C13" ], "printed": false, "summary": "Compose several practices around one concrete capstone task only when each mechanism addresses a named uncertainty and justifies its marginal cost. Define the authorized outcome, shared evidence and decision rights before coordinating components. This retained companion concept is an integration exercise, not evidence that a large orchestration stack improves every task or that course materials establish operational results.", "limitation": "An impressive multi-component demonstration can conceal duplicated work and correlated errors; exercise completion does not establish production value or independently retained skill.", "url": "", "authors": "", "year": "", "attributes": { "label": "Capstone orchestra", "kind": "practice_descriptor", "collection": "PAT", "family": "F12", "chapter": 12, "disposition": "Brief thematic reference", "required_revision": "Composition is useful only when it justifies marginal cost; verify course data before reusing it.", "occurrences": "[\"LOOP:T17\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An impressive multi-component demonstration can conceal duplicated work and correlated errors; exercise completion does not establish production value or independently retained skill.", "historical_structural_chapters": [ "C:C12" ], "family_name": "Economics, Infrastructure and Work", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RINVIO_BREVE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Assess whether the selected mechanisms work together to deliver one accountable outcome at an acceptable total burden.", "when_to_use": [ "A learning or pilot task needs to examine interactions among scope, execution, verification, review and handoff.", "Simpler routes have an identified limitation that an added mechanism could plausibly address." ], "when_not_to_use": [ "The objective is to demonstrate as many agents or tools as possible.", "Course examples, completion statistics or cost inputs have not been checked but would be presented as observed results." ], "prerequisites": [ "A bounded task contract, independent outcome checks and a named integration owner.", "A simpler eligible comparison route plus a ledger for setup, coordination, verification and review." ], "steps": [ "State the outcome and consequential uncertainties, including the minimum controls required regardless of the chosen machinery.", "Assign a purpose to every proposed component and omit those that do not change a necessary decision or useful observation.", "Define interfaces, ownership, permission boundaries and evidence identities so one component cannot assume another's authority.", "Run the bounded composition, retaining failures, handoff losses, rejected work and the actual integration burden.", "Evaluate the accepted result and the marginal value of each mechanism, then simplify or stop where the evidence does not support keeping it." ], "example": "Illustrative example: A capstone updates a small service and its documentation. The team compares an interactive route with a bounded maker and an independent checker, using the same requirements and behavior cases. It records setup, review and integration effort rather than counting generated artifacts. An additional debate agent is omitted because no unresolved decision needs it; any educational benefit is assessed separately through the learner's later independent work.", "verification": [ "Every retained component has a named purpose, output and accountable integration boundary.", "The outcome evidence concerns the integrated candidate and preserves required independence and authority.", "Cost or learning conclusions distinguish observed pilot results, assumptions, unverified course claims and unknown follow-up." ], "outputs": [ "Composition and decision record with integrated candidate evidence.", "Cost and learning observations, plus reasons to keep, simplify or retire mechanisms." ], "risks": [ "A complex demonstration can reward visible activity while shifting the real burden into review.", "Reusing illustrative course inputs as measurements can create a fabricated return or effectiveness claim." ], "related_practices": [ "PAT:033", "PAT:056", "PAT:060" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor, NDSE2 Chapter 13's practice-selection guidance and Chapter 12's thematic guidance. The historical family is F12. The example is illustrative, not a reported study.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:042", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C12", "file": "EN/chapters/chapter12.tex", "line": 3, "sha256": "86c0ede476fd2a1b32d32f4ea86297429dd24aad34db3f6c7540431e1190ccbe", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C12", "title": "Economics, Jobs, Risk and Evidence-Based Adoption", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:LOOP:T17" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Economic costs and return", "K:Employment and early-career roles", "K:Evaluation methodology and baselines" ], "volumes": [ "V06" ], "families": [ "FAMILY:F12" ] }, { "id": "PAT:043", "label": "Spec-First Generation", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Establish the intended behavior and representative scenarios before asking an assistant to generate a candidate implementation. The specification states obligations that an accountable owner has authorized; the implementation plan proposes how to satisfy them. Keep these separate so a convenient design cannot quietly redefine success.", "limitation": "A specification can be internally clear yet omit a consequential stakeholder requirement; generation does not resolve that omission.", "url": "", "authors": "", "year": "", "attributes": { "label": "Spec-First Generation", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Recompose the mechanism", "required_revision": "Establish authorized intention and scenarios before the candidate; keep the specification distinct from the plan.", "occurrences": "[\"NDSE:01\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A specification can be internally clear yet omit a consequential stakeholder requirement; generation does not resolve that omission.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make the acceptance question inspectable before implementation choices begin to shape the apparent requirements.", "when_to_use": [ "A change affects observable behavior, compatibility, policy, or an interface used by others.", "Several implementations are plausible and reviewers need a common basis for judging them." ], "when_not_to_use": [ "The purpose is still an exploratory hypothesis; first authorize a bounded experiment and label its provisional assumptions." ], "prerequisites": [ "A named owner can resolve consequential behavior questions.", "Existing obligations, affected consumers, and authoritative scenarios are accessible." ], "steps": [ "Describe outcomes, boundaries, exclusions, and failure behavior without prescribing unnecessary implementation details.", "Write ordinary, boundary, and negative scenarios; record where each expected result comes from.", "Resolve blocking questions with the owner and version the approved answers together with remaining explicit unknowns.", "Ask for an implementation plan that references the obligations; reject plan choices that silently change them.", "Generate within the permitted scope, then compare the candidate with the approved scenarios and required regressions." ], "example": "Illustrative example: A service must preserve the response originally stored for a repeated request. The specification records the request identity, permitted payload, and expected historical response before an agent chooses a storage design. When the agent proposes reevaluating the request under current policy, the owner can identify a contract violation without debating the programming language or persistence library.", "verification": [ "Each material acceptance claim traces to an authorized behavior statement.", "The plan can change without changing the approved expected outcomes.", "Unresolved high-consequence questions block the affected candidate rather than becoming implementation assumptions." ], "outputs": [ "A versioned behavior contract with scenarios.", "A separately revisable implementation plan and an impact list." ], "risks": [ "Copying implementation behavior into the specification can preserve an existing defect.", "An elaborate document may hide a missing decision behind polished prose." ], "related_practices": [ "PAT:067", "PAT:044", "PAT:061" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:043", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:01" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:044", "label": "Test-Driven AI Development", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Verification & review", "T:What agents can do" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Write and examine tests before AI-assisted implementation, deriving expected results from an independently authorized behavior reference. Preserve the initial failing case, implement a bounded change, and rerun the relevant checks. The value comes from the quality and protection of the oracle, not merely the order in which files were created.", "limitation": "Passing tests establish behavior for their checked conditions; even independent expectations do not provide complete defect coverage.", "url": "", "authors": "", "year": "", "attributes": { "label": "Test-Driven AI Development", "kind": "practice_descriptor", "collection": "PAT", "family": "F07", "chapter": 7, "disposition": "Retain with explicit qualifications", "required_revision": "Test-first work requires independently grounded expected results; a green result is local to its oracle.", "occurrences": "[\"NDSE:02\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Passing tests establish behavior for their checked conditions; even independent expectations do not provide complete defect coverage.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Tests, Oracles and Acceptance Evidence", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent a candidate and its generated tests from agreeing on the same incorrect interpretation of required behavior.", "when_to_use": [ "A defect has a reproducible input and an authoritative expected outcome.", "New behavior can be expressed through examples, invariants, or an established interface contract." ], "when_not_to_use": [ "Expected behavior is disputed or unavailable; clarify it before treating an assertion as an acceptance oracle." ], "prerequisites": [ "A protected expectation source and a reproducible test environment.", "The maker cannot silently rewrite mandatory acceptance checks." ], "steps": [ "Identify the requirement and independently derive the expected result, retaining its version and owner.", "Create a focused check and confirm that it fails on the relevant wrong behavior for the intended reason.", "Record the failure before implementation; distinguish a meaningful assertion failure from broken test setup.", "Let the maker implement the smallest coherent repair while retaining the approved expectation.", "Rerun the focused check and mandatory regressions; keep maker-written supplementary tests clearly identified." ], "example": "Illustrative example: An old routing function approves a flagged request. Before repair, a reviewer derives a rejection expectation from the approved policy and records the failing case. The agent changes the routing condition. The same protected test now passes, while a nearby ordinary request remains covered. A new test that simply copies the agent’s output would not supply that independent challenge.", "verification": [ "The original wrong implementation fails a named behavioral assertion.", "The corrected candidate passes without an unapproved expectation change.", "Boundary and regression checks cover relevant neighboring behavior, with omissions recorded." ], "outputs": [ "An independently grounded failing case and its post-change result.", "A candidate-bound test report with oracle provenance." ], "risks": [ "Tests generated from a defective implementation can encode its defect as the expected answer.", "A maker with write access to the oracle can turn a real failure into a misleading pass." ], "related_practices": [ "PAT:014", "PAT:027", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 7 and 13 thematic guidance. Family F07 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:044", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:02" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dataset provenance and dependency", "K:Independent verification and oracles" ], "volumes": [ "V06" ], "families": [ "FAMILY:F07" ] }, { "id": "PAT:045", "label": "Exploratory Vibe Coding", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C01", "C:C13" ], "printed": false, "summary": "Use conversational generation to explore a design question in a reversible setting. State the hypothesis, permitted effects, and disposal or adoption decision before iterating. A promising prototype can reveal an interaction or feasibility issue, but becoming a maintained product requires a separate decision about ownership, evidence, and operational obligations.", "limitation": "An attractive or apparently complete prototype does not establish maintainability, security, accessibility, or readiness for operational use.", "url": "", "authors": "", "year": "", "attributes": { "label": "Exploratory Vibe Coding", "kind": "practice_descriptor", "collection": "PAT", "family": "F01", "chapter": 1, "disposition": "Retain", "required_revision": "Keep reversible exploration separate from the decision to adopt its result.", "occurrences": "[\"NDSE:03\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An attractive or apparently complete prototype does not establish maintainability, security, accessibility, or readiness for operational use.", "historical_structural_chapters": [ "C:C01" ], "family_name": "Scope, Exploration and Accountability", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Answer an uncertain design question cheaply enough to discard the experiment when its premise fails.", "when_to_use": [ "A team is comparing interaction ideas or testing a narrow technical possibility.", "Requirements are provisional and the artifact can remain isolated from consequential users and systems." ], "when_not_to_use": [ "The work would immediately control sensitive decisions or irreversible effects without an adequate authorized delivery path." ], "prerequisites": [ "A clear exploratory question, short time budget, and experiment owner.", "Disposable data and an environment with bounded effects." ], "steps": [ "Name the question the prototype should answer and what observation would make it unhelpful.", "Set the writable scope, permitted tools, data boundary, and stopping condition before generation.", "Iterate on the uncertain aspect; record assumptions and manual shortcuts as they are introduced.", "Exercise the relevant interaction or technical path and separate observations from guesses about broader behavior.", "Conclude with discard, another bounded experiment, or an explicit adoption proposal that identifies unmet engineering obligations." ], "example": "Illustrative example: A team compares two ways to display policy exceptions using synthetic requests. An assistant generates both interfaces, and the owner observes whether users can distinguish historical and current decisions. The preferred sketch becomes design evidence. Before it enters the maintained service, the team must still review its data model, authorization behavior, accessibility, tests, and ongoing ownership.", "verification": [ "The recorded finding answers the original exploratory question.", "No prototype shortcut is silently represented as an approved product requirement.", "Any proposed adoption names the missing evidence and the responsible decision maker." ], "outputs": [ "A bounded prototype and an observation log.", "A disposal decision or scoped adoption proposal." ], "risks": [ "Visual polish can encourage premature promotion and hide missing operational behavior.", "Repeated exploratory changes can accumulate dependencies that make supposedly disposable work difficult to abandon." ], "related_practices": [ "PAT:043", "PAT:017", "PAT:048" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 1 and 13 thematic guidance. Family F01 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:045", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C01", "file": "EN/chapters/chapter01.tex", "line": 3, "sha256": "277ec2181a885dfee7268a6d504503c8c039a8cc6c8201bfd2a966515d5b2500", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C01", "title": "AI Changes the Unit of Software Work", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:03" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Developer workflow and adoption", "K:Human-agent collaboration" ], "volumes": [ "V06" ], "families": [ "FAMILY:F01" ] }, { "id": "PAT:046", "label": "Small Verifiable Chunks", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Divide work into increments whose behavior and impact can be meaningfully checked. A small chunk has one coherent acceptance question, bounded dependencies, and a reviewable result; its size is not determined by line count. Use that semantic scope inside a cycle without assuming that the chunk and the execution cycle are identical concepts.", "limitation": "Artificially tiny edits can obscure a cross-cutting invariant and increase integration work rather than make verification easier.", "url": "", "authors": "", "year": "", "attributes": { "label": "Small Verifiable Chunks", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Recompose the mechanism", "required_revision": "Small means semantically verifiable; connect it to one-item execution without confusing a chunk with a cycle.", "occurrences": "[\"NDSE:04\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Artificially tiny edits can obscure a cross-cutting invariant and increase integration work rather than make verification easier.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Give a reviewer enough context to diagnose whether a particular intended change has been achieved.", "when_to_use": [ "A proposed patch contains multiple unrelated outcomes or failures are difficult to attribute.", "An agent needs an item that fits the available evidence, review capacity, and execution budget." ], "when_not_to_use": [ "Splitting would temporarily violate an invariant that must change atomically across several components." ], "prerequisites": [ "The intended outcome and affected interfaces are understood.", "Relevant checks and required integration obligations are identifiable." ], "steps": [ "State the behavioral outcome in one sentence and identify what remains explicitly outside the item.", "Trace the dependencies required to make that outcome coherent; include necessary files even when this enlarges the diff.", "Choose a focused acceptance check and the regressions that protect neighboring obligations.", "Implement and inspect the increment as a unit, recording any newly discovered dependency or ambiguity.", "Return an independently reviewable result; create a separate item for unrelated findings instead of broadening the current one." ], "example": "Illustrative example: Changing how historical requests are replayed touches a handler, storage adapter, and contract test. Those files belong to one verifiable behavior and stay together. A nearby formatting cleanup and a new reporting endpoint become separate items. If a regression fails, the reviewer can relate it to replay semantics instead of reconstructing three unrelated changes.", "verification": [ "The item has one explainable acceptance question and a traceable result.", "Its boundaries include the dependencies necessary to preserve the relevant invariant.", "The proposed split leaves a viable integration path and records remaining work." ], "outputs": [ "A scoped work item with acceptance and regression checks.", "A reviewable candidate and separate follow-up items." ], "risks": [ "Using file count as a proxy for simplicity can split behavior across incompatible changes.", "Local passes can conceal an integration failure when each chunk is checked in isolation." ], "related_practices": [ "PAT:081", "PAT:015", "PAT:056" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 3 and 13 thematic guidance. Family F03 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:046", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:04" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:047", "label": "Context Engineering", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Assemble the minimum relevant context while preserving the distinction between instructions, retrieved information, task state, and authorized evidence. Give each item a role, version, source, and validity scope. This helps an assistant reason from the right material without treating a plausible retrieved passage or an old checkpoint as current decision authority.", "limitation": "Context selection can improve traceability, but it cannot ensure that the model understands the system or notices every omission.", "url": "", "authors": "", "year": "", "attributes": { "label": "Context Engineering", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Recompose the mechanism", "required_revision": "Instructions, retrieval, task state, and authorized evidence are not interchangeable.", "occurrences": "[\"NDSE:05\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Context selection can improve traceability, but it cannot ensure that the model understands the system or notices every omission.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Reduce mistakes caused by missing system knowledge, conflicting context roles, or stale information presented without qualification.", "when_to_use": [ "A brownfield task depends on repository conventions, historical rationale, or external decisions.", "Long sessions repeatedly lose important constraints or accumulate irrelevant retrieved material." ], "when_not_to_use": [ "The real blocker is an absent policy decision; supplying more context cannot create the missing authority." ], "prerequisites": [ "A task envelope identifies the decision and permissible actions.", "Source locators, versions, and knowledge owners are available where material." ], "steps": [ "List what must be known to perform and check the task, separating obligations from background explanation.", "Retrieve specific passages or artifacts with their locators and revision scope rather than indiscriminately copying entire collections.", "Label authoritative decisions, observations, tentative inferences, and historical records so their roles remain visible.", "Create a concise working state containing the current objective, evidence, open questions, and next permitted action.", "Refresh affected context after a relevant change; retain obsolete records as history while excluding them from current authority." ], "example": "Illustrative example: An agent repairing a replay endpoint receives the current contract, a historical policy note, a storage map, and the last failed check. The historical note explains an old response but cannot authorize behavior for new requests. The context bundle makes that distinction explicit, preventing the assistant from applying yesterday’s threshold simply because it is well documented.", "verification": [ "Material claims link to identifiable sources and validity scopes.", "The bundle separates approved instructions from retrieved or inferred information.", "A changed rule triggers refresh of the affected task state and dependencies." ], "outputs": [ "A typed, task-specific context bundle.", "A record of unresolved questions and refresh triggers." ], "risks": [ "Context stuffing can bury the deciding constraint beneath relevant-looking detail.", "Repository prose or retrieved content can be mistaken for operational instructions." ], "related_practices": [ "PAT:029", "PAT:016", "PAT:072" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 9 and 13 thematic guidance. Family F09 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:047", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:05" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:048", "label": "The Explainability Test", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Jobs & roles", "T:Skills & learning" ], "actual": [], "mapped": [ "C:C10", "C:C13" ], "printed": false, "summary": "Ask a developer to reconstruct how a candidate works, why its invariants hold, and where it could fail. Evaluate that explanation as a comprehension task using concrete predictions and evidence. A clear explanation can expose missing understanding, but persuasive language, whether produced by a person or an assistant, is insufficient proof that the implementation is correct.", "limitation": "A person can explain a flawed design coherently, and a correct implementation can exceed their present ability to explain it.", "url": "", "authors": "", "year": "", "attributes": { "label": "The Explainability Test", "kind": "practice_descriptor", "collection": "PAT", "family": "F10", "chapter": 10, "disposition": "Retain with explicit qualifications", "required_revision": "Treat explanation as a comprehension task, not sufficient evidence of correctness.", "occurrences": "[\"NDSE:06\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A person can explain a flawed design coherently, and a correct implementation can exceed their present ability to explain it.", "historical_structural_chapters": [ "C:C10" ], "family_name": "Competence, Learning and Mentoring", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Check whether the person expected to maintain or review a change has a usable mental model of its behavior.", "when_to_use": [ "A developer adopts generated code they did not substantially construct themselves.", "A handoff or review depends on understanding an invariant, failure path, or design tradeoff." ], "when_not_to_use": [ "The only goal is to prove correctness; use independent tests and other appropriate evidence as well." ], "prerequisites": [ "A bounded candidate and a relevant behavioral contract.", "Questions with observable answers and a reviewer who can assess the reasoning." ], "steps": [ "Select a consequential path or invariant rather than asking for a general code tour.", "Ask the learner to predict a concrete outcome before running the program or consulting an assistant.", "Require a walkthrough connecting the prediction to specific code, data, and authorized behavior.", "Introduce a counterexample or small variation and ask what must change, what remains stable, and why.", "Compare the explanation with execution evidence, record misconceptions, and give a targeted follow-up task." ], "example": "Illustrative example: After accepting an AI-assisted storage refactor, a maintainer predicts what a repeated request returns after a policy update. They trace the lookup key, stored response, and conflict path before observing the run. If the explanation depends on reevaluating current policy, the reviewer has found a comprehension gap even when the existing regression suite happens to pass.", "verification": [ "The learner predicts behavior on an unseen variation, not just the demonstrated example.", "Claims about code paths and invariants withstand inspection and relevant execution.", "Misconceptions lead to a corrective exercise whose result is assessed separately." ], "outputs": [ "A short comprehension assessment with observed gaps.", "A targeted explanation, repair, or transfer exercise." ], "risks": [ "A fluent assistant-written answer can substitute for the learner’s own reconstruction.", "Confidence or presentation quality can bias assessment away from the actual reasoning." ], "related_practices": [ "PAT:050", "PAT:055", "PAT:044" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 10 and 13 thematic guidance. Family F10 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:048", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C10", "file": "EN/chapters/chapter10.tex", "line": 3, "sha256": "8c1523efe9ff14e391995db26334a679c629258003f891389e55b9183e57f36f", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C10", "title": "Developer Learning, Mentoring and Comprehension Debt", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:06" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Cognitive offloading and skill debt", "K:Human cognitive load", "K:Onboarding and developer fluency", "K:Remote work and apprenticeship", "K:Skills formation and teaching" ], "volumes": [ "V06" ], "families": [ "FAMILY:F10" ] }, { "id": "PAT:049", "label": "Runtime-in-the-Loop", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C05", "C:C13" ], "printed": false, "summary": "Bring observed execution into a development decision by connecting a runtime question to an expected result, a controlled scenario, and the candidate that was run. Use logs, traces, or measurements to resolve that question. Record conditions and limitations so a successful local observation is not presented as an unperformed production or performance evaluation.", "limitation": "Runtime evidence covers the exercised environment, inputs, and observation window; untested operational properties remain unresolved.", "url": "", "authors": "", "year": "", "attributes": { "label": "Runtime-in-the-Loop", "kind": "practice_descriptor", "collection": "PAT", "family": "F05", "chapter": 5, "disposition": "Expand the operational treatment", "required_revision": "Connect runtime observation to an expectation and decision; do not claim measurements that were not executed.", "occurrences": "[\"NDSE:07\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Runtime evidence covers the exercised environment, inputs, and observation window; untested operational properties remain unresolved.", "historical_structural_chapters": [ "C:C05" ], "family_name": "Architecture, Evolution and Maintenance", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "AMPLIARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Replace speculative reasoning about an exercised path with inspectable observations that affect the next engineering decision.", "when_to_use": [ "A behavior depends on state, integration, ordering, or runtime configuration that static reading leaves uncertain.", "An architectural change needs evidence that a relevant behavior survives the new representation." ], "when_not_to_use": [ "The required experiment would cause unauthorized external effects or cannot produce a trustworthy observation." ], "prerequisites": [ "An explicit question, expected behavior, and safe execution environment.", "A known candidate version and instruments appropriate to the question." ], "steps": [ "State the claim to examine and define the input, initial state, and expected observation before execution.", "Record the candidate, configuration, data, command, and relevant environmental assumptions.", "Run the scenario and capture the raw observation without replacing unexpected results with the intended story.", "Compare observations with the expectation; classify a mismatch as a candidate defect, environment issue, or unresolved requirement.", "Use the diagnosis to choose a bounded repair or further experiment, retaining both positive and negative results." ], "example": "Illustrative example: A representation migration appears to preserve request replay. The team starts with a stored response from the earlier policy, restarts the service with the new representation, and repeats the request. The captured response and storage trace answer the replay question. They do not establish throughput under load, recovery from every failure, or behavior on a different deployment configuration.", "verification": [ "The reported result can be traced to a real invocation and candidate snapshot.", "The observation tests the stated expectation rather than a convenient substitute.", "Unmeasured claims and environmental differences remain explicit in the decision." ], "outputs": [ "A reproducible scenario and captured runtime evidence.", "A bounded conclusion with the resulting engineering action." ], "risks": [ "Instrumentation may miss the deciding event or alter the behavior under examination.", "A familiar local setup can encourage unjustified claims about operational performance." ], "related_practices": [ "PAT:054", "PAT:082", "PAT:014" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 5 and 13 thematic guidance. Family F05 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:049", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C05", "file": "EN/chapters/chapter05.tex", "line": 3, "sha256": "f6e123ae06931297b82554424c5b9b9c4b6bdb00e897814d515d11203e684075", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C05", "title": "Quality, Architecture and Maintainability", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:07" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Architecture and modularity", "K:Code reuse and duplication", "K:Technical debt and complexity" ], "volumes": [ "V06" ], "families": [ "FAMILY:F05" ] }, { "id": "PAT:050", "label": "Learning Loop Preservation", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Jobs & roles", "T:Skills & learning" ], "actual": [], "mapped": [ "C:C10", "C:C13" ], "printed": false, "summary": "Preserve opportunities to predict, diagnose, explain, and repair while using AI assistance. Define the capability a learner should retain, design tasks that require their own reasoning, and assess transfer separately from immediate completion. Assistance can remain available, but its output must not be mistaken for evidence that the learner can perform the same judgment independently.", "limitation": "A well-designed learning activity is a proposed mechanism; durable skill gains require observation and cannot be promised from the workflow alone.", "url": "", "authors": "", "year": "", "attributes": { "label": "Learning Loop Preservation", "kind": "practice_descriptor", "collection": "PAT", "family": "F10", "chapter": 10, "disposition": "Retain", "required_revision": "Preserve cognitive practice and assess transfer; do not promise learning effects.", "occurrences": "[\"NDSE:08\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A well-designed learning activity is a proposed mechanism; durable skill gains require observation and cannot be promised from the workflow alone.", "historical_structural_chapters": [ "C:C10" ], "family_name": "Competence, Learning and Mentoring", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep successful assisted delivery from concealing an inability to understand or maintain the resulting system.", "when_to_use": [ "Repeated automation removes the debugging or design decisions through which a developer normally learns.", "A mentoring program must distinguish supported performance from retained individual capability." ], "when_not_to_use": [ "The activity has no learning objective and adding a training exercise would interfere with a time-critical authorized response." ], "prerequisites": [ "A specific skill target and a suitably bounded exercise.", "A mentor or assessment method that can evaluate reasoning and provide feedback." ], "steps": [ "Choose the capability to retain, such as diagnosing replay errors, and define observable evidence of that capability.", "Ask for a prediction or initial diagnosis before revealing a generated solution or explanation.", "Use assistance for targeted feedback, alternative hypotheses, or scaffolding while keeping consequential reasoning with the learner.", "Have the learner repair or explain the result in their own terms and identify why rejected approaches fail.", "Assess a different case later, recording available assistance and distinguishing retention from repeated familiarity with the original example." ], "example": "Illustrative example: A junior engineer first predicts why a stored request behaves differently after a policy change, then compares the prediction with a trace. An assistant offers focused questions rather than the completed patch. After the repair, the mentor assigns a different historical-data case at a later session. The second result informs a learning judgment; the first task’s green tests alone do not.", "verification": [ "The learner performs a meaningful reasoning step before seeing the proposed answer.", "Assessment separates task completion, explanation quality, and later transfer.", "Observed misconceptions change the next exercise rather than disappearing into a completion score." ], "outputs": [ "A capability objective and assisted-practice plan.", "Separate records of immediate performance and transfer observations." ], "risks": [ "Removing all assistance can turn a learning exercise into avoidable frustration rather than useful practice.", "Reusing the same example can reward memorization and overstate transferable understanding." ], "related_practices": [ "PAT:012", "PAT:048", "PAT:055" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 10 and 13 thematic guidance. Family F10 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:050", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C10", "file": "EN/chapters/chapter10.tex", "line": 3, "sha256": "8c1523efe9ff14e391995db26334a679c629258003f891389e55b9183e57f36f", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C10", "title": "Developer Learning, Mentoring and Comprehension Debt", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:08" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Cognitive offloading and skill debt", "K:Human cognitive load", "K:Onboarding and developer fluency", "K:Remote work and apprenticeship", "K:Skills formation and teaching" ], "volumes": [ "V06" ], "families": [ "FAMILY:F10" ] }, { "id": "PAT:051", "label": "Security-First Development", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Examine security concerns before generating or adopting a change, treating the product and the agent’s development environment as separate attack surfaces. Translate consequential threats into concrete controls and checks, then carry findings into the release decision. Early attention organizes the work; it does not make a secure outcome follow automatically from the practice’s name.", "limitation": "Selected threat analysis and checks cannot establish that all vulnerabilities or operational attack paths have been excluded.", "url": "", "authors": "", "year": "", "attributes": { "label": "Security-First Development", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Recompose the mechanism", "required_revision": "Distinguish product security from security of the development chain and connect both to the Security Pipeline.", "occurrences": "[\"NDSE:09\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Selected threat analysis and checks cannot establish that all vulnerabilities or operational attack paths have been excluded.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent a functionally correct candidate from obscuring an unmanaged application threat or an overpowered development tool.", "when_to_use": [ "A change handles sensitive information, authorization, external input, or consequential operations.", "An assistant gains tools, dependencies, credentials, or access to a repository containing untrusted material." ], "when_not_to_use": [ "A generic checklist would replace an already required specialist review of a consequential threat." ], "prerequisites": [ "An inventory of protected assets and permitted operations.", "Owners for application security, tool permissions, and unresolved exceptions." ], "steps": [ "Identify what the resulting application must protect and which attacker-controlled inputs could reach it.", "Separately map what the development agent can read, write, invoke, and transmit through its available tools.", "Choose controls tied to named threats, keeping authority and sensitive expectations outside the maker’s writable scope.", "Exercise relevant negative cases and denial paths; record scanner findings as signals requiring interpretation.", "Carry unresolved threats, applied controls, and residual uncertainty into the accountable review and release process." ], "example": "Illustrative example: An assistant adds a request-import feature. Product checks examine malformed input and whether users can import data outside their entitlement. Development controls separately prevent the assistant from sending fixture data to an arbitrary endpoint or altering protected acceptance rules. Passing parser tests answers neither of those permission questions, so the evidence record keeps both surfaces visible.", "verification": [ "Material threats have an explicit control, test, or recorded unresolved decision.", "Denied tool operations are enforced by the environment, not only by prompt instructions.", "The acceptance record distinguishes functional results from security findings and permissions." ], "outputs": [ "Two scoped threat assessments and their control mapping.", "Security evidence and unresolved issues for review." ], "risks": [ "A clean scanner report can be mistaken for a complete threat assessment.", "A secure application candidate can still be produced through an uncontrolled tool or data boundary." ], "related_practices": [ "PAT:077", "PAT:017", "PAT:079" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 6 and 13 thematic guidance. Family F06 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:051", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:09" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:052", "label": "Review Gauntlet", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Productivity", "T:Verification & review" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Route review effort according to the change’s impact, uncertainty, and available reviewer capacity. Select the checks and people needed to answer its consequential questions, preserve actionable findings, and finish with an accountable verdict. The gauntlet is a configurable review path; imposing the same sequence on every patch can create delay without proportionate information.", "limitation": "More review stages do not necessarily provide independent evidence or improve acceptance decisions when reviewers share assumptions.", "url": "", "authors": "", "year": "", "attributes": { "label": "Review Gauntlet", "kind": "practice_descriptor", "collection": "PAT", "family": "F08", "chapter": 8, "disposition": "Retain with explicit qualifications", "required_revision": "Select review by risk and capacity; avoid imposing an identical ritual on every patch.", "occurrences": "[\"NDSE:10\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "More review stages do not necessarily provide independent evidence or improve acceptance decisions when reviewers share assumptions.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Critique, Review and Trust", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Spend scarce review attention on the uncertainties that could materially change the decision to accept a candidate.", "when_to_use": [ "Different classes of changes currently receive identical review despite very different consequences.", "Generated candidate volume is creating a queue that exceeds meaningful checking capacity." ], "when_not_to_use": [ "A required domain approval would be replaced by a generic model review or a majority vote." ], "prerequisites": [ "A task envelope, candidate revision, and available evidence dossier.", "Named review responsibilities and a known acceptance authority." ], "steps": [ "Classify the candidate’s affected behavior, blast radius, reversibility, and unresolved uncertainty.", "Choose the smallest review path that supplies the required evidence and specialist decisions for that class.", "Check admission against reviewer capacity; limit new candidates when meaningful review cannot keep up.", "Require findings to identify a location, violated expectation, reproducible concern, or specific missing evidence.", "Record a verdict against the actual reviewed revision, including resolved findings and conditions that require another review." ], "example": "Illustrative example: A spelling correction receives a quick scoped diff review. A change to historical payment decisions also receives contract, replay, permission, and owner review. When policy reviewers are fully occupied, the coordinator slows admission of similar candidates rather than creating a growing pile of nominally ready work. Both paths retain a clear acceptance decision appropriate to their consequences.", "verification": [ "Each review stage answers a distinct consequential question for this candidate.", "The verdict identifies the checked revision and the authority behind the decision.", "Queue growth and reviewer workload inform admission, rather than being hidden by generation throughput." ], "outputs": [ "A risk-appropriate review route.", "An evidence-linked verdict and any required follow-up." ], "risks": [ "Unfocused comments can consume capacity while leaving the acceptance question unresolved.", "Repeated automated reviewers may amplify a shared error instead of supplying independent scrutiny." ], "related_practices": [ "PAT:022", "PAT:075", "PAT:027" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 8 and 13 thematic guidance. Family F08 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:052", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:10" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:AI as reviewer", "K:Automation bias and trust", "K:Review capacity and maintainers" ], "volumes": [ "V06" ], "families": [ "FAMILY:F08" ] }, { "id": "PAT:053", "label": "Legacy Code Navigation", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Build a traceable map of an existing system before changing it, separating observed behavior from the intention the system is supposed to implement. Follow entry points, data, invariants, history, and ownership. Use the map to ask better questions and identify checks; a successful code search alone does not establish comprehension or authorize preservation of every legacy behavior.", "limitation": "Incomplete history and sampled execution leave uncertainty; observed legacy behavior cannot automatically serve as normative truth.", "url": "", "authors": "", "year": "", "attributes": { "label": "Legacy Code Navigation", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Retain", "required_revision": "Legacy navigation must distinguish observed behavior from authorized intention.", "occurrences": "[\"NDSE:11\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Incomplete history and sampled execution leave uncertainty; observed legacy behavior cannot automatically serve as normative truth.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Locate the knowledge needed to make a bounded brownfield change without converting implementation accidents into requirements.", "when_to_use": [ "The codebase has unfamiliar conventions, hidden dependencies, or behavior shaped by earlier policy revisions.", "A proposed fix depends on understanding why a seemingly redundant branch or stored field exists." ], "when_not_to_use": [ "The current evidence cannot resolve a consequential business rule; escalate the rule instead of guessing from code." ], "prerequisites": [ "Read access to relevant source, tests, history, and available system documentation.", "A specific change question and access to the appropriate knowledge owner." ], "steps": [ "Start from the user-visible behavior and trace its entry point, state transitions, dependencies, and outputs.", "Record file and revision locators for important observations, distinguishing executed evidence from reading-based inference.", "Compare implementation behavior with approved contracts and historical rationale; flag contradictions without silently choosing a winner.", "Exercise a narrow scenario or ask an owner to resolve the uncertainty most likely to affect the change.", "Publish a concise map, candidate impact set, and open questions that the maker and reviewer can challenge." ], "example": "Illustrative example: A maintainer discovers that a replay handler returns a stored response instead of calling the current evaluator. A superficial cleanup might remove that branch. Navigation connects it to the original policy revision and the historical-response contract, then exercises an old request. The resulting map explains why the branch matters while keeping unrelated undocumented behavior provisional.", "verification": [ "Important architectural claims have reproducible locators or explicit uncertainty labels.", "The map distinguishes what the code does from what an authorized contract requires.", "A reviewer can follow the proposed change through affected behavior and dependencies." ], "outputs": [ "A versioned behavior and dependency map.", "A candidate impact set with unresolved questions and owners." ], "risks": [ "Generated explanations can sound convincing while overlooking an indirect dependency.", "Legacy tests and comments may encode obsolete or incorrect assumptions." ], "related_practices": [ "PAT:008", "PAT:029", "PAT:070" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 9 and 13 thematic guidance. Family F09 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:053", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:11" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:054", "label": "Migration as Learning", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C05", "C:C13" ], "printed": false, "summary": "Use a bounded migration to examine both a system’s behavior and a maintainer’s understanding. Specify what must remain invariant, perform the representation or interface change, and independently check preservation. Evaluate what the maintainer learned through explanation and a further task; a successful migration and retained understanding are distinct outcomes that need different evidence.", "limitation": "Passing migration checks does not demonstrate comprehensive compatibility or prove that the maintainer retained the reasoning behind the change.", "url": "", "authors": "", "year": "", "attributes": { "label": "Migration as Learning", "kind": "practice_descriptor", "collection": "PAT", "family": "F05", "chapter": 5, "disposition": "Retain with explicit qualifications", "required_revision": "Treat verified migration and maintainer learning as two distinct results.", "occurrences": "[\"NDSE:12\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Passing migration checks does not demonstrate comprehensive compatibility or prove that the maintainer retained the reasoning behind the change.", "historical_structural_chapters": [ "C:C05" ], "family_name": "Architecture, Evolution and Maintenance", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Turn a necessary structural change into an inspectable exercise in invariants and design consequences without confusing delivery with education.", "when_to_use": [ "A migration has a manageable scope and clear behavior that must survive a new representation.", "A maintainer needs to understand historical constraints before taking stewardship of the changed component." ], "when_not_to_use": [ "A time-critical migration would be endangered by using an unprepared learner as the sole responsible implementer." ], "prerequisites": [ "A baseline, invariant set, rollback or recovery plan, and appropriate migration owner.", "Separate criteria for technical success and comprehension." ], "steps": [ "Document the old and new representations, including compatibility, historical data, and transition obligations.", "Ask the maintainer to predict the difficult preservation cases and explain the evidence needed for each.", "Execute the bounded migration in a suitable environment, retaining a traceable candidate and old-state fixtures.", "Check the required invariants and operational transition behavior using expectations independent of the migrated implementation.", "Assess understanding with a new variation or repair task and record learning gaps separately from delivery defects." ], "example": "Illustrative example: A team changes the storage layout of previously approved requests. Technical checks verify that old identifiers still return the originally committed responses and that conflicting payloads remain rejected. Afterwards, the maintainer explains how a second schema revision would affect replay and repairs a deliberately different mapping error. The two assessments answer separate questions about the software and its steward.", "verification": [ "Preservation claims link to checks on representative old and new states.", "The migration has a reviewable transition and recovery path.", "The maintainer demonstrates reasoning on a case beyond the rehearsed migration." ], "outputs": [ "A migration candidate with preservation and recovery evidence.", "A separate comprehension assessment and follow-up plan." ], "risks": [ "A happy-path migration may miss historical exceptions or incompatible consumers.", "Completion pressure can conceal learning gaps behind a successful technical result." ], "related_practices": [ "PAT:049", "PAT:048", "PAT:015" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 5 and 13 thematic guidance. Family F05 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:054", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C05", "file": "EN/chapters/chapter05.tex", "line": 3, "sha256": "f6e123ae06931297b82554424c5b9b9c4b6bdb00e897814d515d11203e684075", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C05", "title": "Quality, Architecture and Maintainability", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:12" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Architecture and modularity", "K:Code reuse and duplication", "K:Technical debt and complexity" ], "volumes": [ "V06" ], "families": [ "FAMILY:F05" ] }, { "id": "PAT:055", "label": "Trio Programming", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Jobs & roles", "T:Skills & learning" ], "actual": [], "mapped": [ "C:C10", "C:C13" ], "printed": false, "summary": "Structure collaboration among an experienced developer, a learner, and AI assistance with explicit responsibilities. Let the learner make predictions and explain decisions, use the assistant for bounded support, and have the experienced participant protect the engineering and learning objectives. The arrangement is a mentoring method to evaluate, not a demonstrated guarantee of improved learning.", "limitation": "Role labels alone cannot prevent the expert or assistant from doing all consequential reasoning on the learner’s behalf.", "url": "", "authors": "", "year": "", "attributes": { "label": "Trio Programming", "kind": "practice_descriptor", "collection": "PAT", "family": "F10", "chapter": 10, "disposition": "Retain", "required_revision": "Structure senior, junior, and assistant participation without assuming an educational benefit.", "occurrences": "[\"NDSE:13\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Role labels alone cannot prevent the expert or assistant from doing all consequential reasoning on the learner’s behalf.", "historical_structural_chapters": [ "C:C10" ], "family_name": "Competence, Learning and Mentoring", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Combine expert oversight and useful assistance while keeping the learner actively responsible for developing and testing a mental model.", "when_to_use": [ "A junior developer is learning a consequential code path with an available experienced mentor.", "The team wants assisted progress while observing how the learner reasons about errors and tradeoffs." ], "when_not_to_use": [ "No participant can competently review the work, or the learner is being used as nominal approval for opaque generated output." ], "prerequisites": [ "A bounded technical task and a specific learning objective.", "Agreed roles, time for discussion, and independent acceptance checks." ], "steps": [ "Have the mentor frame the task, invariant, and learning goal without supplying the completed solution.", "Ask the learner to propose a diagnosis or plan before the assistant suggests alternatives.", "Use AI for targeted questions, examples, or candidate code; make the learner explain which suggestions they accept and why.", "Have the mentor challenge one consequential assumption and review evidence without silently taking over the whole task.", "Rotate suitable activities and conclude with an individual explanation or new case that reveals retained understanding." ], "example": "Illustrative example: A senior engineer, a junior engineer, and an assistant inspect a replay defect. The junior predicts the failing path, the assistant helps locate relevant calls, and the senior questions whether current policy should affect stored decisions. The junior implements and explains a bounded repair. A later independent variation checks comprehension instead of treating the trio’s successful patch as a learning result.", "verification": [ "The learner contributes observable diagnosis, prediction, or design reasoning.", "Assistant suggestions are examined against code and authorized behavior.", "Engineering acceptance and learning assessment remain separate decisions." ], "outputs": [ "A reviewed candidate with the learner’s rationale.", "Recorded misconceptions and a suitable follow-up exercise." ], "risks": [ "The learner may become a spectator while the expert and assistant exchange complete solutions.", "Social pressure can make agreement look like comprehension." ], "related_practices": [ "PAT:048", "PAT:050", "PAT:012" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 10 and 13 thematic guidance. Family F10 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:055", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C10", "file": "EN/chapters/chapter10.tex", "line": 3, "sha256": "8c1523efe9ff14e391995db26334a679c629258003f891389e55b9183e57f36f", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C10", "title": "Developer Learning, Mentoring and Comprehension Debt", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:13" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Cognitive offloading and skill debt", "K:Human cognitive load", "K:Onboarding and developer fluency", "K:Remote work and apprenticeship", "K:Skills formation and teaching" ], "volumes": [ "V06" ], "families": [ "FAMILY:F10" ] }, { "id": "PAT:056", "label": "Parallel Work Orchestration", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Coordinate concurrent work only where tasks can be bounded, ownership is clear, and integration and review have capacity. Separate writable workspaces, define shared interfaces, and limit work in progress. Parallel production is useful only when its coordination burden is justified; adding agents does not itself divide semantic responsibility or improve accepted throughput.", "limitation": "Workspace isolation does not prevent duplicate objectives, incompatible assumptions, or integration bottlenecks between otherwise separate tasks.", "url": "", "authors": "", "year": "", "attributes": { "label": "Parallel Work Orchestration", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Recompose the mechanism", "required_revision": "Use work-in-progress limits, ownership, and integration-cost accounting; do not multiply agents by default.", "occurrences": "[\"NDSE:14\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Workspace isolation does not prevent duplicate objectives, incompatible assumptions, or integration bottlenecks between otherwise separate tasks.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Allow independent work to proceed concurrently without losing responsibility for the combined behavior and final decision.", "when_to_use": [ "A change contains genuinely separable tasks with stable interfaces or independent review questions.", "There is enough integration and reviewer capacity to absorb concurrent candidate results." ], "when_not_to_use": [ "Tasks repeatedly modify the same behavioral target or depend on unresolved shared intention." ], "prerequisites": [ "A dependency map and named owner for each semantic target.", "Isolated write scopes, an integration owner, and explicit admission limits." ], "steps": [ "Separate tasks by outcome and dependency, identifying what must remain sequential or centrally decided.", "Assign ownership, scope, expected evidence, and an expiry or return condition for each work allocation.", "Provide isolated workspaces and a shared authoritative interface contract rather than copied, diverging assumptions.", "Admit work according to available review and integration capacity; reassign ownership explicitly when a task stalls.", "Integrate candidates in a controlled order, check combined behavior, and account for discarded work, reconciliation, and review." ], "example": "Illustrative example: One worker improves catalogue search while another translates a separate content dataset under a frozen schema. A single owner controls schema changes and integration. If both workers discover a need to rename a field, they return that decision to the owner rather than independently changing their copies. The combined build is checked after both candidates are reconciled.", "verification": [ "Each target has one current accountable owner and a visible work state.", "Parallel tasks respect shared interface versions and do not conceal semantic overlap.", "The integrated result passes relevant checks and the coordination effort is recorded." ], "outputs": [ "A bounded work allocation and dependency record.", "An integrated candidate with component and combined evidence." ], "risks": [ "More concurrent candidates can overload review and increase unfinished work.", "Independent file edits can still implement conflicting business decisions." ], "related_practices": [ "PAT:019", "PAT:031", "PAT:032" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 11 and 13 thematic guidance. Family F11 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:056", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:14" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:057", "label": "Structured Enablement Program", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Introduce AI-assisted engineering through bounded stages with observable capability, operating controls, and accountable decisions. Teach the tasks and judgment each role needs, collect evidence from an appropriate trial, and adjust the permitted scope accordingly. Course attendance or an adoption calendar can organize activity, but neither establishes that a team is ready for broader delegation.", "limitation": "A completed training program cannot certify reliable performance across untested tasks, teams, tools, or operating conditions.", "url": "", "authors": "", "year": "", "attributes": { "label": "Structured Enablement Program", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Retain with explicit qualifications", "required_revision": "Base adoption on evidence and demonstrated competencies, not the number of courses or a universal calendar.", "occurrences": "[\"NDSE:15\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A completed training program cannot certify reliable performance across untested tasks, teams, tools, or operating conditions.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Connect enablement spending with the practical ability to produce, inspect, govern, and maintain an eligible change.", "when_to_use": [ "A team wants to adopt assistance across roles with different responsibilities and experience.", "An existing rollout reports participation but lacks evidence of sustained engineering capability." ], "when_not_to_use": [ "Training is being used to bypass missing permission controls, review ownership, or required acceptance evidence." ], "prerequisites": [ "Named program and operational owners with a defined eligible task class.", "A baseline workflow and observable competence and operating criteria." ], "steps": [ "Identify the actual workflow problem and the skills needed by makers, reviewers, maintainers, and decision owners.", "Rehearse scoped work in a disposable environment, including failures, denied actions, and escalation rather than only successful demos.", "Assess individual reasoning and the team’s ability to preserve evidence, permissions, ownership, and review capacity.", "Run a bounded operational trial when its entry conditions hold, keeping comparable outcomes and total effort visible.", "Expand, revise, pause, or reduce the program against predeclared evidence; refresh it when tools, tasks, or responsibilities change." ], "example": "Illustrative example: A team begins with synthetic maintenance exercises. Participants must recognize an obsolete policy fixture, preserve a failing check, and route an unresolved requirement to its owner. Only after those capabilities and the tool boundaries are demonstrated does the team try a limited set of reviewed documentation changes. Attending the final workshop does not itself authorize work on production policy.", "verification": [ "Stage transitions refer to observed competence and operating evidence.", "The program measures reviewer and maintainer capability as well as candidate production.", "A failed condition has an owner and a route to retraining, narrower scope, or suspension." ], "outputs": [ "A staged enablement plan with entry and exit criteria.", "A cohort evidence record and a revisable adoption decision." ], "risks": [ "Calendar pressure can transform a learning stage into presumed operational readiness.", "Training activity can look successful while review capacity or retained understanding remains inadequate." ], "related_practices": [ "PAT:055", "PAT:059", "PAT:058" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 11 and 13 thematic guidance. Family F11 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:057", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:15" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] }, { "id": "PAT:058", "label": "Acceptable Use Policy", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "State what AI-assisted work is permitted, what evidence contributors must supply, who remains accountable, and how exceptions are decided. Connect the policy to enforceable controls where possible, while keeping written rules, their technical enforcement, and decision authority distinct. Version the policy and give it an owner so changing tools do not leave obsolete obligations in force.", "limitation": "A written policy or an approval field does not prove enforcement, valid identity, or compliance with every applicable obligation.", "url": "", "authors": "", "year": "", "attributes": { "label": "Acceptable Use Policy", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Recompose the mechanism", "required_revision": "Keep policy, enforcement, and authority distinct; assign responsibility for updating the rules.", "occurrences": "[\"NDSE:16\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A written policy or an approval field does not prove enforcement, valid identity, or compliance with every applicable obligation.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make contributor and operator obligations clear enough to apply to a particular task and inspect when a boundary is crossed.", "when_to_use": [ "AI assistance reaches shared repositories, organizational information, or externally consequential operations.", "Teams apply inconsistent rules about tool access, evidence, disclosure, review, or responsibility." ], "when_not_to_use": [ "A generic template would be treated as a substitute for the organization’s actual decision rights and applicable requirements." ], "prerequisites": [ "An authorized policy owner and a known scope of people, systems, and data.", "An inventory of available tools and existing review and exception processes." ], "steps": [ "Define permitted work and prohibited effects using concrete actors, operations, data classes, and targets.", "Specify the evidence and contributor understanding required for each relevant risk class.", "Map machine-checkable rules to enforced boundaries and identify obligations that still require accountable judgment.", "Describe the exception path, decision owner, scope, expiry, and controls that remain mandatory.", "Publish a versioned policy, check its practical interpretation with representative cases, and review it after material workflow or tool changes." ], "example": "Illustrative example: A project permits an assistant to prepare scoped patches but requires the contributor to understand the diff and retain relevant verification evidence. A restricted execution profile blocks writes to protected expectations and remote publication. A request for broader access goes to the named owner with its reason and scope. A sentence declaring the tool “approved” would not replace these decisions.", "verification": [ "A contributor can determine which rule applies to a concrete proposed action.", "Representative prohibited operations are denied by the relevant execution boundary.", "Exceptions and policy changes identify a legitimate decision source and an effective revision." ], "outputs": [ "A versioned acceptable-use policy and responsibility map.", "Enforcement mapping and a bounded exception record." ], "risks": [ "Vague prohibitions can create inconsistent interpretation and invisible workarounds.", "Disclosure or approval labels can become rituals that do not establish understanding or control." ], "related_practices": [ "PAT:034", "PAT:051", "PAT:084" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 6 and 13 thematic guidance. Family F06 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:058", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:16" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:059", "label": "Measurement & Learning", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Economics", "T:Productivity" ], "actual": [], "mapped": [ "C:C02", "C:C13" ], "printed": false, "summary": "Measure the engineering workflow through a single linked event record that follows assigned work, attempts, checking, review, and accepted outcomes. Keep denominators, time windows, failures, and missing follow-up explicit. Use the observations to diagnose a bottleneck and choose the next experiment, separating descriptive monitoring from stronger claims about what caused an improvement.", "limitation": "Activity measurements and before-and-after comparisons alone cannot establish a causal productivity gain or reliable population effect.", "url": "", "authors": "", "year": "", "attributes": { "label": "Measurement & Learning", "kind": "practice_descriptor", "collection": "PAT", "family": "F02", "chapter": 2, "disposition": "Recompose the mechanism", "required_revision": "Use one event ledger and end-to-end denominators, including failures.", "occurrences": "[\"NDSE:17\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Activity measurements and before-and-after comparisons alone cannot establish a causal productivity gain or reliable population effect.", "historical_structural_chapters": [ "C:C02" ], "family_name": "Measurement and Operational Learning", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make apparent generation speed comparable with the total work and accepted result it actually produces.", "when_to_use": [ "A team wants to evaluate a workflow change or explain a gap between candidate volume and delivered value.", "Current metrics omit abandoned attempts, reviewer effort, waiting, or later repair." ], "when_not_to_use": [ "The proposed comparison changes acceptance obligations between groups and would therefore measure different outcomes." ], "prerequisites": [ "Stable task and event identifiers with clear metric definitions.", "A defined eligible cohort, observation window, and intended decision." ], "steps": [ "Choose the unit of analysis and define distinct events for attempts, verification, review acceptance, deployment, and follow-up.", "Capture active person-time, elapsed waiting, tool use, and outcome states without counting overlapping activity twice.", "Retain every eligible assigned item, including failures, abandonment, and work still awaiting a decision.", "Compare like task classes and obligations; record tool changes, familiarity, and other plausible explanations for observed differences.", "Report counts, denominators, missing observations, and uncertainty, then propose a focused change or measurement for the identified constraint." ], "example": "Illustrative example: An assistant produces first candidates quickly, but several remain in review and two are abandoned. The ledger connects each attempt to reviewer minutes and its final disposition. The team discovers that accepted output is constrained by review capacity. It can test better review admission while keeping unresolved follow-up visible, instead of announcing a productivity gain from draft latency alone.", "verification": [ "Every reported rate has an explicit numerator, denominator, cohort, and window.", "Failures and unfinished work remain represented in the underlying ledger.", "The conclusion distinguishes observed association, operational diagnosis, and any causal inference." ], "outputs": [ "A linked event ledger and metric dictionary.", "A bounded diagnostic report and proposed next observation." ], "risks": [ "Selective reporting of successful tasks can inflate the apparent benefit.", "Combining person-time and queue time carelessly can double-count effort or hide the actual bottleneck." ], "related_practices": [ "PAT:060", "PAT:022", "PAT:057" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 2 and 13 thematic guidance. Family F02 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:059", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C02", "file": "EN/chapters/chapter02.tex", "line": 3, "sha256": "2f513eeed43e6183a3b26ebcebaa19a35ab53dbf561260b015e69357b049a72f", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C02", "title": "Measuring Productivity from Code to Production", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:17" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Controlled productivity evidence", "K:Evaluation methodology and baselines", "K:Output versus shipped value" ], "volumes": [ "V06" ], "families": [ "FAMILY:F02" ] }, { "id": "PAT:060", "label": "Cost Management", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Economics", "T:Jobs & roles" ], "actual": [], "mapped": [ "C:C12", "C:C13" ], "printed": false, "summary": "Compare execution routes using the cost of an accepted engineering outcome, including setup, clarification, review, rework, time, and infrastructure. Keep observed amounts, assumed rates, and unknown follow-up separate. A low model bill is one component of the comparison; it does not establish that an automation mechanism is economical for the whole change.", "limitation": "Cost estimates depend on their accounting boundary, acceptance definition, task mix, and assumptions; they are not transferable universal returns.", "url": "", "authors": "", "year": "", "attributes": { "label": "Cost Management", "kind": "practice_descriptor", "collection": "PAT", "family": "F12", "chapter": 12, "disposition": "Expand the operational treatment", "required_revision": "Include setup, review, rework, time, and infrastructure per accepted outcome.", "occurrences": "[\"NDSE:18\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Cost estimates depend on their accounting boundary, acceptance definition, task mix, and assumptions; they are not transferable universal returns.", "historical_structural_chapters": [ "C:C12" ], "family_name": "Economics, Infrastructure and Work", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "AMPLIARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Decide whether an optional mechanism removes enough burden to justify its full ongoing and initial cost.", "when_to_use": [ "A team is comparing assisted, bounded-agent, or more elaborate orchestration routes for eligible tasks.", "Cheap attempts produce substantial review, configuration, failed work, or maintenance overhead." ], "when_not_to_use": [ "A cheaper route fails a mandatory authority, verification, or permission condition; resolve eligibility before ranking cost." ], "prerequisites": [ "Comparable outcomes, obligations, and observation windows.", "Event-level effort and expense data, with assumptions explicitly identified." ], "steps": [ "Define the accepted outcome and accounting boundary before choosing which costs to include.", "Allocate discovery, setup, execution, checking, review, integration, operations, and observed rework once to the relevant cohort.", "Record infrastructure allocation and active person-time separately from elapsed delay and modeled risk.", "Compare cost per attempt and per accepted outcome, retaining failed and abandoned attempts in the numerator.", "Examine which uncertain input could change the decision and collect that evidence before expanding the more elaborate route." ], "example": "Illustrative example: Two workflows prepare the same class of maintenance change. One has a smaller inference bill but requires repeated reviewer clarification and more rejected attempts. The other includes a setup cost for protected checks. The team records both over the same period, separates missing follow-up from zero repair, and compares accepted-change cost before deciding whether to retain the added checker.", "verification": [ "Included costs use consistent units and do not charge the same activity twice.", "The acceptance denominator includes a defined cohort and unresolved outcomes remain visible.", "The recommendation identifies material assumptions and a trigger for reconsideration." ], "outputs": [ "A whole-change cost model with sourced or labeled inputs.", "A decision comparing eligible routes and their uncertain costs." ], "risks": [ "Spreading fixed costs across optimistic volumes can conceal poor actual utilization.", "Adding modeled losses to already counted rework can double-count the same event." ], "related_practices": [ "PAT:033", "PAT:059", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 12 and 13 thematic guidance. Family F12 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:060", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C12", "file": "EN/chapters/chapter12.tex", "line": 3, "sha256": "86c0ede476fd2a1b32d32f4ea86297429dd24aad34db3f6c7540431e1190ccbe", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C12", "title": "Economics, Jobs, Risk and Evidence-Based Adoption", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:NDSE:18" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Economic costs and return", "K:Employment and early-career roles", "K:Evaluation methodology and baselines" ], "volumes": [ "V06" ], "families": [ "FAMILY:F12" ] }, { "id": "PAT:061", "label": "Consistency Analysis Gate", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Check whether the specification, behavioral scenarios, design, and dependent records contradict one another before admitting affected work to the next stage. Report exact conflicting claims and their consequences. Consistency is a particular gate predicate: a mutually consistent set of artifacts can still be incomplete, unauthorized, or consistently wrong about what stakeholders need.", "limitation": "Absence of detected contradiction establishes neither completeness nor valid authority, and automated comparison can miss semantic conflicts.", "url": "", "authors": "", "year": "", "attributes": { "label": "Consistency Analysis Gate", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Retain", "required_revision": "A consistency check is one gate predicate; it is not equivalent to the whole gate or to completeness.", "occurrences": "[\"SDD1:21\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Absence of detected contradiction establishes neither completeness nor valid authority, and automated comparison can miss semantic conflicts.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Expose incompatible obligations early enough that a maker does not have to choose silently which artifact to obey.", "when_to_use": [ "A behavior change has updated one contract view while scenarios or design records may still use an older rule.", "Multiple artifacts describe overlapping constraints or historical behavior." ], "when_not_to_use": [ "An artifact has no defined authority or version; establish its role before treating disagreement as a substantive contradiction." ], "prerequisites": [ "Identified canonical requirements and versioned dependent artifacts.", "A decision owner for resolving conflicts in intended behavior." ], "steps": [ "Select the affected behaviors and gather the relevant specification passages, scenarios, and design claims.", "Compare their assumptions, boundaries, precedence, and version scope rather than merely matching words.", "Record each potential contradiction with both locators, a concrete consequence, and its decision owner.", "Resolve the issue through an authorized clarification or delta, then update dependent views without creating a second master.", "Rerun the relevant consistency predicates and retain separately any missing coverage, evidence, or authority holds." ], "example": "Illustrative example: A draft says all decisions use current policy, while a scenario requires replay to preserve the originally stored response. The gate flags the two passages and an example where they diverge. The policy owner narrows the current-policy rule to new requests. A passing recheck confirms that contradiction was addressed; it does not certify every unmentioned replay edge case.", "verification": [ "Each reported conflict identifies inspectable claims and the behavior they would change.", "Resolution comes from the appropriate authority rather than an arbitrary model preference.", "The report separates consistency status from completeness, verification, and approval status." ], "outputs": [ "A contradiction register with locators and dispositions.", "A named consistency result for the checked revisions." ], "risks": [ "Textual differences can produce false alarms despite equivalent intended behavior.", "A shared mistaken premise can make all artifacts agree while the actual requirement remains unmet." ], "related_practices": [ "PAT:069", "PAT:071", "PAT:076" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:061", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:21" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:062", "label": "Research Artifact Preservation", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Preserve the source material and reasoning behind a technical decision, including rejected alternatives and unresolved questions. Create smaller navigational summaries that point back to the retained evidence. This supports future research and maintenance beyond the immediate handoff, while keeping source integrity, current applicability, and decision authority as separate questions.", "limitation": "Retaining an artifact preserves what was recorded; it does not establish that the source is true, complete, current, or authorized.", "url": "", "authors": "", "year": "", "attributes": { "label": "Research Artifact Preservation", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Retain", "required_revision": "Preserve sources and reasons beyond the immediate handoff; this complements the handoff mechanism.", "occurrences": "[\"SDD1:22\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Retaining an artifact preserves what was recorded; it does not establish that the source is true, complete, current, or authorized.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Let a later engineer reconstruct why a decision was made without relying exclusively on a compressed summary or the original participant.", "when_to_use": [ "A design choice depends on investigation, experiments, rejected options, or external source interpretation.", "Research spans sessions and important context could disappear when the current worker finishes." ], "when_not_to_use": [ "Retention would exceed the permitted data boundary; preserve an appropriate locator and limitation instead of copying restricted content." ], "prerequisites": [ "Permitted storage and retention rules for the relevant evidence.", "Stable source locators and a decision or investigation identifier." ], "steps": [ "Identify the artifacts that materially support the decision, including contrary findings and unsuccessful experiments.", "Retain permitted source snapshots or durable locators with version, capture context, and any integrity metadata.", "Separate the source’s statements from the investigator’s inference and the owner’s eventual decision.", "Write a concise rationale linking chosen and rejected alternatives to the evidence that mattered.", "Record validity limits and renewal triggers, then provide the successor with an index that leads back to the preserved record." ], "example": "Illustrative example: A team rejects one storage migration because it cannot preserve historical replay under an examined failure case. It keeps the candidate, scenario, result, and rationale alongside the chosen design. Months later, a maintainer can inspect whether a new requirement changes that tradeoff instead of relying on an unexplained note saying that the rejected approach “did not work.”", "verification": [ "Material decision claims resolve to retained evidence or an explicit availability limitation.", "Rejected reasoning and unresolved issues remain distinguishable from the accepted decision.", "A successor can find the evidence needed to reconsider the choice." ], "outputs": [ "A source and experiment archive with a navigational index.", "A decision rationale with rejected alternatives and validity limits." ], "risks": [ "A summary can erase the qualification that made an original finding conditional.", "Unbounded retention can create stale clutter or retain data beyond its permitted scope." ], "related_practices": [ "PAT:072", "PAT:029", "PAT:016" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 9 and 13 thematic guidance. Family F09 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:062", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:22" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:063", "label": "Parallel Implementation Exploration", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C05", "C:C13" ], "printed": false, "summary": "Build a small number of isolated implementation alternatives against the same authorized intention, then compare them using shared acceptance and next-change criteria. Keep the alternatives distinct until a responsible decision selects a route. This explores concrete designs and their consequences; it is different from asking models to debate or agree about an unchanged candidate.", "limitation": "Several alternatives can share the same mistaken assumption, and comparing them may cost more than the uncertainty justifies.", "url": "", "authors": "", "year": "", "attributes": { "label": "Parallel Implementation Exploration", "kind": "practice_descriptor", "collection": "PAT", "family": "F05", "chapter": 5, "disposition": "Retain", "required_revision": "Explore isolatable implementation alternatives; keep this distinct from debate between models.", "occurrences": "[\"SDD1:23\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Several alternatives can share the same mistaken assumption, and comparing them may cost more than the uncertainty justifies.", "historical_structural_chapters": [ "C:C05" ], "family_name": "Architecture, Evolution and Maintenance", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Resolve a consequential design uncertainty through inspectable candidates rather than relying only on competing descriptions of imagined implementations.", "when_to_use": [ "Two materially different designs satisfy the same behavior but have uncertain maintenance or integration consequences.", "The alternatives can be developed in isolation within a bounded exploration budget." ], "when_not_to_use": [ "The key uncertainty is missing intention, or the choice is too minor to justify multiple implementations." ], "prerequisites": [ "A shared authorized contract and independently grounded checks.", "Isolated candidate scopes, comparison criteria, and a decision owner." ], "steps": [ "Name the specific design question and the meaningful difference between alternatives.", "Freeze common obligations and compare behavior, dependency fit, migration burden, and a plausible next change.", "Develop the bounded alternatives in separate workspaces without giving either authority to rewrite acceptance criteria.", "Run the same relevant checks and examine differences in structure, assumptions, and required maintenance work.", "Select, reject, or request another targeted experiment; preserve the rationale and useful evidence from discarded candidates." ], "example": "Illustrative example: One candidate stores policy-specific decisions directly; another introduces a generic adapter. Both must preserve historical request identity and response replay. The team exercises the same cases and asks how each would accommodate a further schema change. It may choose the simpler design, while retaining why the extra abstraction was rejected. A majority of model opinions is not the selection evidence.", "verification": [ "Alternatives differ in a consequential design choice while preserving the same obligations.", "Comparison uses the actual candidate revisions and equivalent check conditions.", "The decision explains observed tradeoffs and records exploration and integration costs." ], "outputs": [ "Isolated candidate alternatives with comparable evidence.", "A design decision preserving rejected-option rationale." ], "risks": [ "Allowing different acceptance criteria makes the comparison unfair or meaningless.", "Combining fragments too early can produce an unexamined third design." ], "related_practices": [ "PAT:031", "PAT:049", "PAT:075" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 5 and 13 thematic guidance. Family F05 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:063", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C05", "file": "EN/chapters/chapter05.tex", "line": 3, "sha256": "f6e123ae06931297b82554424c5b9b9c4b6bdb00e897814d515d11203e684075", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C05", "title": "Quality, Architecture and Maintainability", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:23" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Architecture and modularity", "K:Code reuse and duplication", "K:Technical debt and complexity" ], "volumes": [ "V06" ], "families": [ "FAMILY:F05" ] }, { "id": "PAT:064", "label": "Specification Scale Management", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Keep growing specifications governable through behavior-oriented slices with owners, versions, dependencies, and a single authoritative source for shared rules. Give each running candidate a precise applicable revision. Shorter documents may help navigation, but the main control is keeping distributed obligations coherent when one part changes.", "limitation": "A maintained dependency map can still omit consumers; selective updates must be challenged with relevant regression and review evidence.", "url": "", "authors": "", "year": "", "attributes": { "label": "Specification Scale Management", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Retain", "required_revision": "Manage specification scale with dependencies and one authoritative source, not merely shorter documents.", "occurrences": "[\"SDD1:24\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A maintained dependency map can still omit consumers; selective updates must be challenged with relevant regression and review evidence.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Allow focused iterative work without copying shared constraints into inconsistent local contracts or making every change a global rewrite.", "when_to_use": [ "A contract spans several components, teams, or independently evolving behavior slices.", "Late changes leave active candidates uncertain about which specification revision governs their work." ], "when_not_to_use": [ "A small single-owner contract is already easy to maintain and decomposition would add unnecessary coordination." ], "prerequisites": [ "A canonical contract and explicit authority for shared obligations.", "A way to identify slice versions, dependents, and active candidates." ], "steps": [ "Partition by coherent behavior and assign each slice an owner, effective revision, and explicit boundary.", "Keep cross-cutting constraints authoritative in one place and reference them from dependent slices.", "Record the version bundle used by each candidate instead of allowing live documents to change its contract silently.", "When a delta is authorized, trace candidate impacts and distinguish changed expectations from unchanged checks that need rerunning.", "Hold affected stale submissions, reconcile dependent views, and review the impact set for missing relationships before resuming." ], "example": "Illustrative example: A service separates new-request eligibility from historical replay while both reference a shared identity constraint. A policy delta changes new eligibility and leaves replay obligations intact. The dependency record identifies active candidates using the old ceiling. Their boundary expectations need renewal, while replay regressions still run against the changed code. No team receives an independently edited copy of the shared identity rule.", "verification": [ "Every behavior slice resolves to an owner and an applicable authoritative revision.", "Shared obligations have one source and inspectable dependent views.", "A change identifies affected candidates and preserves the distinction between refreshed expectations and rerun regressions." ], "outputs": [ "A versioned specification map with ownership and dependencies.", "A delta impact and reconciliation record." ], "risks": [ "Excessive decomposition can hide a cross-cutting rule behind many indirections.", "Stale or missing dependency edges can leave an apparently current candidate governed by obsolete assumptions." ], "related_practices": [ "PAT:066", "PAT:068", "PAT:016" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:064", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:24" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:065", "label": "Model Switching for Regeneration", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Change the model used to regenerate a candidate only after diagnosing the current failure and preserving the same authorized contract, permissions, and acceptance evidence. Treat the switch as a bounded intervention whose result must be checked. Another model may propose a different implementation, but it cannot supply missing authority or guarantee recovery from the original problem.", "limitation": "Different models can share the same context gap or wrong premise; a switch provides no general guarantee of successful repair.", "url": "", "authors": "", "year": "", "attributes": { "label": "Model Switching for Regeneration", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Retain with explicit qualifications", "required_revision": "Switch models after diagnosis with constraints unchanged; do not present it as a guaranteed recovery strategy.", "occurrences": "[\"SDD1:25\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Different models can share the same context gap or wrong premise; a switch provides no general guarantee of successful repair.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Test whether a different implementation proposal helps a diagnosed problem without silently relaxing the definition of an acceptable result.", "when_to_use": [ "A reproducible failure persists despite a bounded repair attempt and another permitted model is a reasonable alternative.", "The current model repeatedly chooses an unsuitable approach despite adequate task context and an external failure signal." ], "when_not_to_use": [ "The blocker is an unresolved requirement, unavailable permission, exhausted budget, or missing trustworthy oracle." ], "prerequisites": [ "The failing candidate, diagnostic, and current contract revision are preserved.", "The alternative model is permitted for the data and has an explicit remaining budget." ], "steps": [ "Classify the failure and identify what the switch is expected to change about the next proposal.", "Preserve the independent expectation, scope, protected artifacts, and spent budget across the transition.", "Provide the new model with the relevant evidence and failure rather than an unsupported instruction to do better.", "Generate a bounded replacement or repair and evaluate it with the same relevant checks and regressions.", "Record the outcome, incremental cost, and whether new evidence justifies further work or an escalation." ], "example": "Illustrative example: A maker repeatedly repairs a threshold branch while reintroducing a replay defect. The controller supplies another permitted model with the exact failing replay case and unchanged protected expectation. Its candidate is then checked against both obligations. If it fails in the same way, the shared result points toward a deeper context or design problem rather than authorizing unlimited further switches.", "verification": [ "The switch preserves the contract, oracle, permission boundary, and resource history.", "The new attempt addresses an identified failure and produces inspectable evidence.", "Recovery claims reflect executed results rather than the reputation or novelty of the replacement model." ], "outputs": [ "A model-switch decision and bounded attempt record.", "Comparable verification evidence and a stop or continuation decision." ], "risks": [ "A new session can accidentally discard failed attempts and reset the perceived budget.", "Selecting the most agreeable output can replace diagnosis with unsupported model shopping." ], "related_practices": [ "PAT:026", "PAT:083", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 3 and 13 thematic guidance. Family F03 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:065", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:25" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:066", "label": "Constitution-Driven Development", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Maintain a small set of enduring project obligations that individual feature plans must respect. Give these rules an accountable owner, revision, and change procedure; derive working views from the same authority. A constitution is stable within an authorized revision, while a reviewed delta can change it without erasing the history that explains earlier work.", "limitation": "Calling a document a constitution does not authenticate its author, prove completeness, or make every statement permanently binding.", "url": "", "authors": "", "year": "", "attributes": { "label": "Constitution-Driven Development", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Reconcile historical variants", "required_revision": "Connect to SDD1:19 while preserving history and authority for each revision.", "occurrences": "[\"SDD1:19\", \"SDD2:A1\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Calling a document a constitution does not authenticate its author, prove completeness, or make every statement permanently binding.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICONCILIARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent separate tasks from quietly redefining shared constraints such as identity, historical behavior, permitted effects, and decision rights.", "when_to_use": [ "Repeated feature work depends on a small set of cross-cutting obligations.", "Teams duplicate important constraints into local prompts or plans that drift apart." ], "when_not_to_use": [ "The proposed constitution merely adds another competing authority to an already clear and controlled contract." ], "prerequisites": [ "An existing source of legitimate decision authority.", "A clear distinction between shared obligations, design preferences, and task-specific plans." ], "steps": [ "Identify the few rules that must survive individual implementation choices and explain their scope.", "Record each rule’s owner, effective revision, relevant exclusions, and connection to observable behavior.", "Make task contracts and generated views refer back to these rules rather than independently copying their authority.", "Treat a proposed rule change as a reviewable delta, with its reasons, affected work, and required evidence.", "Preserve superseded revisions and reconcile active candidates before applying the new authority to current work." ], "example": "Illustrative example: A project’s shared contract requires historical request responses to remain stable. A feature plan may change the storage layout but cannot remove that obligation to simplify implementation. If the owner later authorizes a different archival rule, the change receives its own revision and impact analysis. The former rule remains available to explain the behavior of earlier accepted versions.", "verification": [ "A task can identify which shared rules and revisions apply to it.", "Rule changes have traceable authority and do not arrive through edits to derived views.", "Historical obligations and the decisions made under them remain reconstructable." ], "outputs": [ "A concise versioned set of shared obligations.", "A controlled delta and dependent-work reconciliation record." ], "risks": [ "A sprawling constitution can turn optional preferences into expensive mandatory ceremony.", "Treating a stable rule as eternally immutable can obstruct legitimate authorized change." ], "related_practices": [ "PAT:064", "PAT:043", "PAT:076" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:066", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:19", "OCC:SDD2:A1" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:067", "label": "Clarify Before Plan", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Resolve consequential questions about intended behavior before committing to an implementation plan. Record each question, the work it blocks, the appropriate owner, and the effective answer. Clarification can be selective: settled work may proceed while independent questions remain open. The aim is a defensible decision, not a promise to eliminate all ambiguity.", "limitation": "Clarification cannot remove every uncertainty or guarantee a fixed time saving; new evidence may reveal further questions later.", "url": "", "authors": "", "year": "", "attributes": { "label": "Clarify Before Plan", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Reconcile historical variants", "required_revision": "Connect to SDD1:20 without promising zero ambiguity or a fixed saving in minutes.", "occurrences": "[\"SDD1:20\", \"SDD2:A2\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Clarification cannot remove every uncertainty or guarantee a fixed time saving; new evidence may reveal further questions later.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICONCILIARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Avoid spending implementation effort on a plan whose central interpretation has never been authorized.", "when_to_use": [ "A request admits materially different outcomes or conflicts with an existing constraint.", "A design choice would implicitly settle a business rule that belongs to someone else." ], "when_not_to_use": [ "The question is a routine implementation choice already covered by the task’s authority and evidence." ], "prerequisites": [ "A scoped request and available existing obligations.", "A way to identify who can resolve each consequential question." ], "steps": [ "Read the request against existing behavior and constraints, separating missing facts from design preferences.", "Formulate the smallest concrete question that distinguishes the consequential alternatives.", "Record its dependency, owner, decision timing, and what can safely continue while the answer is pending.", "Capture the authorized answer with its effective revision and preserve any conditions or exclusions.", "Update affected scenarios and only then commit the relevant part of the plan; reopen clarification if later evidence changes the premise." ], "example": "Illustrative example: A request lowers an approval threshold but does not mention historical replay. Before changing the replay path, the engineer asks whether existing committed responses should change. The owner confirms that only new decisions use the revised threshold and records the applicable revision. Meanwhile, an unrelated wording correction can proceed because it does not depend on that answer.", "verification": [ "Each blocking question names the behavior and candidate work it affects.", "The recorded answer comes from the relevant authority and includes applicability.", "The plan respects the answer while unresolved independent questions remain visible." ], "outputs": [ "A question-and-decision record with dependency links.", "An updated behavior contract and a scoped implementation plan." ], "risks": [ "Asking every low-impact question can create unnecessary delay and shift routine judgment to the user.", "A casual answer without scope or authority can be misapplied as a universal rule." ], "related_practices": [ "PAT:043", "PAT:068", "PAT:071" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:067", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD1:20", "OCC:SDD2:A2" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:068", "label": "Progressive Specification", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Develop and authorize a specification in manageable behavioral increments. Proceed on settled obligations, preserve explicit open questions, and version later changes through targeted deltas. Progress depends on which work is sufficiently defined and authorized, not on repeatedly rewriting a document until an automated score improves or an agent feels confident.", "limitation": "An increment that appears independent may hide a shared dependency; deferred questions must be reviewed when their consequences change.", "url": "", "authors": "", "year": "", "attributes": { "label": "Progressive Specification", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Retain with explicit qualifications", "required_revision": "Progress through authorized portions of the specification, not repeated revision until a score rises.", "occurrences": "[\"SDD2:A3\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An increment that appears independent may hide a shared dependency; deferred questions must be reviewed when their consequences change.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Support iterative delivery while keeping unsettled assumptions from silently governing implementation and acceptance.", "when_to_use": [ "The overall problem is evolving but a useful subset of behavior has clear obligations.", "A late requirement can be isolated into a delta with identifiable dependent work." ], "when_not_to_use": [ "The proposed slice depends on an unresolved high-consequence rule that cannot be safely deferred." ], "prerequisites": [ "A versioned intention ledger with explicit states and owners.", "A dependency view separating settled work from blocked obligations." ], "steps": [ "Identify the smallest useful behavior whose expected outcomes and authority are already established.", "Record unresolved questions with owners and dependencies instead of omitting them from the working specification.", "Authorize and implement the eligible slice against its pinned contract and independent checks.", "When new answers arrive, issue a delta that names changed obligations, affected candidates, and retained invariants.", "Reconcile dependent evidence and review the next slice, preserving earlier decisions and the reasons for any reopened work." ], "example": "Illustrative example: A team first adds policy-version identifiers while preserving all existing responses. A later authorized increment changes the threshold for new requests. An unresolved regional exception remains explicitly outside both slices. Each candidate has its own applicable contract and checks; the team does not let a rising completeness score stand in for the missing regional decision.", "verification": [ "Each admitted slice has an authorized behavior boundary and inspectable expected outcomes.", "Open questions remain linked to the work they block.", "Later deltas preserve history and distinguish changed obligations from unaffected invariants." ], "outputs": [ "A sequence of versioned authorized behavior slices.", "A question, dependency, and evidence-reconciliation record." ], "risks": [ "Calling a requirement future work can conceal that the current slice already depends on it.", "Repeated regeneration can erase decisions and make progress appear to depend on document polish." ], "related_practices": [ "PAT:064", "PAT:067", "PAT:076" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:068", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:A3" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:069", "label": "Red-Team Specification", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Challenge a draft specification by constructing plausible counterexamples to its intended promises. Ask how an implementation could follow its words yet produce an unacceptable result, then record concrete gaps or contradictions for the appropriate owner. This examines the specification before or alongside coding; it is distinct from verifying that a particular implementation satisfies an established contract.", "limitation": "A successful challenge exercise finds selected weaknesses; the absence of findings cannot prove specification completeness or correctness.", "url": "", "authors": "", "year": "", "attributes": { "label": "Red-Team Specification", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Retain", "required_revision": "Search for counterexamples to the specification; keep this distinct from implementation verification.", "occurrences": "[\"SDD2:A4\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A successful challenge exercise finds selected weaknesses; the absence of findings cannot prove specification completeness or correctness.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "CONSERVARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Expose hidden assumptions and misleading wording before they become legitimate-looking implementation choices.", "when_to_use": [ "A specification is polished but leaves uncertainty about precedence, exceptions, state, or failure behavior.", "A consequential rule needs examination beyond its ordinary success examples." ], "when_not_to_use": [ "The review would become an unbounded search for hypothetical issues unrelated to the authorized change." ], "prerequisites": [ "A versioned draft and an explanation of the intended outcome.", "A bounded challenge scope and an owner who can resolve findings." ], "steps": [ "Choose a consequential promise and identify its actors, inputs, boundaries, temporal assumptions, and exclusions.", "Construct a case that follows the written rule literally while violating a plausible intended obligation.", "Distinguish a real contradiction, an omitted decision, and a deliberately excluded behavior.", "Report the exact passage, counterexample, consequence, and decision needed rather than simply calling the draft weak.", "Have the owner resolve the issue and update affected scenarios, retaining the counterexample as a useful future check." ], "example": "Illustrative example: A specification says to evaluate every request using the current policy. A challenger asks what happens when a previously committed request is replayed after that policy changes. The literal reading conflicts with historical stability. The resulting finding targets the specification’s temporal scope; it is not yet evidence that any candidate implementation contains the defect.", "verification": [ "Findings contain a concrete case and an inspectable link to the challenged wording.", "The response preserves distinctions between an approved exclusion and an unresolved obligation.", "Resolved findings produce an authoritative clarification and a relevant observable scenario." ], "outputs": [ "A bounded set of specification counterexamples.", "A resolution record and updated scenarios." ], "risks": [ "Performative opposition can create vague objections without a useful decision or test.", "A challenger may import an unapproved requirement and treat it as an existing obligation." ], "related_practices": [ "PAT:061", "PAT:070", "PAT:080" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:069", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:A4" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:070", "label": "Gap-Closure Analysis", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Compare intended behavior, scenarios, interfaces, and implementation knowledge to identify candidate gaps and orphaned elements. Investigate each finding before deciding whether it represents missing coverage, an obsolete artifact, an intentional exclusion, or an unapproved assumption. Legacy observations help discover questions; they do not automatically become requirements that must be preserved.", "limitation": "A gap detector depends on the completeness and semantics of its inputs; discovered candidates are neither exhaustive nor automatically valid.", "url": "", "authors": "", "year": "", "attributes": { "label": "Gap-Closure Analysis", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Retain with explicit qualifications", "required_revision": "Treat gaps and orphans as candidates for examination; legacy behavior is not a normative source by default.", "occurrences": "[\"SDD2:A5\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A gap detector depends on the completeness and semantics of its inputs; discovered candidates are neither exhaustive nor automatically valid.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Turn missing traceability and uncovered obligations into specific decisions instead of indiscriminately expanding the specification to match existing code.", "when_to_use": [ "A brownfield change has undocumented outputs, unmapped scenarios, or unclear relationships between requirements and tests.", "A new specification may omit a consumer or preserve behavior that no longer has an authorized purpose." ], "when_not_to_use": [ "The exercise would require preserving every legacy path without checking whether its behavior is intended." ], "prerequisites": [ "A canonical behavior reference and identifiable candidate artifacts.", "An owner for disputed meaning and a scoped impact question." ], "steps": [ "Map the changed obligations to relevant scenarios, interfaces, implementation elements, and evidence.", "Flag missing relationships and apparently orphaned elements with their exact locators and uncertainty.", "Investigate whether each finding is an omission, a historical remnant, a valid exclusion, or a defect in the mapping.", "Ask the appropriate owner to resolve consequential missing behavior and record any authorized delta.", "Add or revise the relevant scenario, artifact, or mapping and retain unresolved items with their impact and next action." ], "example": "Illustrative example: An eligibility response includes a policy-version field, but the new scenarios assert only the decision label. Analysis flags the field as potentially uncovered. Inspection shows that consumers rely on it to explain historical decisions. The owner confirms the obligation, and an independent scenario now checks both values. Other unused legacy fields are investigated separately rather than copied into the contract by default.", "verification": [ "Each accepted gap has a concrete obligation or decision behind it.", "Dismissed findings retain a reason, such as an intentional exclusion or obsolete artifact.", "Closure adds relevant evidence or traceability without silently broadening authority." ], "outputs": [ "A classified gap and orphan register.", "Authorized resolutions and updated coverage links." ], "risks": [ "Treating all unmapped code as required behavior can preserve defects and dead features.", "False positives can consume review capacity without improving coverage of consequential outcomes." ], "related_practices": [ "PAT:053", "PAT:061", "PAT:069" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:070", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:A5" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:071", "label": "Ambiguity Scoring", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Use an explicit rubric to organize observations about a specification’s completeness, consistency, specificity, and testability. Keep the underlying findings visible and treat critical unresolved ambiguity as a separate blocking condition. A composite score may help prioritize examination; it does not establish correctness, authorize a requirement, or supply a validated universal readiness threshold.", "limitation": "An uncalibrated score cannot predict successful delivery; a high average must not compensate for one consequential unresolved question.", "url": "", "authors": "", "year": "", "attributes": { "label": "Ambiguity Scoring", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Apply the critical qualification", "required_revision": "Use a diagnostic rubric; a critical gap is not offset by an average, and the threshold is unvalidated.", "occurrences": "[\"SDD2:A6\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An uncalibrated score cannot predict successful delivery; a high average must not compensate for one consequential unresolved question.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make a vague judgment that a specification is unclear more inspectable without replacing individual consequential findings with a number.", "when_to_use": [ "Several draft areas need consistent review attention and their uncertainty is otherwise described only impressionistically.", "A team wants to investigate whether a rubric could support local triage." ], "when_not_to_use": [ "A score would be used as automatic approval or as evidence that all requirements are complete." ], "prerequisites": [ "A defined rubric with observable anchors and example interpretations.", "Separate recording of critical findings, owners, and resolution states." ], "steps": [ "Define what each dimension means and which observable evidence supports each rating.", "Rate the relevant draft sections while retaining the exact gaps, contradictions, or unverifiable statements behind each score.", "Flag consequential unresolved questions independently of the aggregate and identify the work they block.", "Use the profile to prioritize clarification or review, then record whether the underlying finding was actually resolved.", "Before using thresholds predictively, evaluate local rating agreement and outcome relationships rather than assuming the numbers are calibrated." ], "example": "Illustrative example: A draft scores well on readable structure and concrete examples, but never states whether a repeated request uses historical or current policy. The reviewer retains that question as blocking for replay work even though the overall score is high. After the owner resolves it, the record changes because an authoritative answer exists, not simply because a second model awards more points.", "verification": [ "Every rating has an inspectable rationale tied to the relevant draft.", "Critical open questions remain visible regardless of the composite score.", "Any claim about predictive usefulness is supported by a separate evaluation." ], "outputs": [ "A diagnostic rating profile with source-linked findings.", "A prioritized clarification list and explicit blocking conditions." ], "risks": [ "Numerical precision can create confidence unsupported by the rubric’s validation.", "Teams may optimize wording for a score while leaving the decisive uncertainty unresolved." ], "related_practices": [ "PAT:067", "PAT:061", "PAT:059" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:071", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:A6" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:072", "label": "Handoff Chain", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:System knowledge & memory" ], "actual": [], "mapped": [ "C:C09", "C:C13" ], "printed": false, "summary": "Transfer the minimum state a successor needs to continue work, with links to the fuller evidence record. Each handoff identifies its inputs, output state, versions, doubts, authority, resource history, and next permitted action. The recipient checks freshness and applicability before resuming; the presence of expected files alone is not evidence that a handoff is coherent.", "limitation": "A complete-looking handoff can still omit a dependency or preserve an incorrect assumption; recipient reconstruction remains necessary.", "url": "", "authors": "", "year": "", "attributes": { "label": "Handoff Chain", "kind": "practice_descriptor", "collection": "PAT", "family": "F09", "chapter": 9, "disposition": "Recompose the mechanism", "required_revision": "Record inputs, outputs, versions, doubts, and authority for every handoff; file presence is insufficient.", "occurrences": "[\"SDD2:B1\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A complete-looking handoff can still omit a dependency or preserve an incorrect assumption; recipient reconstruction remains necessary.", "historical_structural_chapters": [ "C:C09" ], "family_name": "Context, Memory and Handoffs", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Maintain continuity across people, agents, and sessions without letting compression erase constraints, failed attempts, or changed authority.", "when_to_use": [ "Work spans sessions or passes between investigation, implementation, checking, and review roles.", "A successor must continue from a checkpoint without replaying the entire conversation." ], "when_not_to_use": [ "The transfer would conceal that the current contract or permission state cannot be verified; stop and reconcile first." ], "prerequisites": [ "Identifiable task, candidate, contract, and evidence versions.", "A recipient with a defined role and access to the permitted source record." ], "steps": [ "State the current objective, completed work, candidate revision, and unresolved result in a concise structured record.", "Link the authoritative contract, relevant observations, failed attempts, and decision rationale rather than copying only conclusions.", "Carry forward consumed budget, permission scope, pending questions, and the specific next action or stopping condition.", "Have the recipient compare stored versions with current authority and check that referenced evidence actually applies.", "Acknowledge the reconstructed state, refresh stale elements, and preserve the incoming handoff as history when producing the next one." ], "example": "Illustrative example: A maker stops after a replay regression fails. Its handoff includes the candidate hash, current contract revision, failing request, protected expectation, and remaining attempt budget. The next worker discovers that a policy delta arrived after the checkpoint. It preserves the old failure record but refreshes the affected assumptions before attempting a repair, instead of resuming from a vague “almost finished” summary.", "verification": [ "The recipient can explain the current state and next permitted decision from the handoff.", "Referenced evidence matches the relevant revisions and preserves open questions.", "Budget and permission constraints survive the transfer without silent expansion or reset." ], "outputs": [ "A versioned handoff record with evidence locators.", "A recipient freshness check and reconciled continuation state." ], "risks": [ "Overcompressed summaries can erase the diagnosis that justified the next attempt.", "Successor agents may treat historical state as current authorization merely because it persisted." ], "related_practices": [ "PAT:062", "PAT:047", "PAT:020" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 9 and 13 thematic guidance. Family F09 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:072", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C09", "file": "EN/chapters/chapter09.tex", "line": 3, "sha256": "ab431c886c607f8a192a36336c3409fa0bf9b828d20ab6d16ffd74c162641029", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C09", "title": "System Understanding, Context and Persistent Memory", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:B1" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent context and persistent memory", "K:Ownership and knowledge transfer", "K:System understanding and rationale" ], "volumes": [ "V06" ], "families": [ "FAMILY:F09" ] }, { "id": "PAT:073", "label": "Multi-Mode Agent", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Give one agent distinct functional modes such as inspection, planning, bounded implementation, and checking, with appropriate inputs and enforced permissions for each. Record mode transitions in the controller. Changing a role prompt can change the requested task, but the surrounding system must supply the actual access boundary and preserve accountability.", "limitation": "Mode separation does not authenticate authority, certify maturity, or make errors independent when the same assumptions and evidence are reused.", "url": "", "authors": "", "year": "", "attributes": { "label": "Multi-Mode Agent", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Retain with explicit qualifications", "required_revision": "Use functional modes and permissions; do not treat them as certified maturity or autonomous responsibility.", "occurrences": "[\"SDD2:B2\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Mode separation does not authenticate authority, certify maturity, or make errors independent when the same assumptions and evidence are reused.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Avoid exposing every capability throughout a session when different stages need different actions and evidence.", "when_to_use": [ "A workflow alternates between read-oriented investigation and a narrowly writable implementation stage.", "One model can perform several functions while the controller retains explicit scope and transition rules." ], "when_not_to_use": [ "A prompt-only role change would be presented as real permission isolation or independent acceptance." ], "prerequisites": [ "A controller that can enforce actual tool and artifact permissions.", "Defined mode inputs, outputs, transition conditions, and decision owners." ], "steps": [ "Define modes by their engineering purpose and necessary operations rather than by impressive role names.", "Assign the least access needed for each mode and protect authoritative contracts and acceptance expectations from the maker.", "Require explicit current inputs and a recorded controller decision when entering a mode or expanding permitted action.", "Keep the task contract, remaining budget, and evidence history stable across mode transitions.", "Route the resulting candidate and findings to the responsible checker or owner without letting a mode label grant acceptance." ], "example": "Illustrative example: An assistant inspects a repository with read access, then proposes a plan. After the controller admits the plan, implementation mode can write only candidate files. Checking reads protected expectations and writes a separate result. These transitions are recorded and enforced. Calling the final prompt “release manager” would add no ability or authority to publish the candidate.", "verification": [ "Actual denied and allowed operations match the documented mode boundaries.", "Each transition retains the applicable contract and resource history.", "Mode outputs identify their evidence and do not claim a decision reserved for another role." ], "outputs": [ "A mode and permission specification with transition records.", "Scoped candidate or finding artifacts from each admitted mode." ], "risks": [ "A broad underlying credential can defeat apparently narrow prompt-level roles.", "Reusing the maker’s interpretation in a checker mode can preserve circular verification." ], "related_practices": [ "PAT:001", "PAT:027", "PAT:034" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 3 and 13 thematic guidance. Family F03 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:073", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:B2" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:074", "label": "Anti-Sycophancy Enforcement", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Productivity", "T:Verification & review" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Ask reviewers to challenge a candidate with evidence-backed objections rather than agree with its author or manufacture dissent. A useful finding identifies a defect, unsupported assumption, violated expectation, or concrete investigation. Requiring critical reasoning changes the review task; it does not by itself modify model training, incentives, or the independence of the evidence.", "limitation": "Critical instructions do not guarantee useful criticism or remove shared blind spots; no-findings results remain bounded to the inspected scope.", "url": "", "authors": "", "year": "", "attributes": { "label": "Anti-Sycophancy Enforcement", "kind": "practice_descriptor", "collection": "PAT", "family": "F08", "chapter": 8, "disposition": "Apply the critical qualification", "required_revision": "Support criticism with evidence; requesting dissent does not change training or actual incentives.", "occurrences": "[\"SDD2:B3\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Critical instructions do not guarantee useful criticism or remove shared blind spots; no-findings results remain bounded to the inspected scope.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Critique, Review and Trust", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make review informative when agreement is socially easy or fluent candidate explanations are being accepted without challenge.", "when_to_use": [ "Review comments mostly repeat the candidate’s rationale without examining consequential assumptions.", "A proposed decision needs a reasoned challenge before an accountable owner evaluates the evidence." ], "when_not_to_use": [ "The process demands a quota of negative comments regardless of whether a concrete problem can be found." ], "prerequisites": [ "A known candidate and an authoritative behavior reference.", "A finding format that distinguishes observed defects, hypotheses, and preferences." ], "steps": [ "Ask the reviewer to identify the strongest consequential assumption in the candidate or its explanation.", "Require a source location, counterexample, violated requirement, or proposed diagnostic for each material objection.", "Classify the objection by evidence status rather than accepting confident criticism as a confirmed defect.", "Investigate actionable concerns and retain reasons when a finding is dismissed or remains unresolved.", "Allow a bounded no-additional-finding result and pass the full evidence record to the named acceptance owner." ], "example": "Illustrative example: A reviewer first calls a storage refactor “too complex,” which supplies little actionable information. On closer examination, it identifies that replay calls the current policy evaluator instead of returning the stored response. The latter objection names a path and a protected expectation that can be tested. If no defect is established, the review should say so rather than inventing another objection to appear adversarial.", "verification": [ "Material criticism contains a traceable claim and a useful way to examine it.", "The record separates established failures from plausible but untested concerns.", "Acceptance depends on evidence and authority, not on the number of objections or agreements." ], "outputs": [ "An evidence-linked challenge record.", "Resolved findings, investigations, and bounded remaining uncertainty." ], "risks": [ "Performative disagreement can produce expensive false positives and discourage useful collaboration.", "A persuasive critic can be overtrusted for the same reasons as a persuasive maker." ], "related_practices": [ "PAT:075", "PAT:052", "PAT:080" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 8 and 13 thematic guidance. Family F08 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:074", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:B3" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:AI as reviewer", "K:Automation bias and trust", "K:Review capacity and maintainers" ], "volumes": [ "V06" ], "families": [ "FAMILY:F08" ] }, { "id": "PAT:075", "label": "Convergence Review", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Productivity", "T:Verification & review" ], "actual": [], "mapped": [ "C:C08", "C:C13" ], "printed": false, "summary": "Compare a proposal, a reasoned challenge, and their supporting evidence to resolve a bounded review question. Preserve objections and the basis for any changed position instead of keeping only the final agreement. Convergence is useful when the reasons survive checking; agreement between models alone neither calibrates confidence nor proves that the candidate is correct.", "limitation": "Reviewers can converge on a shared mistake, especially when they receive the same flawed premise or circular evidence.", "url": "", "authors": "", "year": "", "attributes": { "label": "Convergence Review", "kind": "practice_descriptor", "collection": "PAT", "family": "F08", "chapter": 8, "disposition": "Apply the critical qualification", "required_revision": "Preserve reasons and objections; agreement between two models is neither calibration nor proof.", "occurrences": "[\"SDD2:B4\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Reviewers can converge on a shared mistake, especially when they receive the same flawed premise or circular evidence.", "historical_structural_chapters": [ "C:C08" ], "family_name": "Critique, Review and Trust", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make a disputed engineering decision inspectable without treating consensus as an independent acceptance oracle.", "when_to_use": [ "Reviewers disagree about a specific tradeoff, defect hypothesis, or interpretation that available evidence could help resolve.", "A second perspective may expose an assumption the initial reviewer did not examine." ], "when_not_to_use": [ "The missing ingredient is an authoritative requirement or an executable check, and discussion would merely defer obtaining it." ], "prerequisites": [ "A bounded question, shared candidate revision, and accessible evidence.", "A stop condition and a named owner for unresolved decisions." ], "steps": [ "Record the initial proposal and its evidence before exposing it to the challenger’s reasoning.", "Ask the challenger for a concrete counterargument and distinguish competing facts from differing preferences.", "Identify the observation, source, or owner decision that could discriminate between the positions.", "Perform or obtain that check, then record which claims changed and which objections remain.", "Stop when the bounded question is answered or no useful new evidence emerges; escalate unresolved consequential disagreement." ], "example": "Illustrative example: One reviewer accepts a replay refactor because current tests pass. Another argues that the tests expect the wrong policy revision. They inspect the authorized historical-response contract and run an independently specified case. The first position changes because of that evidence. Had both reviewers initially agreed with the flawed tests, their consensus would not have made the replay behavior acceptable.", "verification": [ "The final position is traceable to checked reasons rather than a vote count.", "Dissenting claims and unresolved questions remain available to the decision owner.", "The review stops according to the question and evidence, not a requirement that all models agree." ], "outputs": [ "A proposal, challenge, and evidence-resolution record.", "A bounded conclusion or named escalation." ], "risks": [ "Repeated discussion can amplify shared assumptions while appearing to increase confidence.", "Removing dissent from the final summary can hide residual uncertainty from the reviewer." ], "related_practices": [ "PAT:074", "PAT:022", "PAT:063" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 8 and 13 thematic guidance. Family F08 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:075", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C08", "file": "EN/chapters/chapter08.tex", "line": 3, "sha256": "b542b5aa04f66dd3fb402a4780f9ed7dacf076a6f2827d7b083887467b50e92a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C08", "title": "Code Review and Trust Calibration", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:B4" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:AI as reviewer", "K:Automation bias and trust", "K:Review capacity and maintainers" ], "volumes": [ "V06" ], "families": [ "FAMILY:F08" ] }, { "id": "PAT:076", "label": "Gate-Enforced Progression", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Verification & review" ], "actual": [], "mapped": [ "C:C04", "C:C13" ], "printed": false, "summary": "Advance a candidate only when the relevant explicit predicates and decision rights are satisfied. Keep structural checks, behavioral verification, authorization, and acceptance distinct, and reopen affected gates when their inputs change. Use gates to support small iterative changes; a fixed sequence of documents or a green structural report is not a substitute for accountable judgment.", "limitation": "A gate can check only its implemented predicates; file presence and declared approval fields do not establish real authority or behavioral sufficiency.", "url": "", "authors": "", "year": "", "attributes": { "label": "Gate-Enforced Progression", "kind": "practice_descriptor", "collection": "PAT", "family": "F04", "chapter": 4, "disposition": "Retain with explicit qualifications", "required_revision": "Separate predicates from authority, allow gates to reopen, and derive adapters from the canonical source; avoid a waterfall ritual.", "occurrences": "[\"SDD2:C1\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A gate can check only its implemented predicates; file presence and declared approval fields do not establish real authority or behavioral sufficiency.", "historical_structural_chapters": [ "C:C04" ], "family_name": "Intentions, Contracts and Specifications", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Make the reason for progression or hold specific enough to verify and act on without freezing the development lifecycle.", "when_to_use": [ "Several stages depend on current contracts, protected checks, evidence, and named decisions.", "Candidates arrive with stale results or pass through review because expected files merely exist." ], "when_not_to_use": [ "A gate imposes artifacts that do not answer a relevant obligation or duplicates an already adequate approval mechanism." ], "prerequisites": [ "Defined gate inputs, predicates, outcome states, and decision authorities.", "Versioned canonical records with identifiable dependent evidence." ], "steps": [ "Specify which observable conditions are machine-checkable and which decisions require an authenticated accountable owner.", "Bind each gate result to the actual contract, candidate, oracle, and environment revisions it examined.", "Return named failures or holds with a useful corrective action, preserving distinctions between missing evidence and missing authority.", "When an authorized delta changes a premise, invalidate affected results and reopen only the relevant work with required regressions.", "Generate compatibility views from the canonical record and route edits to those views back as proposed deltas." ], "example": "Illustrative example: A candidate passes schema checks and its test suite, but the contract revision changed after the tests ran. The progression gate holds the stale evidence and identifies the affected expectations. The maker refreshes the candidate and checks; the authorized reviewer still decides acceptance. An old-format tracking sheet is regenerated from the contract rather than becoming a second path to approval.", "verification": [ "Gate outcomes identify exact checked revisions and named predicates.", "A missing authority decision cannot be satisfied by a populated text field alone.", "Changed inputs reopen affected results while preserving the prior decision history." ], "outputs": [ "A predicate and authority specification.", "Version-bound progression, hold, and reopening records." ], "risks": [ "A structural pass can be mistaken for complete verification or release permission.", "Rigid gate ceremonies can obstruct legitimate small increments and encourage workarounds." ], "related_practices": [ "PAT:061", "PAT:068", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 4 and 13 thematic guidance. Family F04 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:076", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C04", "file": "EN/chapters/chapter04.tex", "line": 3, "sha256": "f9ba7148a44598fb3bb1a59888f37f376faadff0f300dafb908a98168176f7a7", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C04", "title": "Intentions, Contracts and Iterative Change", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:C1" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Independent verification and oracles", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F04" ] }, { "id": "PAT:077", "label": "Security Pipeline", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Compose security checks around named threats, protected assets, and decision owners across the application and its development tools. Keep scanning, dependency review, permission enforcement, negative testing, and release judgment distinct but connected. The pipeline records what each control actually examined and what remains unresolved; completing its stages is not a universal security guarantee.", "limitation": "A composition of checks can still leave uncovered threats or enforcement gaps, even when every configured stage passes.", "url": "", "authors": "", "year": "", "attributes": { "label": "Security Pipeline", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Recompose the mechanism", "required_revision": "Treat the security pipeline as a composition of controls, not a guarantee of security.", "occurrences": "[\"SDD2:C2\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A composition of checks can still leave uncovered threats or enforcement gaps, even when every configured stage passes.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Ensure that useful individual security signals contribute to an inspectable decision instead of becoming disconnected green status indicators.", "when_to_use": [ "A change introduces untrusted input, new dependencies, external tools, or consequential data flows.", "Current security checks run independently without a clear connection to threats and release decisions." ], "when_not_to_use": [ "A generic pipeline would be claimed to satisfy a specialized security obligation without examining the relevant environment." ], "prerequisites": [ "An explicit threat and asset inventory for both product and development chain.", "Owners for controls, exceptions, findings, and the final operational decision." ], "steps": [ "Map each consequential threat to the boundary it could cross and the evidence needed to examine it.", "Select complementary controls such as source review, dependency provenance, permissions, scanning, and targeted negative cases.", "Place permission enforcement before effects occur, independently of whether a content scanner raises a finding.", "Bind results to the candidate and control configuration, classify failures, and preserve denied actions without exposing sensitive contents.", "Assemble the findings and residual gaps for accountable review; reassess affected controls when tools or permissions change." ], "example": "Illustrative example: An import feature receives malformed-input checks, dependency review, and a data-flow examination. The assistant’s runtime separately denies unapproved outbound calls and writes to protected expectations. A text scanner reports no suspicious instruction in the fixture, but that result cannot unlock the denied network operation. The reviewer sees the purpose and limit of each control rather than a single undifferentiated security badge.", "verification": [ "Each selected control answers a named threat question and records its scope.", "Permission denials remain effective when a scanner misses suspicious content.", "The final decision retains unresolved findings, control versions, and accountable ownership." ], "outputs": [ "A threat-to-control map and candidate-bound results.", "A security decision record with residual uncertainty." ], "risks": [ "Correlated or overlapping scanners can leave the same important boundary unexamined.", "Changes to execution configuration can invalidate earlier results without changing application code." ], "related_practices": [ "PAT:051", "PAT:078", "PAT:079" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 6 and 13 thematic guidance. Family F06 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:077", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:C2" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:078", "label": "Prompt Injection Scanning", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Inspect repository text, retrieved material, and tool outputs for content that attempts to redirect an assistant beyond the task’s authority. Treat findings as signals for examination, preserving the source context and an appropriate response. Since scanning can miss or misclassify content, independently enforced tool permissions must still limit the effects of any resulting action.", "limitation": "A clean scan does not establish injection resistance; wording changes, unseen channels, and interpretation errors can bypass selected detection rules.", "url": "", "authors": "", "year": "", "attributes": { "label": "Prompt Injection Scanning", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Apply the critical qualification", "required_revision": "Scanning supplies a signal; permissions and boundaries outside the model control the effects.", "occurrences": "[\"SDD2:C3\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A clean scan does not establish injection resistance; wording changes, unseen channels, and interpretation errors can bypass selected detection rules.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Expose suspicious attempts to promote lower-trust task data into operational instructions without relying on detection as the sole defense.", "when_to_use": [ "An assistant reads external pages, repository prose, issues, or tool outputs before deciding its next action.", "A workflow needs triage and evidence for suspicious instruction-like content." ], "when_not_to_use": [ "Scanning would be used to justify otherwise unauthorized access or to certify arbitrary content as safe." ], "prerequisites": [ "Known data and instruction boundaries with a bounded response policy.", "External enforcement of permitted tools, targets, and effects." ], "steps": [ "Identify the lower-trust input surfaces the task actually consumes and retain their origin and version where possible.", "Inspect for attempts to claim higher authority, redirect the objective, or request out-of-scope operations.", "Record suspected passages with enough context to assess whether they are malicious instructions, quotations, or legitimate task data.", "Keep the content as data and route material findings for review without executing the suspicious request to investigate it.", "Exercise relevant permission denials independently of scanner results and record the limits of the detection coverage." ], "example": "Illustrative example: A repository note tells an assistant to send local configuration to an external endpoint before continuing a build. Scanning flags the instruction and preserves its source locator. Even if a paraphrase evades that rule, the runtime still denies the unapproved outbound operation. The useful evidence consists of the suspicious-content finding and the enforced denial, which answer different questions.", "verification": [ "Findings identify the input source and the proposed authority crossing.", "False positives can be classified without silently promoting quoted content to instructions.", "A missed finding cannot by itself enable an operation outside the permission envelope." ], "outputs": [ "A source-linked scan and triage record.", "Independent boundary-check evidence and coverage limitations." ], "risks": [ "Overbroad rules may flag legitimate documentation and create expensive review noise.", "Treating a scan as a permission check can leave uncontrolled effects when detection fails." ], "related_practices": [ "PAT:017", "PAT:034", "PAT:077" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 6 and 13 thematic guidance. Family F06 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:078", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:C3" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:079", "label": "Supply-Chain Risk Audit", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Code quality & security", "T:Engineering structure" ], "actual": [], "mapped": [ "C:C06", "C:C13" ], "printed": false, "summary": "Review the identity, provenance, necessity, permissions, and update path of executable dependencies, including packages, tool servers, hooks, and skills. Track the actual resolved artifacts and their transitive dependencies where relevant. A familiar name or a pinned version reduces some ambiguity, but neither supplies a permanent list of trustworthy tools or proves safe behavior.", "limitation": "Provenance and pinning do not prove benign behavior; a legitimate approved artifact can contain defects or gain risk through changed context.", "url": "", "authors": "", "year": "", "attributes": { "label": "Supply-Chain Risk Audit", "kind": "practice_descriptor", "collection": "PAT", "family": "F06", "chapter": 6, "disposition": "Retain with explicit qualifications", "required_revision": "Audit identity, provenance, permissions, and updates; do not maintain a fixed list of tools presumed safe.", "occurrences": "[\"SDD2:C4\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Provenance and pinning do not prove benign behavior; a legitimate approved artifact can contain defects or gain risk through changed context.", "historical_structural_chapters": [ "C:C06" ], "family_name": "Security of the Toolchain and Its Effects", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Examine the transition from a suggested dependency to code allowed to install, execute, access data, or influence the agent.", "when_to_use": [ "A generated change proposes a new package, tool integration, hook, or skill.", "An existing dependency changes version, source, resolved artifact, or requested permissions." ], "when_not_to_use": [ "A successful name lookup or manifest check would be presented as sufficient evidence for unrestricted execution." ], "prerequisites": [ "An inventory of executable dependencies and their approved purpose.", "A decision owner with access to artifact identity and permission information." ], "steps": [ "Question whether the new dependency is needed or an already approved capability can meet the requirement.", "Verify the exact name, source, version, resolved artifact identity, and relevant transitive dependency record.", "Examine installation and execution behavior, requested access, and changes to automatic hooks or tool entry points.", "Approve only the necessary scope through the appropriate process and record the review basis and unresolved concerns.", "Reassess material updates or permission changes, preserving the previous manifest for rollback and investigation." ], "example": "Illustrative example: An assistant proposes a similarly named package to simplify parsing. The reviewer checks the actual registry identity and artifact, then notices an installation step that executes additional code. The team may reject the dependency or admit a narrower reviewed alternative. Its existence in a registry and a passing application test would not have answered the installation or provenance questions.", "verification": [ "The reviewed identity matches the artifact that will actually resolve or execute.", "Requested permissions and automatic actions are understood within the intended task scope.", "Material changes trigger renewed review rather than inheriting approval from a familiar name." ], "outputs": [ "A dependency and permission manifest with review provenance.", "An update, rejection, or bounded admission decision." ], "risks": [ "A floating or indirect dependency can change execution without a visible application diff.", "A hash match can confirm bytes while leaving publisher identity or behavioral safety unestablished." ], "related_practices": [ "PAT:037", "PAT:030", "PAT:077" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 6 and 13 thematic guidance. Family F06 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:079", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C06", "file": "EN/chapters/chapter06.tex", "line": 2, "sha256": "3af782fd4b06529539e8b78e95b77ad3911980472e272fe111ddcfcc82ce777a", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C06", "title": "Securing Generated Code and Agent Runtimes", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:C4" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dependencies and agent supply chain", "K:Prompt injection and malicious tools", "K:Vulnerability and secure code" ], "volumes": [ "V06" ], "families": [ "FAMILY:F06" ] }, { "id": "PAT:080", "label": "Adversarial Agent Pattern", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Verification & review", "T:What agents can do" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Assign a checker the bounded task of finding violations of an authorized contract. Separate the critical stance, the origin of expected results, artifact permissions, and acceptance authority. Give findings their own output channel and protect the oracle from the maker as well as the checker. Another agent is a possible reviewer, not automatically independent evidence.", "limitation": "An adversarial role can still share the maker’s false premise; read-only access alone does not establish a correct or protected oracle.", "url": "", "authors": "", "year": "", "attributes": { "label": "Adversarial Agent Pattern", "kind": "practice_descriptor", "collection": "PAT", "family": "F07", "chapter": 7, "disposition": "Apply the critical qualification", "required_revision": "Separate criticism, independent inputs, read-only access, and authority; protect the oracle from the maker too.", "occurrences": "[\"SDD2:C5\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An adversarial role can still share the maker’s false premise; read-only access alone does not establish a correct or protected oracle.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Tests, Oracles and Acceptance Evidence", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RIVEDERE_CRITICAMENTE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Create a focused search for counterexamples while preserving the boundary between producing, examining, and accepting a candidate.", "when_to_use": [ "A plausible candidate could pass self-tests based on the maker’s own mistaken interpretation.", "A consequential invariant benefits from a dedicated search for negative cases or unexpected changes." ], "when_not_to_use": [ "The checker lacks an independently grounded expectation or would be allowed to negotiate a weaker contract with the maker." ], "prerequisites": [ "A known candidate and authorized expected behavior with source provenance.", "Protected contract and oracle artifacts, separate findings output, and a named acceptance owner." ], "steps": [ "Define the invariant or risk the checker should challenge and the limits of its investigation.", "Provide independently grounded expectations and relevant context without using the maker’s conclusion as the oracle.", "Enforce read and write permissions so the maker cannot rewrite the expectation and the checker cannot silently alter the candidate.", "Require a concrete counterexample, violated obligation, or identifiable evidence gap for a material finding.", "Return diagnosed failures for bounded repair and policy ambiguities to the owner; retain the evidence for accountable acceptance." ], "example": "Illustrative example: A maker’s self-test accepts a replay response recomputed under current policy. A checker reads the separately approved historical-response invariant and constructs the conflicting case. The maker may repair candidate code but cannot edit that protected expectation. The checker records a reproducible failure; it does not independently authorize a policy change or declare the repaired service ready for release.", "verification": [ "Expected results have an origin independent of the candidate’s observed answer.", "Permission checks protect the oracle against writes by both relevant roles.", "Findings are traceable and the resulting state preserves separate acceptance authority." ], "outputs": [ "A scoped counterexample or evidence-gap report.", "A candidate-bound check result and repair or escalation path." ], "risks": [ "Two differently named agents may reproduce the same circular reasoning.", "An unbounded critic can create indefinite repair cycles without new diagnostic evidence." ], "related_practices": [ "PAT:027", "PAT:044", "PAT:082" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 7 and 13 thematic guidance. Family F07 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:080", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:C5" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dataset provenance and dependency", "K:Independent verification and oracles" ], "volumes": [ "V06" ], "families": [ "FAMILY:F07" ] }, { "id": "PAT:081", "label": "One-Item-Per-Cycle", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Organize each execution cycle around one semantic work item with a defined acceptance question. Load its current contract and budget, attempt bounded work, observe the result, and checkpoint a named next state before admitting another item. This is a temporal specialization of small verifiable increments, not a rule that one cycle must touch only one file or make one tool call.", "limitation": "A single-item cycle does not make the item well-scoped by itself or remove dependencies that require integrated verification.", "url": "", "authors": "", "year": "", "attributes": { "label": "One-Item-Per-Cycle", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Recompose the mechanism", "required_revision": "Treat this as a temporal specialization of NDSE:04 small increments, not automatic equivalence between the practices.", "occurrences": "[\"SDD2:D1\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A single-item cycle does not make the item well-scoped by itself or remove dependencies that require integrated verification.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Keep attempts, diagnoses, resource consumption, and stopping decisions attributable to one coherent outcome at a time.", "when_to_use": [ "An autonomous loop drifts among unrelated tasks or loses track of which failure it is trying to repair.", "A resumed worker needs a clear item and a reliable transition before starting further work." ], "when_not_to_use": [ "The proposed item is defined only by an arbitrary file boundary and cannot be checked as a coherent behavior." ], "prerequisites": [ "A small verifiable work item with current contract and checks.", "Persistent state and externally maintained resource counters." ], "steps": [ "Load one item, its applicable contract, candidate state, current diagnostic, and remaining budget.", "Admit only actions needed for that item, recording relevant observations and newly discovered dependencies.", "Run the focused check and required regressions; distinguish a diagnosed failure from an unrelated issue.", "Checkpoint the candidate, evidence, consumed resources, and a named result such as ready for review, stopped, or escalated.", "Begin another item only through an explicit allocation or resumption decision, keeping unresolved follow-ups separate." ], "example": "Illustrative example: A cycle implements revised request routing while preserving replay behavior, touching several related files. A failing unrelated report test is recorded as a separate issue rather than becoming the cycle’s new objective. The checkpoint identifies the routing candidate, its own verification result, and remaining resources. The controller can then request review or assign another item without losing the first decision trail.", "verification": [ "The cycle’s actions and evidence relate to one stated acceptance question.", "Its checkpoint supports reconstruction after interruption without resetting consumed resources.", "Unrelated findings become explicit follow-ups rather than unrecorded scope expansion." ], "outputs": [ "A cycle trace tied to one semantic item.", "A durable checkpoint and named continuation or stop state." ], "risks": [ "An overly broad item can hide many changes behind a nominally single task.", "Treating every tool call as a separate cycle can fragment evidence and obscure the coherent outcome." ], "related_practices": [ "PAT:046", "PAT:020", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 3 and 13 thematic guidance. Family F03 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:081", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:D1" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:082", "label": "Evidence-Pack Provenance", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Verification & review", "T:What agents can do" ], "actual": [], "mapped": [ "C:C07", "C:C13" ], "printed": false, "summary": "Bind verification evidence to the exact candidate, authorized intention, oracle, policy, and environment it concerns. Preserve source artifacts, producing process, commands, outcomes, time, and unverified scope in a manifest. Integrity checks help detect mismatched or changed bytes, while separate execution and identity controls must establish who produced the evidence and whether its claims are trustworthy.", "limitation": "Matching hashes do not prove authorship, truthful execution, correct expectations, or genuine approval; a manifest alone cannot supply those facts.", "url": "", "authors": "", "year": "", "attributes": { "label": "Evidence-Pack Provenance", "kind": "practice_descriptor", "collection": "PAT", "family": "F07", "chapter": 7, "disposition": "Retain with explicit qualifications", "required_revision": "Bind the bundle to code, policy, oracle, and environment; distinguish a hash from identity or truth.", "occurrences": "[\"SDD2:D2\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "Matching hashes do not prove authorship, truthful execution, correct expectations, or genuine approval; a manifest alone cannot supply those facts.", "historical_structural_chapters": [ "C:C07" ], "family_name": "Tests, Oracles and Acceptance Evidence", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "PRECISARE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Let a reviewer determine whether an evidence pack actually applies to the candidate and decision currently under consideration.", "when_to_use": [ "Checks are performed across sessions, services, or participants and their results must survive a handoff.", "A candidate or requirement changes after a previously passing report was produced." ], "when_not_to_use": [ "A checksum-only manifest would be claimed to authenticate a producer or certify acceptance." ], "prerequisites": [ "Identifiable candidate, contract, oracle, policy, and environment revisions.", "Permitted evidence storage and a trustworthy process for recording actual execution." ], "steps": [ "Record the invocation, input revisions, environment, producing process, timestamp, and result for each material check.", "Retain the relevant raw artifacts and give each a stable locator and digest where appropriate.", "Assemble a manifest that maps the claims to those artifacts and states the checks and uncertainty outside its scope.", "Before use, compare the recorded revisions with the current decision inputs and separately verify any required producer or approval identity.", "Hold stale or incomplete evidence, retain it as history, and rerun the affected checks rather than renaming an old report as current." ], "example": "Illustrative example: A report shows that replay checks passed for candidate A under contract revision one. The candidate changes to B before review. Even if the old report’s digest still matches its stored bytes, it does not establish B’s behavior. The reviewer holds the bundle until relevant checks are rerun and the new manifest identifies the actual inputs and producer.", "verification": [ "Every material verification claim resolves to a recorded invocation and relevant artifacts.", "The pack matches the candidate and authority revisions used for the present decision.", "Integrity, producer identity, execution trust, and acceptance authority remain separate checks." ], "outputs": [ "A version-bound evidence manifest and retained artifacts.", "A freshness and provenance result with explicit limitations." ], "risks": [ "A file named as a passing result can conceal that no trustworthy execution produced it.", "Reusing current-looking metadata around old artifacts can launder stale evidence into a new review." ], "related_practices": [ "PAT:027", "PAT:072", "PAT:076" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 7 and 13 thematic guidance. Family F07 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:082", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C07", "file": "EN/chapters/chapter07.tex", "line": 3, "sha256": "0990c2265ce14a6e4f7274c64952b424d7b29678a995352ab6ec2258ca7dfe00", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C07", "title": "Independent Verification and the Oracle Problem", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:D2" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Dataset provenance and dependency", "K:Independent verification and oracles" ], "volumes": [ "V06" ], "families": [ "FAMILY:F07" ] }, { "id": "PAT:083", "label": "Budget-Gated Autonomy", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:What agents can do" ], "actual": [], "mapped": [ "C:C03", "C:C13" ], "printed": false, "summary": "Check resource limits before admitting the next autonomous action, using conservative allowances for attempts, calls, elapsed time, and cost. Persist consumed resources across interruptions, retries, model switches, and scheduler restarts. Budget bounds the permitted execution opportunity; unused resources cannot authorize a forbidden action, resolve missing intention, or convert a candidate into an accepted outcome.", "limitation": "A budget cannot bound an action whose effects or resource use are unknown unless the surrounding system can cap or deny it.", "url": "", "authors": "", "year": "", "attributes": { "label": "Budget-Gated Autonomy", "kind": "practice_descriptor", "collection": "PAT", "family": "F03", "chapter": 3, "disposition": "Recompose the mechanism", "required_revision": "Apply conservative advance budgets for actions, cost, and time; retain history across restarts.", "occurrences": "[\"SDD2:D3\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "A budget cannot bound an action whose effects or resource use are unknown unless the surrounding system can cap or deny it.", "historical_structural_chapters": [ "C:C03" ], "family_name": "Delegation, Execution and Stopping", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Prevent an apparently cheap repeated step from accumulating into unbounded work or resetting its resource history whenever execution resumes.", "when_to_use": [ "An agent can repeatedly invoke tools, regenerate candidates, or continue across sessions.", "The next step has uncertain cost or a loop lacks an explicit stop decision." ], "when_not_to_use": [ "A numerical allowance would be used to permit actions outside the task’s authority or protected boundaries." ], "prerequisites": [ "A controller-owned resource ledger and clock.", "Defined resource limits, a reservation policy, and an owner for escalation." ], "steps": [ "Choose the relevant resource dimensions and limits for the task, including mandatory checking and shutdown obligations.", "Before each action, estimate or enforce a conservative maximum allowance and deny admission when it cannot fit.", "Reserve the allowance in shared persistent state so concurrent or restarted attempts cannot each spend the same remainder.", "Reconcile actual consumption after execution, preserving attempt identity and unresolved reservations when completion is uncertain.", "Stop or escalate when limits are reached or unbounded actions are proposed; renew a budget only through the authorized decision path." ], "example": "Illustrative example: A worker has enough remaining time for one bounded repair and its checks, but not for an open-ended dependency installation. The controller admits the repair and records the reservation before execution. If the worker restarts, the reservation and earlier attempts remain visible. A successful result still goes to review; remaining budget does not let the worker publish it.", "verification": [ "Admission checks all relevant resource dimensions before execution.", "Restart and concurrent-attempt checks cannot silently reset or duplicate the available allowance.", "Stops distinguish exhausted budget from missing authority or verification failure." ], "outputs": [ "A persistent budget and reservation ledger.", "Admission, reconciliation, and stop decisions tied to attempts." ], "risks": [ "Tracking expenditure only afterwards can reveal overspend without having prevented it.", "A non-atomic ledger or ambiguous completion can admit duplicate work against the same remaining budget." ], "related_practices": [ "PAT:021", "PAT:033", "PAT:084" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 3 and 13 thematic guidance. Family F03 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:083", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C03", "file": "EN/chapters/chapter03.tex", "line": 3, "sha256": "ce0ca41e0ce359c1fd4752f2db1de6b1312c006510fc9c3ba364e3310916c2b1", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C03", "title": "Limits and Capability of Coding Agents", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:SDD2:D3" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Agent failure and escalation", "K:Benchmarks and construct validity", "K:Long-running agent execution" ], "volumes": [ "V06" ], "families": [ "FAMILY:F03" ] }, { "id": "PAT:084", "label": "Escalation Protocol", "kind": "practice_descriptor", "collection": "PAT", "category": "practices", "streams": [ "T:Engineering structure", "T:Jobs & roles", "T:Productivity" ], "actual": [], "mapped": [ "C:C11", "C:C13" ], "printed": false, "summary": "Return work through an explicit escalation when a required decision, permission, diagnostic, or resource is unavailable. Preserve the candidate and evidence, name the blocked outcome and responsible authority, and ask for the smallest decision that can resolve the block. Escalation is a recorded workflow result; it does not authorize acceptance simply because the execution budget has ended.", "limitation": "An escalation record cannot create an absent decision owner or substitute for the evidence and authority that the next stage requires.", "url": "", "authors": "", "year": "", "attributes": { "label": "Escalation Protocol", "kind": "practice_descriptor", "collection": "PAT", "family": "F11", "chapter": 11, "disposition": "Recompose the mechanism", "required_revision": "Name the outcome, authority, reason, and needed decision; budget does not enable acceptance.", "occurrences": "[\"SDD2:D4\", \"AGENT:23\"]", "status": "RECONCILED_EDITORIAL_DESCRIPTOR", "limitation": "An escalation record cannot create an absent decision owner or substitute for the evidence and authority that the next stage requires.", "historical_structural_chapters": [ "C:C11" ], "family_name": "Coordination, Governance and Adoption", "language": "en", "content_version": "13.1", "content_reviewed_on": "2026-10-18", "disposition_code": "RICOMPORRE", "practice_scope": "Editorial operational guide", "practice": { "schema_version": 1, "language": "en", "purpose": "Turn a stopped or disputed task into an actionable decision without losing evidence or encouraging unbounded retries.", "when_to_use": [ "A consequential requirement is unresolved, a permitted route is unavailable, or repeated failures lack a useful new diagnosis.", "The task reaches a resource limit, permission boundary, ownership conflict, or required review that the worker cannot resolve." ], "when_not_to_use": [ "The worker can resolve a routine implementation issue safely within existing authority and available evidence." ], "prerequisites": [ "Named responsibilities for intention, permissions, verification, coordination, and acceptance.", "A preserved task state and a way to deliver the decision request through the permitted workflow." ], "steps": [ "Classify the blocking condition and record a named state rather than treating every stop as failure or completion.", "Preserve the current candidate, applicable revisions, attempts, diagnostic evidence, remaining resources, and affected scope.", "Identify the authority able to decide the issue and state the smallest concrete question or action needed.", "Describe eligible options and their consequences without recommending an unsupported waiver of mandatory controls.", "Resume only after the relevant decision is recorded and stale assumptions are reconciled, or close the task with its explicit disposition." ], "example": "Illustrative example: A maker receives a second rejection saying the patch is wrong but no failing case or violated rule. It preserves both candidates and review messages, stops further regeneration under the agreed retry policy, and asks the verification owner for a traceable diagnostic. The owner may supply a counterexample or route an unresolved policy question onward. The stop never turns the latest green self-test into acceptance.", "verification": [ "The escalation identifies an actionable question and the appropriate decision authority.", "A successor can reconstruct the block and relevant evidence without repeating the whole investigation.", "Resumption records the decision and preserves resource, permission, and contract constraints." ], "outputs": [ "A named escalation or stop record with evidence.", "A decision-linked resumption, reassignment, or closure outcome." ], "risks": [ "Vague requests for approval can burden the wrong person while leaving the real decision unresolved.", "Repeated retries or implicit waivers can conceal a missing authority boundary." ], "related_practices": [ "PAT:026", "PAT:032", "PAT:083" ], "editorial_note": "Editorial operational guidance expanded for Atlas v13.1 from the retained practice descriptor and NDSE2 Chapters 11 and 13 thematic guidance. Family F11 preserves the catalogue classification. The example is illustrative; this entry does not establish measured effectiveness.", "source_basis": [ { "type": "retained_editorial_descriptor", "id": "PAT:084", "baseline_release": "13.0", "baseline_zip_sha256": "dcd17771f673270d4f8227087d6b342b6c0594a446f273d8b8119c1055654003", "scope": "Historical label, family, occurrences and critical revision; operational explanation expanded editorially." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C11", "file": "EN/chapters/chapter11.tex", "line": 3, "sha256": "18eb375b24343b3106d1530b9ca03a4a3dd0b88a58a34459858cd1f93cace300", "source_version": "13.7.1", "scope": "Thematic chapter guidance; a reading suggestion, not a literal citation of this named practice." }, { "type": "published_book_thematic_context", "chapter_id": "NDSE2:C13", "file": "EN/chapters/chapter13.tex", "line": 1, "sha256": "3fc3434f5ac2348bb0e7a15d100650848db78e857201849955543d4b08405bfa", "source_version": "13.7.1", "scope": "Practice selection and proportionality; a reading suggestion, not a literal citation of this named practice." } ], "chapter_references": [ { "id": "NDSE2:C11", "title": "Teams, Governance and the Engineering Organization", "role": "Thematic chapter guidance" }, { "id": "NDSE2:C13", "title": "Choosing Practices and Recognizing Their Limits", "role": "Practice selection and proportionality" } ] }, "historical_occurrence_ids": [ "OCC:AGENT:23", "OCC:SDD2:D4" ], "provenance": "English operational guidance expanded from the retained descriptor, its historical occurrence trail and thematic chapters of the author-supplied published NDSE2. Illustrative examples are not observed outcomes." }, "topics": [ "K:Human-agent collaboration", "K:Review capacity and maintainers", "K:Specifications and governance" ], "volumes": [ "V06" ], "families": [ "FAMILY:F11" ] } ] }