ENG-02 — Engineering Context, Traceability, and Living Documentation¶

Engineering Foundation · Working Draft · Working Draft v15 · Updated September 6, 2026

1. Objective¶

Establish DragonPay's standard system for connecting authoritative Product requirements, engineering decisions, implementation, testing, deployment evidence, AI-assisted development context, and human-readable living documentation.

DragonPay begins from a true zero-state engineering environment. Cloud accounts, vendor/tool accounts, development environments, CI/CD, shared libraries, and production infrastructure may not yet exist. ENG-02 therefore supports both foundation/decision work and Product implementation work while progressively creating the context system used by developers and Claude.

Keep the Product documentation repository authoritative for Product intent, shared standards, and Product-level architecture decisions.
Keep development repositories authoritative for source code, tests, implementation ADRs, infrastructure code, and implementation traceability.
Use the Product and development repositories as the source for both MkDocs human documentation and Claude implementation context.
Evolve the MkDocs site already being built for executives into an aggregated living view of Product intent, implementation facts, engineering decisions, progress, and environment state.
Provide deterministic, inspectable context selection so Claude receives the minimum sufficient authoritative Product and implementation context for a unit of work.
Provide requirement-to-code-to-test-to-release traceability without allowing implementation behavior or generated documentation to redefine Product requirements.
Support requirement-driven technology decisions, human-approved ADRs, one-time bootstrap, and 0-to-1 setup when the required platform/tooling does not yet exist.
Favor simple Git/file-based tooling and deterministic resolution before introducing semantic retrieval, a metadata database, or a separate web application.

ENG-02 is the engineering-context and traceability standard from this point forward. Existing Product/MkDocs work remains valid and should be migrated incrementally rather than stopped or rebuilt before new development can begin.

2. Operating model and new standard¶

DragonPay separates Product intent, implementation, and observed implementation facts so humans and AI can use all three without confusing their authority.

Layer	Authoritative contents / question answered
Product repository	PH/PP/CX/OX requirements, STD/ENG standards, Product-level ADRs, requirement relationships. Answers: What must DragonPay do?
Development repository/repositories	Source code, tests, Terraform/IaC, implementation ADRs, human engineering documentation, requirement mappings. Answers: How is DragonPay implemented?
Generated implementation evidence	API/event/schema/package/infrastructure catalogs, test evidence, requirement coverage, deployment/environment evidence. Answers: What currently exists?
MkDocs site	Aggregates the above for executives, Product, operations, developers, and reviewers. It is a presentation layer and authoritative for nothing.

The Product repository is separate from development repositories.
Development repositories are created when an actual implementation, ownership, security, deployment, or organizational need justifies them; repository separation is not itself an architectural goal.
Git documents/files remain authoritative. MkDocs is generated from those sources and does not become a second source of truth.
New engineering work should be structured so requirement IDs, implementation mappings, tests, ADRs, and deployment evidence can participate in this model.
Existing MkDocs content intended for executive/Product readers remains readable; detailed engineering/traceability views may be separate or progressively disclosed rather than overwhelming those pages.

Requirement classes¶

Every traceable ID belongs to exactly one of three classes, derived automatically from its document-family prefix — never manually tagged:

Class	Doc family	Lifecycle	Independently released?
PRODUCT	PH / PP / CX / OX / CI	NOT_STARTED → IN_PROGRESS → IMPLEMENTED → VERIFIED → RELEASED (§7)	Yes
FOUNDATION	ENG	UNRESOLVED → PROPOSED → APPROVED → ESTABLISHED (§4)	No — reaches ESTABLISHED, not RELEASED
STANDARD	STD	Referenced only — no independent status of its own	No

A FOUNDATION requirement can absolutely have implementation mappings, tests, ADRs, Terraform, documentation, and validation evidence — it just doesn't pretend to have been "released to PROD" when the story was, for example, selecting and establishing a repository/toolchain standard. ESTABLISHED means the foundation is sufficiently implemented and validated for downstream consumption; it is FOUNDATION's equivalent milestone to PRODUCT's RELEASED, not the same thing under a different name.

A STANDARD requirement is traceable but never a standalone delivery item. It is referenced by the PRODUCT/FOUNDATION requirements that depend on it:

standards:
  - STD01-04
  - STD01-09

There is no independent STD01-04 → RELEASED status — a STANDARD requirement contributes to the conformance of whatever PRODUCT/FOUNDATION requirement consumes it, rather than carrying conformance of its own.

Requirement ID format¶

Every requirement/story/section ID across every epic family and every class uses one uniform format: {PREFIX}{EPIC-NUMBER}-{ITEM-NUMBER} — for example PH08-05, ENG01-21, ENG02-07, STD01-14. The class (PRODUCT/FOUNDATION/STANDARD) determines lifecycle rules; it never changes the ID's shape. This is not a new convention — PH/PP/CX/OX/CI/ENG-01/ENG-02 already use it consistently; STD-01's sections carry the same STD01-NN IDs so the format has no exceptions.

3. Operating modes¶

DragonPay defines three explicit Claude operating modes: PM Mode, ENG Mode, and Admin Mode. The same Claude instance may perform any of the three, but only one is active for a unit of work, and it is invoked explicitly by the user — never entered automatically.

Operating modes and requirement classes (§2) are separate concepts and must not be used interchangeably. PM Mode is not the same scope as the PRODUCT requirement class — it covers the whole Product repository (PH/PP/CX/OX/CI/ENG/STD) when explicitly authorized, not just PRODUCT-class documents. Likewise, ENG Mode is not the same scope as the FOUNDATION requirement class — ENG Mode may implement both PRODUCT-class and FOUNDATION-class requirements and may also perform engineering decision/ADR and setup work. The term "ENG Mode" must not be interpreted as applying only to FOUNDATION-class requirements.

Mode	Primary purpose	Product repo	Development repo(s)	Human gate
PM Mode	Maintain and evolve authoritative Product intent — PH/PP/CX/OX/CI/ENG/STD requirements and Product ADRs, when explicitly authorized	Read/write only in an explicitly authorized Product-authoring action	Read for impact analysis; no implementation edits by default	Human approves Product intent/requirement changes
ENG Mode	Engineering decisions, foundation/ADR work, Product/Foundation implementation, testing, review, and preparing changes for source-control acceptance	Authoritative read-only input	Read/write implementation, tests, IaC, engineering docs, traceability	Engineer reviews locally before source-control acceptance
Admin Mode	Refresh Product indexes, traceability, status, attention items, generated documentation, and MkDocs visibility	Read; generated presentation must not redefine Product	Read; may generate derived documentation/status artifacts as designed	No Product intent change; report actionable items

Locked principle: no automatic mode handoffs. PM Mode, ENG Mode, and Admin Mode are independently invoked actions within the applicable workflow, not automated transitions. Claude may recommend that a different mode looks needed — for example, surfacing that an ENG Mode finding looks like it needs a Product decision — but must not autonomously switch modes or cross repository authority boundaries. In particular, Claude executing an ENG Mode task must not modify authoritative Product documentation merely because it determines a Product update would be useful; a human explicitly invokes PM Mode for that, as its own separate action.

Locked principle: modes are repository-independent. PM Mode, ENG Mode, and Admin Mode are invokable from a session started in either DragonPay repository — the selected mode determines behavioral authority; the session's current working directory supplies only repository-local context, never the mode's authoritative target. A workflow must not require exiting and relaunching Claude in a different repository solely to reach a mode. The mode definitions and repeatable procedures have one canonical implementation, available identically to sessions started from either repository (§ENG02-14).

Locked principle: explicit repository resolution. Before performing any work, every PM/ENG/Admin action must deterministically resolve the authoritative repository or repositories it requires — never assumed from the session's current working directory. If resolution is ambiguous, or the resolved location cannot be validated, the action fails before modifying any files.

Foundation/ADR work is part of ENG Mode, not PM Mode. ENG Mode evaluates engineering choices, reviews applicable DragonPay Product/STD/ENG constraints, compares candidates, and drafts recommendations/ADRs; it also performs foundation setup once a decision is approved. PM Mode is invoked only when an explicitly authorized Product-maintenance action is requested — for example, incorporating an already-approved engineering decision into a Product ADR or ENG/STD document. These remain separate, user-invoked actions, not an automated pipeline:

ENG Mode — Work ENG01-09
  - Resolve engineering/Product context.
  - Evaluate technology choices.
  - Draft recommendation/ADR.
  - Human reviews and approves the decision.

[If the approved decision requires authoritative Product documentation
 changes, the user later explicitly invokes:]

PM Mode — Incorporate the approved ENG01-09 decision into the applicable
Product ADR/ENG/STD documentation.

[The user then explicitly resumes:]

ENG Mode — Continue ENG01-09 implementation using the approved decision.

The overall model stays simple: PM Mode — change what we intend to build. ENG Mode — decide how and build it. Admin Mode — refresh the picture and tell me what needs attention.

If implementation cannot satisfy authoritative Product behavior because of ambiguity, conflict, or a missing Product/engineering decision, development is BLOCKED rather than silently changing the requirement.
An implementation ADR may refine an approved Product decision but may not override Product requirements or Product-level ADRs.
Generated engineering facts and existing code inform Claude about the current system; they never create or override Product behavior.
If code or generated facts conflict with Product requirements, the implementation is wrong, incomplete, or blocked; the discrepancy is not normalized into a new requirement.
Product baseline advancement in a development repository is explicit. Development never silently follows latest Product HEAD.

4. Zero-state foundation and decision lifecycle¶

This lifecycle applies to FOUNDATION-class requirements (ENG-prefixed) — see §2 for the three requirement classes and why PRODUCT and STANDARD requirements don't use it.

ENG-02 assumes no cloud accounts, environments, vendor accounts, CI/CD platform, shared packages, or deployed infrastructure exist unless implementation evidence proves otherwise. Foundation work must therefore support decision, approval, bootstrap, setup, and validation as distinct steps.

Decision state	Meaning
UNRESOLVED	An engineering need is known but no approved technology/approach exists.
PROPOSED	A candidate/recommendation or ADR draft exists and is under review.
APPROVED	An authorized human approved the applicable Product ADR/technology decision.
ESTABLISHED	The minimum usable tooling, infrastructure, configuration, library, or scaffold exists and has been validated for downstream engineering use.

Technology selection is requirement-driven. Claude evaluates candidates against applicable DragonPay Product, STD, ENG, security, operational, development, cost, and deployment constraints rather than generic popularity.
APPROVED does not mean provisioned or usable. Establishment evidence is separate.
A foundation decision that is already APPROVED is not reopened during ordinary implementation merely because another tool is attractive.
One-time manual bootstrap is permitted when required to create accounts, identities, credentials, state, billing ownership, or automation prerequisites.
Manual bootstrap should be limited to prerequisites; steady-state DragonPay-managed infrastructure/configuration transitions to the approved automated/IaC model.
BOOTSTRAP_REQUIRED is a normal workflow checkpoint, not a Product-requirement blocker.

5. Requirement lifecycle, baselining, and evolution¶

Released requirements are historical behavioral contracts. Product growth is represented by additional requirements rather than rewriting what was originally implemented and released.

Relationship	Meaning
modifies	New requirement changes or adds behavior relevant to an existing requirement while the earlier released requirement remains historical context. The modifier and its target both remain relevant to current behavior — modifies never makes its target obsolete. A modifies relationship is always discovered by direct reference only, never chained to find a modifier of a modifier — but a discovered modifier's own current form (whether it has itself been superseded or retired) is resolved the same way any other requirement's is.
supersedes	New requirement explicitly replaces the referenced requirement as part of the current effective contract. A requirement may be the target of at most one supersedes declaration; more than one requirement declaring supersedes against the same target, or a cycle among supersedes relationships, is invalid Product structure — not something resolved by picking one.
retires	The referenced requirement is intentionally no longer a current implementation target, from the defined later release onward, and has no replacement. A requirement cannot be simultaneously the target of both a supersedes declaration and a retires declaration — the two are mutually exclusive for the same target.

Before first release, Product requirements may be edited through the Product-authoring workflow.
At first RELEASED, retain the Product commit and exact requirement content hash/snapshot identity as immutable historical evidence.
After first RELEASED, the behavioral story block must not be materially edited. Later behavior is introduced through a new requirement and an explicit modifies/supersedes/retires relationship.
Normal changes elsewhere in the Product repository do not make a released requirement stale.
A released requirement remains released even when its implementation is later refactored, moved, or replaced internally.
Current effective behavior is the applicable set of Product requirements after relationship rules are applied; release history remains intact.
Relationships are declared from the newer, declaring requirement to the referenced target (e.g. PH08-14: modifies: [PH08-05] declares that PH08-14 modifies PH08-05) — resolving a given requirement's modifiers, superseding successor, or retirement means finding the other requirements that declare a relationship naming it as their target, never anything the requirement itself declares outward.
A requirement's direct modifiers are the requirements that declare a modifies relationship naming it as the target — found one hop only, never a modifier of a modifier.
A superseded requirement's current replacement is found by following the chain of requirements that declare supersedes against it, one link at a time (PH08-20 supersedes PH08-07; if PH08-25 later supersedes PH08-20, PH08-07's current replacement is PH08-25) until reaching a requirement that nothing else declares supersedes against — that requirement is the current replacement, unless it is itself the target of a retires declaration, in which case there is no current implementation target. This chain-walk applies only to supersedes; modifies is never chained. The same chain-walk resolves the current form of a direct modifier, exactly as it resolves the selected requirement's own current replacement — the mechanism is identical, applied once to whichever requirement is being resolved (selected requirement or a direct modifier), never recursively beyond that.

Product relationship metadata¶

Most Product metadata should be derived from the Markdown structure. Only non-derivable evolution relationships should require explicit sidecar metadata, initially under a Product-repository metadata directory.

metadata/requirement-relations.yaml

requirements:
  PH08-14:
    modifies:
      - PH08-05

  PH08-20:
    supersedes:
      - PH08-07

6. Requirement traceability model¶

Each implemented Product/ENG requirement has one traceability owner in a development repository. The current implementation mapping is intentionally mutable; historical verification/release evidence is immutable.

Mutable developer/Claude-maintained metadata	System-generated / historical evidence
requirement_id, Product baseline, work state, implementation paths/packages, tests, implementation ADR references, required deployment units, attention items	verification results/commit, requirement snapshot/hash, deployment evidence/history, first-release evidence, derived VERIFIED/RELEASED status, current conformance evidence

Use one manifest per requirement to reduce merge conflicts and make ownership explicit.
"Mutable" work state is qualified, not absolute: NOT_STARTED/IN_PROGRESS/BLOCKED are freely developer/Claude-declared, but IMPLEMENTED is not — it is derived from a source-control acceptance event, never set by editing this manifest (see §7).
A requirement may reference multiple simultaneous attention_items (a list of IDs, not a single field) — a requirement can have more than one open issue at once. Each attention item's own record is separate from this manifest; ENG02-04 and ENG02-13 validate this list's shape only — the record's exact schema and an authoritative attention-item source remain deferred to a future ENG-02 implementation story not yet identified (see §7).
A released requirement may update implementation paths, tests, ADR mappings, or deployment-unit mappings as the codebase evolves.
Updating current implementation mappings never erases or rewrites historical verification/release evidence.
STD-01 command idempotency or other runtime keys do not belong in this traceability model unless they are implementation facts being referenced.
If a requirement spans multiple repositories in the future, one manifest remains the traceability owner and references evidence from the other repositories rather than duplicating status ownership.

Initial development-repository layout¶

.dragonpay/
  config.yaml
  requirements/
    PH08-05.yaml
    PH10-06.yaml
  generated/
    context/
      PH08-05/
        context-manifest.yaml
        context-bundle.md

Initial config.yaml shape¶

The Product-repository reference is a contract, not a mandated VCS mechanism. The invariant is that a development repo can identify a Product checkout and pin an exact Git commit — nothing about how that checkout is reached (a sibling local checkout, a submodule, a CI-time clone) is part of the contract itself.

product:
  repository_id: dragonpay-product
  path: ../dragonpay-product
  baseline_commit: 82fa91c
  remote: null

Later, once a remote exists:

product:
  repository_id: dragonpay-product
  path: ../dragonpay-product
  baseline_commit: 82fa91c
  remote: <Bitbucket repo>

baseline_commit is what provides reproducibility. remote is location/distribution metadata layered on top.

Locked rule: A Product remote is optional for local development but required before the Product repository is consumed by CI, another machine/contributor, or any environment where the configured local checkout cannot be assumed.

Initial traceability manifest shape¶

requirement_id: PH08-05

product:
  repository: dragonpay-product
  baseline_commit: 82fa91c

work:
  state: IN_PROGRESS

implementation:
  files:
    - packages/connector-core/src/send.ts

tests:
  - packages/connector-core/test/send.spec.ts

implementation_adrs:
  - ADR-017

deployment_units:
  - execution-worker

attention_items: []

7. Work status, verification, conformance, and release¶

This lifecycle applies to PRODUCT-class requirements (PH/PP/CX/OX/CI-prefixed) — see §2 for the three requirement classes.

State	Authority / meaning
NOT_STARTED	Mutable work state: no active implementation work identified.
IN_PROGRESS	Mutable work state: selected work is actively being developed/reviewed locally or on a non-authoritative working branch.
BLOCKED	Mutable work state: a scoped unresolved issue prevents meaningful safe continuation of the affected work.
IMPLEMENTED	Not developer/Claude-declared. Reviewed implementation and required traceability have been accepted into the configured authoritative Development branch (see "Authoritative Development branch" below). It does not mean the implementation has built, passed CI, or been deployed.
VERIFIED	System-derived only: required verification passed against a known Product requirement version and implementation revision.
RELEASED	System-derived historical milestone: VERIFIED plus all required deployment units containing the verified implementation are objectively confirmed in PROD.

Claude or developer-edited metadata must not independently create IMPLEMENTED, VERIFIED, or RELEASED. Editing a manifest field can declare NOT_STARTED, IN_PROGRESS, or BLOCKED only.
If CI fails after source-control acceptance, the requirement remains IMPLEMENTED with failed verification. The source-control acceptance itself is never reversed by a later CI failure.
RELEASED never regresses; it records that the requirement reached production at least once.
current_conformance is PASS, FAIL, or UNKNOWN, and stays scoped to whether the current implementation still satisfies an already-released historical contract — it is not the generic result of the most recent CI run. A not-yet-released IMPLEMENTED requirement with failing CI is represented as IMPLEMENTED, not yet VERIFIED — never as current_conformance: FAIL, which only applies once a requirement has been RELEASED at least once.
A later defect may therefore show RELEASED + current conformance FAIL without pretending the requirement was never released.
A superseded/retired requirement remains in historical release views but may be removed from the current conformance contract from the applicable later release onward.

Authoritative Development branch¶

Phase	Authoritative implementation acceptance
Bootstrap / local-only	Human-reviewed commit or merge to the configured local authoritative branch.
Shared remote established	Approved merge to the configured protected integration/default branch in the authoritative remote repository.

A push to a feature/working branch does not by itself mean IMPLEMENTED — the authoritative branch is explicitly configured (development.authoritative_branch in .dragonpay/config.yaml, see ENG02-01). When a shared remote exists, branch protection and normal PR/peer-review policy may strengthen the acceptance gate without changing this lifecycle semantics. No separate "accept in Claude" action exists: engineer review happens before source-control acceptance, and the source-control event itself is the durable evidence for IMPLEMENTED.

Preflight and issue severity¶

Preflight classifies a unit of work before implementation begins, and issues found along the way are scoped to what they actually affect rather than stopping everything:

Preflight result	Meaning	Engineering behavior
READY	No meaningful unresolved issue affects the selected work.	Proceed through plan/review/implementation.
READY_WITH_ISSUES	Known issues exist, but meaningful safe implementation can continue.	Record/route issues and continue unaffected portions.
BLOCKED	No meaningful safe work remains on the affected selected work until a required resolution occurs.	Stop the affected work, create an attention item, and work elsewhere if possible.

READY_WITH_ISSUES and BLOCKED here are preflight outcomes, not requirement lifecycle states — they never appear as a work.state value.

Issue severity	Meaning
OBSERVATION	Worth recording or reporting; no required action before current work proceeds.
ACTION_REQUIRED	Requires later Product/Admin/Foundation/Engineering follow-up but does not prevent current safe progress.
BLOCKING_CURRENT_WORK	Prevents correct or safe continuation of the affected portion of the selected work.

Partial implementation. If only part of a requirement is blocked, Claude continues implementable acceptance behavior when doing so doesn't create unsafe assumptions or throwaway work — the requirement stays IN_PROGRESS and the unresolved portion is explicitly recorded as an attention item, rather than stopping the whole requirement. Example: AC1/AC2/AC4 are implementable and continue; AC3 is missing a Product decision and becomes an attention item. Overall preflight is READY_WITH_ISSUES, not BLOCKED.

Initial blocker type	Meaning
REQUIREMENT_AMBIGUITY	Product behavior cannot be determined unambiguously.
REQUIREMENT_CONFLICT	Two authoritative Product contracts cannot be reconciled.
MISSING_PRODUCT_DECISION	A Product decision is required before correct implementation can continue.
MISSING_ENGINEERING_DECISION	A required foundation/engineering decision is not yet approved/established.
EXTERNAL_DEPENDENCY	A required external account, provider, access, prerequisite, or dependency is unavailable.

Attention items and mode usage¶

Findings become visible, queryable work rather than something lost in a Claude conversation. A requirement may have multiple simultaneous attention items, so the model never assumes a single blocker reference:

attention_items:
  - DPI-004
  - DPI-009

Each attention item eventually captures, at minimum: issue type, severity, affected requirement, affected acceptance criterion/section where known, status, reason, and a suggested mode/action for resolution. ENG02-04 and ENG02-13 validate that each reference is a well-formed entry (shape only); the record's exact schema and an authoritative attention-item source remain deferred to a future ENG-02 implementation story not yet identified.

There is no automatic routing. Each blocker type has a default suggested next action, but reaching it always requires an explicitly invoked PM Mode or ENG Mode action (§3) — never an automatic handoff:

Blocker	Suggested resolution
REQUIREMENT_AMBIGUITY	Creates a Product attention item; addressable through an explicitly invoked PM Mode action.
REQUIREMENT_CONFLICT	Creates a Product attention item; addressable through an explicitly invoked PM Mode action.
MISSING_PRODUCT_DECISION	Creates a Product attention item; addressable through an explicitly invoked PM Mode action.
MISSING_ENGINEERING_DECISION	Addressed through an explicitly invoked ENG Mode foundation/ADR action.
EXTERNAL_DEPENDENCY	Remains with the originating work until the prerequisite is satisfied; does not by itself require a PM Mode or ADR action.

Example: an Azure account hasn't been created yet — that's a prerequisite to complete, not a Product or architecture question, so it stays in place rather than generating a PM Mode or ADR action. Claude may identify and recommend the appropriate next mode/action; it does not invoke that mode itself.

8. Environment and deployment evidence model¶

Canonical DragonPay environments are DEV, STA, and PROD. Local developer execution and ephemeral PR environments do not participate in canonical requirement release status.

Environment state	Meaning
UNPROVISIONED	The canonical environment does not yet exist.
PROVISIONED	Required environment resources exist but may not yet be proven usable for application deployment.
AVAILABLE	Environment is usable for its intended deployment/validation purpose.
UNAVAILABLE	Environment exists but is currently not usable; operational evidence should explain why when available.

Deployment evidence field	Requirement
environment	DEV, STA, or PROD.
deployment_unit	Deployable component required by one or more requirements.
repository	Source repository that produced the artifact.
source_commit	Git revision used to build the deployed artifact.
artifact_version	Deployable artifact/release version when available.
deployment_id	Stable deployment/run reference.
deployed_at	Observed deployment timestamp.

A requirement is deployed to an environment only when every required deployment unit has valid evidence for an artifact containing the applicable verified implementation revision.
For V1, "contains" may be proven by exact Git commit or descendant/ancestry where repository topology permits; if provenance cannot prove inclusion, the environment state for that requirement is not considered satisfied.
RELEASED requires the same condition specifically in PROD.
The CI/CD provider used to produce deployment evidence may remain TBD until ENG-01 selects it. ENG-02 defines the evidence contract rather than hard-coding a vendor.
At first RELEASED, retain immutable first-release evidence: Product requirement snapshot/hash, verified code revision, and qualifying PROD deployment evidence.
Later deployments create additional deployment history and current-environment views without rewriting the first-release record.

9. Engineering documentation and MkDocs aggregation¶

Engineering documentation supports review and reuse but does not add Product requirements. The existing MkDocs site is the starting human interface and evolves toward an aggregated Product + engineering view.

Human-authored engineering documentation¶

Implementation ADRs.
Package/module README and architecture notes.
Developer setup and local-development instructions.
Integration implementation notes.
Operational/runbook documentation.
Deployment/topology notes that explain implementation decisions.

Generated implementation facts¶

OpenAPI/API catalog.
Event catalog and schema versions.
Database/persistence schema catalog.
Package/module/dependency inventory.
Terraform/infrastructure inventory.
Test and requirement-coverage evidence.
Build/version and DEV/STA/PROD deployment evidence.
Generated facts describe what currently exists; they do not state what DragonPay is supposed to do.
Generated artifacts should carry provenance including source repository, source commit, generator/source type, and generation time where practical.
Do not manually maintain duplicate prose for facts that can be deterministically regenerated from source/schema/Terraform/CI/deployment evidence.
MkDocs reads/aggregates Product and configured development repositories plus generated build evidence. Generated progress is not written back into the Product repository.
Requirement pages should visibly distinguish authoritative Product content from implementation evidence/status so executive and engineering readers do not confuse them.

Canonical pages vs. curated pages¶

Two audiences, two page types, both required — neither replaces the other:

Curated narrative pages (DragonPay's existing MkDocs Engineering Architecture section — Identity & Access, Data Architecture, Infrastructure, Observability, and so on) synthesize information across multiple source documents for human readability. They remain exactly as built.
Canonical requirement-reference pages additionally expose each traceable document with its original headings and stable IDs intact — [ENG-01](eng-01.md), ENG-02, [STD-01](std-01.md) — so every requirement ID (ENG01-21, STD01-12, etc.) has one deterministic URL/anchor. These don't need to clutter primary navigation — they can live under a dedicated "Requirements Reference" group or be linked contextually.

Canonical source page
    ↑
    │ authoritative content
    │
Curated narrative page
    │
    └─ presents/summarizes for humans

A curated page is never a requirement's only physical representation. Without a canonical anchor: dp-eng cannot link to a requirement, MkDocs-generated progress has nowhere to attach, Claude cannot resolve it deterministically, and humans/curated pages cannot deep-link to it. This is a small addition now that avoids a much larger remapping problem once traceability tooling exists.

10. Implementation context standard¶

Implementation context is a first-class engineering artifact. Claude should receive the minimum sufficient authoritative Product and implementation context for the work rather than the complete DragonPay knowledge base.

Context class	Initial contents / behavior
Mandatory Product	Containing epic, requested requirement, direct modifying requirements resolved to their own current form, the current replacement for a superseded requirement (§5), STD-01, ENG-01, applicable Product ADRs, resolvable direct cross-references.
Mandatory implementation	Development CLAUDE.md, traceability manifest, mapped source/tests, implementation ADRs, relevant human engineering docs, relevant generated facts.
Protected existing contracts	Other Product requirements whose traceability already explicitly maps the same implementation path(s) expected to change (§ENG02-12; package/module-level matching deferred until an authoritative model exists).
Discoverable	Neighboring requirements, broader engineering docs, generated facts, similar code, historical ADRs; retrieve on demand when needed.
Excluded by default	Unrelated epics/products, unrelated source, and transitive dependency trees that are not directly relevant.

V1 intentionally loads the entire containing epic rather than attempting perfect paragraph-level extraction.
A dependency does not automatically load its complete transitive dependency tree.
Context may expand on demand when a referenced contract or implementation detail is unresolved.
Requirement IDs and structured relationships drive authoritative retrieval first; semantic retrieval is supplemental discovery only.
When implementation targets are known, existing requirements mapped to those targets must be treated as contracts to preserve and included in context.
STD-01 (and any other STANDARD-class document with no discrete requirement IDs beyond its own sections) is always Mandatory Product context — never itself an independently traceable delivery item, per §2's requirement classes.
For ENG-02 implementation itself, this ENG-02 document is authoritative context. For normal downstream development, root CLAUDE.md should carry the concise operating rules derived from ENG-02 and point back to ENG-02 when deeper context is needed.

11. Deterministic context resolver and CLI¶

ENG-02 introduces a local, inspectable TypeScript repository tool. Working command/package name is dp-eng. V1 uses Git, Markdown/YAML, filesystem inspection, and deterministic rules rather than a centralized metadata database or RAG service.

Command	Initial purpose
dp-eng baseline show	Show the Product repository and pinned Product commit used by the development repo.
dp-eng baseline advance	Explicitly advance the Product baseline after validating the target commit and affected traceability.
dp-eng product index	Build/rebuild an index of Product documents, requirement IDs, locations, relationships, references, and Product ADRs.
dp-eng validate	Validate Product baseline, IDs, relationships, traceability manifests, mapped files/tests, baselined requirement integrity, blocker records, and context resolution.
dp-eng context	Resolve and materialize inspectable Product + implementation context for the work.
dp-eng trace	Show requirement -> code -> tests -> ADR -> verification -> environment/release evidence.
dp-eng status	Show mutable work state, effective status, current conformance, and DEV/STA/PROD state.
dp-eng refresh	Admin Mode's refresh entry point — coordinates, as applicable: Product index refresh, traceability validation, effective status calculation, attention-item refresh, generated implementation/documentation views, and MkDocs generated content/build. Exact internals may evolve as later ENG02 stories are implemented; this command is the standard answer to "Admin Mode — refresh DragonPay and tell me what needs attention."

Product index — derived, not authoritative¶

Every dev repo/context operation builds or refreshes its own Product index from its configured pinned Product checkout:

Dev repo
  ↓ configured Product path + baseline commit
  ↓ dp-eng product index
  ↓ local generated Product index

If DragonPay eventually has five dev repos, each produces the same index from the same Product commit independently — the MkDocs aggregation build generates its own copy once per site build and reuses it internally. Locked rule: Product indexes are reproducible derived artifacts generated from the pinned Product checkout. They may be cached/reused within a build, but they are never authoritative and do not need to be committed. There is no central mutable requirements-index database that every repo depends on — that would create a second source of truth.

Context resolver V1 sequence¶

Locate the requested requirement in the pinned Product baseline.
Resolve Product evolution relationships naming the requested requirement as target: its direct modifiers, each resolved to its own current form (one hop only), and — if the requirement or a modifier is superseded — the current replacement found by following the supersedes chain to termination (§5).
Include the entire containing epic plus STD-01, ENG-01, applicable Product ADRs, and direct resolvable references.
Read the development CLAUDE.md and owning traceability manifest.
Resolve mapped implementation files/packages, mapped tests, implementation ADRs, engineering docs, and relevant generated facts.
Resolve other requirements whose traceability explicitly maps the same implementation path(s) expected to change and mark them as protected existing contracts (§ENG02-12; package/module-level matching deferred until an authoritative model exists).
Run deterministic preflight/conflict checks; unresolved authoritative conflict is BLOCKED rather than inferred.
Produce an inspectable context manifest and convenience context bundle.

.dragonpay/generated/context/PH08-05/
  context-manifest.yaml
  context-bundle.md

Context bundles are build/working artifacts and should not become a second manually maintained source of truth. CI may retain manifests as artifacts for audit/debugging.

12. Required workflows¶

A. Foundation decision and 0-to-1 setup (ENG Mode)¶

ENG Mode — ENG requirement / engineering need
  -> resolve context
  -> approved decision exists?
       no: evaluate -> ADR proposal -> human approval
       yes: continue
  -> setup plan
  -> BOOTSTRAP_REQUIRED when necessary
  -> automated/IaC/application scaffolding
  -> validation
  -> ESTABLISHED

Claude may research current vendor/tool information and produce a requirement-driven decision package.
Human approval is mandatory before a Product ADR/technology decision becomes APPROVED. This approval is a human decision point within the same ENG Mode session — it is not itself a mode switch.
If the approved decision needs to be committed into authoritative Product documentation (a Product ADR, an ENG/STD document), that commit is a separately, explicitly invoked PM Mode action (§3) — not an automatic continuation of this workflow.
Setup planning distinguishes one-time human bootstrap from Terraform/automation/application/CI work.
ESTABLISHED requires explicit validation evidence showing the foundation is usable for dependent development.

B. Product requirement implementation (ENG Mode)¶

Requirement selected
  -> Context resolved
  -> Preflight
  -> Claude implementation plan
  -> Engineer plan review
  -> Claude implements locally
  -> Claude self-validates
  -> Engineer implementation/behavior review
  -> Iterate as needed
  -> Engineer accepts through source-control action
  -> Implementation reaches authoritative Development branch
  -> IMPLEMENTED
  -> Automated verification
  -> VERIFIED
  -> Deployment
  -> RELEASED

Two distinct engineer review checkpoints, not one collapsed step: a plan review before coding, and a separate implementation/behavior review after Claude builds locally. The engineer determines whether the implementation meets the requirement objective, acceptance criteria, applicable Product/STD/ENG context, architectural expectations, and maintenance expectations — review depth is professional judgment based on the nature and risk of the change, not a fixed checklist, review duration, or manual-test count.

After local self-validation, Claude presents a concise review package: what changed; requirement/acceptance coverage; applicable standards/ADRs; existing requirements protected; tests/checks performed; decisions/assumptions made; known issues or limitations. §19 (Engineering Scope and Assumption Guardrails) defines the full required structure for implementation planning and engineer review, including required-now/deferred classification, assumptions requiring review, and post-implementation scope reconciliation.

Implementation starts from explicit stable requirement IDs.
Preflight verifies required Product/engineering decisions exist and authoritative context is internally consistent (§7's READY/READY_WITH_ISSUES/BLOCKED).
Implementation plans identify expected changes, acceptance mapping, and existing requirements that must be preserved.
Plan review is required before coding during initial DragonPay development and may later become configurable for routine low-risk work.
Claude may not approve its own PR, claim engineer acceptance on its own behalf, or mark its own work IMPLEMENTED/VERIFIED/RELEASED by editing metadata — IMPLEMENTED is derived only from the source-control acceptance event (§7).
No separate "accept in Claude" action exists; the source-control acceptance event is the durable evidence.
Product baseline advancement remains explicit even when newer Product commits exist.

C. Product attention-item resolution (ENG Mode → explicitly invoked PM Mode → ENG Mode)¶

ENG Mode — Development discovers a Product/decision problem
  -> BLOCKED (scoped to the affected work)
  -> attention item created (§7)

[Explicitly invoked, separately, only if Product documentation needs
 to change:]

PM Mode — Update Product docs/ADR as appropriate
  -> human approval + Product commit

[Explicitly invoked, separately, to continue:]

ENG Mode — explicit development baseline advance
  -> validate + rerun context
  -> resume implementation

This is not a continuous automatic pipeline — each mode line above is a distinct, user-invoked action, per §3's "no automatic mode handoffs" rule. It preserves the ENG Mode read-only Product boundary without preventing the Product owner from separately using PM Mode to maintain and reconcile Product documentation. See §7's "Attention items and mode usage" for which blocker types suggest a PM Mode action versus an ENG Mode foundation/ADR action versus staying in place.

13. Required repository artifacts and interfaces¶

Artifact / interface	Purpose
.dragonpay/config.yaml	Development-repo configuration: Product repo reference (repository_id/path/baseline_commit/remote), the configured `development.authoritative_branch` (§7), and local ENG-02 tooling configuration.
Product metadata/requirement-relations.yaml	Non-derivable modifies/supersedes/retires relationships maintained through Product-authoring workflow.
.dragonpay/requirements/.yaml	One current implementation/traceability manifest per owned requirement.
Attention item records	One record per open issue (issue type, severity, affected requirement, affected AC/section where known, status, reason, suggested mode/action); a requirement's manifest references zero or more by ID via `attention_items` (§7). `ENG02-04`/`ENG02-13` validate reference shape only; exact schema and an authoritative source remain deferred to a future ENG-02 implementation story not yet identified.
Product index	Rebuildable generated index of Product documents, stable IDs, section locations, references, relationships, and ADRs. Derived, never committed — see §11.
context-manifest.yaml	Inspectable explanation of the authoritative/implementation context selected for one work item and why.
context-bundle.md	Convenience materialization for human/Claude review; rebuildable, not authoritative.
VerificationEvidence contract	System/CI-produced evidence tying Product baseline + requirement identity to implementation revision and passing verification.
DeploymentEvidence contract	Provider-neutral DEV/STA/PROD artifact/deployment provenance used to calculate environment state and RELEASED.
Generated MkDocs workspace	Temporary/build output that joins Product content, engineering docs, status, and implementation facts without writing progress back into Product source.

14. Reference examples¶

Example A — New payment story before code exists. In ENG Mode, PH08-05 is selected while DragonPay has no implementation mapping. dp-eng resolves PH-08, STD-01, ENG-01, Product ADRs, and the root development instructions. Work becomes IN_PROGRESS; Claude proposes an implementation plan, the engineer reviews it, Claude implements tests/code/mapping locally and self-validates, the engineer reviews the actual implementation, and — once accepted — the engineer merges it into the configured authoritative Development branch. That merge is what makes the requirement IMPLEMENTED, not Claude's self-validation or a plan being accepted. CI then runs against the accepted implementation and derives VERIFIED. No Product requirement is modified during this ENG Mode workflow.

Example B — Refactor one month after release. PH08-05 is already RELEASED. Its implementation moves from services/execution/send.ts to packages/connector-runtime/send.ts. The current mapping and tests are updated through a dev-repo PR. Historical PH08-05 requirement snapshot, original verified commit, and first PROD release remain unchanged. Current conformance remains PASS if the applicable verification continues to pass.

Example C — Later Product behavior change. A new PH08-14 requirement changes behavior originally introduced by PH08-05. Product-authoring workflow records PH08-14 modifies PH08-05. PH08-05 remains RELEASED historical evidence. Implementing PH08-14 resolves both the new behavior and protected PH08-05 contract so Claude understands what must change and what must remain.

Example D — Tool choice from zero. ENG01-06 requires messaging but no account/service exists. Context shows the DragonPay event, outbox, retry, security, and operational constraints. Claude compares viable Azure options and drafts an ADR. Human approval makes the decision APPROVED. Claude then produces account/bootstrap prerequisites, Terraform/CI/application scaffolding, tests, and validation. The capability becomes ESTABLISHED only after the minimum usable path works.

Example E — Existing MkDocs evolves. The Product repo already builds an executive-readable MkDocs site. ENG-02 work does not replace it. The build later checks out configured dev repos, runs dp-eng, and adds implementation/status/engineering sections while Product pages remain sourced from the Product repository and generated progress remains build-only.

15. Implementation stories¶

The stories below are implementation contracts for building ENG-02 incrementally. Each story should be small enough to hand to Claude independently. The current ENG-02 document, ENG-01, STD-01, applicable Product artifacts, and existing implementation from prior ENG02 stories remain authoritative context. Prefer simple, inspectable implementation over autonomous inference.

ENG02-01 — Establish repository and Product-baseline configuration¶

Objective: Define how a development repository locates the Product repository, pins the exact Product Git revision used for development, and identifies its own authoritative Development branch.

Inputs / Preconditions

ENG-02 authority rules and Product/dev repository separation.
A local or configured Product repository path/reference and Git repository accessible to the development workspace.

Required Behavior

Create a versioned configuration schema under .dragonpay/config.yaml per §6's config shape: repository_id, path, baseline_commit, remote (optional).
Record Product repository identity/reference and explicit baseline Git commit; remote is optional for local development and required only once the Product repository is consumed by CI, another machine/contributor, or an environment where the configured local checkout can't be assumed.
Also record the configured authoritative Development branch, e.g. development.authoritative_branch: main — during the local-only bootstrap period this may name a local Git branch; once a shared remote repository exists, it should normally name the protected authoritative/default integration branch there. This is what §7's IMPLEMENTED definition and every downstream status calculation resolve against.
Provide baseline show and explicit baseline advance behavior; never automatically follow Product HEAD.
Validate that the pinned commit exists and the Product repository is readable at the configured path.
Do not assume a development repository corresponds to one service or that future services require separate repositories.

Writes / Outputs

Configuration schema and example, including development.authoritative_branch.
dp-eng baseline show / baseline advance behavior or equivalent library/CLI surface.
Tests for missing repo, invalid commit, unchanged baseline, and explicit advancement.
Developer documentation for configuring a fresh local dev repo.

Acceptance

The same dev commit + config resolves the same Product baseline.
New Product commits do not change the dev baseline until an explicit advance occurs.
An invalid Product baseline fails before context/traceability operations proceed.
A config with remote: null is valid for local development; validation does not require a remote to be set.
development.authoritative_branch is present and resolvable before any status calculation depends on it (§7, ENG02-07).

ENG02-02 — Build deterministic Product document index¶

Objective: Create a rebuildable index that resolves stable Product document and requirement IDs without a separate metadata database.

Inputs / Preconditions

Pinned Product baseline from ENG02-01.
Product Markdown/document files containing stable Document IDs and implementation-story IDs.

Required Behavior

Scan configured Product documentation paths deterministically.
Extract Document ID, requirement/story ID, title, parent document, source path, heading/anchor/section range, explicit references, and Product ADR entries where available.
Derive requirement class (PRODUCT/FOUNDATION/STANDARD, §2) from the ID's document-family prefix rather than requiring manual tagging.
Reject duplicate stable requirement IDs.
Do not mutate Product source while indexing.
Index output must be rebuildable from Product Git content alone plus approved sidecar metadata.
The index is a reproducible derived artifact (§11): built or refreshed per dev-repo/context operation from the configured pinned checkout, never a shared mutable store, never committed.

Writes / Outputs

Generated Product index in a build/cache location.
Programmatic lookup by requirement ID.
Index validation/tests with duplicate, missing, and malformed fixtures.

Acceptance

Given PH08-05, tooling resolves its source Product document and containing epic deterministically.
Repeated indexing of the same Product commit yields equivalent IDs/locations.
Duplicate IDs fail validation rather than selecting one arbitrarily.
STD01-12 resolves to STD-01 with class STANDARD; ENG01-21 resolves to ENG-01 with class FOUNDATION; PH08-05 resolves to PH-08 with class PRODUCT.

ENG02-03 — Implement Product requirement relationship metadata¶

Objective: Support Product evolution relationships without requiring large metadata blocks inside every Product story.

Inputs / Preconditions

Product index from ENG02-02.
Product-side metadata/requirement-relations.yaml or equivalent approved sidecar path.

Required Behavior

Support only modifies, supersedes, and retires initially.
Validate that source and target requirements exist at the pinned Product baseline.
Reject self-reference and malformed/cyclic relationships that make current contract resolution ambiguous. Reject more than one requirement declaring a supersedes relationship against the same target — a requirement may be the target of at most one supersedes declaration. Reject a target that is simultaneously the target of both a supersedes declaration and a retires declaration — the two are mutually exclusive for the same target.
Keep sidecar metadata Product-owned; development workflow reads it but does not edit it.
Expose relationships through the Product index/API.

Writes / Outputs

Relationship schema and parser.
Index enrichment with incoming/outgoing relationships.
Validation fixtures/tests.

Acceptance

A new requirement that modifies PH08-05 is discoverable deterministically.
A relationship to a nonexistent requirement fails validation.
Development tooling does not need Product Markdown edits merely to add non-derivable relationship metadata.
A requirement targeted by more than one supersedes declaration fails validation.
A requirement targeted by both a supersedes declaration and a retires declaration fails validation.

ENG02-04 — Implement traceability manifest schema¶

Objective: Define one current implementation/traceability record per requirement owned by a development repository.

Inputs / Preconditions

ENG-02 traceability model.
Product lookup/index available.

Required Behavior

Use one manifest per requirement under .dragonpay/requirements/<ID>.yaml or equivalent versioned path.
Support requirement_id, Product baseline, mutable work state, implementation files/packages, mapped tests, implementation ADRs, required deployment units, and an attention_items list (zero or more references to separately-stored attention-item records — never a single blocker field, since a requirement may have multiple simultaneous issues).
Do not provide developer-authoritative IMPLEMENTED, VERIFIED, or RELEASED fields. The schema's mutable work.state field accepts only NOT_STARTED, IN_PROGRESS, and BLOCKED — IMPLEMENTED is derived externally, from the authoritative-branch acceptance event (§7), never written into this manifest directly.
Validate Product requirement existence against the pinned baseline.
Validate referenced local implementation/test paths when present.
Design schema so a future owning manifest can reference evidence from other repositories without duplicating status ownership.
A single schema supports all three requirement classes; lifecycle rules vary by class (§2) rather than requiring three separate schemas.

Writes / Outputs

Versioned traceability schema.
Parser/validator.
Example manifests and test fixtures.

Acceptance

Invalid work states, unknown requirement IDs, malformed attention-item references, and nonexistent mapped local files fail validation.
A valid NOT_STARTED manifest requires no implementation mapping.
The schema cannot be used to manually claim IMPLEMENTED, VERIFIED, or RELEASED.
A manifest can reference more than one attention item at once.

ENG02-05 — Implement traceability update and refactor behavior¶

Objective: Allow current implementation mappings to evolve safely before and after release while preserving historical evidence.

Inputs / Preconditions

Traceability schema from ENG02-04.
Synthetic or later verification/release evidence fixtures.

Required Behavior

Permit normal dev-PR updates to work state, implementation paths/packages, tests, implementation ADRs, required deployment units, and blockers.
Treat current mapping as mutable even after a requirement is released.
Store/generated verification/release history separately from mutable current mapping.
Updating or moving source/test mappings must not delete or rewrite prior verification/release evidence.
Provide validation that removed paths are either remapped or intentionally no longer part of the current implementation.

Writes / Outputs

Update library/CLI behavior and tests.
Documented rules for mutable vs historical fields.

Acceptance

A released PH08-05 can move from one source path to another while its first-release evidence remains byte-for-byte unchanged.
A refactor does not regress historical RELEASED status.

ENG02-06 — Implement released-requirement baselining guard¶

Objective: Protect the exact Product behavioral contract that first reached PROD without treating normal Product growth as staleness.

Inputs / Preconditions

Product index/relationship metadata.
Verification and synthetic release evidence sufficient to identify a first release.

Required Behavior

At first RELEASED, record the Product commit and exact content hash/snapshot identity for the requirement story block.
Retain first verified implementation revision and qualifying first PROD release evidence.
Validate future pinned Product baselines against baselined requirement content.
A material edit to a baselined requirement block must fail validation unless the historical Product revision is being viewed; later behavior must be represented by a new related requirement.
Do not flag unrelated Product-repository changes as staleness for the released requirement.

Writes / Outputs

Requirement-baseline evidence model.
Baselined-content validator and fixtures.

Acceptance

Changing acceptance behavior inside a baselined story is detected.
Adding a new requirement that modifies PH08-05 does not mark PH08-05 stale.
Unrelated changes elsewhere in Product docs do not invalidate PH08-05.

ENG02-07 — Implement work and effective status calculation¶

Objective: Separate mutable implementation work claims from system-derived verification/release status, across all three requirement classes.

Inputs / Preconditions

Traceability manifests.
Verification/release evidence interfaces may initially use fixtures.

Required Behavior

Support mutable work states NOT_STARTED, IN_PROGRESS, BLOCKED for PRODUCT-class requirements (§7), and UNRESOLVED, PROPOSED, APPROVED, BLOCKED for FOUNDATION-class requirements (§4). IMPLEMENTED is not a mutable, developer-declared state for PRODUCT-class requirements — derive it only from the configured authoritative Development branch's acceptance event (§7's "Authoritative Development branch"), never from an edited manifest field.
Support blocker categories REQUIREMENT_AMBIGUITY, REQUIREMENT_CONFLICT, MISSING_PRODUCT_DECISION, MISSING_ENGINEERING_DECISION, EXTERNAL_DEPENDENCY, applicable to either class.
Derive effective status deterministically; developer metadata alone cannot produce IMPLEMENTED, VERIFIED, RELEASED, or ESTABLISHED.
A CI failure after IMPLEMENTED does not revert IMPLEMENTED — the requirement stays IMPLEMENTED with failed verification (§7); status calculation must not reinterpret a failed build as "never accepted."
current_conformance (PASS/FAIL/UNKNOWN) is calculated only for requirements that have reached RELEASED at least once — it is not a generic "did the last CI run pass" flag, and must not be populated for a not-yet-released IMPLEMENTED requirement whose verification is merely pending or failing (§7).
BLOCKED requires reason/context and may apply before release/establishment when correct implementation cannot proceed.
STANDARD-class requirements have no independent status calculation — they are referenced, not tracked, per §2.
Do not use percentage-complete status.
READY/READY_WITH_ISSUES/BLOCKED (§7) are preflight outcomes calculated separately from this work/effective status model — they are never persisted as a work.state value.

Writes / Outputs

Status calculator/library, aware of requirement class.
dp-eng status initial output.
Unit tests for every work/evidence combination, across both PRODUCT and FOUNDATION classes, including CI-fails-after-IMPLEMENTED.

Acceptance

Changing YAML alone cannot produce IMPLEMENTED, VERIFIED, or RELEASED; changing YAML alone from APPROVED cannot produce ESTABLISHED.
Malformed BLOCKED records fail validation.
Status calculation is deterministic from the same manifest/evidence.
A requirement merged to the authoritative branch shows IMPLEMENTED even before CI runs; a subsequent CI failure leaves it IMPLEMENTED, not reverted, and does not populate current_conformance since it was never RELEASED.

ENG02-08 — Implement current conformance tracking¶

Objective: Show whether current implementation still satisfies released/current Product contracts without rewriting release history.

Inputs / Preconditions

Released requirement fixtures/history.
Current mapped verification/conformance evidence or absence of evidence.

Required Behavior

Derive current conformance as PASS, FAIL, or UNKNOWN.
RELEASED remains a historical milestone and never regresses because current conformance changes.
PASS requires current applicable verification evidence to succeed for the current implementation/effective requirement contract.
FAIL is reported when applicable conformance verification fails.
UNKNOWN is used when current evidence is missing or cannot prove conformance.

Writes / Outputs

Conformance calculator and status integration.
Tests for released+PASS, released+FAIL, released+UNKNOWN.

Acceptance

A later failing test can produce RELEASED + current conformance FAIL.
Fixing the implementation can return conformance to PASS without creating a new historical release status.

ENG02-09 — Define environment and deployment evidence contract¶

Objective: Define provider-neutral evidence used to represent DEV/STA/PROD existence and deployment provenance from a zero-state starting point.

Inputs / Preconditions

ENG-02 environment/release rules.
No specific CI/CD vendor is required.

Required Behavior

Support canonical environments DEV, STA, PROD.
Represent environment states UNPROVISIONED, PROVISIONED, AVAILABLE, UNAVAILABLE.
Define DeploymentEvidence containing environment, deployment_unit, repository, source_commit, artifact_version when available, deployment_id, deployed_at.
Keep environment provisioning state separate from deployment-unit deployed/not-deployed state.
Define how evidence proves a deployed artifact contains a verified implementation revision; V1 may use exact Git commit or descendant/ancestry when valid.
If evidence cannot prove inclusion, do not claim deployment for the requirement.

Writes / Outputs

DeploymentEvidence schema/interface.
Synthetic evidence provider/fixtures.
Status display support using fixtures.

Acceptance

With no environment evidence, DEV/STA/PROD can correctly show UNPROVISIONED.
Synthetic evidence can deterministically prove or fail deployment for a verified revision.
The contract does not require GitHub Actions, Azure DevOps, or another vendor.

ENG02-10 — Implement system-derived release calculation¶

Objective: Determine RELEASED only from verification plus qualifying PROD deployment evidence.

Inputs / Preconditions

VERIFIED evidence.
Required deployment_units from the current traceability manifest.
DeploymentEvidence from ENG02-09.

Required Behavior

A requirement is RELEASED only when it is VERIFIED and every required deployment unit has qualifying PROD evidence containing the verified implementation.
Partial deployment across required units does not release the requirement.
At first release, persist immutable first-release evidence.
Later PROD deployments append history/current state but do not rewrite first-release evidence.
No developer/Claude command may directly mark a requirement RELEASED.

Writes / Outputs

Release calculator and evidence persistence interface.
Status integration and fixtures for one/multiple deployment units.

Acceptance

A verified requirement with only DEV/STA evidence remains VERIFIED.
A two-unit requirement with one PROD unit remains VERIFIED.
Qualifying PROD evidence for all units derives RELEASED automatically.

ENG02-11 — Implement deterministic context resolver V1¶

Objective: Generate bounded, inspectable Product + implementation context for one requirement ID.

Inputs / Preconditions

Product baseline/index/relationships.
Traceability manifest and development CLAUDE.md (established by ENG02-14 — see §16 for sequencing).
Existing mapped code/tests/ADRs/docs when present.

Required Behavior

Load the entire containing Product epic for V1.
Include the selected requirement and its direct modifiers (requirements that declare a modifies relationship against it; discovered one hop only, never a modifier of a modifier).
If the selected requirement, or any of its direct modifiers, is the target of a supersedes declaration, follow the chain of requirements that declare supersedes against it (§5) to identify its current replacement, terminating at a requirement that nothing else declares supersedes against — the same resolution applies identically to the selected requirement and to each direct modifier, never recursing beyond one such resolution per requirement. If a modifier is superseded, include its current replacement as the current form of that modification, not the stale modifier — this is ordinary context assembly, not the implementation-target confirmation gate below, which applies only to the selected requirement. If a modifier is retired with no replacement, that modification is no longer current and is not included. If the selected requirement is directly retired, or its own supersedes chain terminates at a requirement that is itself retired, it has no current implementation target.
Include STD-01, ENG-01, applicable Product ADRs, and resolvable direct references.
Include development CLAUDE.md, current traceability, mapped implementation, mapped tests, implementation ADRs, relevant human engineering docs, and relevant generated facts.
Do not recursively load the complete transitive dependency tree — the supersedes chain resolution above is the one narrow exception, bounded strictly to identifying a current replacement (for the selected requirement or a direct modifier), never a general traversal.
Allow context expansion later/on demand without changing initial deterministic selection.
Run preflight validation and report authoritative conflicts as BLOCKED/diagnostics rather than selecting one interpretation. dp-eng context <ID> always succeeds and reports a diagnostic for a superseded or retired selected requirement rather than failing. Substantive ENG Mode implementation, however, is separately gated: a clean supersede requires the current replacement to be explicitly selected/confirmed as the implementation target before implementation proceeds — implementation must not continue against the superseded requirement itself, though dp-eng context <old-ID> may still succeed for inspection/historical purposes; a requirement with no current implementation target (retired directly, or terminating at a retired requirement) is BLOCKED as MISSING_PRODUCT_DECISION (§7). Malformed relationship topology (more than one requirement superseding the same target, a supersedes cycle, or a target simultaneously superseded and retired) is rejected earlier, at Product relationship validation (ENG02-03) — the context resolver never encounters it.

Writes / Outputs

dp-eng context .
.dragonpay/generated/context//context-manifest.yaml.
Convenience context-bundle.md.
Resolver tests using representative PH/ENG fixtures.

Acceptance

Same Product/dev revisions produce equivalent context-selection manifest.
Unrelated epics do not appear merely because they exist.
The context manifest records why each source was included.
A requirement's direct modifiers are discovered one hop only, never a modifier of a modifier.
A direct modifier that has itself been superseded is resolved to its current replacement, not included as its stale superseded form.
A direct modifier that has itself been retired with no replacement is not included — that modification is no longer current.
A superseded requirement's context resolution identifies its current replacement by following the chain of supersedes declarations to termination.
A retired requirement's resolution reports that it has no current implementation target — whether directly retired, or because its supersedes chain terminates at a requirement that is itself retired.
dp-eng context <ID> always succeeds with a diagnostic for a superseded or retired selected requirement rather than failing; substantive ENG Mode implementation is separately gated — the current replacement must be explicitly selected/confirmed as the implementation target for a clean supersede (never continuing against the superseded ID), BLOCKED as MISSING_PRODUCT_DECISION when no current implementation target exists.

ENG02-12 — Add implementation-impact protection¶

Objective: Ensure Claude sees existing Product contracts that share the implementation area it is about to change.

Inputs / Preconditions

Context resolver V1.
Requirement-to-file/package mappings from traceability manifests.

Required Behavior

When requested work has mapped or planned target implementation path(s), identify other requirements whose traceability explicitly maps the same implementation path(s). Package/module-level or other implicitly-shared-unit matching is deferred until an authoritative package/module model exists — V1 matches only on explicitly recorded implementation-path overlap.
Add those requirements to context as protected existing contracts.
Do not treat protected requirements as new implementation work unless explicitly selected; they are constraints to preserve.
If a planned implementation area has no mapping, permit code discovery but record that protection coverage may be incomplete.

Writes / Outputs

Protected-existing-requirements section in context manifest/bundle.
Tests for shared and unrelated implementation areas.

Acceptance

Changing code shared by PH08-05 and PH08-06 causes both contracts to be visible when implementing a new requirement that touches the same code.
Unrelated mappings do not inflate context.
Two requirements mapped to different files within the same package/module, with no shared explicit file-path mapping, are not treated as protected against each other in V1.

ENG02-13 — Implement repository/context validation CLI¶

Objective: Provide one deterministic command suitable for local use and CI to validate ENG-02 integrity.

Inputs / Preconditions

ENG02-01 through ENG02-12 artifacts as available.

Required Behavior

Implement dp-eng validate as the single, common validation entry point, established early.
Validate Product baseline/repository, duplicate IDs, broken references, requirement relationships, traceability schema, local mapped paths, attention-item reference shape, and the configured development.authoritative_branch from day one.
Return non-zero exit on validation failure with actionable diagnostics.
Do not silently repair Product source during development validation.
Incremental validation. dp-eng validate implements the validations supported by the capabilities available at the point it's first built; it is not required to validate baselined-requirement mutation (ENG02-06), context-resolution errors (ENG02-11), attention-item status-evidence consistency, or deployment evidence (ENG02-09) before those capabilities exist. Attention-item validation is shape-only for as long as no authoritative attention-item model/source exists; referential validation — confirming a reference resolves to a real record — is added once that source becomes available, not claimed before then. Later ENG02 stories extend this same command's validations with applicable checks as new metadata, context, baselining, verification, and deployment capabilities become available — dp-eng validate is one command that grows, not a command deferred until the whole system is complete.

Writes / Outputs

CLI command and machine/human-readable diagnostics.
Comprehensive fixture suite for the validations implemented so far.

Acceptance

CI can use one command to reject invalid traceability/context changes, from the earliest V1 build onward.
Diagnostics identify the requirement/artifact and rule that failed.
Adding ENG02-06/09/11's validations later extends dp-eng validate, not a new command.

ENG02-14 — Establish Claude Code operating-mode instructions and shared workflow definition¶

Objective: Make PM Mode / ENG Mode / Admin Mode (§3), engineer review, scoped blockers, and source-control-driven status the normal AI-assisted development operating model without requiring the architecture to be re-explained in each conversation, via one canonical shared Claude Code workflow definition available identically to sessions started from either DragonPay repository, with each mode explicitly resolving its authoritative target repository before acting.

Inputs / Preconditions

ENG-02 standard (§3, §7, §12) and dp-eng context/validate capabilities available so far.
Development repository root.
A mechanism for defining and consuming one canonical shared Claude Code configuration (Skills, subagents, hooks) across repositories is available in the installed Claude Code version.

Required Behavior

Create concise root CLAUDE.md instructions derived from ENG-02, covering all three operating modes: PM Mode, ENG Mode, and Admin Mode.
Require the user to invoke a mode explicitly (e.g. "ENG Mode — implement PH08-05," "Admin Mode — refresh DragonPay and tell me what needs attention") rather than Claude inferring or switching modes on its own; Claude may recommend a different mode but must not autonomously act in it (§3).
State that ENG Mode covers both PRODUCT-class and FOUNDATION-class implementation plus foundation/ADR drafting — "ENG Mode" is not synonymous with the FOUNDATION requirement class (§2, §3).
Require Product implementation work to start from explicit requirement IDs and resolved context.
Treat Product repo as authoritative read-only input in ENG Mode; Product edits happen only in an explicitly invoked PM Mode action.
Require inspection/reuse of shared components, mapped implementation, protected existing requirements, and active ADRs before inventing new patterns.
Require acceptance behavior to have verification coverage.
Require Product ambiguity/conflict/missing decisions to become BLOCKED (scoped to the affected work, §7) and recorded as an attention item, rather than inferred or silently worked around.
Prohibit weakening tests/requirements simply to make generated code pass.
Require the two-checkpoint engineer review (plan review, then implementation/behavior review) before source-control acceptance, and require Claude to present the review package (§12.B) after self-validation.
State plainly that Claude may not claim engineer acceptance, mark work IMPLEMENTED by editing metadata, or approve its own PR — IMPLEMENTED is derived only from acceptance into the configured authoritative Development branch (§7).
Require mutable traceability updates (work state, implementation paths/tests/ADRs, attention items) when they change.
Point to ENG-02 for the full standard rather than duplicating the entire document in CLAUDE.md.
Create one canonical shared Claude Code workflow definition (PM/ENG/Admin Skills, the Plan Critic subagent, required hooks) available identically to sessions started from either dragonpay-product or dragonpay-dev — never duplicated, independently-maintained per-repository copies.
Keep each repository's own CLAUDE.md small: repository-local authority/context only, plus how to reach the shared workflow definition — never a full restatement of PM/ENG/Admin procedures or the Guardrail Catalog.
Require every PM/ENG/Admin action to explicitly and deterministically resolve the authoritative repository or repositories it requires before performing any work — never assumed from the session's current working directory. Ambiguous or unverifiable resolution fails the action before any file is modified.
Leave the exact repository-resolution storage/mechanism to implementation design, not fixed by this requirement — but it must (a) have a single, clearly defined responsibility distinct from .dragonpay/config.yaml (which governs the Development→Product baseline-pinning relationship specifically, not general-purpose repository discovery), so the two are never competing sources of truth for the same fact, and (b) fail closed rather than guess when resolution is ambiguous.
Require substantive ENG Mode work to occur under Claude Code's native plan-review precondition (§ENG02-21), enforced via the shared workflow's hooks.
The canonical shared workflow definition supports mode-specific review subagents and review procedures established by later ENG requirements.

Writes / Outputs

The canonical shared Claude Code workflow definition (V1: a Claude Code plugin — PM/ENG/Admin Skills, the Plan Critic subagent, hooks — published from its own versioned source, available identically to sessions started from either repository).
Root CLAUDE.md in each repository, kept small per Required Behavior.
The repository-resolution mechanism (exact form is implementation design).
Example "ENG Mode — implement ," "PM Mode — incorporate into ," and "Admin Mode — refresh" workflow documentation.

Acceptance

A fresh Claude Code session can determine how to begin PH08-05 in ENG Mode without conversational explanation of the repository authority/context model.
The instructions make clear that entering ENG Mode does not grant Product-write authority, and that only an explicit PM Mode invocation does.
The instructions state that no mode switch happens automatically, matching §3's locked principle.
All three modes are invokable from a session started in either DragonPay repository, using the same canonical workflow definitions with no duplicated per-repository configuration and no session restart required; each mode resolves and operates against its authoritative target repository regardless of the session's starting point.
Any PM/ENG/Admin action fails, before modifying files, when it cannot deterministically resolve its required repository/repositories.
The repository-resolution mechanism's relationship to .dragonpay/config.yaml is explicit and non-competing.

ENG02-15 — Implement foundation/ADR workflow support¶

Objective: Use the same context and traceability principles for unresolved ENG foundation decisions and 0-to-1 setup.

Inputs / Preconditions

ENG-01 engineering story/need.
Product/STD/ENG constraints and existing Product ADRs.

Required Behavior

Support decision states UNRESOLVED, PROPOSED, APPROVED, ESTABLISHED.
Provide context assembly for an ENG decision including relevant constraints and existing ADRs.
Allow Claude to produce decision package/ADR draft but require explicit human approval before APPROVED.
Support BOOTSTRAP_REQUIRED checkpoint with human-action checklist.
After approval/bootstrap, allow normal dev-repo scaffolding implementation and establishment validation.
Do not assume cloud/vendor/tool accounts already exist.

Writes / Outputs

Foundation decision metadata/interface as needed.
Decision/ADR workflow documentation.
Bootstrap checklist structure.
Establishment evidence/validation convention.

Acceptance

An unresolved messaging/tool decision can be evaluated without being treated as already approved.
Completing bootstrap alone does not establish a capability until required validation passes.
Claude cannot promote its own recommendation to APPROVED.

ENG02-16 — Aggregate Product and implementation content into MkDocs¶

Objective: Evolve the existing MkDocs site into the living DragonPay Product + engineering view without replacing the executive/Product experience already built.

Inputs / Preconditions

Existing Product MkDocs source/configuration.
Configured Product/dev repositories and dp-eng generated data.

Required Behavior

Preserve Product pages as sourced from the Product repository.
Preserve the existing curated Engineering Architecture pages exactly as built; add canonical requirement-reference pages alongside them per §9's canonical-vs-curated distinction — don't make either the only physical representation of a requirement.
Add generated implementation/status sections where applicable: work/effective status, conformance, Product baseline, implementation mappings, tests, implementation ADRs, modifying/superseding requirements, DEV/STA/PROD state.
Add an Attention Required view (Product issues, missing decisions, partial blockers, external prerequisites), a Foundation view (UNRESOLVED/PROPOSED/APPROVED/ESTABLISHED decisions and setup state), and an Engineering view (current IN_PROGRESS/IMPLEMENTED/BLOCKED requirements and mappings) — driven by dp-eng refresh (§11), Admin Mode's entry point.
Keep authoritative Product content visually/semantically distinct from implementation evidence.
Build by reading/checking out configured repos and generating temporary/build workspace content; do not write generated progress back into Product source.
Allow executive/Product views to remain concise while engineering detail remains available through dedicated/detail pages.
Because MkDocs is already running for DragonPay, this story may start incrementally earlier than its position in §16's sequence suggests, wherever a canonical page is useful before the rest of ENG-02 exists.

Writes / Outputs

MkDocs aggregation/build integration, invoked via dp-eng refresh.
Generated requirement status/detail pages or sections, and the Attention Required/Foundation/Engineering views.
Documentation explaining local/CI build inputs.

Acceptance

Existing Product/executive content remains readable.
A PH requirement page can show current implementation/status evidence without changing its Product source Markdown.
Rebuilding the site from the same source/evidence revisions produces equivalent joined content.

ENG02-17 — Generate engineering implementation catalogs with provenance¶

Objective: Expose reusable implementation facts to humans and Claude without creating a second requirements source.

Inputs / Preconditions

Development source, schemas, Terraform, tests, and/or other deterministic implementation inputs.

Required Behavior

Generate initial catalogs only where deterministic source exists; candidate catalogs include API/OpenAPI, events, persistence/schema, packages/modules, Terraform/infrastructure, tests/coverage, and deployments.
Every generated artifact identifies source repository/commit and generator/source type; include generated_at where practical.
Generated content describes implementation facts, not Product rules.
Prefer regeneration over manually maintained duplicate Markdown.
Make catalogs usable by MkDocs and context resolver.

Writes / Outputs

One or more initial generated catalogs and provenance schema/convention.
Integration tests against fixture repositories.

Acceptance

A generated page clearly identifies its implementation source revision.
Changing source and regenerating updates facts without requiring manual prose edits.
Generated facts cannot override Product context in resolver authority.

ENG02-18 — Integrate CI verification evidence¶

Objective: Move VERIFIED from an implementation claim to objective automated evidence tied to Product and code revisions.

Inputs / Preconditions

CI platform may be selected through ENG-01; if not yet available, define adapter/interface and fixtures first.
Traceability/test mappings and dp-eng validate.

Required Behavior

On applicable PR/default-branch CI, validate ENG-02 metadata/context integrity.
Run required mapped/acceptance verification according to repository testing standards, against work already IMPLEMENTED (accepted into the authoritative Development branch, §7) — CI evidence advances already-accepted work to VERIFIED, it does not itself create IMPLEMENTED.
Produce VerificationEvidence tying requirement ID, Product baseline/content identity, code commit, and passing verification result.
A failed build after acceptance leaves the requirement IMPLEMENTED with failed verification — do not treat CI failure as reverting or invalidating the source-control acceptance (§7).
Prevent manually authored YAML from substituting for verification evidence.
Allow CI provider integration to be implemented behind a provider-neutral evidence contract.

Writes / Outputs

VerificationEvidence schema/provider integration.
Status-calculation integration.
CI documentation and fixtures.

Acceptance

A requirement reaches VERIFIED only from qualifying evidence.
A failed required verification cannot produce VERIFIED even when work.state=IMPLEMENTED.
A failed build after acceptance leaves the requirement IMPLEMENTED, not un-accepted, and does not populate current_conformance (which is reserved for already-RELEASED requirements, §7).

ENG02-19 — Integrate environment/deployment evidence¶

Objective: Connect the selected CI/CD/deployment platform to ENG-02 environment state and system-derived release.

Inputs / Preconditions

DeploymentEvidence contract from ENG02-09.
Actual CI/CD/deployment tooling selected/established through ENG-01.

Required Behavior

Capture provider deployment evidence and normalize it to ENG-02 contract.
Track DEV/STA/PROD deployment provenance by deployment unit.
Update status views/release calculation from objective evidence.
Do not require Product source changes when deployment state changes.
Retain deployment history sufficient to explain first release and current environment state.

Writes / Outputs

Deployment evidence adapter/integration.
Environment/current release view.
MkDocs/status integration.

Acceptance

Deploying all verified required units to PROD derives RELEASED automatically.
Deploying only DEV or STA does not.
Current PROD evidence remains inspectable after later releases.

ENG02-20 — Add optional discovery enhancements¶

Objective: Improve retrieval only after deterministic V1 is operational and actual usage shows a need.

Inputs / Preconditions

Working deterministic Product index, traceability, context resolver, and real usage feedback.

Required Behavior

Potential enhancements may include semantic code search, semantic Product discovery, dependency-graph enrichment, and more precise section-level context extraction.
Semantic discovery may suggest additional context but must not determine Product authority, requirement precedence, or silently resolve conflicts.
The deterministic resolver must remain fully usable with semantic capabilities disabled.
Add complexity only to solve observed context-quality/scale problems.

Writes / Outputs

Optional discovery modules and measured evaluation if/when justified.

Acceptance

Disabling optional semantic functionality does not break requirement resolution, authority, validation, status, or traceability.

ENG02-21 — Engineering Guardrail Framework¶

Objective: Establish a repeatable, Product-controlled guardrail framework for Claude-assisted ENG work that prevents silent scope expansion, undocumented material assumptions, duplicate/false models, inaccurate defaults, contradictory-evidence normalization, approximate requirement satisfaction, hidden dependencies, and unsafe continuation from invalid prerequisites — mechanically requiring Claude Code's native plan-review precondition and a structurally validated plan before engineer approval, while leaving the guardrails themselves free to evolve through an authoritative, separately-versioned Guardrail Catalog without requiring this story to be reimplemented.

Inputs / Preconditions

ENG-02 operating-mode rules are established (§3, §19).
ENG02-14's canonical shared workflow definition and repository-resolution mechanism are available.
The Guardrail Catalog exists as its own Product document.
A selected PRODUCT-class or FOUNDATION-class requirement can be resolved to its authoritative context.
The engineer remains responsible for reviewing the implementation plan and completed implementation.

Once ENG02-12 is available, the protected-existing-requirements data it produces becomes an input to ENG02-21's implementation planning and Scope Reconciliation reporting. ENG02-21 does not depend on ENG02-12 for its initial operation. ENG02-21 can initially perform this review using the authoritative context available at the time. ENG02-12 later makes the identification of shared implementation impact more deterministic.

Required Behavior

Before implementation, ENG Mode must:

map the selected requirement's objective and acceptance behavior to the proposed implementation;
identify applicable Product, STD, ENG, and ADR constraints;
identify functionality explicitly owned by later requirements;
classify material findings as REQUIRED_NOW, IMPLEMENTATION_DETAIL, DEFERRED_TO_EXISTING_STORY, MISSING_ENGINEERING_DECISION, or PRODUCT_ISSUE;
include a Deferred / Not Implemented section in the plan;
include an Assumptions / Decisions Requiring Review section, explicitly stating None when no material undocumented assumptions are identified;
surface material undocumented engineering choices for review before encoding them;
surface missing/ambiguous Product behavior rather than resolve it through code;
continue safely implementable work when issues do not actually block the affected work;
load the Guardrail Catalog (baseline-pinned via dp-eng, §11), filter it to guardrails applicable to ENG or ALL, and determine which are relevant to the current action using each guardrail's Applies When guidance;
perform a Plan Integrity Review evaluating every applicable, relevant Catalog guardrail against the selected requirement, the current implementation sequence, and the available authoritative context (§19);
perform a distinct Plan Critic pass before the plan is presented for engineer approval, independently evaluating the same applicable Catalog guardrails, challenging rather than expanding the plan (§19).

ENG Mode must not:

implement a later requirement merely because doing so is convenient;
treat examples, placeholders, legacy artifacts, existing code, or current file conventions as authority for undefined semantics;
establish a reusable convention from an undocumented assumption without review;
weaken or reinterpret Product requirements to make implementation easier;
automatically change PM-controlled Product content;
persist, report, or encode a knowingly inaccurate state merely because the correct lifecycle, evidence model, or capability has not yet been implemented;
create a second durable representation of an existing concept without authoritative justification (§19);
interpret absence of data, artifacts, mappings, events, or evidence as a default state without authoritative support (§19);
invent precedence between contradictory evidence, or silently normalize a contradiction, merely to produce a deterministic result (§19).

Substantive ENG Mode work must occur under Claude Code's native plan-review precondition; if invoked while that precondition is not active, ENG Mode fails immediately with a clear instruction to enter it and retry — Claude must not silently continue and must not autonomously switch modes on the engineer's behalf.

Every substantive ENG plan must be assembled in the required structure (§19's Plan Review Summary, followed by the detailed plan) and validated for that structure — required sections present, each populated or explicitly stated as None — before it can be presented for engineer approval. This structural validation is deterministic and checks structure only; it never evaluates whether the plan's content is correct, sufficient, or reflects sound engineering judgment.

If the Guardrail Catalog cannot be loaded or fails structural validation, or applicable guardrails cannot be determined reliably for the current mode/action, substantive ENG work must not proceed.

After implementation, ENG Mode must perform scope reconciliation against the approved plan. The reconciliation must identify whether implementation:

exceeded the approved scope;
differed materially from the approved plan;
introduced new shared abstractions or contracts;
introduced persistent schema/data changes not identified in the plan;
implemented behavior assigned to another requirement;
introduced any material assumption not previously reviewed;
encoded a Product decision that should instead have been surfaced.

Writes / Outputs

ENG Mode planning/review instructions must produce the Mandatory ENG Plan Review Summary and the detailed plan structure defined in §19, and the Scope Reconciliation report structure defined in §19. These may initially be implemented through Claude instructions/templates rather than a new runtime service or workflow engine.

When the current story introduces or changes a durable model, a default/absence-semantics rule, or a state/evidence derivation, the plan must also explicitly address: Existing Model Reused / New Durable Model Introduced; Defaults and Absence Semantics; State / Evidence Invariants; and Contradictory Input Handling. These do not require four new long-form sections — they may be concise subsections or entries within Required Now, Implementation Details, Assumptions / Decisions Requiring Review, and Plan Critic Findings. Use None where not applicable.

V1 implements this via: a shared, versioned Claude Code plugin component — PM/ENG/Admin Skills (§ENG02-14), a read-only Plan Critic subagent, and a small hook set enforcing (a) the plan-review precondition via the session's active permission mode and (b) required plan structure by inspecting the current plan file before ExitPlanMode; and a dp-eng capability retrieving the baseline-pinned, mode-filtered Guardrail Catalog (exact command name not fixed by this requirement) and performing basic structural validation on it — rejecting malformed content, duplicate guardrail IDs, missing required fields, or invalid mode-applicability/enforcement-type values. This is catalog-input validation, not a guardrail-evaluation engine.

Acceptance

An ENG Mode plan explicitly identifies and removes or explicitly justifies capabilities belonging to later requirements rather than silently implementing them.
A material undocumented engineering choice is surfaced for human review before implementation.
A routine local/reversible coding choice can proceed without unnecessary approval.
A missing Product behavior is surfaced as a Product issue rather than resolved by implementation.
Every plan explicitly contains an assumptions section, including None when applicable.
A knowingly inaccurate substitute state is rejected rather than persisted.
The plan demonstrates the primary behavior through a concrete scenario.
At least one relevant failure, mutation, retry, refactor, stale-state, or partial-completion scenario is evaluated before coding.
A distinct Plan Critic pass is performed before engineer plan approval, evaluating the same applicable Catalog guardrails as the Plan Integrity Review, not just the items it happens to notice.
The critic challenges scope, authority, assumptions, and internal consistency without expanding the requirement.
Completed work is reconciled against the approved plan before engineer acceptance.
A newly introduced material assumption discovered during implementation is surfaced before source-control acceptance.
Non-blocking issues do not unnecessarily prevent safe implementation of unaffected work.
A plan introducing a durable representation demonstrates that the same concept is not already represented authoritatively, or explicitly justifies why both representations are required.
A plan does not introduce a convenience default for missing data without confirming that absence semantically maps to that default.
Known historical/current facts are not knowingly contradicted by a default derived from a missing artifact or record.
A state/evidence derivation identifies material impossible or contradictory input combinations.
Contradictory inputs are rejected, surfaced, or resolved only according to an established authoritative rule.
Claude does not invent evidence precedence or silently normalize contradictions solely to produce a deterministic result.
ENG Mode loads the Guardrail Catalog from the pinned Product baseline and evaluates only ENG/ALL entries applicable and relevant to the current work.
A new Catalog guardrail can be added through PM Mode without changing this story's implementation.
Substantive ENG Mode work started outside the required plan-review precondition fails immediately with a clear instruction, rather than proceeding.
An assembled plan missing required structure is not presented for engineer approval; structural validation never evaluates semantic correctness.
Substantive ENG work does not proceed when the Guardrail Catalog cannot be loaded/validated, or applicable guardrails cannot be reliably determined.
The dp-eng Catalog capability rejects malformed Catalog content (duplicate IDs, missing required fields, invalid mode-applicability/enforcement-type values) without attempting to evaluate guardrail semantics.
The guardrails require no new workflow service, database, risk-scoring system, approval system, separate AI product, generic invariant engine, or schema registry for V1, and do not require exhaustive formal modeling of every possible invalid state.

ENG02-22 — Extend traceability manifests for cross-repository implementation¶

Objective: Let a traceability manifest truthfully represent implementation that legitimately spans more than one repository — starting with ENG02-14's own canonical shared Claude Code workflow package, which by design lives outside any single Development repository — without inventing an ad-hoc path convention that merely happens to pass today's existence validation by accident.

Inputs / Preconditions

ENG02-04's traceability manifest schema is established.
ENG02-14's repository-resolution registry exists and is the established cross-repository discovery authority.
A concrete, already-surfaced gap: ENG02-14's own manifest cannot today truthfully list its shared workflow package's files.

Required Behavior

Generalize the repository-resolution registry ENG02-14 established to name additional repositories beyond the fixed Product/Development pair, each by a stable logical name and absolute path — extending the same registry, not introducing a second one.
Add an explicit, distinctly-named manifest field for cross-repository implementation references (repository name + path within it), separate from implementation.files — implementation.files's existing meaning (paths within this Development repository's own root) does not change, and every existing manifest remains valid unmodified.
Validate cross-repository entries the same way local ones are validated today — existence-checked at manifest-read time, resolved through the registry — never assumed to exist, never validated merely by accident of how a relative/absolute path happens to resolve.
dp-eng validate and dp-eng status incorporate the new field the same way they already incorporate implementation.files.
Once implemented, update ENG02-14's own manifest to truthfully list its shared workflow package's files via the new field — the actual fix for the gap that prompted this story.

Writes / Outputs

A registry-reading capability inside dp-eng itself (a new small module, following existing conventions like config.ts) — today the registry is read only by Claude Code Skill/hook instructions, not by any dp-eng code at all.
Manifest schema extension (new field, parser, validator) and its test suite, following existing dp-eng test conventions.
ENG02-14's manifest updated to use it.

Acceptance

A manifest can truthfully reference implementation in a registered non-Development repository via the new field, existence-validated through the registry.
implementation.files's existing meaning and validation are unchanged; every existing manifest remains valid without modification.
No second, competing repository registry is introduced.
ENG02-14's manifest, once updated, truthfully lists its shared workflow package's files instead of omitting them.

ENG02-23 — Product Change Review and Consistency Critic¶

Objective: Establish an independent review step for meaning-changing PM Mode Product updates so proposed changes are evaluated for local correctness, containing-epic consistency, relevant solution-wide consistency, conflicts, ambiguities, historical impact, and scoped improvement opportunities before Product-owner approval.

Inputs / Preconditions

ENG-02 operating-mode rules are established (§3).
ENG02-14's canonical shared workflow definition is available, extended to support mode-specific review subagents and review procedures.
The Guardrail Catalog exists (ENG02-21) and gains the PM-scoped entries this story adds.
A meaning-changing PM Mode draft exists to review — this story does not apply to cosmetic/typo-level fixes, which remain applied directly per the existing tiering.

Required Behavior

For every meaning-changing PM Mode draft:

the PM Skill creates the proposed Product change first;
PM identifies the directly changed requirements, the containing epic, explicit relationships/references, and other materially affected requirements/standards;
a read-only product-critic custom subagent reviews the proposed change — not just the pre-change Product source;
the critic receives bounded authoritative context (exactly the scope PM already identified above) rather than reading the entire Product repository;
the critic loads the Guardrail Catalog and evaluates every entry applicable to PM or ALL, organizing its review through three lenses — change (the specific proposed diff), epic (the containing epic's internal consistency), and solution (cross-epic/platform-wide consistency) — covering: proposed-change correctness; acceptance-criteria completeness; containing-epic consistency; relevant cross-epic/solution consistency; conflicting or duplicate requirements; unclear ownership; remaining ambiguity or missing decisions; released-history implications; modifies/supersedes/retires implications; implementation detail leaking into Product; scoped opportunities to simplify or improve the change.

The critic must not:

modify Product;
broaden the requested Product change merely because additional functionality would be useful.

Findings return to the PM Skill and are incorporated into the draft review package before Kevin approves anything. A material unresolved issue remains visible even when Claude proposes a resolution.

Writes / Outputs

A read-only product-critic subagent (no Product-write access), consumed by the pm-mode Skill — the PM-side counterpart to ENG02-21's Plan Critic, part of the same shared plugin package (ENG02-14), not a new runtime service.
Seven new Guardrail Catalog entries, Applies To: PM: Product Change Scope Discipline, Epic Consistency, Cross-Requirement Conflict, Requirement Ownership / Duplication, Released History Preservation, Implementation Detail Leakage, Product Acceptance-Criteria Completeness — evaluated by the Product Critic alongside any ALL-scoped entries.
The required PM review output, replacing today's plainer PM draft presentation:

Field	Content
Blocking Product Issues	None / findings
Epic Consistency Issues	None / findings
Cross-Epic / Solution Conflicts	None / findings
Ambiguities / Missing Decisions	None / findings
Improvement Opportunities	None / findings
Relationship / Historical Impact	None / findings
Product Critic Findings	None / findings
Recommended PM Action	APPROVE DRAFT \| REVISE DRAFT \| RESOLVE PRODUCT DECISION FIRST

Followed immediately below by the actual proposed Product edits. Recommended PM Action is advisory only and creates no approval state on its own, matching the same rule already established for ENG's Recommended Engineer Action (§19) — Kevin's explicit conversational approval remains the whole gate.

Acceptance

Every meaning-changing PM Mode draft is reviewed by the product-critic subagent before Kevin is asked to approve it; cosmetic/typo-level fixes are unaffected.
The critic reviews the proposed change itself, using bounded context (the directly affected requirements/epic/relationships), never an unbounded read of the whole Product repository.
The critic never modifies Product and never broadens the requested change merely because more would be useful.
Critic findings are incorporated into the review package presented to Kevin; a material unresolved issue remains visible even when Claude proposes a resolution.
The review package uses the required structure above, each field explicitly None or populated, followed by the actual proposed edits.
Recommended PM Action creates no lifecycle/approval state on its own.
No new workflow service, database, or risk-scoring system is introduced for V1.

ENG02-24 — Optimize AI-Assisted Development Workflow¶

Objective: Reduce avoidable AI/model cost, redundant work, and unnecessary context consumption across the full end-to-end PM Mode / ENG Mode / Admin Mode AI-assisted workflow, based on an investigation of how the workflow actually operates today, without weakening the review, authority, or fail-closed guarantees that workflow depends on.

Inputs / Preconditions

ENG02-11 (deterministic context resolver), ENG02-12 (implementation-impact protection), ENG02-14 (canonical shared workflow definition, PM/ENG/Admin Skills), ENG02-21 (Engineering Guardrail Framework, Plan Critic), and ENG02-23 (Product Change Review and Consistency Critic) are established as Product requirements this document already defines.
Available PM/ENG/Admin operating evidence is used where it exists; absence of sufficient evidence for a particular workflow area does not prevent ENG02-24 from beginning.

Required Behavior

Before proposing or implementing any specific optimization, produce a current-workflow usage/cost analysis covering, at minimum: PM Mode and ENG Mode context acquisition and repository resolution; whether deterministic context assembly repeatedly rediscovers or reloads identical authoritative context; plan generation and the volume/form of material sent into plans; Plan Critic and Product Critic invocation frequency, input size, rerun behavior, and model choice; where deterministic checks could substitute for model reasoning; repeated reasoning across initial planning, critic correction, engineer review, implementation, and post-implementation review; subagent usage and duplication of work between the primary session and critics/subagents; and opportunities across Product authoring, Engineering planning, implementation, validation, traceability, and Admin refresh — not only critique steps.
The analysis must not presume which mechanism is the answer. Caching, fingerprinting, delta review, model tiering, smaller critic packets, fewer critic reruns, deterministic preprocessing, and workflow restructuring are examples of candidate engineering solutions the analysis and subsequent plan may consider — none is mandated by this requirement.
The analysis must not assume ENG02-21's Plan Critic or ENG02-23's Product Critic are the primary source of avoidable cost merely because their usage prompted this story; the full PM/ENG/Admin workflow is in scope, and the analysis must identify where the largest opportunities actually are.
The analysis must use available operating evidence from actual PM/ENG/Admin workflow execution. Where evidence for a potentially significant workflow area is insufficient to evaluate it, the analysis must not guess at a conclusion for that area, and insufficient evidence in one area must not block the analysis, or this story, as a whole.
Where a potentially significant workflow area lacks sufficient evidence to evaluate during this story, establish lightweight ongoing measurement for that area, sufficient to support a later evidence-based decision, rather than optimizing it from assumption.
Usage evidence this story requires must be captured through normal PM/ENG/Admin workflow execution where practical, not through a separate manual measurement process an engineer must remember to run.
This story implements a bounded initial optimization set based on evidence available during the story: each workflow area with sufficient evidence receives an explicit optimization decision — implement, or explicitly decline with reasoning — rather than being silently skipped. An opportunity for which sufficient evidence does not yet exist is recorded as a deferred finding stating what could not yet be determined, what evidence is being collected toward it — explicitly None where the area doesn't warrant the ongoing-measurement bullet above — and what evidence would be sufficient to support a later evaluation, without inventing an arbitrary fixed threshold unless the analysis itself justifies one. Re-evaluating a deferred finding is separate, later work, explicitly initiated as its own bounded optimization review once accumulated evidence justifies it — this story does not itself monitor for sufficient data, automatically re-evaluate, or reopen once complete, and does not keep this story open indefinitely waiting for that later work.
An ENG Mode implementation plan may recommend and implement specific optimizations only after the analysis exists, and each optimization must trace to a specific analysis finding rather than a predetermined approach.
Independent Plan Critic review remains mandatory for every substantive ENG Mode plan, and independent Product Critic review remains mandatory for every meaning-changing PM Mode draft — no optimization may remove or bypass either.
No optimization may weaken Product authority boundaries, fail-closed behavior, engineer approval authority, traceability, or existing protection against material assumptions or conflicts.
No optimization may reduce cost by removing authoritative context that a correct decision actually depends on.
Prefer a deterministic mechanism over model reasoning wherever it can establish the same fact reliably.
Minimize repeated expensive reasoning over information that has not changed, where doing so is safe.
Critic or model reruns must be driven by whether a prior conclusion may have been invalidated, not merely by the fact that surrounding text changed.
The optimized workflow must remain understandable and operable by an engineer, not become a complex optimization framework in its own right.
Where a specific optimization constitutes a material engineering/technology decision, it is proposed and approved through the existing foundation-decision/ADR pathway (§4, §12.A) rather than plan review alone; a routine, reversible implementation choice follows ordinary ENG Mode plan review (§12.B, §19) instead. This story does not introduce a new decision pathway.

Writes / Outputs

A current-workflow usage/cost analysis identifying where model calls, context volume, repeated reads/reasoning, and critic/subagent executions occur, and which represent the largest optimization opportunities (exact artifact form and location are implementation design, not fixed by this requirement — following ENG02-14's precedent for leaving a storage mechanism unspecified at the Product level).
A bounded initial set of implemented optimizations, each traced to a specific analysis finding backed by sufficient evidence.
Lightweight ongoing measurement for potentially significant areas where evidence was insufficient during the story, integrated into normal PM/ENG/Admin workflow execution rather than a separate manual process.
A record of deferred optimization opportunities and the evidence that would be needed to evaluate each.
Any resulting changes to the shared Claude Code workflow package (Skills, subagents, hooks), dp-eng capabilities, or workflow sequencing that the analysis and plan justify.
Enough recorded usage/decision evidence, produced as part of the optimized workflow itself, to evaluate afterward whether unnecessary AI work was actually reduced.

Acceptance

The current PM/ENG/Admin AI workflow has been analyzed end-to-end and its major model-intensive or redundant steps identified, before any specific optimization is proposed.
The recorded analysis findings span the full range Required Behavior mandates — context acquisition/assembly, plan generation, critic invocation cost, deterministic-substitution opportunities, repeated reasoning across the planning-through-post-implementation sequence, subagent/critic duplication, and opportunities across Product authoring, Engineering planning, implementation, validation, traceability, and Admin refresh — not only Plan Critic/Product Critic invocation cost, so a review limited to the two critics could not satisfy this criterion.
A specific optimization that constitutes a material engineering/technology decision is routed through the existing foundation-decision/ADR pathway (§4, §12.A), not approved through ordinary plan review alone.
Every proposed optimization states which existing controls remain unchanged and why quality/safety is preserved.
A substantive ENG Mode plan still receives independent Plan Critic review.
A meaning-changing PM Mode draft still receives independent Product Critic review.
A deterministic check replaces model reasoning wherever it can establish the same fact with equivalent authority.
Unchanged context or already-completed work is not needlessly recomputed or reconsidered where safe reuse is possible.
A non-material correction does not automatically trigger the same expensive review sequence to repeat from the start.
A material change still triggers the appropriate re-evaluation.
The resulting workflow is simpler, or no more operationally complex, than the value of the optimization justifies.
Enough usage/decision evidence is recorded to evaluate whether the optimization actually reduced unnecessary AI work, after the fact.
An area with sufficient evidence during the story results in an immediate, evidence-traced optimization decision — implement, or explicitly decline.
A potentially significant area lacking sufficient evidence has ongoing measurement established for it, rather than being optimized from assumption.
Normal workflow operation produces the relevant measurement going forward without requiring a separate manual data-collection step, where practical.
Deferred opportunities are recorded together with what could not yet be determined, what evidence is being collected toward them (explicitly None where not warranted), and the evidence that would be needed to evaluate them later.
Completion of ENG02-24 does not depend on waiting indefinitely for future usage data to accumulate.
A deferred opportunity is re-evaluated only when explicitly initiated as later, separate work — ENG02-24 does not automatically reopen, monitor for sufficient evidence, or re-trigger itself.

ENG02-25 — Decision Register¶

Objective: Give a cross-cutting open question — one that precedes, spans, or doesn't yet belong to any single requirement, so §7's attention-item model (which is referenced only from a specific requirement's traceability manifest) has nowhere to represent it — a lightweight place to live: a coordination and visibility tool for open, proposed, decided, and deferred questions arising during DragonPay design and implementation, without becoming a competing source of truth for the actual decision once made.

Inputs / Preconditions

The Foundation decision/ADR pathway (§4, §12.A) and .dragonpay/decisions/<ID>/ decision-package artifacts (ENG02-15) are established — the register is explicitly separate from these, not a replacement.
ENG02-22's repository-resolution registry — generalizing ENG02-14's original Product/Development-pair registry to name additional repositories by stable logical name (§15) — is established for external consumers that need to locate the register's owning repository from outside it.
dp-eng validate's extensible validation entry point (ENG02-13) and dp-eng refresh's MkDocs generation step (ENG02-16) exist to extend.
§7's Attention Items taxonomy and routing rules are established; its record schema/authoritative source remain deferred to an unidentified future story (§6, §7, §13) — the register is a distinct artifact from that still-unbuilt attention-item record store, not an early implementation of it (see Required Behavior).
ENG-01 §10 already requires a "current technology/library decision register with classification and ADR links" as a minimum engineering artifact — a different, separate artifact from this one (see Required Behavior for the boundary between them).

Required Behavior

The Decision Register tracks open, proposed, decided, and deferred cross-cutting questions spanning technology/platform choices, architecture, security/identity, domain definitions (e.g. user roles), operations/deployment, and implementation choices — items are added whenever an unresolved question is identified that is useful to track independently. This list of areas is illustrative, not a closed enumeration.
The register is a coordination and visibility tool. It must not create, approve, duplicate, or replace a Product ADR or Foundation decision — an item requiring one continues through the existing pathway (§4, §12.A) unchanged, and the register item is updated to DECIDED only afterward, carrying a reference to the actual authoritative outcome. It is not, and does not become, an early implementation of the still-unidentified attention-item record store §6/§7/§13 defer — that remains separate, future, and scoped specifically to attention items.
Each item records: id (a stable identifier outside the Product requirement ID space — e.g. DR-NNN, following §19's established GR-NNN convention for the same reason: a flat, cross-cutting catalog rather than a per-requirement traceable item); area (free text — the areas above are examples, not a closed enumeration); question; status; needed_imminently (a required boolean — see below); required_by (optional — the requirement or implementation area the question is relevant to or informs, when one applies; purely informational, and distinct from a §7 attention item — see below); proposal (optional — directional guidance only, never authoritative); resolution_authority (free text identifying where the final answer belongs — for example PRODUCT, FOUNDATION, ENGINEERING, or OPERATIONS); resolution_ref and adr_ref (each optional individually, but at least one of the two is required once status is DECIDED — see below).
status is restricted to exactly four values — no other value is valid: OPEN (identified, no proposed direction exists yet), PROPOSED (a current direction exists but is not authoritative or final), DECIDED (its author believes the underlying question has been resolved in an authoritative source — see the DECIDED bullet below for exactly what this does and doesn't guarantee), DEFERRED (intentionally postponed, with no automatic re-review trigger — a DEFERRED item is revisited only when someone deliberately returns to it; the register does not create or require a scheduling/reminder mechanism). These four values are a closed set specific to a Decision Register item and must not be conflated with any other same-named concept in this document: not §4's FOUNDATION decision-state PROPOSED (a candidate/ADR draft under review — a different meaning for the same word, in a different field), not §19's plan-time REQUIRED_NOW/DEFERRED_TO_EXISTING_STORY finding classification (scoped to one plan review, never persisted as a standing item), and not ENG02-24's "deferred finding" (a workflow-optimization opportunity lacking sufficient evidence, scoped to that story's own analysis, with its own separate lifecycle). None of these other concepts is extended, read, or written by the Decision Register, and the Decision Register does not extend or write theirs.
needed_imminently is a required boolean on every item, independent of status: true indicates the unresolved decision requires near-term engineering attention because approaching work is expected to depend on it; false indicates the decision is known and remains in the register but does not currently require active resolution. No status change automatically alters needed_imminently, and no needed_imminently change automatically alters status; the two fields are set independently by the item's author, and the Immediate Open Decisions view (see below) filters on both together. needed_imminently is, like required_by, purely informational and does not itself represent a blocking relationship: it must not be conflated with required_by (required_by identifies what the question relates to; needed_imminently identifies only whether it currently needs near-term attention — an item can carry a required_by and remain needed_imminently: false, or be needed_imminently: true with required_by left empty), and anything actually blocking a unit of ENG Mode work continues to be represented exclusively by §7's attention-item model; the Immediate Open Decisions view is not, and does not become, an attention-item queue, and neither signal is derived from the other.
A PROPOSED item's proposal is directional guidance only. Wherever it is shown, it is shown together with the item's status; no view presents a proposal on its own or without a clear indication that it is not an authoritative decision.
A DECIDED item must carry a non-empty resolution_ref and/or a non-empty adr_ref; a DECIDED item with both empty is invalid. Marking an item DECIDED is a manual, hand-maintained bookkeeping action — by a human, or by Claude within an explicitly invoked ENG Mode action — recording that its author believes an authoritative decision has actually been made; it is never automatically derived, and it is never bundled into, or automatically triggered by, the separate PM Mode or ENG Mode action that produced the underlying decision itself (consistent with §3's "no automatic mode handoffs" principle). This is a deliberate, disclosed departure from two related but distinct established principles: §7's and §12.B's rule that IMPLEMENTED, VERIFIED, and RELEASED are system-derived and never self-declared, and §4's/§12.A's/ENG02-15's rule that a FOUNDATION requirement's APPROVED requires explicit human approval that Claude cannot grant itself. A Decision Register item's DECIDED carries no independent authority of its own, is checked only for the mechanical presence of a non-empty reference (not resolved against, or verified to exist in, the cited source — see Writes/Outputs), and an item may therefore remain OPEN or PROPOSED for a time after its real answer already exists elsewhere. Keeping the register consistent with reality is an accepted manual-maintenance limitation of a lightweight coordination tool, not a system guarantee.
The register has exactly one canonical owning development repository. ENG02-22's repository-resolution registry (§15) is the single authoritative record of which registered repository, by stable logical name, that is — the same registry both a local dp-eng validate run and an external consumer (such as the MkDocs build) read, so neither can reach a different answer than the other, and a repository cannot make itself the owner merely by claiming to be. Because that registry names only development and Product repositories (ENG02-14, ENG02-22), and this designation names one of the development ones specifically, the owning repository is necessarily a development repository, never the Product repository. dp-eng validate's register checks (see Writes/Outputs), including the missing-file failure, apply only when run within the repository the registry designates as owner; running dp-eng validate in any other repository neither checks for nor requires the register file, regardless of whether one happens to be present there. This is distinct from .dragonpay/decisions/<ID>/ decision-package artifacts (in that or any other repository) — decision packages remain scoped to Foundation technology/vendor decisions specifically (§4, ENG02-15), while the register tracks open cross-cutting questions generally, including ones that may never require a formal decision package at all.
Once this capability exists, the canonical register file itself must always be present in its owning repository. An explicit, empty register (items: []) is a valid, deliberate state, but the file being missing is a validation failure, not an empty register — absence must never be read as proof of an explicitly-empty state, the same distinction this document already draws for bootstrap-checklist absence versus an explicit empty-items determination (§4, ENG02-15).
Existing items are not deleted. A question that is no longer relevant, or whose answer turns out not to matter, is marked DECIDED or DEFERRED with an explanatory reference rather than removed — the register's value depends on showing what was asked and how it was resolved, not only its current open items.
Items are authored directly in the canonical register file — by a human, or by Claude within an explicitly invoked ENG Mode action. This capability does not introduce a dedicated mutation CLI; adding, proposing, or deferring an item is a direct edit to the canonical file. Authoring a register entry — including a proposal on an item whose resolution_authority is PRODUCT — is not itself a Product-authoring action and does not require or imply PM Mode; it also is not an Admin Mode action (Admin Mode's authority in a development repository is limited to read access and generating derived documentation/status artifacts, §3, and does not extend to authoring the register's own canonical content). Claude must never use the register to bypass the existing Product-decision or Foundation-decision/ADR approval process.
required_by is purely informational and does not itself represent a blocking relationship. A question that is actually blocking a specific unit of ENG Mode work remains represented exclusively by §7's attention-item model (a MISSING_PRODUCT_DECISION/MISSING_ENGINEERING_DECISION attention item referenced from the affected requirement's own traceability manifest). The same underlying question may reasonably have both a Decision Register item (for general visibility) and a §7 attention item (for the specific blocked work) at the same time; neither record is authoritative over the other, and this story does not create or require a cross-reference between them.
The MkDocs site exposes a generated, read-only view of the current register so its state can be reviewed without reading the canonical file directly, showing at minimum, per item: ID, Area, Question, Status, Proposed Direction, Required By, and Resolution/ADR reference — plus summary counts by status. This is additive to, and does not replace or restructure, ENG02-16's existing Attention Required / Foundation / Engineering views; a later story may choose to also surface register items within those views, but doing so is not required now. Regenerating this page is part of dp-eng refresh's (§11) existing MkDocs generation step — this story adds a page to that generation, not a new refresh responsibility.
A missing or unreadable canonical register degrades each generated register-derived page — the Decision Register page and the Immediate Open Decisions page below — to a clear "unavailable" notice rather than failing the overall MkDocs build; a missing or unreadable register must never be rendered as a page's genuine empty/no-qualifying-items state.
In addition to the full register view, the MkDocs site exposes a second, generated view named Immediate Open Decisions: the subset of register items whose status is OPEN or PROPOSED and whose needed_imminently is true. It is generated directly from the same canonical register data on every regeneration and must not maintain any decision record of its own, introduce a second data store, a separate backlog, an additional approval process, or any additional lifecycle state — an item's presence in this view is a pure function of the two fields already named. It shows, per item: ID, Area, Question, Status, Required By, Proposed Direction, and Resolution Authority. A status transition to DECIDED or DEFERRED removes an item from this view; the item remains visible, unchanged, in the full register page. When the canonical register is readable and genuinely contains no item meeting the filter, the view renders a plain statement that no item currently needs immediate attention — distinct from, and never substituting for, the "unavailable" notice a missing or unreadable register produces (see above).
The register must remain lightweight: it does not replace Product requirements, ADRs, engineering documentation, or project-management tooling. As a concrete, checkable form of that constraint, its field set is fixed to what this story defines — adding a field or new structure requires a change to this document, and dp-eng validate rejects an item carrying an unrecognized field (see Writes/Outputs).
ENG-01 §10's "current technology/library decision register with classification and ADR links" is a separate artifact with its own requirements — this story does not satisfy, replace, or become it. A Decision Register item may track an open technology/library question before any such decision exists, and its adr_ref may point at the resulting ADR once one does, but that is incidental overlap, not satisfaction: this register is append-only and stale-tolerant by design (see the DECIDED bullet above), tracks only questions someone thought to raise rather than every current decision, and validates area/adr_ref only for non-emptiness rather than as a controlled classification or a verified ADR link — none of which would satisfy a "current... with classification and ADR links" artifact requirement.

Writes / Outputs

A canonical Decision Register data file in its one owning development repository, designated in ENG02-22's repository-resolution registry, with the item schema above, separate from .dragonpay/decisions/<ID>/.
Validation integrated into dp-eng validate (extending ENG02-13's entry point), applied only when run within the owning repository: every item has non-empty id/area/question/status/resolution_authority, and a needed_imminently value that is present and a genuine boolean (true or false — missing, or present as a string such as "true", is rejected); every item's fields are limited to this story's defined schema, with an unrecognized field rejected; status is restricted to the four-value enum; a DECIDED item has a non-empty resolution_ref and/or adr_ref (checked for presence only — not resolved against, or verified to exist in, the cited authoritative source); ids are unique; the canonical file's absence is itself a validation failure, distinct from a present file's explicit items: [].
A generated MkDocs Decision Register page, produced as part of dp-eng refresh's MkDocs generation (read-only, degrading gracefully to an "unavailable" notice rather than failing the build when the register is missing/unreadable), rendering the required fields above and summary counts by status.
A generated MkDocs Immediate Open Decisions page, produced as part of the same dp-eng refresh MkDocs generation step as the Decision Register page (read-only, sourced from the same canonical register data, never a store of its own), rendering the OPEN/PROPOSED-and-needed_imminently:true subset of items with the columns described above; degrading to the same "unavailable" notice as the Decision Register page when the canonical register is missing/unreadable, and rendering a plain no-items-currently-need-attention notice only when the register is readable and genuinely contains no qualifying item.

Acceptance

One tracked, canonical Decision Register exists, in one owning development repository designated in ENG02-22's repository-resolution registry; dp-eng validate run in any other repository does not check for or require it; the registry is the one place both a local dp-eng validate run and an external consumer (such as MkDocs) read, so they cannot disagree about which repository owns it.
A new item can be added with only its required fields (id, area, question, status, needed_imminently, resolution_authority) — no ceremony beyond a direct edit to the canonical file.
A PROPOSED item's proposal is always rendered together with its status, never on its own.
dp-eng validate rejects: an item missing any of id/area/question/status/resolution_authority; an item whose needed_imminently is missing or is not a boolean; an item carrying a field outside this story's defined schema; an item whose status is not one of the four defined values; a DECIDED item lacking both resolution_ref and adr_ref; and a duplicate id across items.
dp-eng validate fails when the canonical register file is missing from its owning repository; an explicit items: [] is valid and distinct from the file being absent.
The MkDocs Decision Register page renders every item's ID, Area, Question, Status, Proposed Direction, Required By, and Resolution/ADR reference, plus summary counts by status, without failing the overall MkDocs build when the register is unavailable.
The Immediate Open Decisions page shows exactly the items whose status is OPEN or PROPOSED and whose needed_imminently is true, sourced from the same canonical register data as the full Decision Register page — never a separately maintained record, backlog, approval process, or lifecycle state. An item moving to DECIDED or DEFERRED disappears from this view and remains visible, unchanged, in the full Decision Register page. A missing or unreadable register produces the same "unavailable" notice as the full Decision Register page, never a false "no items need attention" statement.
Every item's required_by value, when set, is rendered in its own column, so items relevant to a specific requirement or implementation area can be found by scanning that column; this is independent of, and does not replace, §7's attention-item mechanism for anything actually blocking a unit of work.
No existing ADR/decision-package behavior (§4, ENG02-15), and no existing §7 attention-item behavior, changes as a result of this capability.
The register never creates, approves, duplicates, or replaces a Product ADR or Foundation decision; authoring a register entry is never itself treated as a PM Mode or Admin Mode action.
Marking an item DECIDED is always a separate, manual action from whatever mode/action produced the underlying decision — nothing in this capability triggers it automatically.

16. Initial implementation sequence¶

Sequenced in four phases rather than one flat list, so the investment in dp-eng matches what a 1-person team actually needs before serious Product implementation, without either under-building (bare naming conventions) or over-building (every story in §15 before [PH-01](../../product/hub-epics/ph-01.md)).

Phase 1 — Context Engine V1 (build before serious PH implementation)¶

ENG02-01 — repository/Product-baseline configuration.
ENG02-02 — Product indexing.
ENG02-03 — requirement relationships.
ENG02-04 — traceability schema.
ENG02-07 — requirement types/status basics.
ENG02-13 — validation framework (V1 — see its own "incremental validation" rule).
ENG02-14 — Claude development instructions. (Sequenced before the context resolver, not after — ENG02-11 needs a real development CLAUDE.md to read.)
ENG02-21 — engineering scope and assumption guardrails. (ENG02-21 should govern the implementation of ENG02-11, ENG02-12, and ENG02-15 themselves — ENG02-11/12 later make ENG02-21 stronger by providing more deterministic context and impact information, but they are not prerequisites for the initial guardrail behavior.)
ENG02-23 — Product Change Review and Consistency Critic. (The PM-side counterpart to ENG02-21's Plan Critic, built on the same shared workflow package and drawing PM-scoped entries from the same Guardrail Catalog ENG02-21 establishes — sequenced immediately after it for exactly that reason.)
ENG02-11 — context resolver V1.
ENG02-12 — implementation-impact protection.
ENG02-15 — foundation/ADR workflow support.

At the end of Phase 1: given a requirement such as PH08-05, Claude and a human can inspect one deterministic context bundle containing the authoritative Product contract, applicable standards/ADRs, existing implementation/tests, and other mapped contracts that must be preserved — and Claude Code knows the rules it's operating under. This is the milestone to reach before investing heavily in anything below.

Phase 2 — incrementally alongside Product development¶

ENG02-05 — richer post-release mapping behavior.
ENG02-22 — cross-repository traceability, closing the gap ENG02-14 surfaced.
ENG02-16 — richer MkDocs aggregation. Because MkDocs is already running, this can start earlier than this phase where useful (see ENG02-16's own note).
ENG02-17 — generated engineering catalogs.
ENG02-24 — analyze and optimize the AI-assisted development workflow using available operating evidence, establishing ongoing measurement where evidence is insufficient. Investigates the PM/ENG/Admin workflow as a whole — not scoped to ENG02-21/23 merely because their critic passes prompted the story.
ENG02-25 — Decision Register: a lightweight coordination/visibility tracker for open cross-cutting questions, explicitly decoupled from Product/Foundation decision authority.

Phase 3 — defer until CI/cloud exist¶

ENG02-06 — released-requirement baselining.
ENG02-08 — current conformance automation.
ENG02-09 — deployment evidence contract (fixtures may be built even before a real CI/CD provider exists, if useful).
ENG02-10 — RELEASED calculation (same fixture caveat as ENG02-09).
ENG02-18 — CI verification integration, once CI is established.
ENG02-19 — deployment integration, once environments and deployment tooling exist.

We already know these contracts (§8, §9) — there's no need to build fake deployment machinery before DEV itself exists.

Phase 4 — much later¶

ENG02-20 — semantic/discovery enhancements, only once real Phase-1 usage identifies an actual need.

17. Out of scope¶

A centralized metadata database for V1; Git/files remain the persistence layer for Product and implementation metadata.
A separate context-engine web application or React/admin UI; MkDocs remains the initial human UI.
Embeddings/vector databases/RAG as a prerequisite for V1.
Automatically editing Product requirements during development execution.
Automatically approving Product ADRs or foundation technology decisions.
Automatically advancing development repositories to latest Product HEAD.
Percentage-complete status inferred by Claude.
Treating generated engineering prose/facts as Product requirements.
Creating a development repository for every service/module solely for separation.
Blocking Product or engineering work until every ENG-02 story is complete.
Solving all future multi-repository, scale, semantic-search, or BI/documentation needs before actual usage requires them.
Mandating a specific VCS mechanism (e.g. a Git submodule) for the Product-repository reference — §6 defines a path/pinned-commit contract, not a required implementation technique.
Automatic mode handoffs or autonomous mode switching — PM Mode, ENG Mode, and Admin Mode are always independently, explicitly invoked (§3).
A separate ticketing platform for attention items in V1 — a repository-derived attention queue, surfaced through Admin Mode/MkDocs, is sufficient (§7).

18. Completion criteria¶

The Product repo and development repo(s) have explicit authority and write-boundary rules across all three operating modes (PM Mode, ENG Mode, Admin Mode, §3), with no automatic handoff between them.
ENG Mode's scope is explicitly distinguished from the FOUNDATION requirement class, and PM Mode's scope from the PRODUCT requirement class — operating modes and requirement classes are never used interchangeably.
A development repo pins an explicit Product baseline (path + commit, remote optional) and its own configured authoritative Development branch, and never silently follows Product HEAD.
Stable Product requirement IDs can be indexed and resolved deterministically, with requirement class (PRODUCT/FOUNDATION/STANDARD) derived from document-family prefix.
Every epic family — including STD-01 — uses the same uniform {PREFIX}{EPIC-NUMBER}-{ITEM-NUMBER} ID format; there are no ID-format exceptions by class.
Product evolution can be expressed through modifies/supersedes/retires relationships without rewriting released behavioral history.
One requirement traceability manifest maps current implementation, tests, ADRs, work state, attention items, and required deployment units.
Historical verification/release evidence is kept separate from mutable current implementation mapping.
IMPLEMENTED is derived from acceptance into the configured authoritative Development branch, never from developer/Claude-edited metadata; VERIFIED and RELEASED are system-derived for PRODUCT requirements; ESTABLISHED is system-validated for FOUNDATION requirements; RELEASED requires objective PROD evidence for all required deployment units.
Released requirements preserve their first Product/implementation/release evidence while current conformance can independently show PASS/FAIL/UNKNOWN, scoped only to requirements that have reached RELEASED at least once.
DEV/STA/PROD can begin UNPROVISIONED and later report objective deployment provenance.
Foundation work can move from UNRESOLVED through human-approved ADR to validated ESTABLISHED setup without assuming accounts/tools already exist, entirely within ENG Mode.
Every blocker type has an explicit suggested resolution — a PM Mode action, an ENG Mode foundation/ADR action, or "stays in place" (EXTERNAL_DEPENDENCY) — reached only through explicit invocation, never automatic routing.
A requirement may carry multiple simultaneous attention items, surfaced through Admin Mode's dp-eng refresh and MkDocs, without a single-blocker-reference assumption anywhere in the model.
dp-eng can validate repository integrity and resolve inspectable context for a selected requirement, with dp-eng validate extensible as later capabilities land rather than complete only once the whole system exists.
Context includes the Product contract, shared standards/ADRs, current mapped implementation/tests, and other existing requirements the change could affect.
Claude Code can begin a requirement implementation using repository instructions and resolved context without the architecture needing to be re-explained conversationally.
The existing MkDocs site evolves to include engineering/traceability evidence while preserving readable Product/executive documentation and never becoming authoritative itself — canonical requirement-reference pages exist alongside curated narrative pages, not instead of them.
Generated engineering catalogs have provenance and describe implementation facts rather than requirements.
The deterministic V1 remains useful without a cloud account, CI/CD provider, deployed environment, vector database, or semantic search service.
ENG-02 can be implemented story-by-story, in the four-phase order §16 defines, so Claude assists in building the context system that later governs Claude-assisted DragonPay development.

19. Engineering Guardrail Framework¶

ENG Mode must distinguish requirements from implementation convenience. Claude must not silently expand the current story, implement behavior assigned to later requirements, or convert undocumented assumptions into permanent engineering or Product contracts.

This section defines the guardrail framework: how guardrails are loaded, evaluated, surfaced, reviewed, and reconciled, and the exact plan/review output structures ENG Mode must produce. The Guardrail Catalog — a separate, authoritative Product document — is the sole authoritative source for individual guardrail definitions and their evaluation checks. This section must not maintain a second, competing list of guardrails.

Before implementation, Claude must classify material findings as one of:

Classification	Meaning
REQUIRED_NOW	Required to satisfy the selected requirement.
IMPLEMENTATION_DETAIL	Local, reversible engineering choice needed to implement the requirement.
DEFERRED_TO_EXISTING_STORY	Capability already owned by another Product/Foundation requirement.
MISSING_ENGINEERING_DECISION	Material engineering choice not established by an applicable requirement, standard, ADR, or authoritative contract.
PRODUCT_ISSUE	Missing, ambiguous, or conflicting Product behavior.

If a PRODUCT_ISSUE or MISSING_ENGINEERING_DECISION finding remains unresolved after the applicable plan review, it may be persisted as an attention item using §7's issue-type taxonomy. PRODUCT_ISSUE maps to REQUIREMENT_AMBIGUITY, REQUIREMENT_CONFLICT, or MISSING_PRODUCT_DECISION as applicable; MISSING_ENGINEERING_DECISION maps directly. Do not interpret creation of an attention item as automatically making the current requirement BLOCKED.

Uncertainty alone does not cause blocking. Material risk from proceeding under unresolved uncertainty does. Claude must block the affected work when proceeding without resolution could materially compromise correctness, Product intent, security or authorization, financial behavior, persistent data integrity, external contracts, or create a difficult-to-reverse shared architectural decision. Blocking applies only to the affected scope; unrelated or safely implementable work may continue. This does not introduce a LOW/MEDIUM/HIGH/CRITICAL risk taxonomy or any other risk framework — the existing preflight outcomes (§7) remain exactly READY, READY_WITH_ISSUES, and BLOCKED.

Functionality owned by a later requirement must not be implemented early merely because it would simplify the current implementation. If the current story cannot be implemented correctly without a minimal prerequisite from later work, that prerequisite must be identified explicitly in the implementation plan and reviewed before coding.

Substantive ENG Mode work must occur under Claude Code's native plan-review precondition; if invoked while that precondition is not active, ENG Mode fails immediately with a clear instruction to enter it and retry — Claude must not silently continue and must not autonomously switch modes on the engineer's behalf.

Every substantive ENG plan must be assembled in the required structure (the Mandatory ENG Plan Review Summary below, followed by the detailed plan) and validated for that structure — required sections present, each populated or explicitly stated as None — before it can be presented for engineer approval. This structural validation is deterministic and checks structure only; it never evaluates whether the plan's content is correct, sufficient, or reflects sound engineering judgment — semantic evaluation remains the Plan Integrity Review's, the Plan Critic's, and the engineer's responsibility.

Guardrail Catalog¶

The Guardrail Catalog is a separate, authoritative Product document holding stable-ID guardrail entries — fields: ID, Name, Applies To (PM/ENG/ADMIN/ALL, or multiple named modes), Rule, Applies When, Evaluation Check, Enforcement Type (EVALUATIVE, DETERMINISTIC, or BOTH). ENG Mode and Admin Mode read it through the Development repository's pinned Product baseline, never live Product HEAD (the same invariant §11 already locks in for every other Product artifact); PM Mode reads it directly against the Product repository it is authoring, since no baseline-pinning relationship applies there. A guardrail can be added or refined through PM Mode without requiring this section or ENG02-21 to be reimplemented, as long as the framework already supports its Applies To/Enforcement Type shape.

Fail-closed Catalog behavior. If the authoritative Catalog cannot be loaded or fails structural validation, or applicable guardrails cannot be determined reliably for the current mode/action, substantive ENG work must not proceed. The baseline-pinned retrieval capability performs basic structural validation before any guardrail content is used — rejecting malformed catalog content, duplicate guardrail IDs, missing required fields, invalid mode applicability, or invalid enforcement type. This is catalog-input validation, not a guardrail-evaluation engine — it never judges whether a guardrail's Rule is correct, only whether the Catalog file is well-formed.

Mandatory ENG Plan Review Summary¶

Every substantive ENG Mode plan must begin with this consolidated review surface before implementation detail:

Summary field	Required content
Preflight	READY \| READY_WITH_ISSUES \| BLOCKED
Blocking Current Work	None, or each issue that prevents affected work from safely/correctly proceeding.
Decisions / Assumptions Requiring Engineer Review	None, or each material choice not established by authoritative context.
Product Issues	None, or requirement ambiguity/conflict/missing Product decision.
Engineering Concerns	None, or material design, consistency, truthfulness, invariant, maintainability, or implementation concerns.
Later-Story / Scope Collisions	None, or capabilities touched/approached that are owned by another requirement.
Plan Critic Findings	None, or material findings from the critic pass, including important findings corrected before presentation.
Recommended Engineer Action	APPROVE PLAN \| APPROVE AFTER LISTED CORRECTIONS \| RESOLVE LISTED ITEMS BEFORE IMPLEMENTATION

The summary must not hide a material issue merely because Claude proposes a solution later in the plan.
Empty categories must explicitly state None.
The summary must distinguish blocking from non-blocking concerns.
Recommended Engineer Action is advisory only and creates no lifecycle/approval state.

The Plan Review Summary does not replace the detailed plan. The required order is: 1. Plan Review Summary; 2. Requirement / Acceptance Coverage; 3. Required Now; 4. Implementation Details; 5. Deferred / Not Implemented; 6. Later Requirements Touched or Approached; 7. Assumptions / Decisions Requiring Review; 8. Product / Engineering Issues; 9. Scenario Review; 10. Plan Critic Findings; 11. Planned Files / Components; 12. Engineer Plan Review. Where an applicable section has no findings, an explicit None is valid.

Plan Integrity Review¶

Before an ENG Mode implementation plan is presented for engineer approval, Claude must perform a Plan Integrity Review: load the Guardrail Catalog, filter to guardrails applicable to ENG or ALL, determine which are relevant to the current action using each guardrail's Applies When guidance, and evaluate every relevant, applicable guardrail against the selected requirement, the current implementation sequence, and the available authoritative context. The Catalog is the sole authoritative source for what is checked and how — this framework does not separately enumerate individual checks.

Later-story collision review¶

For every later requirement that the current plan touches or approaches, the plan must identify:

Field	Required content
Requirement	The later requirement ID
Capability	The behavior or capability being approached
Needed now	Yes / No
Implemented now	Yes / No
Reason	Why it is required now or why it remains deferred

If later-story behavior is not required for the current story, it remains deferred. If a minimal prerequisite is required early, the plan must explain why the current story cannot be implemented correctly without it, what minimum behavior is being introduced now, and what remains owned by the later story.

Plan Critic pass¶

Before engineer plan approval, perform a distinct Plan Critic pass, independent of the planner's own accumulated reasoning. The critic's purpose is to challenge, reduce, and attempt to break the proposed plan — not to make it more comprehensive. The critic independently evaluates the same applicable Guardrail Catalog entries as the Plan Integrity Review, and confirms the plan's required sections are substantively complete, not merely present.

The critic must not:

add desirable future functionality;
redesign unrelated architecture;
expand scope because additional capability would be useful;
turn optional improvements into blockers.

Material assumptions¶

Before coding, Claude must identify any material assumption required by the proposed implementation that is not explicitly established by authoritative context.

A material assumption includes a choice affecting:

Product-visible behavior;
persistent data or schema;
state/lifecycle transitions;
public or shared internal interfaces;
event/message contracts;
security or authorization;
idempotency, retry, timeout, resilience, or failure behavior;
infrastructure/tooling standards;
shared abstractions or conventions likely to be reused;
operational behavior;
difficult-to-reverse implementation decisions.

Material undocumented assumptions must be proposed for human review before being encoded. Routine, local, reversible implementation choices do not require separate approval.

Each material assumption requiring review must state:

what is missing or undocumented;
why a choice is required;
which authoritative sources were checked;
the proposed options and recommendation;
the impact if the assumption is wrong.

Every implementation plan must contain Assumptions / Decisions Requiring Review, with either the identified items or an explicit None.

New assumptions discovered after plan approval¶

Plan approval does not authorize undisclosed material assumptions. If implementation later exposes a new material assumption, materially changes the expected impact/blast radius, or requires a material decision not contained in the approved plan, Claude must surface it for review before encoding it when proceeding would create material risk.

The decision behavior is:

If the newly discovered issue does not create material risk, record it appropriately and continue safely implementable work.
If proceeding would create material risk, stop only the affected work and request review.
Do not silently interpret prior plan approval as authorization to make the new decision.

Scope reconciliation¶

Before presenting implementation for engineer acceptance, Claude must compare the completed implementation with the approved plan and report:

any implementation outside the approved scope;
any capability belonging to another requirement that was implemented;
any new persistent field, schema, interface, event, or shared abstraction;
any material assumption introduced after plan approval;
any Product behavior inferred rather than established;
any Product ambiguity resolved through code rather than surfaced;
any intentional deviation from the approved implementation plan;
whether the scenarios reviewed during planning still hold.

A newly discovered material issue must not be hidden simply because implementation is already complete or tests pass.

Findings do not automatically block unrelated work. ENG Mode continues to use READY, READY_WITH_ISSUES, and BLOCKED, with blocking scoped only to work that cannot safely or meaningfully continue.

Before source-control acceptance, ENG Mode presents this report in the following structure: Implementation Summary; Acceptance Coverage; Validation Performed; Protected Existing Requirements; Scope Reconciliation; New Assumptions / Decisions; Known Issues / Attention Items; Engineer Review Requested.

Intent¶

ENG02-21 is intended to prevent Claude from quietly turning missing information, examples, legacy artifacts, implementation convenience, or future requirements into architecture. It is not intended to stop development whenever something is uncertain.

Governing principle: surface material undocumented assumptions before they become contracts; block only the affected work when the cost of guessing could be significant.

Governing principle (model, default, and evidence guardrails): do not create a second truth when one already exists; do not turn absence into certainty without authority; and do not hide contradictory evidence behind a plausible derived result.

Implemented by ENG02-21 (§15).