diff --git a/.github/workflows/protected-head-refresh-ci.yml b/.github/workflows/protected-head-refresh-ci.yml index 6d5d9be3..b195df15 100644 --- a/.github/workflows/protected-head-refresh-ci.yml +++ b/.github/workflows/protected-head-refresh-ci.yml @@ -142,6 +142,6 @@ jobs: # candidate contracts without projecting a false reviewed authority. - name: Verify deterministic candidate contracts run: | - npm run agentic-sdlc:policy:check + npm run adlc:policy:check npm run agenticrag:guidelines-map:check npm run git-guidelines:test diff --git a/docs/documents/agentcos-tech-stack-document.md b/docs/documents/agentcos-tech-stack-document.md index b62cb061..e2095484 100644 --- a/docs/documents/agentcos-tech-stack-document.md +++ b/docs/documents/agentcos-tech-stack-document.md @@ -44,7 +44,7 @@ traceability: # Agentic OS (agentcos) — Tech Stack Document **Context**: Solo-dev, AI-native startup. `agentcos` is the Agentic OS — the harness/orchestration plane that supervises, verifies, and delivers multiple target product repositories. First targets: `agntgrph` (knowledge-graph canvas product) and `gamexr` (game/XR product). Runtime topology: Dev (`GitHub/agntgrph`, `GitHub/gamexr`, `npm run dev`; Home Apex supervisor `npm run dev:apex`) → Prod mirrors (`GitHub/huijoohwee/content/agntgrph`, `GitHub/huijoohwee/content/gamexr`) → Delivery (`airvio.co`, `airvio.co/agntgrph`, `airvio.co/gamexr`). -**Intent**: Provide the end-to-end reference for agentcos user flow, orchestration/harness flow, workflow, and data flow — evaluated through the four compounding lenses (min-viable-max-value, TCO-zero, token economics, harness-first) and the governing Agentic SDLC execution contract (roles, budgets, gates, receipts). +**Intent**: Provide the end-to-end reference for agentcos user flow, orchestration/harness flow, workflow, and data flow — evaluated through the four compounding lenses (min-viable-max-value, TCO-zero, token economics, harness-first) and the governing ADLC execution contract (roles, budgets, gates, receipts). **Directive**: Treat `agentic-canvas-os/docs` (Git, frontmatter-first) as the invocation and contract SSOT. Resolve `/`, `#`, `@` only through the three invocation dictionaries. Every AI pipeline runs in a typed harness with a cost log; every loop carries a max-iteration bound and circuit-breaker; every verdict comes from an Evaluator mechanism distinct from the Implementer; every promotion toward a delivered surface passes a closed-by-default Deploy Boundary. ### Reference Implementation Note @@ -280,7 +280,7 @@ flowchart TB | Memory log | `memory-log/v1` append-only shards | Durable agent history at $0 TCO | ✓ Git | | Planning records | `todo-context-record/v2` immutable per-task records | Cross-repo planning authority | ✓ Git | | Runtime-readiness validators | Deterministic receipt evaluators (exit-zero gates) | Fail-closed readiness derivation | ✓ Internal | -| SDLC execution contract | Orchestrator/Implementer/Evaluator/Operator roles + four bounds | Self-grade-proof verdicts; finite tasks | ✓ Internal | +| ADLC execution contract | Orchestrator/Implementer/Evaluator/Operator roles + four bounds | Self-grade-proof verdicts; finite tasks | ✓ Internal | ### Orchestration Runtime @@ -500,4 +500,4 @@ Routes are **owned and declared** by the three invocation dictionaries in the in --- -*Document created 2026-08-20. Adherent to [PRD, TAD & ADR Guidelines v1.7.0](../../guidelines/prd-tad-adr-guidelines.md) and [Agentic SDLC Guidelines v1.16.0](../../guidelines/agentic-sdlc-guidelines.md); session posture per `agentic-canvas-os/docs/START-WORKFLOW.md` (authoring lane, Dev-only, deploy boundaries closed).* +*Document created 2026-08-20. Adherent to [PRD, TAD & ADR Guidelines v1.7.0](../../guidelines/prd-tad-adr-guidelines.md) and [ADLC Guidelines v1.16.0](../../guidelines/adlc-guidelines.md); session posture per `agentic-canvas-os/docs/START-WORKFLOW.md` (authoring lane, Dev-only, deploy boundaries closed).* diff --git a/docs/documents/agentic-game-os-prd-tad-adr.md b/docs/documents/agentic-game-os-prd-tad-adr.md index f17812f4..513e1bbe 100644 --- a/docs/documents/agentic-game-os-prd-tad-adr.md +++ b/docs/documents/agentic-game-os-prd-tad-adr.md @@ -21,7 +21,7 @@ research_input_digest: "sha256:5fb8f9f4a0c4bc6d7e96866ff5224cbb46f937368f8f22bb9 # Agentic Game OS — Persistent Strategy and Shared-World Reopening — PRD/TAD/ADR -Governed by PRD, TAD & ADR Guidelines v1.7.0 (2026-07-28). The Agentic SDLC Guidelines separately own task decomposition, tool blast radius, verification, integration, and release. +Governed by PRD, TAD & ADR Guidelines v1.7.0 (2026-07-28). The ADLC Guidelines separately own task decomposition, tool blast radius, verification, integration, and release. Status boundary: this is a spec-complete source contract. It is not an implementation receipt, protected integration result, browser result, Xcode or Simulator result, physical-device result, Production authorization, or Cloudflare deployment result. Present-tense criteria describe required behavior, not observed behavior. Every Evidence Reference remains none recorded. diff --git a/docs/documents/git-guidelines.md b/docs/documents/git-guidelines.md index 762818e0..c7df2b3c 100644 --- a/docs/documents/git-guidelines.md +++ b/docs/documents/git-guidelines.md @@ -9,7 +9,7 @@ local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" universal_scope: false -companion_of: "guidelines/agentic-sdlc-guidelines.md" +companion_of: "guidelines/adlc-guidelines.md" invocation_token: "/git.guidelines" semantic_filters: ["#git-collaboration"] bindings: ["@git-guidelines"] @@ -23,14 +23,14 @@ This git-layer companion projects the execution set into byte-preserving, provid | ID | Rule family | Disposition | Owner | Class | |---|---|---|---|---| -| C1 | claim identity | consumes | [Collaboration Module](../../guidelines/agentic-sdlc-cloud-collaboration.md) | advisory | -| C2 | authority order | consumes | [Collaboration Module](../../guidelines/agentic-sdlc-cloud-collaboration.md) | advisory | -| C3 | write-scope comparison | consumes | [Collaboration Module](../../guidelines/agentic-sdlc-cloud-collaboration.md) | advisory | -| C4 | fence meaning | consumes | [Collaboration Module](../../guidelines/agentic-sdlc-cloud-collaboration.md) | advisory | -| C5 | handoff semantics | consumes | [Collaboration Module](../../guidelines/agentic-sdlc-cloud-collaboration.md) | advisory | -| C6 | additive lane admission and preservation proof | consumes | [Lane Admission Module](../../guidelines/agentic-sdlc-scoped-lane-admission.md) | advisory | +| C1 | claim identity | consumes | [Collaboration Module](../../guidelines/adlc-cloud-collaboration.md) | advisory | +| C2 | authority order | consumes | [Collaboration Module](../../guidelines/adlc-cloud-collaboration.md) | advisory | +| C3 | write-scope comparison | consumes | [Collaboration Module](../../guidelines/adlc-cloud-collaboration.md) | advisory | +| C4 | fence meaning | consumes | [Collaboration Module](../../guidelines/adlc-cloud-collaboration.md) | advisory | +| C5 | handoff semantics | consumes | [Collaboration Module](../../guidelines/adlc-cloud-collaboration.md) | advisory | +| C6 | additive lane admission and preservation proof | consumes | [Lane Admission Module](../../guidelines/adlc-scoped-lane-admission.md) | advisory | | C7 | frontmatter, Rule_ID, findings, and readiness rungs | consumes | [Authoring Authority](../../guidelines/prd-tad-adr-guidelines.md) | advisory | -| C8 | task model, roles, independence, blast radius, and budgets | consumes | [Execution Companion](../../guidelines/agentic-sdlc-guidelines.md) | advisory | +| C8 | task model, roles, independence, blast radius, and budgets | consumes | [Execution Companion](../../guidelines/adlc-guidelines.md) | advisory | | C9 | commit, push, and deploy command sequences | consumes | [Delivery Guidelines](../../guidelines/commit-push-deploy-guidelines.md) | advisory | | O1 | git lane projection and branch naming | owns | — | advisory | | O2 | coordination artifact layout and schemas | owns | — | advisory | diff --git a/guidelines/agentic-sdlc-anti-pattern-guards.md b/guidelines/adlc-anti-pattern-guards.md similarity index 87% rename from guidelines/agentic-sdlc-anti-pattern-guards.md rename to guidelines/adlc-anti-pattern-guards.md index e9ef1428..639b307b 100644 --- a/guidelines/agentic-sdlc-anti-pattern-guards.md +++ b/guidelines/adlc-anti-pattern-guards.md @@ -1,16 +1,16 @@ --- -title: "Agentic SDLC Execution Anti-Pattern Guards" +title: "ADLC Execution Anti-Pattern Guards" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-08-27" +version: "1.1.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Orchestrator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" -provider_neutral: "true" +universal_scope: true +provider_neutral: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- @@ -21,12 +21,12 @@ lifecycle_status: "proposed" |---|---| | An Implementer marking its own task complete; a `done` state any role may set; a verdict derived from state the Evaluator cannot see | `verified` as the only success state, set only by an Evaluator that is a distinct mechanism, judging surfaced output only | | Tasks invented at task-authoring time to cover behaviour the specification never stated | Every task derived from a VCC; a behaviour gap returned to the authoring loop as a specification defect | -| Picking among several equally-ready candidates by convenience, recency, or an unstated preference, with no recorded reason | Constraint satisfaction filters infeasible candidates first, outranking eliminates the dominated, and argumentation settles what remains — with the trail recorded | +| Picking among several equally-ready candidates by convenience, recency, or an unstated preference, with no recorded reason | Hard constraints gate a bounded Constraints ↔ Argumentation ↔ Outranking loop; changed evidence reopens affected checks, preserves incomparability, and records a supported choice or unresolved decision | | Tasks dispatched with no token, iteration, wall-clock, or context bound; bounds raised mid-run to rescue a failing task | All four bounds stated before dispatch with a circuit-breaker; overruns trigger re-decomposition, not a larger bound | | Session-wide capability grants; an agent widening its own permissions mid-task; a standing approval for irreversible operations | Narrowest sufficient class granted per task; escalation via `blocked` and re-dispatch; an explicit Operator decision per irreversible occurrence | | Tasks that reach a mirror or delivery surface, or transmit project content outward, because it was convenient | Execution confined to the authoring lane; promotion is the Deploy Boundary's job and never a task | | Success asserted without a named check and a recorded result; a check named after the fact to match what happened | Named check stated before dispatch, run during the task, and its result surfaced in the Implementer's own output | -| Bug fixes with no check that failed on the unfixed state; stated correctness properties with no executable property test | Failing-first witness per fix; one property test per stated property with its class named and shrinking enabled | +| Behavioral defects fixed without a failing witness; a general correctness claim unsupported by a meaningful check | A behavioral defect needs a bounded failing witness and passing result; use property tests when a general invariant and meaningful generated cases justify them | | Long runs that cannot resume, discovering the context boundary by losing work at it | Run state persisted after every terminal transition; checkpoint before the context bound; resume from persisted state, not memory | | Operator decisions inferred, defaulted, simulated, or accepted through a non-interactive confirmation flag because the run would otherwise stall | Absent decisions produce `blocked`; the configured interaction adapter records the exact human challenge response before the authority adapter can authorize | | A green merge automatically deploying the current protected ref, one interaction transport treated as universal, or a release rebuilding after human approval | Protected integration emits no deployment authority; the configured interaction and authority adapters record one authenticated exact-candidate decision, and the controller deploys those reviewed bytes without rebuild | diff --git a/guidelines/agentic-sdlc-artifact-continuity.md b/guidelines/adlc-artifact-continuity.md similarity index 93% rename from guidelines/agentic-sdlc-artifact-continuity.md rename to guidelines/adlc-artifact-continuity.md index 26fa5064..421a0b09 100644 --- a/guidelines/agentic-sdlc-artifact-continuity.md +++ b/guidelines/adlc-artifact-continuity.md @@ -1,8 +1,8 @@ --- -title: "Agentic SDLC Artifact Continuity Module" +title: "ADLC Artifact Continuity Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-22" +version: "1.1.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Orchestrator function" @@ -10,12 +10,12 @@ local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" schema: "agentic-artifact-continuity/v1" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- -# Agentic SDLC Artifact Continuity Module +# ADLC Artifact Continuity Module ## Scope and Ownership @@ -24,24 +24,20 @@ Context-Intent-Directives (CID) remain joined to Role-Action-Outcome (RAO) execu demonstration, and successor planning. It defines semantic roles and joins, never file names, directory layouts, document products, providers, tools, storage formats, or workflow transports. -The main Agentic SDLC Guidelines own execution roles, task state, budgets, permissions, and evidence emission. The +The main ADLC Guidelines own execution roles, task state, budgets, permissions, and evidence emission. The Specification Chain Module owns the requirements-design-tasks chain and its two coverage seams. This module owns only the continuity envelope around that chain: CID-to-RAO coverage, companion-artifact joins, outcome evidence, revision freshness, and feedback into a successor Context. ## Semantic Separation -CID is the policy plane. RAO is the accountable transformation plane. Artifacts carry state. Evidence records an -observation and verdict. None substitutes for another. +The shared [CID/RAO/SVO contract](./cid-guidelines.md#shared-field-contract) owns message fields across PRD, TAD, +ADR, and execution. This module adds joins, not another schema: CID frames intent and constraints, RAO assigns +transformation, SVO expresses that same action. Artifacts carry state; evidence records observations and verdicts. | Concept | Owns | Must not own | |---|---|---| -| **Context** | Applicability, conditions, and bounded scope | A solution, implementation mechanism, or completion claim | -| **Intent** | One desired future state | An observed result or self-issued verdict | -| **Directive** | One required constraint, safeguard, or prohibition | A provider, tool, file path, or hidden implementation choice | -| **Role** | One accountable function | A person, product identity, or mutable session identity | -| **Action** | One atomic transformation over declared inputs | Multiple independently closable transformations | -| **Outcome** | One concrete, measurable result directly produced by the Action | The verdict that the result satisfies an Intent | +| **CID/RAO/SVO fields** | Meanings owned by the shared field contract | Additional aliases or narrower local definitions | | **Artifact** | Versioned state consumed or produced by an Action | Authority, approval, or evidence by existence alone | | **Evidence** | A recorded observation, surface, check, result, and independent verdict | New behaviour, structure, or task scope | | **Successor Context** | Findings, changed conditions, and the next bounded Intent | Retrospective mutation of prior Context, Outcome, or Evidence | @@ -92,6 +88,7 @@ which evidence supports its result. - Bind every consumed and produced artifact to an immutable revision or digest; forbid mutable labels as evidence of sameness - Record derivation revisions on consumers; forbid accepting a stale join because its prose still appears plausible - Preserve prior records and append a successor reference; forbid rewriting history to manufacture continuity +- Preserve owner-authored bytes and reconstructable history through migration; a reviewed successor may remove or replace obsolete content with exact provenance. Lossless continuity forbids silent loss, not intentional scoped cleanup ## CID-to-RAO Coverage Seam @@ -113,7 +110,7 @@ execution vocabulary rather than creating a parallel authority model. | Role | Atomic Action | Measurable Outcome | |---|---|---| -| **Operator** | Authorizes one CID revision or phase transition | One exact decision reference bound to the authorized revision | +| **Operator** | Authorizes a bounded objective or exact effect | Decision reference joined to each covered revision or phase transition; exact effect identities remain bound where required | | **Orchestrator** | Derives one bounded set of grounded RAO Steps | One acyclic graph with complete joins and declared bounds | | **Implementer** | Executes one declared Action | Enumerated produced artifacts and recorded results | | **Evaluator** | Evaluates one Outcome against named conditions | One independent verdict with Evidence References and findings | diff --git a/guidelines/agentic-sdlc-autonomous-continuation.md b/guidelines/adlc-autonomous-continuation.md similarity index 73% rename from guidelines/agentic-sdlc-autonomous-continuation.md rename to guidelines/adlc-autonomous-continuation.md index 370f9a10..43704887 100644 --- a/guidelines/agentic-sdlc-autonomous-continuation.md +++ b/guidelines/adlc-autonomous-continuation.md @@ -1,16 +1,16 @@ --- -title: "Agentic SDLC Autonomous Continuation & Interaction Economy" +title: "ADLC Autonomous Continuation & Interaction Economy" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-08-27" +version: "1.1.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Orchestrator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" -provider_neutral: "true" +universal_scope: true +provider_neutral: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- @@ -26,19 +26,27 @@ The normal execution state is progress, not prompting. Human attention is a scar An Operator decision chooses or authorizes an effect. A digest, capability, nonce, command string, confirmation token, or signed receipt is only a transport encoding of that decision. - When an explicit current decision already binds the same subject set, effect class, destructive reach, and externally visible consequence, controllers derive, sign, store, and transport every required machine encoding internally -- A changed source, subject, scope, effect class, destructive reach, target, policy, or externally visible consequence invalidates the prior decision and requires a new one +- Revalidate every changed source, subject, scope, effect class, destructive reach, target, policy, or externally visible consequence against the decision's declared bounds; an effect-bound identity change invalidates that authorization. An in-scope reversible edit covered by the existing objective is not automatically a new decision - A retry, refreshed nonce, regenerated digest, successor capability, or idempotent projection of the unchanged effect is not a new decision - A broad objective is authority for normal in-scope reversible work, verification, and protected integration mechanics; it is not standing authorization for an unspecified irreversible effect or production candidate ## Autonomous Continuation Contract - Continue across read-only discovery, reversible local work, already-authorized protected integration, verification, retry, observation, and idempotent replay while objective, bounds, scope, and evidence agree +- Repair contradicted or missing implementation assumptions in the owning authoring phase within authorized scope, then re-ground and re-derive affected joins; block dependent execution until checks pass. Ask only when evidence leaves an unresolved product choice, scope, or authority decision - Persist the run and resume automatically after context compaction, external waits, transient failures, status requests, and turn boundaries; none cancels the objective - Treat inability to consume a valid recorded decision as an interaction- or authority-adapter defect, not as a new decision; preserve state, continue disjoint safe work, and repair the adapter through the protected path - Ask once for the smallest unresolved semantic decision only after evidence proves it cannot be derived from the specification, current policy, or a still-valid recorded decision - Batch independent decisions that are simultaneously ready; do not serialize avoidable Operator interruptions - Stop when the decision itself is absent at a human gate. Autonomous continuation supplies mechanics and evidence; it never substitutes agent judgment for a reserved human choice +## Bounded Recovery + +- Distinguish a contention race from a deterministic contract rejection: refresh authoritative state and retry a race within the existing bound; diagnose the full violated contract before changing a rejected request +- After the same approach fails twice, correct the earliest wrong owned input or choose another approach; command aliases and new agents do not reset the run-wide attempt budget +- Every external wait names its dependency, condition, timeout or recheck, and escalation path; preserve blocked work and continue disjoint tasks without polling loops or duplicate lanes +- Reuse a live role or disjoint lane when it already covers the task; spawn only for independent useful work within declared capacity. Retire exact completed authorities and clean only receipt-eligible projections + ## Interaction Adapter Contract - Present the decision, current evidence, options, and consequence through the configured interaction adapter diff --git a/guidelines/agentic-sdlc-cloud-collaboration.md b/guidelines/adlc-cloud-collaboration.md similarity index 98% rename from guidelines/agentic-sdlc-cloud-collaboration.md rename to guidelines/adlc-cloud-collaboration.md index bd142c8e..5a80100b 100644 --- a/guidelines/agentic-sdlc-cloud-collaboration.md +++ b/guidelines/adlc-cloud-collaboration.md @@ -1,18 +1,24 @@ --- -title: "Agentic SDLC Cloud-Authoritative Collaboration" +title: "ADLC Cloud-Authoritative Collaboration" doc_type: "Guideline Module" -version: "1.2.0" -date: "2026-08-28" +version: "1.2.1" +date: "2026-09-05" lang: "en-US" schema: "agentic-cloud-collaboration/v1" status: "spec-complete" authority: "provider-neutral protected remote collaboration ledger" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" mutation_policy: "remote claim before shared mutation" +frontmatter_contract: "required" +owner: "Collaboration controller function" +local_rung: "spec-complete" +delivered_rung: "undocumented" +lane: "authoring" +lifecycle_status: "proposed" --- -# Agentic SDLC Cloud-Authoritative Collaboration +# ADLC Cloud-Authoritative Collaboration ## Purpose diff --git a/guidelines/agentic-sdlc-conformance-runtime.md b/guidelines/adlc-conformance-runtime.md similarity index 97% rename from guidelines/agentic-sdlc-conformance-runtime.md rename to guidelines/adlc-conformance-runtime.md index 71cf2d10..fce992d3 100644 --- a/guidelines/agentic-sdlc-conformance-runtime.md +++ b/guidelines/adlc-conformance-runtime.md @@ -1,24 +1,24 @@ --- -title: "Agentic SDLC Behavioral Conformance Runtime Module" +title: "ADLC Behavioral Conformance Runtime Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-07-30" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Conformance evaluator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- -# Agentic SDLC Behavioral Conformance Runtime Module +# ADLC Behavioral Conformance Runtime Module ## Scope and Ownership -This module is universal, neutral, implementation-agnostic, and independently loadable. The main Agentic SDLC Guidelines own behavioral rules and finding names. This module owns the machine boundary that joins operation-derived evidence to deterministic stage verdicts and digest-bound receipts. +This module is universal, neutral, implementation-agnostic, and independently loadable. The main ADLC Guidelines own behavioral rules and finding names. This module owns the machine boundary that joins operation-derived evidence to deterministic stage verdicts and digest-bound receipts. The runtime evaluates evidence; it does not manufacture it. A schema-valid assertion, prose report, screenshot, mutable label, or Implementer verdict is not operation-derived evidence. Evidence producers remain responsible for observing the operation they describe and binding its exact input, output, mechanism, actor role, and result. diff --git a/guidelines/agentic-sdlc-guidelines.md b/guidelines/adlc-guidelines.md similarity index 86% rename from guidelines/agentic-sdlc-guidelines.md rename to guidelines/adlc-guidelines.md index 45ccc54c..6d1fe73c 100644 --- a/guidelines/agentic-sdlc-guidelines.md +++ b/guidelines/adlc-guidelines.md @@ -1,59 +1,60 @@ --- -title: "Agentic SDLC Guidelines" +title: "ADLC Guidelines" doc_type: "Guidelines" -version: "1.24.0" -date: "2026-08-30" +version: "2.0.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Orchestrator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" upstream_blocking_policy: "prevent-not-bypass" lifecycle_status: "proposed" --- -# Agentic SDLC Guidelines +# ADLC Guidelines ## Scope & Neutrality Contract - **Universal**: these guidelines apply to any product, domain, language, or runtime, and to any agent implementation; nothing here assumes a specific company, repository, file path, model, framework, or vendor. - **Neutral**: name agents, roles, and mechanisms by their function, never by a brand. Where a concrete tool is shown, it appears only under a heading or block whose own text contains the words "reference implementation", and may be swapped for any equivalent. - **Agnosticity**: every rule is evaluated from document content and parsed frontmatter only — never from file names, directory layout, or downstream mirrors. Examples use placeholders (`[...]`) rather than real identifiers. - **Simple**: where two mechanisms discharge the same rule at equivalent rigor, the one with fewer moving parts, fewer new concepts, and fewer configurable knobs is conformant and the other is not required; a rule that a plain check can discharge must never be discharged by a bespoke framework instead. -- **Modular**: each `##` section is self-contained and addressable by its heading anchor (see Module Index). Sections may be lifted into another guideline set without rewriting their internals. +- **Modular, reusable, interoperable, portable**: sections are addressable by stable anchors; share one CID/RAO/SVO contract and typed evidence joins across tools, devices, and runtimes. Adapt transports and providers without copying policy or introducing another controller. - **Enforceable**: every rule is written so a conformance check can record a typed finding against it (see Execution Conformance Findings). A statement that cannot be violated observably is guidance, not a rule, and is labelled as such. - **Complementary**: this set owns **execution**. Authoring — what a PRD, TAD, or ADR must contain, the Readiness Ladder, the Rule ID scheme, and the authoring-domain finding vocabulary — is owned by the **PRD, TAD & ADR Guidelines** companion set. This set does not restate those rules; it names them and consumes them. - **Adaptive**: rules scale their evidence to the size and kind of the change, and the artifact chain may collapse or reorder its phases, but a rule never adapts away the obligation it encodes. Scaling evidence is conformant; eliding a coverage obligation, a bound, an independent verdict, or a gate is not. - **Autonomous**: after the Operator supplies an objective, scope, bounds, and the capabilities needed to act, the Orchestrator continues through every safe, in-scope, dependency-ready step without requesting clerical confirmation. It derives and transports machine tokens, digests, commands, retries, and idempotent continuations internally. Autonomy never invents a missing product choice, widens scope or capability, crosses a promotion boundary, or authorizes a new irreversible effect. +**Reference implementation**: [Agentic OS ADLC](https://github.com/huijoohwee/agentic-os/blob/main/docs/adlc-guidelines.md) owns its lifecycle controller; consumers retain product and target policy and reference its start/release workflows. This guideline defines contracts, not another controller. ## Module Index - `scope--neutrality-contract` — universality, neutrality, agnosticity, modularity, enforceability, complementarity rules - `boundary-with-the-authoring-set` — what this set owns, what it consumes, and where the seam sits - `agent-roles--independence` — the four execution roles and the independence rule that must not collapse - `specification-to-task-bridge` — how baselined documents become an executable task list - `task-model` — task identity, minimum-resource core-value granularity, dependency graph, orchestration-reasoned completion-time estimation, and state vocabulary -- [Scoped Concurrent Lane Admission](./agentic-sdlc-scoped-lane-admission.md) — additive authoring admission, authoritative write-scope comparison, remote fencing, and preservation proof +- [Scoped Concurrent Lane Admission](./adlc-scoped-lane-admission.md) — additive authoring admission, authoritative write-scope comparison, remote fencing, and preservation proof - `execution-contract` — what an agent receives, what it must surface, and what closes a task - `tool-permission--blast-radius` — capability classes, escalation, and irreversibility rules - `per-task-budgets` — token, iteration, wall-clock, and context bounds per task - `verification-strategy` — test obligations, property-based testing, and evidence emission - `checkpoint--recovery` — resumability, compaction survival, and partial-failure handling -- [Autonomous Continuation & Interaction Economy](./agentic-sdlc-autonomous-continuation.md) — bounded autonomous progress, decision-versus-transport separation, and minimum necessary Operator interruption +- [Autonomous Continuation & Interaction Economy](./adlc-autonomous-continuation.md) — bounded autonomous progress, decision-versus-transport separation, and minimum necessary Operator interruption - `human-in-the-loop-gates` — which decisions an agent must not make alone - `global-release-control-rule` — universal control boundary for every enrolled repository and deployment target - `dependency-ordered-integration` — canonical-frontier planning, no-op detection, dependency waves, and exact integration closure - `atomic-lane-convergence` — one externally simple controller for integration, preservation, recovery, retirement, and minimal active-lane closure through modular adapters -- [Proportionate Closeout](./agentic-sdlc-proportionate-closeout.md) — least-powerful outcome selection, disjoint progress, exact evidence reuse, and retained cleanup -- [End-to-End Production Release Lifecycle](./agentic-sdlc-production-release-lifecycle.md) — provider-neutral release frontiers, adapter ports, joined receipts, exact authorization, state reconciliation, transport-separated verification, rollback, publication, and cleanup +- [Proportionate Closeout](./adlc-proportionate-closeout.md) — least-powerful outcome selection, disjoint progress, exact evidence reuse, and retained cleanup +- [End-to-End Production Release Lifecycle](./adlc-production-release-lifecycle.md) — provider-neutral release frontiers, adapter ports, joined receipts, exact authorization, state reconciliation, transport-separated verification, rollback, publication, and cleanup - `runtime-readiness-enforcement` — fail-closed derivation of layer-specific runtime claims from joined evidence, with the repository audit profile in the companion module -- `upstream-dependency-admission` — companion module for early admission, bounded deferral, and disjoint-work continuation +- [Upstream Dependency Admission](./adlc-upstream-dependency-admission.md) — early admission, bounded deferral, and disjoint-work continuation - `execution-conformance-findings` — the execution-domain finding vocabulary and severities - `execution-load-budget` — phase-scoped loading of this set -- [Rapid MVP Sprint Profile](./agentic-sdlc-rapid-mvp-sprint.md) — reference-implementation phase-collapse mapping for a declared, time-boxed sprint clock, and what a collapse may never elide +- [Rapid MVP Sprint Profile](./adlc-rapid-mvp-sprint.md) — reference-implementation phase-collapse mapping for a declared, time-boxed sprint clock, and what a collapse may never elide - `validation-checklist` — pre-execution, per-task, and post-run gates -- [Execution Anti-Pattern Guards](./agentic-sdlc-anti-pattern-guards.md) — prohibited execution patterns and their corrections +- [Execution Anti-Pattern Guards](./adlc-anti-pattern-guards.md) — prohibited execution patterns and their corrections - `mantra-application` — the framing mantra -- [Cloud-Authoritative Collaboration](./agentic-sdlc-cloud-collaboration.md) — provider-neutral multi-device claims, fencing, offline admission, and remote runtime-readiness -- [Specification Chain](./agentic-sdlc-specification-chain.md) — artifact roles, the requirements-design-tasks seams, re-derivation cascade, phase-advance authority, and seam-preserving adaptation; [Artifact Continuity](./agentic-sdlc-artifact-continuity.md) — CID-to-RAO coverage, companion-artifact joins, outcome evidence, revision freshness, and successor feedback +- [Cloud-Authoritative Collaboration](./adlc-cloud-collaboration.md) — provider-neutral multi-device claims, fencing, offline admission, and remote runtime-readiness +- [Specification Chain](./adlc-specification-chain.md) — artifact roles, the requirements-design-tasks seams, re-derivation cascade, phase-advance authority, and seam-preserving adaptation; [Artifact Continuity](./adlc-artifact-continuity.md) — CID-to-RAO coverage, companion-artifact joins, outcome evidence, revision freshness, and successor feedback - `specification-chain-phases` — the mandatory execution seam over that chain ## Boundary with the Authoring Set The two sets meet at a single seam: **a baselined document pair with derived VCCs on one side, an executable task list with recorded Evidence References on the other.** @@ -64,7 +65,7 @@ The two sets meet at a single seam: **a baselined document pair with derived VCC | Rule ID scheme and artifact-bearing classification | Authoring set | Reuses unchanged for execution rules | | Finding recording contract, severities, determinism | Authoring set | Reuses unchanged; extends the type enumeration only | | VCC primitive and Evidence Reference shape | Authoring set | Produces Evidence References during execution | -| Pain-point-to-monetization ranking of candidate VCCs (provable demand, solution, feature, time-to-first-dollar) | Authoring set | Consumes the resulting order; breaks ties among equally-ready candidates locally per Task Model's Granularity, with the reasoning trail recorded | +| Pain-point-to-monetization ranking of candidate VCCs (validated pain, evidenced WTP, reusable solution, feature, time-to-first-dollar) | Authoring set | Consumes the resulting order; breaks ties among equally-ready candidates per Task Model's Granularity, with the reasoning trail recorded | | Diagram identity, class, notation, and canvas projection rules | Authoring set's diagram companion modules | Obeys; emits the projection check result as an Evidence Reference | | Lane topology and Deploy Boundary | Authoring set | Obeys; never promotes across a boundary | | CID-to-RAO artifact continuity | Shared continuity module | Verifies joined planning, authoring, execution, demonstration, and successor references | @@ -76,11 +77,11 @@ The two sets meet at a single seam: **a baselined document pair with derived VCC | Execution-to-release handoff | **This set** | Emits an Integration Receipt; never promotes | | Release orchestration and delivery adapters | Lifecycle controller | Consumes the receipt only after execution closes | **Directives**: -- Treat a baselined document pair with zero open `blocker` findings, including a current Codebase Grounding Record for every externally authored, generated, or imported specification input, as the entry precondition for execution; reject dispatch when a material current-state claim used to justify baseline, execution, or readiness is `contradicted`, `absent`, or `unverified`, and return the conflict to the authoring loop rather than repairing it downstream +- Require a baselined document pair with zero open `blocker` findings and a current Codebase Grounding Record for each non-native specification input. A material claim marked `contradicted`, `absent`, or `unverified` blocks only dependent execution; return it to the authoring loop, correct and re-ground within existing authorized scope, and re-derive affected joins before dispatch. Escalate only a product, scope, or authority decision that remains unresolved; never present planned capabilities as existing ones - Reuse the authoring set's Rule ID derivation and finding recording contract verbatim; forbid a second, parallel conformance vocabulary - Forbid either set redefining a Finding Type the other owns; the conformance vocabulary is the union of the two enumerations - Name the companion set wherever a rule crosses the seam; forbid an execution rule that silently assumes an authoring rule the reader has not been pointed at -- Apply the Artifact Continuity companion to every authoring-to-execution handoff; forbid dispatch from an unjoined or stale CID-to-RAO lineage +- Apply the Artifact Continuity companion and shared [CID/RAO/SVO grammar](./cid-guidelines.md) to each authoring-to-execution handoff; forbid parallel schemas or dispatch from an unjoined or stale lineage - Close execution with a verified Integration Receipt before invoking a release controller; forbid an Implementer task from preparing, authorizing, or deploying a release ## Agent Roles & Independence Four execution roles. Roles are **functions**, not people and not necessarily separate processes — except where the independence rule says otherwise. @@ -95,20 +96,19 @@ Four execution roles. Roles are **functions**, not people and not necessarily se - Independence is **mechanical**, not organisational: a deterministic check, a hook, or a separate evaluating process satisfies it; a different job title applying the same judgement does not - A solo operator satisfies the rule by delegating the verdict to a check they do not adjudicate, and violates it by reading their own output and declaring it done - The Implementer may collapse into the Orchestrator only where the Orchestrator performs no judgement; forbid an Orchestrator that both implements and marks complete -- The Operator never collapses into any other role, because an inferred approval is not an approval - A verdict produced by the Implementer about its own task is a `self-graded-verdict` finding at `blocker` severity, regardless of how convincing the output reads **Directives**: - Name the mechanism that discharges the Evaluator role before execution starts; forbid execution with an unnamed evaluator - Route every completion verdict through the Evaluator; forbid a task transitioning to a terminal success state on the Implementer's assertion alone - Record which role produced every state transition, so a self-graded verdict is detectable after the fact rather than only in the moment ## Specification Chain Phases -The separately loadable [Specification Chain Module](./agentic-sdlc-specification-chain.md) owns the complete reusable protocol for the three artifact roles — requirements, design, task list — the two coverage seams between them, the re-derivation cascade, phase-advance authority, and seam-preserving adaptation. This section owns its mandatory execution seam. +The separately loadable [Specification Chain Module](./adlc-specification-chain.md) owns the complete reusable protocol for the three artifact roles — requirements, design, task list — the two coverage seams between them, the re-derivation cascade, phase-advance authority, and seam-preserving adaptation. This section owns its mandatory execution seam. A specification reaches this set as a chain, not as a single document. Execution consumes the task list, but a task list is only trustworthy to the degree its upstream seams are closed. **Directives**: - Verify both chain seams are closed before dispatching any task derived from them; an uncovered criterion is an `undesigned-criterion` and an ungrounded design element is an `ungrounded-design-element` - Reject a task list whose upstream artifact revision no longer matches the artifact it was derived from; a stale downstream artifact is a `stale-downstream-artifact` and re-derivation precedes dispatch - Forbid an execution task deciding structure or introducing behaviour absent upstream; either is a `requirement-introduced-downstream` at `blocker` severity and returns to the owning phase -- Require a recorded Operator decision for each seam crossing before execution starts; an unapproved crossing is a `phase-advanced-without-approval` and an absent decision is a `blocked` state +- Bind each seam crossing to a recorded Operator decision covering its scope and effect, plus independent coverage checks; reuse that decision for authorized reversible transitions. An uncovered decision remains `phase-advanced-without-approval`; new scope, product choices, irreversible effects, or promotion require their own authority - Permit a collapsed or reordered chain only where both seams still carry joins; a missing coverage obligation is a `seam-elided` at `blocker` severity, however small the change ## Specification to Task Bridge The authoring set ends at a baselined pair with derived VCCs. Execution begins at a task list. The bridge is a **derivation**, not a fresh authoring act. @@ -131,7 +131,7 @@ Task ID = [hierarchical ordinal within the task list, maximum two levels] - Limit hierarchy to two levels: a task and its sub-tasks; forbid a third level, which trades comprehensibility for the illusion of precision - Record the Task ID on every state transition, every Evidence Reference, and every finding raised during that task ### Collaboration Identity & Scoped Lane Admission -Every writer is identified by the tuple; [Cloud-Authoritative Collaboration](./agentic-sdlc-cloud-collaboration.md) owns protected remote claims, while [Scoped Concurrent Lane Admission](./agentic-sdlc-scoped-lane-admission.md) owns the decision to add one isolated lane without touching existing lanes: +Every writer is identified by the tuple; [Cloud-Authoritative Collaboration](./adlc-cloud-collaboration.md) owns protected remote claims, while [Scoped Concurrent Lane Admission](./adlc-scoped-lane-admission.md) owns the decision to add one isolated lane without touching existing lanes: ``` Actor ID + Device ID + Session ID + Worktree ID + Branch ID + Scope ID + Lease Epoch + Fence Revision ``` @@ -139,7 +139,7 @@ Actor ID + Device ID + Session ID + Worktree ID + Branch ID + Scope ID + Lease E - Expose exactly four provider-neutral root operations: `claim(scope)`, `continue(claim)`, `integrate(candidate)`, and `retire(claim)`; each emits a typed digest-bound receipt, and adapters must not add authority-bearing aliases or compatibility operations - Define a cross-repository coordination task as a dependency-ordered group of immutable per-repository work units; every unit retains its own repository, branch, worktree, semantic scope, claim, epoch, fence, PR/review identity, named checks, and handoff evidence - Treat dependency edges as the group's only ordering authority; a shared task identity or semantic label never creates a shared branch, worktree, lease, claim, fence, review identity, or handoff -- Permit policy-unbounded but operationally bounded concurrent current authorities for disjoint normalized write sets, meaning unlimited concurrent current authorities for disjoint normalized write sets at the policy layer: each repository adapter declares and enforces its current resource, evaluator, and coordination capacity, and exactly one current write authority remains permitted per overlapping declared write set; equivalently, exactly one current write authority per overlapping declared write set. Authenticate each authority, while local worktrees, leases, PRs, processes, and provider metadata remain replaceable projections. Classify each lane as `canonical`, `overlapping`, `disjoint-attributed`, or `ambiguous`, where an overlapping newcomer is a non-writing waiting successor and undeclared or unparseable future scope is `ambiguous` and cannot create authority +- Permit policy-unbounded concurrency for disjoint normalized write sets within declared resource, evaluator, and coordination capacity; exactly one current write authority owns an overlapping write set. Authenticate each authority; worktrees, leases, PRs, processes, and provider metadata are replaceable projections. Classify lanes as `canonical`, `overlapping`, `disjoint-attributed`, or `ambiguous`; an overlapping newcomer waits without writing, and ambiguous scope cannot create authority - Separate the append-only ledger's physical audit head from the semantic claim-conflict fence: derive a bounded conflict-set digest from the immutable claim subject, normalized write scope, current policy and canonical evidence, and only overlapping, same-work-item, predecessor, or successor lineages. Exclude provider ordering, observation time, retry count, the global head itself, and unrelated disjoint transitions; global-head movement alone is never a claim conflict and claim admission never requires exact global-ledger parity or inactivity - Re-evaluate a claim dynamically after every compare-and-swap loss or authoritative refresh. Return an existing receipt for an exact idempotent replay; attempt or boundedly re-parent the same frozen transition when the conflict set is unchanged; apply current overlap policy to an unsealed request; and return a typed fail-closed conflict requiring replan when the relevant conflict set, immutable subject, policy, canonical evidence, ancestry, or scope becomes changed, missing, or ambiguous. Every outcome preserves existing lanes and bytes, and adapters may change transport but not this decision - `claim(scope)` admits only an exact clean canonical base, normalized declared scope, authenticated actor, no competing overlap, and a monotonic compare-and-swap transition; failure leaves every existing lane and the requester unchanged @@ -159,14 +159,14 @@ Actor ID + Device ID + Session ID + Worktree ID + Branch ID + Scope ID + Lease E - Treat `origin/main` as the only shared canonical branch state; forbid treating a private branch or unpushed local `main` commit as published source of truth - Treat local `main` as the canonical synchronization lane, not the default long-lived authoring lane; normal task authoring belongs in an admitted temporary branch derived from a clean canonical base - If local authoring starts on `main`, preserve the exact authored bytes by moving them into one isolated lane before the next ordinary commit, review, or publication step, then restore local `main` to exact parity -- Remove merged temporary task branches only after verified integration, canonical parity, and value-closure proof are all established +- Retain or remove temporary branches according to the declared profile and exact authorized cleanup receipt; verified integration, canonical parity, and value closure establish eligibility, never implicit deletion authority ### Granularity A well-sized task follows the universal minimum-time-and-resource / maximum-core-value chain: `highest-ranked baselined core VCC (or coherent group) → smallest dependency-closed mandatory obligation set → narrowest sufficient mechanism → independent verification → stop or select the next ranked core VCC`, within one per-task budget. -**What "highest-ranked" resolves against**: a VCC's core value traces back to a pain point → solution → feature → monetization chain — a pain point evidenced by provable demand (a named prospective payer, not a hypothesized one), the solution it justifies, the feature ranked by proximity to code already shipped (zero or minimal change outranks a rewrite of comparable scope), and the fastest path to a first real dollar. The authoring set fixes this order wherever it can; execution never re-derives it from scratch. Where a wave still admits more than one ready candidate for the same budget, break the tie locally and in this fixed sequence, never as three independent votes: -1. **Constraint satisfaction** first removes any candidate that would violate a hard bound — a stated budget, a FOSS or platform gate, a Deploy Boundary — before ranking runs at all. -2. **Outranking** then eliminates a surviving candidate that is no worse than another on every remaining criterion and strictly worse on at least one. -3. **Argumentation** settles what outranking leaves tied, by weighing each surviving candidate's stated reason against its stated counter-reason and keeping the one whose reason survives attack. +**What "highest-ranked" resolves against**: consume the authoring set's pain point → solution → feature → monetization order: validated pain and evidenced willingness-to-pay (WTP), the nearest reusable solution, and the shortest credible path to a first paid outcome. A prospective payer or price signal is not collected revenue. For equally-ready candidates, reuse its bounded **Constraints ↔ Argumentation ↔ Outranking** pipeline: +1. **Constraints** exclude violations of stated hard bounds before comparison; arguments or scores cannot waive a failed bound. +2. **Outranking** preserves partial orders and eliminates a dominated candidate when another is no worse on every relevant criterion and strictly better on at least one; other methods consume the authoring contract's recorded relation. +3. **Argumentation** challenges supporting evidence, assumptions, and unresolved comparisons. Changed evidence reopens only affected constraints and comparisons within the existing budget; independent evaluation closes a supported choice or records the unresolved decision. | Signal | Too small | Right-sized | Too large | |---|---|---|---| | VCC coverage | Fraction of one VCC | One VCC, or a coherent group | Spans unrelated VCCs | @@ -177,7 +177,7 @@ A well-sized task follows the universal minimum-time-and-resource / maximum-core - Before dispatch, record the selected core VCCs, mandatory obligations, named completion check, projected elapsed time and resource consumption, and any known conforming alternative; classify the selection as an `oversized-task` when an alternative delivers at least the same verified core value with no more time or resources and less of at least one - Split a task that exceeds its budget rather than raising the budget; a persistent overrun or Pareto-dominated path is a decomposition defect, and adaptation may collapse or reorder mechanisms but never elide a mandatory obligation - Forbid a task with no verifiable outcome and forbid over-investing in non-core periphery: defer work untraced to the selected core VCCs or a specification- or policy-required correctness, safety, security, privacy, accessibility, legal, operability, recovery, evidence, or gate obligation; unused budget never authorizes it, and it resumes only after the authoring loop baselines its marginal core value above projected time and resource cost. Documentation-only tasks state the artifact and conforming check -- Record the tie-break trail wherever a wave admits more than one ready candidate for the same budget: which candidates constraint satisfaction removed, which outranking eliminated, and the argumentation exchange that settled the remainder; an unrecorded choice among competing ready candidates is a `ranking-rationale-absent` finding +- Record one compact tie-break trail: failed constraints, pairwise relations, contested evidence, and the independent verdict. Reuse unchanged evidence; avoid duplicate worksheets or agents for a decided comparison. Missing rationale is `ranking-rationale-absent`; inconclusive reasoning stops at its bound while disjoint work continues #### Reference implementation — zero-infra tie-breaker profile Any repository profile may declare its own tie-breaker criteria in place of these; they are shown only as a concrete example, per the Scope & Neutrality Contract, and carry no universal authority. - Prefer the mechanism runnable in a browser or at the edge over one requiring dedicated infrastructure, and the offline-capable mechanism over one requiring a live connection @@ -251,12 +251,12 @@ Capability is granted per task, not per session, and scales to reversibility. | **Local write** | Create or edit an artifact inside the task's declared scope | Granted per task with scope stated | Reversible via version control | | **Local execute** | Run a build, a test, a linter, a formatter | Granted per task | Reversible | | **Environment mutate** | Install a dependency, change configuration, alter shared local state | Granted per task with the change stated in advance | Recoverable with effort | -| **Irreversible** | Delete beyond a single declared artifact, rewrite history, mass-modify, drop persistent state | **Requires an Operator decision per occurrence** | Not reversible | +| **Irreversible** | Unrecoverable deletion, persistent-state destruction, irreversible external commitment | **Requires an Operator decision binding the exact effect envelope** | Not reversible | | **Boundary-crossing** | Anything that mutates a mirror or delivery surface, or transmits project content outward | **Forbidden during execution** | Out of scope | **Directives**: - Grant the narrowest class that completes the task; forbid granting a class the task does not name a use for - Forbid self-escalation: an Implementer that needs a wider class returns `blocked` with the reason, and the Orchestrator re-dispatches with a new grant. Widening a grant mid-task is a `self-escalated-capability` finding at `blocker` severity -- Require an explicit Operator decision per irreversible operation; forbid a standing or session-scoped approval for irreversibility, because a standing approval is indistinguishable from no gate +- Require an explicit Operator decision for each distinct irreversible effect envelope; propagate its receipt across unchanged idempotent continuations. A session or broad objective never authorizes unspecified irreversibility - Forbid boundary-crossing capability in any task; promotion is the Deploy Boundary's job, and a task that reaches a delivered surface is a `deploy-boundary-breach` under the authoring set's enumeration - Forbid transmitting project content, credentials, or user data to an external endpoint during execution unless the Operator requested that specific transmission - State the declared write scope before dispatch; a write outside it is an `out-of-scope-write` finding @@ -285,22 +285,22 @@ Execution produces the Evidence References the Readiness Ladder consumes. Weak v ### Obligations Per Task - Every task states its **named check** before dispatch, phrased as it is invocable -- Every code-bearing task adds or extends automated tests covering the behaviour it introduces -- Every bug-fixing task first adds a check that fails on the unfixed state; a fix with no failing-first check is a `fix-without-witness` finding -- Every task runs the project's existing verification lane, not only its own new check; a task that passes its own check while breaking a neighbour's is a regression the Evaluator must see +- Every behavior-changing task supplies a meaningful automated check; extend tests only where existing coverage cannot falsify the changed behavior. Prose, naming, or reversible refactoring may use existing focused conformance checks +- Every bug fix records a reproducible behavioral witness and its corrected result, using an existing or new check as appropriate; a code defect without that witness is `fix-without-witness`. Do not add tests that merely restate a prose edit or implementation detail +- Run the repository's required verification lane and checks for affected risks; reuse valid evidence for unchanged immutable inputs. Broaden testing only for a concrete remaining risk or required gate ### Property-Based Obligations Example-based tests confirm the cases an author imagined. Properties confirm the ones they did not. - Derive a property from every correctness property stated in the specification; a stated property with no executable test is an `unproven-property` finding -- Pair every parser or serialiser with a round-trip property; forbid asserting round-trip fidelity by example alone +- Where the specification claims parser or serialiser round-trip fidelity, prove that property over its declared input domain; a lossy transform must state its different invariant - Pair every ordering, dedup, or aggregation rule with an invariant or metamorphic property - State each property's class explicitly — round trip, invariant, metamorphic, idempotence, confluence, error condition — so coverage gaps are visible by class rather than by count - Set a minimum iteration count per property and keep shrinking enabled; a property run once is an example test wearing a costume ### Evidence Emission - Emit one Evidence Reference per satisfied VCC, carrying the named check, the recorded result, and the surface (always `authoring` during execution) -- Forbid emitting an Evidence Reference for a check that was not run in this task +- Emit evidence only for an observed check result; reuse it by exact input, policy, and revision reference when still valid, never by unverified recollection - Forbid an Evidence Reference whose recorded result is an assertion that a result exists - For a task that adds or changes a diagram, run the projection check named by the authoring set's canvas-render contract and surface its node, edge, and cluster counts plus zero cost fields; a visual confirmation is not a recorded result, and a non-projecting class records zero rather than omitting the counts ## Checkpoint & Recovery @@ -317,7 +317,7 @@ Long runs outlive working context. A run that cannot resume is a run that must r ## Autonomous Continuation & Interaction Economy -The canonical [Autonomous Continuation & Interaction Economy](./agentic-sdlc-autonomous-continuation.md) module owns bounded autonomous progress, decision-versus-transport separation, adapter behavior, findings, and verification. Execution consumes it by reference; this seam does not duplicate its rules. +The canonical [Autonomous Continuation & Interaction Economy](./adlc-autonomous-continuation.md) module owns bounded autonomous progress, decision-versus-transport separation, adapter behavior, findings, and verification. Execution consumes it by reference; this seam does not duplicate its rules. ## Human-in-the-Loop Gates @@ -329,8 +329,8 @@ Some decisions an agent must not make alone, regardless of confidence. | **Irreversible operation** | Any Irreversible capability class operation | Return `blocked` with the exact operation stated | | **Boundary promotion** | Any movement toward a mirror or delivery surface | Refuse inside execution; emit or consume the explicit lifecycle receipt at the release seam | | **Production authorization** | One immutable candidate and its controlled review surface still prove runtime readiness | Revalidate the exact source, dependency closure, probes, candidate, release-run reference, and review-surface locator before requiring an authenticated human to answer the exact candidate-and-target challenge | -| **Specification defect** | A VCC is unsatisfiable, contradictory, or self-contradictory | Return `blocked` with the contradiction quoted | -| **Budget re-authorisation** | A bound is exhausted and the work is genuinely larger than estimated | Return `failed` with consumption; re-decomposition or re-authorisation is an Operator decision | +| **Specification defect** | A VCC is unsatisfiable or contradictory | Block the affected transition; repair and re-ground in the authorized authoring loop, or surface the exact unresolved product/scope decision | +| **Budget re-authorisation** | A bound is exhausted and work remains | Record consumption; split or replan within unchanged run bounds autonomously. Raised bounds, new scope, or an uncovered effect require an Operator decision | | **Repeated failure** | The same approach failed twice | Diagnose, state the root cause, and switch approach; escalate on the third distinct failure rather than continuing to vary details | **Directives**: @@ -357,7 +357,7 @@ Every repository and deployment target governed by this set is subject to one gl This rule is adaptive only in its adapter and evidence scale. It does not require a shared repository host, branch convention, deployment provider, or release cadence, and it never lets a smaller change bypass the control boundary. ## Dependency-Ordered Integration -The separately loadable [Dependency-Ordered Integration Module](./agentic-sdlc-integration-order.md) owns the complete reusable protocol. This section owns its mandatory execution seam. +The separately loadable [Dependency-Ordered Integration Module](./adlc-integration-order.md) owns the complete reusable protocol. This section owns its mandatory execution seam. ``` Integration Unit = immutable change identity + write scope + dependency set + named checks + runtime impact @@ -381,7 +381,7 @@ Integration Frontier = exact canonical revisions + exact transitive dependency c - Seal one release frontier only after every unit is terminal and every dependency identity matches; a candidate from an earlier frontier is `stale-candidate-frontier` ## Atomic Lane Convergence -One atomic top-level convergence controller owns a logical work unit from observed inventory to terminal closure. Its externally stable contract remains provider-, repository-, branch-, workspace-, and deployment-agnostic, with replaceable internal phase adapters that never become separately authorized top-level controllers. The separately loadable [Proportionate Closeout Module](./agentic-sdlc-proportionate-closeout.md) owns requested-outcome selection, the source-integrated fast path, immutable evidence reuse, and `integrated-retained`; this section retains convergence, preservation, authority, and no-discard invariants. +One atomic top-level convergence controller owns a logical work unit from observed inventory to terminal closure. Its externally stable contract remains provider-, repository-, branch-, workspace-, and deployment-agnostic, with replaceable internal phase adapters that never become separately authorized top-level controllers. The separately loadable [Proportionate Closeout Module](./adlc-proportionate-closeout.md) owns requested-outcome selection, the source-integrated fast path, immutable evidence reuse, and `integrated-retained`; this section retains convergence, preservation, authority, and no-discard invariants. ``` Convergence = stable plan identity + bounded effect authorization + atomic authority continuation + minimal active set + terminal receipt @@ -401,7 +401,7 @@ Stable Plan Identity = intended effect class + exact subject set + immutable val - Emit one terminal receipt binding plan and authorization identities, canonical remote/local revisions, zero file delta, final minimal inventory, removed and retained projections, recovery locators, untouched out-of-scope work, and every adapter effect; closure requires the canonical local ref equals the canonical remote ref and no requested effect remains pending ## End-to-End Release Lifecycle Protocol -The separately loadable [End-to-End Production Release Lifecycle Module](./agentic-sdlc-production-release-lifecycle.md) owns the complete reusable protocol only when sealed intent includes delivery or publication; source integration alone neither loads nor invokes it. This section owns its mandatory execution seam. +The separately loadable [End-to-End Production Release Lifecycle Module](./adlc-production-release-lifecycle.md) owns the complete reusable protocol only when sealed intent includes delivery or publication; source integration alone neither loads nor invokes it. This section owns its mandatory execution seam. **Directives**: - Treat protected integration as Integration Receipt authority only; it never creates forward-deployment authority @@ -413,7 +413,7 @@ The separately loadable [End-to-End Production Release Lifecycle Module](./agent - Publish mirrors only after the Live Verification Receipt exists; remove only clean, integrated, completion-proven task lanes, preserve unrelated work, and require the repository-owned deterministic evaluator to exit zero only for a joined terminal receipt chain ## Runtime Readiness Enforcement -Runtime readiness is a derived claim over one immutable execution input and its joined evidence; never infer it from document status, source existence, review labels, or delivery state. The separately loadable [Behavioral Conformance Runtime Module](./agentic-sdlc-conformance-runtime.md) owns the stage-gate evidence and receipt contract; the [Repository Runtime Readiness Module](./agentic-sdlc-repository-runtime-readiness.md) owns the bounded local-first repository audit profile. +Runtime readiness is a derived claim over one immutable execution input and its joined evidence; never infer it from document status, source existence, review labels, or delivery state. The separately loadable [Behavioral Conformance Runtime Module](./adlc-conformance-runtime.md) owns the stage-gate evidence and receipt contract; the [Repository Runtime Readiness Module](./adlc-repository-runtime-readiness.md) owns the bounded local-first repository audit profile. - Require typed inputs and outputs, bounded orchestration, independent evaluation, named checks with recorded results, cost and fallback evidence, and closed mutation and deployment gates before deriving `runtime-ready` - Bind one immutable source revision and its complete dependency closure; drift invalidates the claim and returns the affected unit to `blocked` @@ -504,16 +504,16 @@ The **execution-domain** half of the conformance vocabulary. The recording contr | Stage | Sections to load | |---|---| | Run start | `boundary-with-the-authoring-set`, `agent-roles--independence`, `specification-chain-phases`, `specification-to-task-bridge` | -| Chain seam check | `specification-chain-phases`, [Specification Chain](./agentic-sdlc-specification-chain.md) | +| Chain seam check | `specification-chain-phases`, [Specification Chain](./adlc-specification-chain.md) | | Task derivation | `specification-to-task-bridge`, `task-model` | -| Lane admission | `task-model`, [Scoped Concurrent Lane Admission](./agentic-sdlc-scoped-lane-admission.md), [Cloud-Authoritative Collaboration](./agentic-sdlc-cloud-collaboration.md) | +| Lane admission | `task-model`, [Scoped Concurrent Lane Admission](./adlc-scoped-lane-admission.md), [Cloud-Authoritative Collaboration](./adlc-cloud-collaboration.md) | | Dispatch | `task-model`, `execution-contract`, `tool-permission--blast-radius`, `per-task-budgets`, `autonomous-continuation--interaction-economy` | | Implementation | `execution-contract`, `verification-strategy`, `tool-permission--blast-radius`, `autonomous-continuation--interaction-economy` | | Verification | `verification-strategy`, `execution-conformance-findings` | | Recovery | `checkpoint--recovery`, `autonomous-continuation--interaction-economy` | | Escalation | `autonomous-continuation--interaction-economy`, `human-in-the-loop-gates` | -| Protected source integration | [Proportionate Closeout](./agentic-sdlc-proportionate-closeout.md), `dependency-ordered-integration`, `atomic-lane-convergence`, `autonomous-continuation--interaction-economy`, `human-in-the-loop-gates` | -| Production or publication handoff | [Proportionate Closeout](./agentic-sdlc-proportionate-closeout.md), `dependency-ordered-integration`, `atomic-lane-convergence`, [End-to-End Production Release Lifecycle](./agentic-sdlc-production-release-lifecycle.md), `autonomous-continuation--interaction-economy`, `human-in-the-loop-gates` | +| Protected source integration | [Proportionate Closeout](./adlc-proportionate-closeout.md), `dependency-ordered-integration`, `atomic-lane-convergence`, `autonomous-continuation--interaction-economy`, `human-in-the-loop-gates` | +| Production or publication handoff | [Proportionate Closeout](./adlc-proportionate-closeout.md), `dependency-ordered-integration`, `atomic-lane-convergence`, [End-to-End Production Release Lifecycle](./adlc-production-release-lifecycle.md), `autonomous-continuation--interaction-economy`, `human-in-the-loop-gates` | | Any stage | `scope--neutrality-contract`, `module-index` | **Directives**: @@ -521,7 +521,7 @@ The **execution-domain** half of the conformance vocabulary. The recording contr - Record this set's load cost in the per-run token total alongside the authoring set's; the cost of governing the work is part of the cost of the work - Load `rapid-mvp-sprint-profile` at Run start alongside the roles and bridge sections whenever a Sprint Clock is declared; skip it entirely otherwise ## Rapid MVP Sprint Profile -The optional [Rapid MVP Sprint Profile](./agentic-sdlc-rapid-mvp-sprint.md) module owns the provider-neutral compression map, Sprint Clock directives, and critical-path reforecast. It is a reference implementation, not universal authority; no phase collapse may elide an obligation. +The optional [Rapid MVP Sprint Profile](./adlc-rapid-mvp-sprint.md) module owns the provider-neutral compression map, Sprint Clock directives, and critical-path reforecast. It is a reference implementation, not universal authority; no phase collapse may elide an obligation. ## Validation Checklist **Pre-Execution**: - [ ] **Frontmatter present** with baseline and conformance keys; `owner` declared; `local_rung` and `delivered_rung` separate @@ -543,7 +543,7 @@ The optional [Rapid MVP Sprint Profile](./agentic-sdlc-rapid-mvp-sprint.md) modu **Per-Task**: - [ ] Named check run and its recorded result surfaced -- [ ] Existing verification lane run, not only the task's own check +- [ ] Required verification lane and affected behavior checks satisfied; reused evidence binds unchanged immutable inputs - [ ] Artifacts changed enumerated, including incidental changes - [ ] Budget consumption recorded against all four bounds - [ ] Verdict issued by the Evaluator, never the Implementer @@ -565,14 +565,14 @@ The optional [Rapid MVP Sprint Profile](./agentic-sdlc-rapid-mvp-sprint.md) modu - [ ] **Integration order closed**: every unit is terminal, dependencies preceded consumers, no equivalent or superseded unit was re-merged, and exact-canonical checks advanced each frontier - [ ] **Protected review metadata exact**: the repository-owned review-request template is instantiated, the current canonical base revision is recorded, and the declared scope token equals the admitted semantic scope and any projected branch-scope segment - [ ] **Runtime and release frontiers agree**: every runtime-impacting unit converged before candidate sealing, and the candidate binds the final dependency closure -- [ ] **Authorization prompt runtime-ready**: candidate, source, release run, and controlled review-surface locator are revalidated from the current Runtime Review Receipt before the prompt is emitted; the prompt identifies its canonical portable formatter as `agentic-canvas-os/scripts/production-release-authorization-contract.mjs` and, directly after its loopback locator, prints the runtime-resolved local formatter source path +- [ ] **Authorization prompt runtime-ready**: candidate, source, release run, and controlled review surface are revalidated from the current Runtime Review Receipt; the configured interaction adapter's identity, revision, and evidence are recorded, and the prompt presents the exact decision and consequence - [ ] **Canonical release owner stable**: from candidate sealing through authorization interaction, one canonical release-owner checkout stays on the exact protected revision used for review; any branch flip or local-ref drift retires or blocks the run until the owner is restored and the receipt chain is refreshed - [ ] **Receipt chain joined**: Integration, Runtime Review, Candidate, Authorization Interaction, Human Authorization, Deployment, State Reconciliation, Live Verification, Publication, and Rollback receipts join by exact digest where each stage applies - [ ] **Overlapping work preserved**: every pre-existing non-canonical work item is content-bound and accounted for; overlapping items remain retained with recovery handles, while any restored disjoint item matches its captured state exactly - [ ] **Atomic convergence closed**: one stable plan and bounded effect authorization own the exact keep / port / drop inventory; authority continuation is atomic, no coordination-only content revision or projection-only recovery blocker remains, and every adapter effect joins the terminal receipt - [ ] **When scoped lane admission applies, admission preservation closed**: the candidate leaves every existing lane untouched; each peer is unchanged or advances only through separately proven current disjoint authority and a joined typed peer-operation receipt - [ ] **Candidate closure exact**: canonical source, all transitive dependencies, policy, target, review, artifact, manifest, and candidate digests agree -- [ ] **Human authorization exact**: the interaction receipt proves the configured transport, browser dependency, exact challenge response, and authenticated actor; the authority adapter records the same human decision for that candidate and target +- [ ] **Human authorization exact**: the interaction receipt proves the configured transport, declared dependencies, exact challenge response, and authenticated actor; the authority adapter records the same human decision for that candidate and target - [ ] **Terminal prompt handshake exact**: terminal automation captures the printed exact reply, waits for the live prompt, and only then submits that reply; missing challenge capture, missing prompt readiness, or out-of-order input blocks authorization - [ ] **Controller singular and idempotent**: one target-scoped controller owns deployment; duplicate dispatch resolves to the same result or fails closed - [ ] **No drift or rebuild**: current evidence still matches the authorized candidate byte-for-byte; otherwise authorization is invalid and forward deployment remains blocked @@ -583,7 +583,7 @@ The optional [Rapid MVP Sprint Profile](./agentic-sdlc-rapid-mvp-sprint.md) modu - [ ] **Turn ends at canonical or parked state**: completed lane payload is absorbed into the protected canonical frontier and the canonical owner is cleanly parked there, or incomplete work is explicitly parked in its owned lane with canonical remaining clean ## Anti-Pattern Guards -The canonical [Execution Anti-Pattern Guards](./agentic-sdlc-anti-pattern-guards.md) module owns the compact prohibited-pattern → required-correction map. This seam keeps the finding vocabulary in this execution owner while avoiding duplicate rule prose. +The canonical [Execution Anti-Pattern Guards](./adlc-anti-pattern-guards.md) module owns the compact prohibited-pattern → required-correction map. This seam keeps the finding vocabulary in this execution owner while avoiding duplicate rule prose. ## Mantra Application @@ -592,7 +592,7 @@ The canonical [Execution Anti-Pattern Guards](./agentic-sdlc-anti-pattern-guards - **Specification grounds**: a task with no VCC behind it is work no rung will credit, so the bridge is a derivation and never a fresh authoring act - **Bounds make finite**: four bounds and a circuit-breaker per task, because an unbounded task is an unbounded loop wearing a checkbox - **Independence makes trustworthy**: the Evaluator is a mechanism the Implementer does not adjudicate; every other role may collapse, this one may not -- **Grants make deliberate**: capability is scoped per task to the narrowest sufficient class, and irreversibility is gated per occurrence rather than per session +- **Grants make deliberate**: capability is scoped to the task; exact irreversible effects need a recorded decision, whose receipt continues unchanged effects without session-wide authority - **Evidence earns**: execution's output is not code, it is the Evidence References that let the Readiness Ladder move; unsurfaced work raises nothing - **Persistence makes resumable**: state lives outside working context, so a long run survives compaction instead of re-spending its way back to where it was - **Autonomy carries**: once intent and authority are present, safe mechanics and idempotent continuation stay inside the controller instead of becoming repeated Operator work diff --git a/guidelines/agentic-sdlc-integration-order.md b/guidelines/adlc-integration-order.md similarity index 96% rename from guidelines/agentic-sdlc-integration-order.md rename to guidelines/adlc-integration-order.md index c3d84462..8356b34b 100644 --- a/guidelines/agentic-sdlc-integration-order.md +++ b/guidelines/adlc-integration-order.md @@ -1,25 +1,26 @@ --- -title: "Agentic SDLC Dependency-Ordered Integration Module" +title: "ADLC Dependency-Ordered Integration Module" doc_type: "Guidelines Module" -version: "1.1.0" -date: "2026-08-30" +version: "1.1.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Integration orchestrator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true lifecycle_status: "proposed" +runtime_readiness_policy: "fail-closed" --- -# Agentic SDLC Dependency-Ordered Integration Module +# ADLC Dependency-Ordered Integration Module ## Scope and Ownership This module is universal, neutral, implementation-agnostic, and independently loadable. It defines how separately verified changes converge into canonical source and one release frontier. It does not define a source-control product, branch name, file layout, build system, approval product, hosting provider, or deployment adapter. -The main Agentic SDLC Guidelines own task execution and the release receipt chain. This module owns integration-unit identity, dependency order, canonical-frontier advancement, duplicate and supersession handling, exact-canonical proof, and release-frontier sealing. +The main ADLC Guidelines own task execution and the release receipt chain. This module owns integration-unit identity, dependency order, canonical-frontier advancement, duplicate and supersession handling, exact-canonical proof, and release-frontier sealing. ## Integration Unit Contract diff --git a/guidelines/agentic-sdlc-production-release-lifecycle.md b/guidelines/adlc-production-release-lifecycle.md similarity index 98% rename from guidelines/agentic-sdlc-production-release-lifecycle.md rename to guidelines/adlc-production-release-lifecycle.md index 885de202..6c8f6172 100644 --- a/guidelines/agentic-sdlc-production-release-lifecycle.md +++ b/guidelines/adlc-production-release-lifecycle.md @@ -1,20 +1,20 @@ --- -title: "Agentic SDLC End-to-End Production Release Lifecycle" +title: "ADLC End-to-End Production Release Lifecycle" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-08-02" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Lifecycle controller function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "promotion" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- -# Agentic SDLC End-to-End Production Release Lifecycle +# ADLC End-to-End Production Release Lifecycle ## Scope and Neutrality diff --git a/guidelines/agentic-sdlc-proportionate-closeout.md b/guidelines/adlc-proportionate-closeout.md similarity index 92% rename from guidelines/agentic-sdlc-proportionate-closeout.md rename to guidelines/adlc-proportionate-closeout.md index de843e06..1c244931 100644 --- a/guidelines/agentic-sdlc-proportionate-closeout.md +++ b/guidelines/adlc-proportionate-closeout.md @@ -1,23 +1,23 @@ --- -title: "Agentic SDLC Proportionate Closeout" +title: "ADLC Proportionate Closeout" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-08-29" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Convergence controller function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" -provider_neutral: "true" +universal_scope: true +provider_neutral: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- # Proportionate Closeout -This module selects the least-powerful closeout profile that fully satisfies sealed Operator intent. It scales applicable work, never the rigor of a triggered obligation. The main [Agentic SDLC Guidelines](./agentic-sdlc-guidelines.md) retain protected integration, atomic convergence, preservation, and finding authority; the [Production Release Lifecycle](./agentic-sdlc-production-release-lifecycle.md) retains delivery and publication authority; the [Rapid MVP Sprint Profile](./agentic-sdlc-rapid-mvp-sprint.md) may compress elapsed time but never these obligations. +This module selects the least-powerful closeout profile that fully satisfies sealed Operator intent. It scales applicable work, never the rigor of a triggered obligation. The main [ADLC Guidelines](./adlc-guidelines.md) retain protected integration, atomic convergence, preservation, and finding authority; the [Production Release Lifecycle](./adlc-production-release-lifecycle.md) retains delivery and publication authority; the [Rapid MVP Sprint Profile](./adlc-rapid-mvp-sprint.md) may compress elapsed time but never these obligations. ```text Closeout Plan = sealed outcome + exact subject set + write scopes + applicable adapters + cleanup effects + evidence keys diff --git a/guidelines/agentic-sdlc-rapid-mvp-sprint.md b/guidelines/adlc-rapid-mvp-sprint.md similarity index 54% rename from guidelines/agentic-sdlc-rapid-mvp-sprint.md rename to guidelines/adlc-rapid-mvp-sprint.md index 9e92b82f..fe6b271a 100644 --- a/guidelines/agentic-sdlc-rapid-mvp-sprint.md +++ b/guidelines/adlc-rapid-mvp-sprint.md @@ -1,16 +1,16 @@ --- -title: "Agentic SDLC Rapid MVP Sprint Profile" +title: "ADLC Rapid MVP Sprint Profile" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-08-27" +version: "1.1.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Orchestrator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" -provider_neutral: "true" +universal_scope: true +provider_neutral: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- @@ -28,7 +28,7 @@ Collapse = fewer named phases discharging the same obligations, never fewer obli | Normally | Under this profile | What still cannot be elided | |---|---|---| -| Requirements → design → task list as three artifacts | One VCC-bearing one-pager: pain point, provable demand, feature, acceptance checks | Both chain seams; an uncovered criterion remains `undesigned-criterion` | +| Requirements → design → task list as three artifacts | One VCC-bearing one-pager: validated pain, WTP evidence, reusable feature, acceptance checks | Both chain seams; an uncovered criterion remains `undesigned-criterion` | | Multi-wave dependency-ordered integration | One wave per dependency layer, fitting the sprint in one or two waves | Acyclic graph and write-disjoint waves | | Separate Orchestrator and Implementer processes | One operator-run loop | Evaluator remains a distinct mechanism the operator does not adjudicate | | Four-bound table per task | One sprint-wide token/time ceiling divided across remaining tasks at dispatch | Token, iteration, wall-clock, and context bounds remain stated | @@ -39,13 +39,27 @@ Collapse = fewer named phases discharging the same obligations, never fewer obli ## Directives - State the Sprint Clock before the first dispatch; without it the run is ordinary-cadence -- Use the one-pager only for a feature tracing to a pain point with provable demand and a named prospective payer +- Use the one-pager for a feature tracing to validated pain, a named prospective payer or segment, and evidenced WTP; mark a proposed price or unpaid pilot separately from collected revenue - Collapse Orchestrator and Implementer only when the Evaluator stays independently named and mechanized - Reallocate the remaining sprint-wide token/time ceiling at each dispatch without raising the total ceiling - State property-test narrowing explicitly; narrowing claims is allowed, leaving a stated property untested is not - Record the Human Authorization decision once through the configured interaction adapter and propagate its receipt autonomously - At the midpoint, split feature scope if the selected features will not close; never silently drop a bound, check, or gate +## Value-to-Revenue Loop + +Use the same CID/RAO/SVO lineage and independent checks from discovery through operation; a new phase does not require a new agent, document, or worktree. + +1. **Design**: select validated pain and the strongest evidenced WTP within hard constraints. Record the smallest useful outcome, acceptance checks, and facts still needing validation +2. **Build**: inspect current capabilities, prefer a conforming reuse or minimal extension, and implement one dependency-closed vertical slice through its real interfaces +3. **Verify**: join independent behavior evidence to that exact slice and its applicable production runtime, configuration, recovery, and resource checks; mocks, test payments, demos, and successful builds retain their limited evidence labels +4. **Launch**: pass the declared protected integration and delivery workflow with exact target authorization; record integration, runtime, deployment, and cleanup outcomes separately +5. **Learn**: measure the real user's completed outcome, paid conversion, and operating cost; count first revenue only with actual payment evidence. Feed failures or absent conversion into the next bounded Context instead of claiming a complete revenue loop + +Record only failure modes material to the slice, with their prevention check and recovery action. Prioritize irreversible loss, duplicate effects, rejected authorization, broken recovery, or an unusable core flow when applicable; do not create a generic risk register detached from acceptance checks. + +**Reference implementation — lean agentic commerce**: a mobile/web/offline-first service may expose one reusable capability through browser, MCP, WebMCP, and `/`, `@`, `#` adapters, with local/edge operation where the dependency contract permits. Rank delivered buyer value, time-to-first-dollar, and token/TCO economics through the shared Constraints ↔ Argumentation ↔ Outranking pipeline; test-mode transactions never prove revenue or production settlement. + ## Completion-Time Forecast The ordinary orchestration-reasoned WBS still applies. Use the smallest dependency-closed outcome WBS that can expose the critical path, evidenced concurrency, waits, verification, expected rework, and confidence inside the Sprint Clock. Reforecast at the midpoint and whenever evidence changes the critical path. diff --git a/guidelines/agentic-sdlc-repository-runtime-readiness.md b/guidelines/adlc-repository-runtime-readiness.md similarity index 99% rename from guidelines/agentic-sdlc-repository-runtime-readiness.md rename to guidelines/adlc-repository-runtime-readiness.md index f2484817..b20cbbc0 100644 --- a/guidelines/agentic-sdlc-repository-runtime-readiness.md +++ b/guidelines/adlc-repository-runtime-readiness.md @@ -1,15 +1,15 @@ --- -title: "Agentic SDLC Repository Runtime Readiness" +title: "ADLC Repository Runtime Readiness" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-07-30" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Evaluator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" lifecycle_status: "proposed" --- diff --git a/guidelines/agentic-sdlc-scoped-lane-admission.md b/guidelines/adlc-scoped-lane-admission.md similarity index 99% rename from guidelines/agentic-sdlc-scoped-lane-admission.md rename to guidelines/adlc-scoped-lane-admission.md index 68f0022c..de772b78 100644 --- a/guidelines/agentic-sdlc-scoped-lane-admission.md +++ b/guidelines/adlc-scoped-lane-admission.md @@ -1,19 +1,25 @@ --- -title: "Agentic SDLC Scoped Concurrent Lane Admission" +title: "ADLC Scoped Concurrent Lane Admission" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-07-30" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" schema: "agentic-scoped-lane-admission/v1" collaboration_schema: "agentic-cloud-collaboration/v1" status: "spec-complete" authority: "provider-neutral additive mutation-lane admission" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" mutation_policy: "preserve every pre-existing lane and mutate only one admitted candidate" +frontmatter_contract: "required" +owner: "Lane admission evaluator function" +local_rung: "spec-complete" +delivered_rung: "undocumented" +lane: "authoring" +lifecycle_status: "proposed" --- -# Agentic SDLC Scoped Concurrent Lane Admission +# ADLC Scoped Concurrent Lane Admission ## Purpose diff --git a/guidelines/agentic-sdlc-specification-chain.md b/guidelines/adlc-specification-chain.md similarity index 85% rename from guidelines/agentic-sdlc-specification-chain.md rename to guidelines/adlc-specification-chain.md index d312b85c..06a3b410 100644 --- a/guidelines/agentic-sdlc-specification-chain.md +++ b/guidelines/adlc-specification-chain.md @@ -1,19 +1,20 @@ --- -title: "Agentic SDLC Specification Chain Module" +title: "ADLC Specification Chain Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-13" +version: "1.1.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Orchestrator function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true lifecycle_status: "proposed" +runtime_readiness_policy: "fail-closed" --- -# Agentic SDLC Specification Chain Module +# ADLC Specification Chain Module ## Scope and Ownership @@ -22,7 +23,7 @@ specification travels from stated intent to executable work across three artifac them. It does not define a document product, file name, directory layout, editor, template engine, agent product, or storage format. -The main Agentic SDLC Guidelines own task identity, state, budgets, roles, and the condition-to-task bridge. The +The main ADLC Guidelines own task identity, state, budgets, roles, and the condition-to-task bridge. The PRD, TAD & ADR authoring set owns document contents, the Readiness Ladder, the Rule ID scheme, and the authoring-domain finding vocabulary. This module owns only the chain: artifact-role identity, the two coverage seams, the re-derivation cascade, phase-advance authority, and the adaptation rules that let the chain shrink or @@ -86,13 +87,13 @@ An upstream edit invalidates downstream coverage whether or not the downstream a ## Phase Advance Authority -Each seam is crossed by decision, not by elapsed effort or apparent completeness. +Each seam consumes recorded authority and independent coverage evidence, not elapsed effort or apparent completeness. **Directives**: -- Require a recorded Operator decision to cross each seam; crossing on an agent's own assessment is a `phase-advanced-without-approval` at `blocker` severity -- Treat an absent decision as a `blocked` state, never an assumed yes; an inferred, defaulted, scheduled, or simulated approval is not an approval -- Record the decision reference on the artifact revision it authorises, so the authorisation remains auditable after the artifact advances -- Forbid an agent that authored an artifact from also recording the decision that advances it; the independence rule applies to phase advance exactly as it applies to task verdicts +- Bind each crossing to an explicit Operator decision covering its objective, scope, bounds, and effects; reuse that decision for reversible authoring, re-grounding, and execution transitions within those terms after independent seam checks pass +- Require a new decision only for an uncovered product choice, scope, authority, irreversible effect, or promotion; absence blocks that transition while authorized dependency-disjoint work continues. Never infer a decision from silence or apparent readiness +- Record the existing decision reference and current artifact revision on each transition; refreshing a revision after an authorized correction is not a new product decision, but effect-bound authorization must be revalidated under the lifecycle contract +- The author may record the reference but cannot fabricate the Operator decision or adjudicate their own seam verdict; the Evaluator remains an independent mechanism ## Adaptivity @@ -117,7 +118,7 @@ unchanged. | `ungrounded-design-element` | `minor` | A design element cites no criterion | | `requirement-introduced-downstream` | `blocker` | Normative behaviour or a correctness property first appears in the design artifact or task list | | `stale-downstream-artifact` | `major` | An upstream artifact changed and a downstream artifact was not re-derived | -| `phase-advanced-without-approval` | `blocker` | A seam was crossed with no recorded Operator decision | +| `phase-advanced-without-approval` | `blocker` | A seam was crossed without a recorded Operator decision covering its scope and effects | | `seam-elided` | `blocker` | A seam's coverage obligation is absent rather than satisfied | ## Module Load Budget @@ -143,7 +144,7 @@ unchanged. - [ ] **No downstream behaviour**: no normative behaviour or correctness property originates in design or tasks - [ ] **Seam 2 closed**: every task cites its criterion, condition, and design element joins - [ ] **Cascade current**: each downstream artifact records the upstream revision it was derived from, and that revision is current -- [ ] **Advance authorised**: each seam crossing carries an Operator decision reference recorded by a party that did not author the artifact +- [ ] **Advance authorised**: each crossing joins current coverage evidence, an independent verdict, and the recorded Operator decision covering its scope and effects - [ ] **Adaptation seam-preserving**: any collapsed or reordered chain still satisfies both seams ## Mantra Application diff --git a/guidelines/agentic-sdlc-upstream-dependency-admission.md b/guidelines/adlc-upstream-dependency-admission.md similarity index 95% rename from guidelines/agentic-sdlc-upstream-dependency-admission.md rename to guidelines/adlc-upstream-dependency-admission.md index 78d470b0..5b3174a7 100644 --- a/guidelines/agentic-sdlc-upstream-dependency-admission.md +++ b/guidelines/adlc-upstream-dependency-admission.md @@ -1,18 +1,24 @@ --- -title: "Agentic SDLC Upstream Dependency Admission" +title: "ADLC Upstream Dependency Admission" doc_type: "Guideline Module" -version: "1.0.0" -date: "2026-07-30" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" schema: "agentic-upstream-dependency-admission/v1" status: "spec-complete" authority: "provider-neutral upstream dependency admission" -universal_scope: "true" +universal_scope: true runtime_readiness_policy: "fail-closed" mutation_policy: "no source adoption or projection before protected admission" +frontmatter_contract: "required" +owner: "Upstream admission evaluator function" +local_rung: "spec-complete" +delivered_rung: "undocumented" +lane: "authoring" +lifecycle_status: "proposed" --- -# Agentic SDLC Upstream Dependency Admission +# ADLC Upstream Dependency Admission ## Purpose diff --git a/guidelines/cid-guidelines.md b/guidelines/cid-guidelines.md index dc42f9c7..ecc8f005 100644 --- a/guidelines/cid-guidelines.md +++ b/guidelines/cid-guidelines.md @@ -1,291 +1,132 @@ -# CID Guidelines – Universal Template & Implementation - -## Overview - -- **Context**: Focus domain of concern (the "what" or "where") -- **Intent**: Desired principle or guiding goal (the "why" or "how") -- **Directive**: Explicit prohibition or required safeguard (the "must not" or "must do") -- **Sorting**: Each line/column is organized alphabetically (A→Z) for clarity and neutrality -- **Purpose**: Provides a reusable template for creating Context—Intent—Directive guidelines across any domain - ---- - -## Meta-Guidelines - -### Context -- **Documentation systems**: establish structured rules to ensure order, define clear responsibilities to preserve accountability, align workflows to maintain cohesion, empower teams to guarantee ownership, and set unambiguous guidelines to secure clarity. - -### Intent -- **Meta-guideline intent**: structure with CID to ensure coherence, enforce SRP to preserve modularity, chain RAO to maintain resilience, clarify with SVO to guarantee transparency, and trace operations to secure accountability. - -### Core Directives (SVO Format) - -- **CID Guidelines structures documentation into three-part compositions** - - Context establishes environmental conditions and problem scope - - Intent declares purpose and desired outcomes - - Directives prescribe actionable rules in SVO format - -- **SRP enforces focused responsibility boundaries** - - Components handle single concerns - - Modules avoid overlapping responsibilities - - Systems compose focused units into complex behaviors - -- **RAO defines accountability chains** - - Roles identify responsible agents - - Actions specify transformative operations - - Outcomes declare measurable results - -- **SVO clarifies operational semantics** - - Subjects identify actors or components - - Verbs specify concrete actions - - Objects define targets and artifacts - ---- - -## Usage Instructions - -### When to Create CID Guidelines - -- **Create CID guidelines when you need to**: - - Establish consistent standards across a domain (codebase, project, documentation, system design) - - Define clear principles with explicit boundaries - - Enable team alignment through structured, searchable mantras - - Prevent common anti-patterns through explicit prohibitions - - Maintain neutrality and avoid project-specific assumptions - -### How to Populate This Template - -1. **Identify your domain**: What area needs guidelines? (e.g., neutrality, maintainability, project rules, documentation, system design) -2. **Extract contexts**: List all relevant focus areas alphabetically (e.g., Adaptability, Architecture, Caching) -3. **Define intents**: For each context, specify the desired principle or goal -4. **State directives**: Explicitly prohibit anti-patterns or require safeguards using checkboxes `- [ ]` -5. **Maintain neutrality**: Avoid project names, dataset references, or domain-specific examples -6. **Sort alphabetically**: Keep all contexts in A→Z order for easy navigation and reference - -### Template Structure - -This template provides two formats: -1. **Slogan-style mantras**: Concise three-beat format for quick reference and memorization -2. **Detailed table**: Comprehensive format with full context, intent, and directive specifications - ---- - -## Slogan-style, three-beat mantra form - -- Each line is a three-beat `Context; Intent; Directive` mantra: - -``` -- [ ] [Context A]; [intent/principle]; forbid [anti-pattern/violation] -- [ ] [Context B]; [intent/principle]; forbid [anti-pattern/violation] -- [ ] [Context C]; [intent/principle]; forbid [anti-pattern/violation] -``` - -- **Example from Neutrality Guidelines**: -``` -- [ ] Adaptability; enable customization; forbid hardcoded behavior -- [ ] Algorithms; apply general-purpose logic; forbid dataset dependencies -- [ ] Configuration; externalize parameters; forbid embedded settings -- [ ] Domains; operate across sectors; forbid sector-specific assumptions -``` - ---- - -## Context—Intent—Directive Table - -- Each row is a universal, neutral, project-agnostic one-liner mantra: `Context (focus domain) | Intent (desired principle) | Directive (explicit prohibition)` - -``` -| Context | Intent | Directive | -|---------------------|-------------------------------------|------------------------------------------------------------------------------------------------| -| [Context A] | [Intended principle or goal] | - [ ] [Action verb] [object]; [intended outcome]; forbid [anti-pattern or violation] | -| [Context B] | [Intended principle or goal] | - [ ] [Action verb] [object]; [intended outcome]; forbid [anti-pattern or violation] | -| [Context C] | [Intended principle or goal] | - [ ] [Action verb] [object]; [intended outcome]; forbid [anti-pattern or violation] | -``` - -**Example from Maintainability Guidelines**: -``` -| Context | Intent | Directive | -|---------------------|-------------------------------------|------------------------------------------------------------------------------------------------| -| Caching | Optimize data retrieval | - [ ] Implement caching; optimize retrieval; forbid redundant fetches | -| Centralization | Establish single source of truth | - [ ] Centralize copy; establish single source; forbid duplicate strings | -| Chunks | Constrain bundle sizes | - [ ] Limit chunks to <500kB; constrain sizes; forbid oversized bundles | -| Classes | Maintain single responsibility | - [ ] Scope classes; maintain single responsibility; forbid multi-concern classes | -``` - ---- - -## Directive Pattern Guidelines - -### Standard Directive Format - -``` -- [ ] [Action verb] [object/target]; [intended state/outcome]; forbid [specific anti-pattern] -``` - -### Common Action Verbs (alphabetically) - -> Apply, Assign, Avoid, Build, Cache, Centralize, Configure, Define, Design, Document, Enable, Enforce, Ensure, Establish, Externalize, Implement, Maintain, Maximize, Minimize, Monitor, Preserve, Prevent, Provide, Scope, Secure, Separate, Specify, Standardize, Track, Use, Validate - -### Common Prohibition Verbs (after "forbid") - -> Forbid [noun/gerund]: embedded logic, hardcoded values, duplicate code, unclear intent, unmeasured metrics, undocumented behavior, single points of failure, unbounded resources - -### Directive Quality Checklist - -- A well-formed directive should: - - [ ] Start with an action verb in present tense - - [ ] Specify a clear object or target - - [ ] State the intended outcome or principle - - [ ] Explicitly prohibit a specific anti-pattern - - [ ] Be measurable or verifiable - - [ ] Remain domain-agnostic (no project/dataset names) - - [ ] Use neutral, universal terminology - ---- - -## Integration with Other Frameworks - -### CID + SRP (Single Responsibility Principle) - -- **CID**: Defines what contexts need guidelines and what's prohibited -- **SRP**: Ensures each module/component/class handles one concern -- **Together**: CID frames the rules; SRP isolates the implementation - -### CID + RAO (Role—Action—Outcome) - -- **CID**: Establishes standards and prohibitions -- **RAO**: Assigns responsibilities to roles for implementing those standards -- **Together**: CID defines what; RAO defines who does what - -### CID + SVO (Subject—Verb—Object) - -- **CID**: Provides the governance framework -- **SVO**: Expresses operations with grammatical precision -- **Together**: CID frames rules; SVO clarifies execution semantics - --- - -## Role—Action—Outcome - -- **Role: Guideline Designer** --> Action: defines CID structure, SRP boundaries, RAO chains, SVO patterns as reusable templates --> Outcome: produces meta-guideline enabling consistent documentation across domains - -- **Role: Documentation Author** --> Action: applies CID structure, decomposes systems via SRP, maps workflows to RAO, expresses rules as SVO --> Outcome: generates clear, focused, accountable specifications - -- **Role: System Architect** --> Action: consumes CID-structured guidelines, enforces SRP separation, traces RAO chains, validates SVO clarity --> Outcome: builds systems with verifiable alignment to documented intent - -- **Role: Validator** --> Action: checks Context completeness, verifies Intent alignment, audits Directive actionability, confirms RAO traceability --> Outcome: ensures guideline adherence and documentation quality - +title: "Shared CID, RAO and SVO Contract" +doc_type: "Guidelines Module" +version: "2.0.0" +date: "2026-09-05" +lang: "en-US" +frontmatter_contract: "required" +owner: "Directive contract" +local_rung: "spec-complete" +delivered_rung: "undocumented" +lane: "authoring" +universal_scope: true +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- -## Mantra Application - -> **"CID frames, SRP focuses, RAO aligns, SVO clarifies"** - -- **CID frames**: Establishes scope, purpose, rules as structured triplet -- **SRP focuses**: Ensures each component owns single concern -- **RAO aligns**: Maps responsibilities to actions to outcomes -- **SVO clarifies**: Expresses operations with grammatical precision - -### Extended Template - -> **"CID frames [domain] standards, SRP isolates [component] concerns, RAO aligns [role] responsibilities, SVO clarifies [operation] semantics"** - -- **CID frames**: Establishes scope ([domain area]), purpose ([key goals]), rules ([core principles + prohibitions]) -- **SRP isolates**: Ensures each [module/component/class] handles [single concern], each [unit] owns [focused responsibility] -- **RAO aligns**: Maps [role 1], [role 2], [role 3], [role N] to their [domain-specific] deliverables -- **SVO clarifies**: Expresses all operations ([examples of subject-verb-object statements]) with grammatical precision enabling [accountability/clarity/traceability] - ---- - -## Anti-Pattern Guards - -❌ Vague context statements -> ✅ Specific environmental conditions -❌ Multiple intents per guideline -> ✅ Single focused purpose -❌ Imperative commands without subjects -> ✅ SVO-structured directives -❌ Ambiguous responsibilities -> ✅ Explicit Role—Action—Outcome chains - ---- - -## Example CID Guidelines by Domain - -### Codebase Neutrality -- Context: Adaptability, Configuration, Domains, Flexibility -- Intent: Enable cross-domain deployment, support customization -- Directive: Forbid hardcoded assumptions, dataset dependencies - -### Maintainability -- Context: Boundaries, Centralization, Duplication, Size -- Intent: Maintain clarity, ensure consistency, reduce technical debt -- Directive: Forbid oversized modules, duplicate code, stale references - -### Project Rules -- Context: Agility, Alignment, Feedback, Resilience -- Intent: Accelerate learning, align progress, sustain longevity -- Directive: Forbid slow validation, unmeasured objectives, technical debt - -### Documentation -- Context: Clarity, Neutrality, Traceability, Transparency -- Intent: Enable adaptation, preserve provenance, ensure reproducibility -- Directive: Forbid hardcoded examples, undocumented APIs, opaque specifications - -### System Design -- Context: Resilience, Scalability, Security, Observability -- Intent: Maximize availability, ensure reliability, protect integrity -- Directive: Forbid single points of failure, unbounded resources, unmonitored systems - ---- - -## Complete Example - -``` -- Mantra: "CID frames, SRP focuses, RAO aligns, SVO clarifies." -- Directive: Use the CID (Context—Intent—Directives) guideline together with SRP (Single Responsibility Principle) and RAO (Role—Action—Outcome) to organize rules into SVO (Subject—Verb—Object) statements, ensuring clarity, focus, accountability, and purpose. -- Example: - Context: Exploratory Data Analysis (EDA) and Model Lifecycle Planning (MLP) in Agentic GraphRAG - Intent: Ensure reproducible workflows and prevent ad-hoc coupling between analysis and lifecycle stages - Directive (SVO): Analysts define data exploration steps, models record lifecycle states, systems enforce separation - Role—Action—Outcome: - - Role: Analyst -> Action: explores representative datasets -> Outcome: produces reproducible insights - - Role: Model steward -> Action: tracks lifecycle transitions -> Outcome: ensures accountability and auditability - - Role: System -> Action: enforces modular boundaries -> Outcome: maintains clarity and prevents duplication -``` - ---- - -## Quick Start Checklist - -To create new CID guidelines using this template: - -``` -- [ ] Identify the domain requiring guidelines -- [ ] List 20–100 relevant contexts alphabetically -- [ ] For each context, define the intended principle -- [ ] For each context, specify explicit prohibitions -- [ ] Verify all entries use domain-agnostic language -- [ ] Sort all contexts alphabetically (A→Z) -- [ ] Create both slogan-style and table formats -- [ ] Add domain-specific mantra application -- [ ] Review for neutrality and completeness -- [ ] Validate directives are measurable and actionable +# Shared CID, RAO and SVO Contract + +## Scope and Ownership + +This is the shared semantic contract for PRD, TAD, ADR and ADLC dispatch. It applies across products, +languages, runtimes, models, devices and collaboration transports. It prescribes meanings and joins, +not a provider, directory layout, message serialization or separate document per decision. + +[PRD, TAD and ADR](./prd-tad-adr-guidelines.md) own requirements, design and decision records. +[ADLC](./adlc-guidelines.md) owns execution obligations; [Artifact Continuity](./adlc-artifact-continuity.md) +owns revision and evidence joins. Consumers reference this field contract instead of forking it. + +## Shared Field Contract + +| Field | Meaning | Required consistency | +|---|---|---| +| `context` | Current conditions, evidence, constraints and bounded scope | Cite inspectable source/revision or mark the assumption unverified | +| `intent` | Desired value or future state | Distinguish intended value from an observed result | +| `directive` | Required action, constraint or safeguard | Trace to intent; do not smuggle in scope or authority | +| `role` | Accountable function performing the work | Name a responsibility, not a brand or personality | +| `action` | One independently verifiable transformation | Name inputs and operation; split independently closable outcomes | +| `outcome` | Observable state produced by the action | State its acceptance check; do not substitute a self-issued verdict | +| `subject` | Functional actor performing the action | Resolve to the same accountable role | +| `verb` | Operation expressed by the action | Prefer one precise transitive verb | +| `object` | Target transformed or inspected | Resolve to the same scoped input or artifact | + +CID expresses context, purpose and obligation. RAO expresses accountability, transformation and result. +SVO compresses the same action. None introduces a second instruction or supplies missing authorization. +A human, agent or component may be the subject; no literal actor name is universally required. + +### Composition Rule + +- Every RAO action implements its referenced directive, and its outcome can be checked against intent. +- Derive SVO from RAO; do not author an unrelated command merely to fill three fields. +- Inherit stable context, scope and role by an explicit reference. Expand only changed or ambiguous fields. +- A concise sentence, table row or structured record is valid when the same semantics can be recovered. + Machine interfaces declare the serialization they accept. Ordinary progress messages need no nine-field wrapper. +- Record stable IDs and exact revisions at handoff boundaries. Paths locate content; they do not prove identity. + +### Reference serialization + +This YAML is one portable representation, not an additional schema or mandatory message wrapper: + +```yaml +context: "Criterion C1 at revision r2 needs a result; input I1 is verified." +intent: "A caller receives the requested valid result." +directive: "Implement C1 within the accepted scope and resource limits." +role: "Implementer" +action: "Implement result validation for C1." +outcome: "Named check V1 passes for valid input and rejects invalid input." +subject: "Implementer" +verb: "implement" +object: "result validation for C1" ``` ---- - -## Notes - -- **Neutrality**: All contexts, intents, and directives must remain project-agnostic, dataset-agnostic, and domain-agnostic -- **Universality**: Guidelines should apply across teams, codebases, and organizational contexts -- **Clarity**: Each directive should be unambiguous and actionable -- **Completeness**: Cover all relevant contexts within the domain -- **Maintainability**: Keep guidelines up-to-date as domain evolves -- **Searchability**: Alphabetical sorting enables quick reference and lookup -- **Traceability**: RAO chains ensure accountability from role through action to outcome -- **Precision**: SVO format guarantees grammatical clarity in all operational statements \ No newline at end of file +## PRD, TAD and ADR Alignment + +| Artifact role | Consumes | Produces | +|---|---|---| +| PRD | Grounded pain, WTP evidence, constraints and current capabilities | Intent, scope, requirements and verifiable acceptance criteria | +| TAD | The exact accepted PRD revision | Component owners, contracts and designs covering those criteria | +| ADR | A material design choice and its supporting/attacking evidence | Decision, rejected alternatives, consequences and relevant recovery condition | +| ADLC task | Joined criteria, design, applicable decisions and authority | Scoped RAO work, recorded results and independent evaluation | + +A combined artifact may contain all roles. Split only for a real ownership, review or size constraint. +Maintain requirement → design → task → evidence joins; a merged file does not erase those obligations. +Update the owning requirement or design before dependent implementation when grounding changes a premise. +A reserved product choice still needs the operator; routine in-scope correction uses existing authorization. + +## Grounding and Clarification + +- Inspect the current inputs that materially justify reuse, ownership, feasibility or readiness. + Cross-agent output is an input to verify, not implementation evidence by provenance alone. +- Separate confirmed facts, contradicted claims, absent capabilities and unverified assumptions. + Research, source inspection, tests and deployed observations prove different things. +- Repair mechanical gaps within the authorized scope and recheck affected joins. Continue disjoint safe work. +- Ask only for a decision that cannot be derived from current evidence and authorization; explain the actual + scope, consequence or authority gap. Present a concrete recommendation when useful; do not require a + binary reply or invented confirmation token. +- Preserve valid authorization for unchanged effects. A transport failure or new digest does not create + a new product choice; a material effect or target change must be re-evaluated. + +## Minimal Task and Budget Contract + +A task references its criterion/design, accountable role, scoped action, observable outcome, named check, +permissions, dependencies and applicable resource bounds. Reuse run-level bounds rather than repeating +identical tables. Decompose only where independent outcomes, ownership or the budget require it. + +- State elapsed-time and resource bounds; record measured use where available and label estimates honestly. +- Keep authored files below 600 lines and chunks below 500 kB in profiles adopting these repository limits. +- Do not create an agent, worktree, schema or artifact unless it reduces an evidenced coordination or + verification cost. One lane may contain disjoint agent work; every writable path still has one owner. +- On repeated deterministic failure, change approach from the cause. Use bounded retries for contention. + External waits name a condition and recheck trigger, not an invented completion ETA. + +## Preservation and Interoperability + +- Preserve owner-authored work and reconstructable history. Intentional deletion or replacement belongs + in the reviewed diff; losslessness does not require retaining obsolete text in every successor. +- Never overwrite concurrent work, invent evidence, transfer ownership by copying bytes, or force a + successful result by editing a receipt or projection. +- Keep wire identities and accepted versions stable until an explicit compatibility migration exists. + Human-readable names may change without renaming unrelated protocol fields or historical receipts. +- Use stable content identity and revision joins for portable handoffs. Follow the repository's naming + convention; do not require a timestamp, alphabetic ordering or one new file for every message. + +## Density and Verification + +A contract is sufficient when its reader can identify the obligation, owner, scope, check and authority. +Remove duplicated prose, unexplained fields and ceremony that protects no observed failure mode. +Prefer one cited record with multiple views over copies that can drift. + +An independent check verifies that CID, RAO and SVO converge, each task covers a criterion, each observed +outcome has evidence, and unsupported assumptions cannot become readiness or revenue claims. Reuse the +finding vocabulary in the [authoring set](./prd-tad-adr-guidelines.md) and +[ADLC set](./adlc-guidelines.md); this module introduces no parallel finding taxonomy. diff --git a/guidelines/commit-push-deploy-guidelines.md b/guidelines/commit-push-deploy-guidelines.md index 5582f35c..41193c2d 100644 --- a/guidelines/commit-push-deploy-guidelines.md +++ b/guidelines/commit-push-deploy-guidelines.md @@ -1,8 +1,8 @@ --- title: "Commit, Push, Integrate, and Deploy Guidelines" doc_type: "Delivery and Release Control Guideline" -version: "2.0.0" -date: "2026-08-26" +version: "2.1.0" +date: "2026-09-05" lang: "en-US" owner: "Delivery policy" local_rung: "runtime-ready" @@ -47,11 +47,16 @@ of repository, workspace topology, integration method, and one or more exact required-check names. Direct canonical writes are forbidden. Dirty, unversioned, or local-checkout deployment is forbidden. -The [Agentic SDLC Guidelines](./agentic-sdlc-guidelines.md) own universal task, -authority, verification, and release-control rules. The Agentic Canvas OS -`START-WORKFLOW.md` and `RELEASE-WORKFLOW.md` are the executable reference -contracts. This document owns the commit, push, protected-integration, and -delivery sequence. +The [ADLC Guidelines](./adlc-guidelines.md) own universal task, +authority, verification, and release-control rules. + +### Reference implementation — Agentic OS + +The pinned `agentic-os` package owns `docs/START-WORKFLOW.md`, `docs/RELEASE-WORKFLOW.md` +and the executable lifecycle controller. Consumers invoke those assets instead of copying them. +This document supplies repository-specific delivery policy, not a second controller. +The required-check context `agentic-sdlc-policy-contract` remains a provider compatibility name; +changing it requires an exact ruleset/workflow migration, not a documentation rename. ## Identity and repository profile diff --git a/guidelines/media-gaming-development-guidelines.md b/guidelines/media-gaming-development-guidelines.md index b614e547..9ee46fc5 100644 --- a/guidelines/media-gaming-development-guidelines.md +++ b/guidelines/media-gaming-development-guidelines.md @@ -51,7 +51,7 @@ lifecycle_status: "proposed" ## Boundary with the Companion Sets -Three sets meet at two seams. **Authoring** (what a PRD, TAD, or ADR must contain, the Readiness Ladder, the Rule ID scheme) is owned by the **PRD, TAD & ADR Guidelines** companion set. **Execution** (task decomposition, agent roles, tool blast radius, per-task budgets, run state) is owned by the **Agentic SDLC Guidelines** companion set. This set does not restate either; it specializes the first for rich-media and game content, and consumes the second unchanged for anything that runs as a task. +Three sets meet at two seams. **Authoring** (what a PRD, TAD, or ADR must contain, the Readiness Ladder, the Rule ID scheme) is owned by the **PRD, TAD & ADR Guidelines** companion set. **Execution** (task decomposition, agent roles, tool blast radius, per-task budgets, run state) is owned by the **ADLC Guidelines** companion set. This set does not restate either; it specializes the first for rich-media and game content, and consumes the second unchanged for anything that runs as a task. | Concern | Owner | This set's relationship | |---|---|---| diff --git a/guidelines/prd-tad-adr-cid-matrix.md b/guidelines/prd-tad-adr-cid-matrix.md index a1de008b..93a3bc9d 100644 --- a/guidelines/prd-tad-adr-cid-matrix.md +++ b/guidelines/prd-tad-adr-cid-matrix.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR CID Directive Matrix Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.9.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR CID Directive Matrix Module diff --git a/guidelines/prd-tad-adr-diagram-canvas-render.companion.md b/guidelines/prd-tad-adr-diagram-canvas-render.companion.md index 3297c95c..2af4ad9d 100644 --- a/guidelines/prd-tad-adr-diagram-canvas-render.companion.md +++ b/guidelines/prd-tad-adr-diagram-canvas-render.companion.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Diagram Canvas-Render Contract (Companion)" doc_type: "Guidelines Companion" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Diagram Guidelines (Companion)" -parent_version: "1.1.0" +parent_version: "1.1.1" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Diagram Canvas-Render Contract (Companion) @@ -25,7 +27,7 @@ A static notation renderer consumes the diagram source and emits a picture. A ** | Concern | Owner | |---|---| | Document contents, Readiness Ladder, Rule ID scheme, authoring-domain findings | **PRD, TAD & ADR Guidelines** | -| Task decomposition, agent roles, budgets, run state, Evidence References | **Agentic SDLC Guidelines** | +| Task decomposition, agent roles, budgets, run state, Evidence References | **ADLC Guidelines** | | Diagram identity, class catalog, notation rules, labelling, complexity budget | **PRD, TAD & ADR Diagram Guidelines** companion | | Render-target declaration, ingest surfaces, graph element contract, visual property namespace, projection rules, canvas-domain findings | **This module** | diff --git a/guidelines/prd-tad-adr-diagram-guidelines.companion.md b/guidelines/prd-tad-adr-diagram-guidelines.companion.md index 704d155b..98001e0f 100644 --- a/guidelines/prd-tad-adr-diagram-guidelines.companion.md +++ b/guidelines/prd-tad-adr-diagram-guidelines.companion.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Diagram Guidelines (Companion)" doc_type: "Guidelines Companion" -version: "1.1.0" -date: "2026-08-20" +version: "1.1.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.8.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Diagram Guidelines (Companion) @@ -23,7 +25,7 @@ This companion expands one section of the parent set — `architecture-diagram-s | Concern | Owner | |---|---| | What a PRD, TAD, or ADR must contain; the Readiness Ladder; the Rule ID scheme; the authoring-domain finding vocabulary | Parent set — **PRD, TAD & ADR Guidelines** | -| Task decomposition, agent roles, tool blast radius, per-task budgets, run state | **Agentic SDLC Guidelines** companion set | +| Task decomposition, agent roles, tool blast radius, per-task budgets, run state | **ADLC Guidelines** companion set | | Diagram identity, class selection, notation rules, labelling contract, complexity budget, render reach, diagram drift, and the diagram-domain finding vocabulary | **This companion** | | Render-target declaration, ingest surfaces, graph element contract, projection rules, and the canvas-domain finding vocabulary | [Diagram Canvas-Render Contract](./prd-tad-adr-diagram-canvas-render.companion.md) | | Copy-ready template bodies for every diagram class | [Diagram Templates](./prd-tad-adr-diagram-templates.companion.md) | @@ -433,7 +435,7 @@ The [Diagram Canvas-Render Contract](./prd-tad-adr-diagram-canvas-render.compani ## Conformance Findings — Diagram Domain -**Defines the typed vocabulary a conformance check records against this companion.** It is the diagram-domain member of the union described by the parent's Conformance Findings section: authoring-domain types stay in the parent, execution-domain types stay in the Agentic SDLC set, and no set redefines a type another owns. +**Defines the typed vocabulary a conformance check records against this companion.** It is the diagram-domain member of the union described by the parent's Conformance Findings section: authoring-domain types stay in the parent, execution-domain types stay in the ADLC set, and no set redefines a type another owns. Findings here use the parent's six-field recording contract, the parent's three severities, the parent's deduplication triple `(Finding Type, Rule ID, artifact reference)`, and the parent's ordering rule. The artifact reference for a diagram finding is the **Diagram ID**. @@ -467,7 +469,7 @@ Findings here use the parent's six-field recording contract, the parent's three ### Directives -- Treat this enumeration as the single source of truth for **diagram-domain** finding names; forbid this companion redefining a type the parent set, the Agentic SDLC set, or the Canvas-Render module owns +- Treat this enumeration as the single source of truth for **diagram-domain** finding names; forbid this companion redefining a type the parent set, the ADLC set, or the Canvas-Render module owns - Raise a diagram-domain type where the defect is in the drawing and a canvas-domain type where the defect is in the projection; both may be raised for one diagram, and the conformance vocabulary is the union of all four domains - Raise the parent's type, not a diagram type, where the defect is in the specification rather than the rendering: an unbounded loop in the spec is `unbounded-loop`, an unbounded loop drawn without its bound is `unbounded-loop-unrendered`, and both may be raised for the same pipeline - Raise the parent's type where the diagram is the only place a status, residency, or lane claim appears: a rung visible only in a diagram is `unproven-claim`, a store with no residency is `incomplete-topology-node`, a missing lane is `missing-lane`, an open boundary with no operator instruction is `ungated-promotion`, and an authoring-to-delivery edge is `deploy-boundary-breach` diff --git a/guidelines/prd-tad-adr-diagram-templates.companion.md b/guidelines/prd-tad-adr-diagram-templates.companion.md index 55aff602..36504856 100644 --- a/guidelines/prd-tad-adr-diagram-templates.companion.md +++ b/guidelines/prd-tad-adr-diagram-templates.companion.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Diagram Templates (Companion)" doc_type: "Guidelines Companion" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Diagram Guidelines (Companion)" -parent_version: "1.1.0" +parent_version: "1.1.1" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Diagram Templates (Companion) diff --git a/guidelines/prd-tad-adr-economics.md b/guidelines/prd-tad-adr-economics.md index 6e751e2b..dc999fce 100644 --- a/guidelines/prd-tad-adr-economics.md +++ b/guidelines/prd-tad-adr-economics.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Economics & Time-to-Value Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.9.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Economics & Time-to-Value Module diff --git a/guidelines/prd-tad-adr-guidelines.md b/guidelines/prd-tad-adr-guidelines.md index 3ed8fa0e..c2de3f8b 100644 --- a/guidelines/prd-tad-adr-guidelines.md +++ b/guidelines/prd-tad-adr-guidelines.md @@ -1,17 +1,17 @@ --- title: "PRD, TAD & ADR Guidelines" doc_type: "Guidelines" -version: "2.3.0" -date: "2026-09-04" +version: "2.4.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" -worktree_id: "main" -agent_id: "orchestrator" +universal_scope: true +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Guidelines @@ -39,9 +39,9 @@ agent_id: "orchestrator" - `markdown-yaml-frontmatter-enforcement` — authoring contract for frontmatter SSOT, including concurrency provenance keys - `overview` — what PRD/TAD are, the governing standards, and the ADLC/MCP-/WebMCP-native operating posture - `solo-operator-ai-native-orientation` — binding lens, harness, and bound obligations -> [Economics & Time-to-Value](./prd-tad-adr-economics.md) -- `directive-grammar-cid` — binding CID/RAO/SVO message schema, WBS Task Node decomposition, grounding, and budget obligations -> [CID Template](./CID-template.md) +- `directive-grammar-cid` — shared CID/RAO/SVO message fields, decomposition, grounding, and budgets -> [CID Guidelines](./cid-guidelines.md#shared-field-contract) - `artifact-continuity-authoring-seam` — PRD/TAD/ADR CID ownership, codebase grounding, revision joins, RAO grounding, and execution handoff -- `concurrent-collaboration--work-tree-integrity` — binding multi-device, multi-LLM, multi-agent, multi-work-tree obligations -> [Concurrency & Work-Tree Protocol](./prd-tad-adr-concurrency.md) +- `concurrent-collaboration--work-tree-integrity` — multi-device, multi-LLM, multi-agent, multi-work-tree obligations -> [Cloud-Authoritative Collaboration](./adlc-cloud-collaboration.md) - `from-0-to-1-prd--tad-creation-process` — binding gate order -> [Process & Flow Patterns](./prd-tad-adr-process-flows.md) - `flow-patterns` — binding five-pattern coverage -> [Process & Flow Patterns](./prd-tad-adr-process-flows.md) - `time-to-value` — binding TTV metric obligation -> [Economics & Time-to-Value](./prd-tad-adr-economics.md) @@ -51,12 +51,12 @@ agent_id: "orchestrator" - `autonomous-implementation-verification` — binding VCC and Evidence obligations -> [Verification & Conformance](./prd-tad-adr-verification.md) - `cid-directive-matrix` — lookup surface -> [CID Directive Matrix](./prd-tad-adr-cid-matrix.md) - `core-templates` — binding template-field obligations -> [Core Templates](./prd-tad-adr-templates.md) -- `platform-specific-selection-criteria--multi-agent-reasoning-pipeline` — binding constraints → outranking → argumentation obligation for any platform/vendor/provider choice -> [Selection Criteria](./prd-tad-adr-selection-criteria.md) -- `pain-point-to-feature-mapping` — binding pain-point-to-feature traceability obligation -> [Pain-Point Mapping](./prd-tad-adr-pain-point-mapping.md) -- `demo-skeleton` — binding time-boxed demonstration obligation -> [Demo Skeleton](./prd-tad-adr-demo-skeleton.md) -- `domain-object-rubric-assessment` — binding breakthrough-level self-assessment obligation -> [Domain-Object Rubric](./prd-tad-adr-domain-object-rubric.md) -- `roadmap` — binding phased reuse/delta sequencing obligation -> [Roadmap](./prd-tad-adr-roadmap.md) -- `monetization` — binding real-payer validation obligation -> [Monetization](./prd-tad-adr-monetization.md) +- [Selection Criteria](#platform-specific-selection-criteria--multi-agent-reasoning-pipeline) — bounded Constraints ↔ Argumentation ↔ Outranking for platform/vendor/provider choices +- [Pain-Point Mapping](#pain-point-to-feature-mapping) — pain-point-to-feature traceability +- [Demo Skeleton](#demo-skeleton) — bounded demonstration of the acceptance condition +- [Domain-Object Rubric](#domain-object-rubric-assessment) — evidence-based capability assessment +- [Roadmap](#roadmap) — phased reuse and delta sequencing +- [Monetization](#monetization) — payer validation and revenue evidence - `architecture-diagram-standards` — diagram format obligations, and the seam to the diagram companion set - [Diagram Guidelines](./prd-tad-adr-diagram-guidelines.companion.md) — diagram identity, class catalog, notation, labelling, complexity, drift, diagram-domain findings - [Diagram Canvas-Render Contract](./prd-tad-adr-diagram-canvas-render.companion.md) — surface declaration, ingest surfaces, graph element contract, projection rules, canvas-domain findings @@ -65,17 +65,17 @@ agent_id: "orchestrator" - `anti-pattern-guards` — prohibited patterns -> [CID Directive Matrix](./prd-tad-adr-cid-matrix.md) - `conformance-findings` — binding recording contract -> [Verification & Conformance](./prd-tad-adr-verification.md) - `validation-checklist` — binding alignment gate -> [Verification & Conformance](./prd-tad-adr-verification.md) -- `division-of-work` — binding capability-ownership obligation, single-writer across concurrent work trees -> [Division of Work](./prd-tad-adr-division-of-work.md) +- [Division of Work](#division-of-work) — one capability owner and reuse decisions across concurrent worktrees - `roleactionoutcome` — role-to-deliverable mapping - `mantra-application` — the framing mantra -**Modular set**: this document is the always-loaded index and binding layer; it aggregates pointers to every companion module and is the one file in the set exempted from the per-module line ceiling below, since aggregation is its sole responsibility and it owns no module's protocol content. Each `##` section states only what binds a PRD, TAD, or ADR directly; the full protocol for a section lives in the module its entry names. Every **companion** module stays under 600 lines and carries one responsibility, so a single-phase task loads one module rather than the whole set. +**Modular set**: load the bindings and named owners needed for the current phase. Every file stays under 600 lines; a compact protocol may live in its owning section, while larger protocols remain separately loadable. Do not copy a companion's rules into this index or require the entire set for one bounded action. -**Companion sets**: this document is the authority for **authoring** — what a PRD, TAD, or ADR must contain and how conformance is named. Execution — task decomposition, agent roles and independence, tool blast radius, per-task budgets, and run state — is owned by the **Agentic SDLC Guidelines** companion set. Concurrent multi-device, multi-LLM, multi-agent, multi-work-tree collaboration is owned by the **Concurrency & Work-Tree Protocol** module. The **diagram domain** — diagram identity, class selection, notation, labelling, canvas projection, and templates — is owned by the three diagram companion modules named in the Module Index. No set restates another; each names the others where a rule crosses the boundary, and the conformance vocabulary is the union of their enumerations. A claim about execution, concurrency, or a diagram's canvas-renderability, sourced from this document alone is incomplete. +**Companion sets**: this document owns authoring. [ADLC Guidelines](./adlc-guidelines.md) own execution; [Cloud-Authoritative Collaboration](./adlc-cloud-collaboration.md) and [Scoped Lane Admission](./adlc-scoped-lane-admission.md) own concurrency. The three diagram companions own their domain. Consume each owner at its seam; the conformance vocabulary is the union of their enumerations. -**Continuity companion**: the [Artifact Continuity Module](./agentic-sdlc-artifact-continuity.md) owns the universal CID-to-RAO seam, companion-artifact joins, outcome evidence, revision freshness, and successor feedback. This authoring set supplies its PRD, TAD, and ADR inputs; it does not redefine the continuity vocabulary. +**Continuity companion**: the [Artifact Continuity Module](./adlc-artifact-continuity.md) owns the universal CID-to-RAO seam, companion-artifact joins, outcome evidence, revision freshness, and successor feedback. This authoring set supplies its PRD, TAD, and ADR inputs; it does not redefine the continuity vocabulary. -**Message envelope companion**: the [CID Template module](./CID-template.md) owns the Context/Intent/Directive, Role/Action/Outcome, and Subject/Verb/Object message schema — its frontmatter contract, Sender/Receiver Grounding protocol, Clarification Protocol, Composition Rule, Density Rules, Reinforced Constraints, ADLC Budgets, WBS Task Node dispatch form, File Naming convention, and Forbidden-pattern list. Every `**Directives**:` block in this document, and every authoring-to-execution or agent-to-agent dispatch message — including across work trees, devices, and LLMs — instantiates that schema; this document publishes only the Field Contract vocabulary (see Directive Grammar (CID)) and does not redefine it. +**Message envelope companion**: [CID Guidelines](./cid-guidelines.md#shared-field-contract) own the shared Context/Intent/Directive, Role/Action/Outcome, and Subject/Verb/Object contract. PRD, TAD, ADR, and cross-agent dispatch consume its grounding, composition, clarification, density, and budget rules; compact prose and exact references may carry fields without copying a full form. --- @@ -177,54 +177,36 @@ The separately loadable [Solo-Operator AI-Native Orientation module](./prd-tad-a ## Directive Grammar (CID) -Every directive in this guideline set — and every authoring-to-execution or agent-to-agent dispatch message that consumes it, including one dispatched across work trees, devices, or LLMs — is expressed with the uniform, project-agnostic schema owned by the separately loadable [CID Template module](./CID-template.md). That module owns the full frontmatter contract, Sender/Receiver Grounding, the Clarification Protocol, the Composition Rule (including SVO derivation from RAO), Density Rules, Reinforced Constraints, ADLC Budgets, the WBS Task Node dispatch form, the File Naming convention, and the Forbidden-pattern list. This section publishes the **Field Contract** vocabulary, because every `**Directives**:` block in this document instantiates it and a consumed interface belongs with the index rather than behind a load. - -This is the *only* `role`/`action`/`outcome`/`subject`/`verb`/`object` schema this document defines. Every other place "RAO" or "SVO" appears here is one of two things, never a competing schema: -- **A granularity extension of this same triad.** Role—Action—Outcome states each role's default `role`/`action`/`outcome` envelope at document scope; Division of Work re-extends the identical triad to component scope (`role` = owning component — still function, not persona, per the Field Contract), and Concurrent Collaboration & Work-Tree Integrity re-extends it again to work-tree scope (`role` = owning work tree for a capability's current write). Artifact Continuity Authoring Seam's RAO Steps are literal CID `role`/`action`/`outcome` instances, one per execution step, decomposed via the module's WBS Task Node schema whenever a step's `outcome` spans more than one atomic action or ADLC phase. -- **An unrelated reuse of the same three letters.** Mantra Application's "SVO clarifies" names general subject-verb-object grammatical clarity for requirement prose (a PRD user story, a TAD data-flow line, an ADR consequence) — a writing discipline, not this module's `subject`/`verb`/`object` field. That field is the mechanical, per-directive atomic-command derived from `action` per the Composition Rule, and its `subject` defaults to `agent` regardless of which grammatical subject a requirement sentence names. +PRD, TAD, ADR, and authoring-to-execution or agent-to-agent messages consume one [CID/RAO/SVO contract](./cid-guidelines.md#shared-field-contract). Its roles name functions; worktree, device, and agent identities remain provenance rather than competing role definitions. SVO expresses the same RAO action at command granularity, not a second instruction. ### Field Contract -```yaml -context: # situational grounding — what's true right now (state, constraints, prior turns), file/path-cited -intent: # why this message exists — the goal behind the ask, not the ask itself -directive: # the imperative — what the receiver must do, stated as a command, traceable to real repo state - -role: # who the receiver is acting as (function, not persona) -action: # the verb-phrase the role performs -outcome: # the state that must exist when action is complete — the exit condition - -subject: # actor executing the action -verb: # the action itself, single transitive verb where possible -object: # what the verb acts on -``` - -`context + intent + directive` scopes *why/what*; `role + action + outcome` scopes *who/how/done*; `subject + verb + object` is the atomic, derived restatement a receiver parses if it drops everything else. All three tiers must resolve to the same instruction at increasing compression — see Composition Rule in the module. +The [shared field contract](./cid-guidelines.md#shared-field-contract) is the sole schema owner. Carry its fields explicitly or by unambiguous reference in prose, tables, or structured records; all three tiers must resolve to the same instruction. This section adds no fields or mandatory serialization. ### Sorting Each `CID Directive Matrix` entry is organized alphabetically (A→Z) for clarity and neutrality. **Directives**: -- Express every directive in this set, and every dispatched agent-to-agent message, as the Field Contract above; a directive or message missing a required field is a `cid-schema-noncompliant` finding +- Keep each directive and dispatched message resolvable against the shared Field Contract; unresolved required meaning or a competing schema is `cid-schema-noncompliant`, while an omitted duplicate form is not - Cite `context` and `directive` against real, locatable state — a file path, a revision, a Rule ID, a command output — or state `source=unverified` explicitly, per the module's Sender Grounding contract; an uncited or silently-paraphrased citation is a `cid-context-uncited` finding -- Require the receiving agent to open and diff every cited path against actual content before acting on the directive, per Receiver Grounding — this applies with no exception when the cited state was produced by a different work tree, device, or LLM; proceeding on an unverified citation is a `cid-grounding-unverified` finding -- Resolve genuine ambiguity through the Clarification Protocol — one bounded recommendation with a binary confirm/reject outcome, never an open question; an open-ended clarification request is a `cid-clarification-malformed` finding +- Verify cited source state before consuming it, regardless of worktree, device, or LLM origin; reuse evidence bound to an unchanged immutable revision and refresh volatile facts at their consuming transition. Acting on an unverified material claim is `cid-grounding-unverified` +- Resolve ambiguity from current evidence and existing decisions first; ask one concise question only for an unresolved semantic decision, with a concrete recommendation where available. A request for mechanically derivable facts or unnecessary reconfirmation is `cid-clarification-malformed` - Keep the three grammar tiers convergent per the Composition Rule; a `context`/`intent`/`directive` that resolves to a different instruction than its own `role`/`action`/`outcome` or `subject`/`verb`/`object` is a `cid-composition-divergence` finding - Apply the module's Density Rules and forbid its named anti-patterns — Ceremony, Complication, Verbosity — in every directive; a violation of either is a `cid-density-violation` finding -- Decompose a directive into WBS Task Nodes, per the module's schema, when its `outcome` spans more than one atomic action or more than one ADLC phase; a multi-action directive dispatched as a single undecomposed CID is a `cid-decomposition-missing` finding +- Decompose independently closable outcomes into bounded task nodes with dependencies and checks; reuse the same lineage across phases. Missing actionable decomposition is `cid-decomposition-missing`; a phase label alone does not require another file or agent - Stay within the ADLC Budgets on every always-load surface this document or its companions define; a directive that grows such a surface without stating its projected byte/module delta is a `cid-budget-exceeded` finding -- Name any persisted CID message file per the module's File Naming convention (`CID-YYYYMMDDTHHmmZ-.md`, one file per decision); a non-conforming filename is a `cid-naming-noncompliant` finding +- Preserve stable identity and exact revision for persisted messages using the project's declared naming convention; do not require a file per decision. An ambiguous persisted identity is `cid-naming-noncompliant` --- ## Artifact Continuity Authoring Seam -The [Artifact Continuity Module](./agentic-sdlc-artifact-continuity.md) owns the reusable seam and its complete validation contract. PRD owns the product Context, Intent, Directives, normative criteria, and VCCs. TAD consumes that exact PRD revision and owns the structural response. ADR records one grounded decision and its consequences, including the risk it accepts, the mitigation or rollback it commits to, and the failure mode it was written to avoid. The execution companion consumes their joined projection as bounded RAO Steps — each one a CID `role`/`action`/`outcome` instance per Directive Grammar (CID), decomposed via the module's WBS Task Node schema wherever a step's `outcome` spans more than one atomic action or ADLC phase; evidence, demonstration, and successor planning remain downstream companions rather than authoring phases. Where PRD, TAD, or ADR revisions arrive from more than one concurrently active work tree, the join additionally satisfies Concurrent Collaboration & Work-Tree Integrity before baseline. +The [Artifact Continuity Module](./adlc-artifact-continuity.md) owns joins and validation. PRD owns product intent, scope, criteria, and VCCs; TAD consumes that exact revision and owns structure; ADR records material decisions, alternatives, consequences, and relevant recovery. Execution consumes their joined projection as bounded RAO Steps under the shared CID contract. Decompose independently closable outcomes, not phase labels; concurrent revisions also satisfy the collaboration seam before baseline. **Directives**: - Declare stable continuity IDs and exact revisions across PRD, TAD, and ADR; forbid prose, filename, or co-location joins -- Name every generated PRD, TAD, or ADR file `---.md` (`DOC` = `PRD`\|`TAD`\|`ADR`\|`PRD-TAD-ADR`), mirroring the CID Template's File Naming convention (Directive Grammar (CID)) rather than a sequential counter, since a shared counter collides under concurrent multi-work-tree authoring; the timestamp marks creation only, the filename stays fixed for the document's lifetime, and the join to its companions is carried by the continuity ID above, never by the filename — a non-conforming filename, or one touched to reflect a revision, is an `artifact-naming-noncompliant` finding -- Default `DOC` to `PRD-TAD-ADR` — one combined, non-split document carrying all three sections — under the Solo-Operator AI-Native Orientation's min-viable-max-value lens; split into separate `PRD`, `TAD`, `ADR` files only on a stated reason (independent review cadence, cross-team ownership, or a size past the Guideline Load Budget); an unstated split is a `cid-density-violation` finding, since a split that protects nothing costs an extra continuity join for no narrowed failure mode +- Give every generated PRD, TAD, or ADR a stable, collision-free locator under the project's declared naming convention; identify its role and continuity in content. A rename retains exact provenance and repaired references; a filename substituted for a continuity join is `artifact-naming-noncompliant` +- Default to one combined `PRD-TAD-ADR` document with addressable sections; split only for a stated size, ownership, or review need. An unstated split that protects no boundary is a `cid-density-violation` - Carry the continuity ID and exact revision as the join between the `PRD`, `TAD`, and `ADR` sections whether combined in one file or split across several; a filename-based join is `artifact-naming-noncompliant` in either shape - Before baseline, produce an embedded or linked **Codebase Grounding Record** for every externally authored, generated, or imported document (a non-native input) used as specification input, including any PRD: bind the input revision and scoped codebase revision or digest; enumerate every material current-state claim used for capability existence, ownership, reuse, dependency or interface/configuration choice, feasibility, or readiness; cite source, configuration, schema, test, or runtime-contract evidence; and disposition each claim as `confirmed`, `contradicted`, `absent`, or `unverified`. Document provenance and internal consistency are not implementation evidence, while codebase evidence never silently rewrites product intent; a missing record or unresolved claim used to justify baseline, execution, or readiness is an `unproven-claim` - Close PRD-to-TAD coverage, TAD grounding, and applicable ADR joins before deriving RAO Steps @@ -232,23 +214,23 @@ The [Artifact Continuity Module](./agentic-sdlc-artifact-continuity.md) owns the - Require joined independent evidence before satisfaction or readiness advances; forbid narrative or self-graded completion - Reuse the Artifact Continuity Module's findings and reference projections; forbid a parallel continuity vocabulary -**Authoring-to-execution gate**: advance only when Codebase Grounding Record closure, PRD-to-TAD coverage, TAD grounding, Directive-to-RAO coverage, RAO grounding, revision freshness, and evaluator independence are complete. An absent or failing join yields a typed finding and a blocked transition, never an inferred approval. +**Authoring-to-execution gate**: advance only with current Codebase Grounding Records, complete PRD-to-TAD and Directive-to-RAO coverage, grounded design and RAO steps, independent checks, and a recorded decision covering the scope. Correct and re-ground in the authorized authoring loop without clerical reconfirmation; unresolved product, scope, or authority choices block the affected transition. A confirmed capability gap may become planned work within that scope; it never becomes evidence of an existing capability. --- ## Concurrent Collaboration & Work-Tree Integrity -The separately loadable [Concurrency & Work-Tree Protocol module](./prd-tad-adr-concurrency.md) owns the full merge protocol, the lease-free coordination pattern, and the reap-or-merge cadence for hybrid cloud/local operation across multiple devices, multiple LLMs, multiple agents, and multiple work trees. This section owns only the obligations that bind a PRD, TAD, or ADR directly, and states the failure modes this guideline set forbids by name: **deadlock**, **corruption**, **hallucination**, **drift**, and **work-tree sprawl**. Every cross-work-tree transfer this set governs is additionally required to be **lossless** — content present in either parent revision survives the merge — as the positive obligation `drift` and `corruption` are the negative image of. +[Cloud-Authoritative Collaboration](./adlc-cloud-collaboration.md) and [Scoped Lane Admission](./adlc-scoped-lane-admission.md) own coordination across devices, LLMs, agents, and worktrees. This section applies their contracts to PRD, TAD, and ADR and forbids **deadlock**, **corruption**, **hallucination**, **drift**, and **work-tree sprawl**. **Lossless** means preserved owner-authored work and reconstructable history; reviewed intentional replacement or deletion is permitted, silent loss is not. **Directives**: - Carry `worktree_id` and `agent_id` on every revision per Markdown YAML Frontmatter Enforcement whenever more than one work tree is concurrently active on the same document; an unattributed revision under those conditions is a `worktree-provenance-missing` finding - Enforce single-writer-per-capability from Division of Work across every concurrent work tree and agent, not only within one; two work trees mutating the same owning component's capability without a recorded, merged reuse decision is a `duplicate-capability-owner` finding -- Require every cross-work-tree merge to be idempotent and additive — replaying the same merge twice yields the same state — and require every persisted CID message to be append-only per the File Naming convention; a merge whose result depends on ordering or replay count is a `merge-non-idempotent` finding at `major` severity -- Require every cross-work-tree merge to be lossless in addition to idempotent: no field, constraint, Evidence Reference, or continuity ID present in either parent revision may be dropped or silently overwritten; a merge that loses content present in a parent revision is a `merge-lossy` finding at `major` severity, distinct from `merge-non-idempotent` +- Require idempotent integration by exact candidate and receipt: replay returns the recorded result without repeating effects; a replay that changes state is `merge-non-idempotent`. Dependency order remains explicit; arbitrary merges need not commute or preserve obsolete content as a union +- Preserve every owner's unintegrated work and the provenance of intentional changes; a reviewed candidate may remove replaced content while keeping evidence and continuity reconstructable. Silent overwrites, dropped concurrent work, or invented resolution are `merge-lossy`; never force a content union to manufacture preservation - Treat any recorded state that no longer matches its governing source — a phase order, a diagram, a status vocabulary, a continuity ID, a rung — as **drift** the moment it is observed; forbid letting it stand once named, and route it through the specific Finding Type its governing section already owns (`gate-order-drift`, `diagram-spec-drift`, `status-conflict`, or the closest section-owned equivalent) rather than inventing a parallel drift vocabulary - Forbid any lock, lease, or wait condition spanning more than one work tree or device without a stated timeout and an escalation path to the Evaluator; an unbounded cross-work-tree wait is a `deadlock-unbounded-wait` finding at `blocker` severity - Apply Receiver Grounding (Directive Grammar (CID)) with no exception to state produced by another work tree, device, or LLM before acting on it; treat an unverified cross-origin claim as a hallucination risk, not a shortcut — proceeding on it is a `cid-grounding-unverified` finding -- Cap the count of simultaneously open, unmerged work trees per capability at a project-stated ceiling and observe a stated reap-or-merge cadence; a work tree left open past that cadence with no active directive is a `work-tree-sprawl` finding at `minor` severity +- Bound active agents and worktrees by declared task capacity and review cadence; reuse admitted disjoint scopes before opening another lane. Retire or clean only exact profile-selected, receipt-eligible targets; unexplained inactive lanes raise `work-tree-sprawl` without authorizing deletion - Route every irreconcilable concurrent claim — two work trees each asserting a different `outcome` for the same directive — to the Evaluator for a binding verdict; forbid resolving such a conflict by whichever write lands last - Treat a hybrid cloud/local topology as a deployment-model variant of one coordination protocol, never a separate one; a claim authored locally and one authored in cloud CI reconcile through the identical merge and grounding rules, with no silent preference for either origin @@ -366,7 +348,7 @@ The separately loadable [Core Templates module](./prd-tad-adr-templates.md) owns ## Platform-Specific Selection Criteria — Multi-Agent Reasoning Pipeline -The separately loadable [Selection Criteria module](./prd-tad-adr-selection-criteria.md) owns the full constraint worksheet, outranking worksheet, argumentation-graph schema, and worked examples. This section owns only the obligations that bind a PRD, TAD, or ADR directly. Any platform-, vendor-, or provider-level choice runs through three ordered stages — **constraints → outranking → argumentation** — each with a distinct agent role and a distinct recorded artifact; no stage's output may be replaced by a single scalar score standing in for the others, and legacy single-pass weighted-sum or distance-to-ideal scoring (including TOPSIS) is retired from this set. +This section owns the reusable **Constraints ↔ Argumentation ↔ Outranking** pipeline for platform, vendor, or provider choices. The stages name reasoning functions, not a mandatory process count or one-way workflow: constraints gate comparison first, argumentation may challenge assumptions or pairwise relations, and changed evidence reopens affected checks. Keep one compact decision record with source evidence, constraints, comparisons, contested arguments, and an independent verdict; separate agents only where they contribute independent reasoning or evaluation. Single scalar or distance-to-ideal scoring cannot replace hard constraints or the recorded comparison relation. ### Stage 1 — Constraints @@ -379,24 +361,26 @@ A gating pass, run before any comparison: every candidate is disposed `pass` or ### Stage 2 — Outranking -Surviving candidates are compared pairwise against a project-stated, explicitly weighted criteria set using a non-compensatory outranking method — concordance, discordance, and (where the method uses it) credibility per pair — or an equivalent auditable multi-criteria outranking method. The output is a partial order: some pairs resolve to "outranks," some do not resolve at all, and an unresolved pair is a legitimate result, not a defect. +Compare admitted candidates against project-stated criteria with an auditable non-compensatory relation. A simple Pareto comparison suffices when one candidate is no worse on every criterion and strictly better on at least one; use weighted concordance/discordance only when the tradeoff requires it. The result is a partial order; an unresolved pair is legitimate. **Directives**: -- Score every surviving candidate pairwise against the weighted criteria set and record concordance and discordance (or the equivalent intermediate values for a substituted outranking method) per pair; a ranking presented without that pairwise record is unauditable and is an `outranking-relation-unstated` finding at `minor` severity +- Record the criteria and supporting pairwise comparisons needed to justify the selected candidate, including concordance and discordance where the chosen method uses them; an unsupported relation is `outranking-relation-unstated`. A sole admitted candidate needs no fabricated comparison - Preserve incomparability where the outranking relation does not resolve a pair; forbid collapsing an unresolved pair into an arbitrary total order — a forced order over an unresolved pair is an `outranking-incomparability-collapsed` finding at `minor` severity, and every pair it leaves unresolved routes to Stage 3 -- Derive criteria weights from the same governing-requirements source as Stage 1's constraints, never from a candidate's own claims; a criteria set matching one vendor's differentiators is a `vendor-coupling` finding under Scope & Neutrality +- Derive criteria and any weights from the governing requirements, never candidate marketing; a criteria set matching one vendor's differentiators is `vendor-coupling` ### Stage 3 — Argumentation -Every pair the outranking relation leaves unresolved, and every contested verdict, is routed to structured multi-agent argumentation: independent agents each submit an argument — a claim, its support, and its attack or support relation to prior arguments — for or against a candidate, forming an argument graph. The Evaluator (Role—Action—Outcome), distinct from every agent whose argument appears in the graph, renders the binding verdict from the graph's accepted extension (or the equivalent semantics of a substituted argumentation framework). +Route unresolved comparisons and contested assumptions to structured argumentation: a claim, its source evidence, and support/attack relations. Independent agents may test competing reasons within the same declared budget. The Evaluator, independent of the argument producers, records the accepted arguments and verdict; it may leave a choice unresolved rather than invent a winner. **Directives**: -- Build and persist the argument graph — claims, attack/support edges, accepted extension — for every candidate pair reaching this stage; an unresolved pair closed with no recorded argument graph is an `argumentation-graph-missing` finding at `major` severity +- Record the argument graph — claims, support/attack edges, accepted arguments — inline or by exact reference for a contested choice; compact prose or a table suffices when the relations are unambiguous. Closing a contested choice without that record is `argumentation-graph-missing` - Require the rendering Evaluator to hold no argument of its own in the graph it adjudicates; a verdict authored by the same agent that submitted a winning argument is an `argumentation-self-graded` finding at `blocker` severity, extending Evaluator independence (Autonomous Implementation Verification) into the selection pipeline - Attach the persisted argument graph to the selection ADR as its Evidence Reference; a selection ADR whose contested candidates carry no linked argument graph is an `unproven-claim` **Directives (cross-stage)**: -- Label the outcome by its pipeline derivation, never by preference: a write-up naming a winning candidate without its Stage 1 disposition, Stage 2 pairwise record, and (where invoked) Stage 3 argument graph is a `vendor-preference-unscored` finding regardless of whether the ranking itself was sound +- Label the outcome by its pipeline derivation: require constraint dispositions, pairwise evidence when alternatives survive, and an argument graph when contested. An unsupported winning choice is `vendor-preference-unscored`; record why a stage is inapplicable instead of fabricating evidence +- Reopen only affected constraints and comparisons when a cited fact changes; revising a governing requirement follows the authoring authority seam. Argumentation never waives a failed hard constraint, and no useful new evidence means no further reasoning round +- Bound the whole pipeline by the task's time, token, and iteration limits; reuse unchanged evidence and agent roles. At the bound, record the unresolved decision or select a supported in-scope alternative; preserve incomparability and continue disjoint work - Present illustrative constraints, criteria, and candidates only under a heading or block whose own text contains the words "reference implementation," per the Scope & Neutrality Contract; a checklist or candidate list naming real vendors outside such a label is a `vendor-coupling` finding **Reference implementation** — for a solo-operator, AI-native, MCP-/WebMCP-native, edge-native product (any project instantiates its own constraint set, criteria set, and candidates; none of this is universal): Stage 1 constraints typically include license compliance, offline/edge capability, and zero-infra posture; Stage 2 criteria typically include AI-native fit (embedding/vector and agentic-workload support), total cost of ownership, primary-deployment-platform fit, and a mobile-/web-/offline-first delivery triad — browser-based (web-first) delivery, mobile-first delivery, and offline-first operation via on-device/edge execution and local-first data ownership — scored alongside concurrency-safety under multi-device/multi-agent use, token performance and economics, min-viable-max-value, time-to-value, and ROI, with an ELECTRE- or PROMETHEE-style outranking relation; Stage 3 argumentation typically uses an abstract argumentation framework (Dung-style attack graph with grounded or preferred extension). A project's "primary-platform fit" criterion names whichever platform that project has already adopted as primary as a reference implementation of the general criterion — the criterion itself, not the named platform or method, is what every future ADR in that project's set re-applies. @@ -405,12 +389,12 @@ Every pair the outranking relation leaves unresolved, and every contested verdic ## Pain-Point-to-Feature Mapping -The separately loadable [Pain-Point Mapping module](./prd-tad-adr-pain-point-mapping.md) owns the fixed six-field card form and its authoring procedure. This section owns only the obligations that bind a PRD directly. +This section owns the pain-point-to-feature record and its evidence requirements; embed it in the PRD or reference the exact record. **Directives**: - Trace every `Must`-priority feature to exactly one named pain point stated as: pain point, hook, break, fix, close, and a min-time-resource-max-value note; a feature with no traceable pain point is unscoped, not merely under-documented - State the min-time-resource-max-value note as an explicit reuse-or-build split against components named in Division of Work; forbid presenting a fix as net-new when an existing capability already covers it -- Label a pain point `unvalidated` until it carries a named evidence reference (a user quote, a ticket, a measured drop-off), and label it `demand-proven` only when that evidence is a real paying customer — a signed pilot, an active subscription, a completed transaction — rather than expressed interest; an `unvalidated` pain point still backing a `Must` feature at baseline sign-off is a `pain-point-not-validated` finding at `major` severity +- Label a pain point `unvalidated` until a user quote, ticket, or measured behavior supports it; label it `demand-proven` only with actual paid-customer evidence. A price signal, unpaid signed pilot, or test transaction is WTP or mechanism evidence, not collected revenue; an `unvalidated` pain point backing a `Must` at baseline is `pain-point-not-validated` - Rank competing fixes for the same pain point by proximity to what is already built — zero-code-change configuration first, minimal-code-change extension of an existing component second, net-new build last — before weighing any other feasibility factor; a fix ranked above a lower-cost equivalent with no stated reason is a `roadmap-order-unexplained` finding - Prioritize among qualifying pain points by evidence of willingness-to-pay (WTP) magnitude — a stated price point, deal size, or committed budget — ahead of build cost or technical elegance; a `Must` ranking that inverts a recorded WTP ordering with no stated reason is a `roadmap-order-unexplained` finding, and a pain point with no WTP evidence at all cannot outrank one that has it - Forbid a hook or close that implies a capability the fix does not have; both restate the pain point, they do not extend the claim beyond it @@ -419,7 +403,7 @@ The separately loadable [Pain-Point Mapping module](./prd-tad-adr-pain-point-map ## Demo Skeleton -The separately loadable [Demo Skeleton module](./prd-tad-adr-demo-skeleton.md) owns the beat catalog and timing conventions. This section owns only the obligations that bind a PRD directly. +This section owns the bounded demonstration sequence; one compact flow may satisfy it without another document. **Directives**: - Require a fixed, time-boxed beat table — Hook, Probe, Reveal, `[domain action]`, Close — for every feature claiming `Must` priority or a Domain-Object Rubric rung of L3 or above; a beat with no stated time bound is a `missing-demo-beat` finding @@ -431,11 +415,11 @@ The separately loadable [Demo Skeleton module](./prd-tad-adr-demo-skeleton.md) o ## Domain-Object Rubric Assessment -The separately loadable [Domain-Object Rubric module](./prd-tad-adr-domain-object-rubric.md) owns the leveled rubric catalog and scoring procedure. This section owns only the obligations that bind a PRD or TAD directly. +This section owns rubric assessment. When using a rubric, the PRD or TAD declares or cites its exact levels and named acceptance checks; no universal domain object or external catalog is implied. **Directives**: - Identify the product's actual domain object before applying any external leveled capability rubric; forbid scoring against a rubric's supplied example object when the product's own domain object is structurally different -- Report the rubric level as the lowest level not yet cleared, not the highest level partially attempted; a self-assessment reporting an aspirational level while a lower level's named prerequisite is absent is an `overclaimed-rubric-level` finding at `major` severity +- Report the attained rubric level as the highest contiguous level whose checks pass, and the next unpassed level as a gap; claiming an aspirational level while a prerequisite is absent is `overclaimed-rubric-level` - Name the specific blocking component for every unclaimed rung between the current and target level; an unclaimed rung with no stated blocker is an `unresolved-rubric-gap` finding - Permit closing a rubric gap by reusing an existing capability from another artifact in this set; require an explicit cross-artifact reference per Division of Work rather than a silent re-implementation @@ -443,7 +427,7 @@ The separately loadable [Domain-Object Rubric module](./prd-tad-adr-domain-objec ## Roadmap -The separately loadable [Roadmap module](./prd-tad-adr-roadmap.md) owns the phase-table template and sequencing procedure. This section owns only the obligations that bind a PRD or TAD directly. +This section owns the compact roadmap: feature, current reuse, new work, priority rationale, and prerequisite per phase. **Directives**: - State, for every roadmap phase: the feature, what it reuses (naming the specific existing component or artifact), what is genuinely new, and a priority rationale; a phase with an empty reuse statement and no stated justification is a `roadmap-reuse-unstated` finding @@ -455,13 +439,13 @@ The separately loadable [Roadmap module](./prd-tad-adr-roadmap.md) owns the phas ## Monetization -The separately loadable [Monetization module](./prd-tad-adr-monetization.md) owns the stream-labelling procedure and validation-action catalog. This section owns only the obligations that bind a PRD directly. +This section owns monetization evidence and stream selection; reference observed customer results and distinguish them from pricing or settlement mechanism checks. **Directives**: -- Label every monetization stream exactly one of `mechanism-proven` (the pricing/settlement logic works against test data) or `demand-validated` (a named customer segment has indicated willingness to pay, or has paid); presenting `mechanism-proven` as `demand-validated` is a `monetization-demand-unvalidated` finding at `major` severity +- Track `mechanism-proven` (pricing/settlement works against stated test inputs) and `demand-validated` (a named segment supplies WTP evidence) independently; either may exist without the other. Record actual payment separately before claiming revenue; using a mechanism test as demand or paid evidence is `monetization-demand-unvalidated` - Select the nearest-term stream by which customer segment already exists in the current phase, not by which stream is technically simplest; a stream requiring a segment gated behind a later phase is `Should`/`Could` at best until that segment exists, never `Must` - Order every viable stream by its distance to a real first dollar — the fewest unvalidated assumptions and the least unbuilt infrastructure between today and one paying transaction — and state that ordering explicitly; a monetization section that proposes multiple streams without ranking them by time-to-first-dollar is a `monetization-demand-unvalidated` finding -- Require a stated validation action — a customer conversation, a priced pilot, real signups — before using the `demand-validated` label +- Require the result of a validation action — a priced customer conversation, pilot commitment, or payment — before using `demand-validated`; a planned action or unpriced signup alone is not WTP evidence - Forbid deferring a monetization decision without stating the deferral explicitly; an undocumented default-to-free stance forecloses the test of whether a real payer exists --- @@ -543,7 +527,7 @@ The separately loadable [Validation Checklist module](./prd-tad-adr-verification ## Division of Work -The separately loadable [Division of Work module](./prd-tad-adr-division-of-work.md) owns the capability-ownership procedure and the reuse-decision record form. This section owns only the obligations that bind a TAD or ADR directly, and extends the CID `role`/`action`/`outcome` triad (Directive Grammar (CID)) from human-role granularity — as catalogued in Role—Action—Outcome — to component granularity: `role` names the owning component (still function, not persona, per the Field Contract), `action` names the capability it performs, `outcome` is that capability existing and reachable only through that component. Concurrent Collaboration & Work-Tree Integrity re-applies this same single-writer-per-capability rule across simultaneously active work trees, devices, and agents. +This section owns capability ownership and reuse decisions in TAD and ADR. Apply the shared RAO contract to components: the role is the capability owner, action is its transformation, and outcome is independently checked behavior. Other consumers call that owner; collaboration provenance identifies the current writer without redefining the role. **Directives**: - Assign exactly one owning component per capability (a pricing computation, a state-change detection, a ledger mutation); every other consumer calls the owning component rather than re-implementing its logic; a second implementation of an existing capability is a `duplicate-capability-owner` finding at `major` severity, extending `duplicate-owner` from document ownership to component ownership @@ -561,9 +545,9 @@ Each entry is the document-scope default `role`/`action`/`outcome` envelope defi **System Architect** → designs component interactions, maps data flows, specifies interfaces, documents ADRs, defines quality attributes, plans deployment → establishes technical foundation enabling scalable implementation -**Solo Founder / AI Orchestrator** *(collapses all **authoring** roles in a solo-operator context, however many concurrent work trees, devices, or LLM agents carry the work; does not collapse the Evaluator)* → validates ROI before writing any doc, applies min-viable-max-value lens to MoSCoW, designs harness contracts for every AI component, sets token budgets, maintains FOSS-first ADRs, tracks TCO actuals each sprint, keeps concurrent work trees within the reap-or-merge cadence → ships high-ROI features at near-zero infrastructure cost while keeping the codebase auditable and the AI pipelines observable +**Solo Founder / AI Orchestrator** *(combines authoring roles while preserving independent evaluation)* → grounds pain and WTP, ranks reusable solutions, states resource bounds, tracks observed TCO, and keeps collaboration within declared capacity and exact cleanup policy → delivers verified user outcomes and measured economics without duplicate agents or lanes -**Evaluator** *(a mechanism, never a person; the one role that must not collapse into any other, including any work tree or agent whose output it judges)* → judges each VCC against the surfaced output only, records the Evidence Reference, derives the readiness rung, resolves irreconcilable concurrent claims, renders selection verdicts from an argumentation graph it holds no argument in, and emits the finding set with types and severities → produces verdicts no participant can self-grade, which is what makes a rung and an alignment claim trustworthy. See the Agentic SDLC Guidelines companion set for how this role is instantiated and bounded during execution. +**Evaluator** *(a mechanism, never a person; the one role that must not collapse into any other, including any work tree or agent whose output it judges)* → judges each VCC against the surfaced output only, records the Evidence Reference, derives the readiness rung, resolves irreconcilable concurrent claims, renders selection verdicts from an argumentation graph it holds no argument in, and emits the finding set with types and severities → produces verdicts no participant can self-grade, which is what makes a rung and an alignment claim trustworthy. See the ADLC Guidelines companion set for how this role is instantiated and bounded during execution. **UX Designer** → creates personas, maps user journeys, validates usability requirements, provides design guidance → ensures user-centered design principles guide feature development @@ -581,18 +565,18 @@ Each entry is the document-scope default `role`/`action`/`outcome` envelope defi **"CID frames PRD/TAD standards · Flow patterns anchor stories to reality · Agent-platform readiness sequences Must before Follow-on · Pain points ground every feature · Demo skeletons prove the story in one sitting · Domain-object rubrics name the breakthrough honestly · Roadmaps sequence reuse before invention · Monetization tests a real payer before it tests a mechanism · RAO aligns team responsibilities · Division of work gives each capability exactly one owner · Concurrent collaboration keeps every work tree honest without a single point of blocking · SVO clarifies requirement semantics · VCC closes the loop from criterion to verified implementation · Evidence earns the rung · Findings make the rules checkable · Boundaries stay closed until an operator opens them"** -- **CID frames**: establishes scope (product + technical), purpose (user value + clarity), rules (problem-first · domain-agnostic · traceable), every directive cited against real state and held to the CID Template's grounding, density, and ADLC-budget obligations +- **CID frames**: establishes scope, user value, and traceable rules under the shared CID contract's grounding, density, and ADLC budgets - **Flow patterns anchor**: user journeys, workflows, data flows, orchestration/harness flows, and topology connect abstract requirements to observable system behavior; every feature traces through all five; time-to-value is the gate metric that validates the shortest path through them - **Agent-platform readiness sequences**: Agentic OS visibility → AI Agent discovery → Gateway federation (Must); then spend safety → live orchestration proof → operator UI (Follow-on); forbid proxy duplication and dependency-blind parallel surface work - **Pain points ground**: every `Must` feature traces to one named pain point in fixed form, labelled `unvalidated` until an evidence reference exists — a feature with no pain point is unscoped, not merely under-documented - **Demo skeletons prove**: a fixed, time-boxed beat table anchors the Reveal beat to the feature's own VCC, so the demonstration shows the acceptance condition holding rather than narrating a claim of it - **Domain-object rubrics name**: the product's actual domain object is identified before any external rubric is applied, and the reported level is the lowest not yet cleared — never the highest aspired to - **Roadmaps sequence**: phases order by reuse-adjusted build cost, each stating what it reuses and what is genuinely new; a real, deferred idea is marked `Won't (this increment)`, never silently dropped -- **Monetization tests**: a stream is `mechanism-proven` or `demand-validated`, never presented as one when it is only the other, and the nearest-term stream is chosen by which customer segment already exists, not by which mechanism is simplest to build +- **Monetization tests**: mechanism evidence, WTP evidence, and collected revenue remain separate; prioritize an existing payer segment and the shortest credible path to its paid outcome - **RAO aligns**: maps each role to documentation deliverables with clear accountability and measurable outcomes — the document-granularity instance of the CID `role`/`action`/`outcome` triad (Directive Grammar (CID)) - **Division of work**: assigns exactly one owning component per capability, extending the CID `role`/`action`/`outcome` triad from roles-to-documents into components-to-capabilities — every other consumer calls the owner rather than re-implementing it -- **Concurrent collaboration keeps honest**: re-applies single-writer-per-capability across simultaneously active work trees, devices, and agents; merges are idempotent and lossless, waits are timeboxed with an escalation path, and cross-origin claims are re-grounded before use — deadlock, corruption, hallucination, drift, and work-tree sprawl are named failure modes, not incidental risks -- **SVO (Subject-Verb-Object) clarifies**: expresses every requirement sentence — a PRD user story, a TAD data-flow line, an ADR consequence — with grammatical precision (users accomplish tasks → systems process data → components deliver artifacts), enabling unambiguous implementation; distinct from the CID module's `subject`/`verb`/`object` field, which is the mechanical atomic-command derived from a single directive's `action` (Directive Grammar (CID)) +- **Concurrent collaboration keeps honest**: one current writer owns an overlapping scope; exact replays are idempotent, owner work and history survive, and reviewed obsolete content may be removed. Bound waits and capacity, verify cross-origin claims, and use exact profile-selected cleanup receipts +- **SVO (Subject-Verb-Object) clarifies**: expresses the same accountable action as RAO using the shared contract; requirement prose names its actor, action, and target without creating another command schema - **Evidence earns**: a readiness rung is computed from named checks with recorded results, never asserted; the ladder is monotone under added evidence, so status can only be raised by proof - **Findings make checkable**: every prohibition carries a type and a severity, so alignment is a comparable measurement across runs rather than an impression that resets each review - **Boundaries stay closed**: promotion toward a public surface requires a named gate, its evidence, its rollback path, and a referenced operator instruction; the default state is closed, so nothing reaches the delivery lane by momentum diff --git a/guidelines/prd-tad-adr-process-flows.md b/guidelines/prd-tad-adr-process-flows.md index 07319413..dd152e72 100644 --- a/guidelines/prd-tad-adr-process-flows.md +++ b/guidelines/prd-tad-adr-process-flows.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Process & Flow Patterns Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-20" +version: "1.1.0" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.9.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Process & Flow Patterns Module @@ -26,10 +28,13 @@ It inherits the parent set's Scope & Neutrality Contract, Rule Identity derivati ## From 0 to 1: PRD & TAD Creation Process -A sequential, phase-gated process for producing aligned PRD and TAD from scratch. +These are artifact roles and evidence seams, not mandatory meetings or separate files. Existing explicit +objective/scope authorization covers reversible in-scope authoring and execution after the relevant checks. +Re-enter only the affected seam when evidence changes; new product choices and production effects retain +their authority boundary under [ADLC autonomous continuation](./adlc-autonomous-continuation.md). ### Phase 0 — Problem Discovery -**Before writing any document, validate the problem exists.** +**Start with a falsifiable pain hypothesis; validate it before claiming demand.** 1. Identify target personas and their pain points via research 2. Quantify problem impact with observable metrics @@ -40,7 +45,9 @@ A sequential, phase-gated process for producing aligned PRD and TAD from scratch 7. Identify whether the solution requires an AI harness, FOSS tools, or proprietary APIs — flag any dependency with non-zero egress or token cost 8. Estimate **time-to-value (TTV)**: count the minimum steps a target persona must complete from zero state (prerequisites installed, no configuration done) to first successful outcome; set an acceptable TTV ceiling before Phase 1 begins; flag if TTV exceeds threshold -**Gate**: proceed only when problem is validated, scoped, ROI-positive at estimated TCO, and TTV is within acceptable ceiling. +**Gate**: record pain/WTP evidence or label the hypothesis unvalidated, scope the next learning or delivery +outcome, and compare expected value, TCO and TTV with explicit assumptions. A bounded discovery sprint +may gather missing evidence; it cannot claim demand, revenue or production readiness without proof. ### Phase 1 — PRD Authoring **Translate validated problems into structured requirements.** @@ -56,7 +63,8 @@ A sequential, phase-gated process for producing aligned PRD and TAD from scratch 9. Log open questions and unresolved assumptions 10. Flag every dependency: FOSS, zero-TCO, or justify proprietary selection inline -**Gate**: architects review PRD for technical feasibility **and TCO/token-budget alignment** before Phase 2. +**Gate**: verify PRD feasibility and TCO/token-budget alignment before dependent design. A named check +or independent reviewer supplies the verdict; a separate architect role or meeting is not required. ### Phase 2 — TAD Authoring **Translate PRD requirements into verifiable architecture.** @@ -76,10 +84,11 @@ A sequential, phase-gated process for producing aligned PRD and TAD from scratch 13. Render architecture diagrams in the mandated notation; compile the component inventory table and the Diagram Register 14. Derive Verifiable Completion Conditions (VCCs) from acceptance criteria — each criterion must be expressible as a condition an autonomous agent can evaluate from its own surfaced output -**Gate**: product manager validates TAD preserves user value **and** ROI/TCO envelope before Phase 3. +**Gate**: independently verify that TAD preserves user value and the accepted ROI/TCO envelope. +Reuse the current scope decision; ask only when a material choice remains unresolved. ### Phase 3 — Alignment & Review -**Verify PRD ↔ TAD coherence and stakeholder sign-off.** +**Verify PRD ↔ TAD coherence and applicable authorization.** 1. Establish bidirectional traceability: `PRD-[Epic]-[Story] ↔ TAD-[Component]-[Interface]` 2. Confirm no implementation detail in PRD; no business logic in TAD @@ -93,7 +102,9 @@ A sequential, phase-gated process for producing aligned PRD and TAD from scratch 10. Confirm every lane and Deploy Boundary is documented and that every boundary reads `closed` absent a referenced operator instruction 11. Resolve or formally track all open questions -**Gate**: both documents version-stamped and baselined, and the alignment check reporting zero `blocker` findings, before implementation begins. +**Gate**: referenced artifact revisions and affected alignment checks must support dependent implementation. +Correct in-scope grounding defects in the owning artifact, then recheck; continue dependency-disjoint work. +Do not request a new approval for a reversible seam already covered by the recorded objective and scope. ### Phase 4 — Living Documents **Iterate documents as product and architecture evolve.** @@ -101,7 +112,7 @@ A sequential, phase-gated process for producing aligned PRD and TAD from scratch - Apply semantic versioning to every change - Update PRD and TAD together whenever requirements shift - Re-run relevant gate reviews for breaking changes -- Archive superseded ADRs; do not delete +- Preserve superseded ADR decisions through a stable successor link and retrievable revision history; reviewed cleanup may remove obsolete projections - Re-derive VCCs whenever acceptance criteria change; stale conditions produce false completions - **Re-derive every readiness rung** whenever a VCC or an Evidence Reference changes; a rung is a computed value, so leaving it pinned after the evidence moves is a false completion - **Re-run the alignment check** on every baselined change and compare the finding set against the prior run; a new `blocker` finding is a regression, not a note diff --git a/guidelines/prd-tad-adr-readiness.md b/guidelines/prd-tad-adr-readiness.md index 226fc6d5..4b1e55fa 100644 --- a/guidelines/prd-tad-adr-readiness.md +++ b/guidelines/prd-tad-adr-readiness.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Readiness & Lane Topology Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.9.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Readiness & Lane Topology Module diff --git a/guidelines/prd-tad-adr-templates.md b/guidelines/prd-tad-adr-templates.md index 6b76e08f..fd5f6775 100644 --- a/guidelines/prd-tad-adr-templates.md +++ b/guidelines/prd-tad-adr-templates.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Core Templates Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.9.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Core Templates Module diff --git a/guidelines/prd-tad-adr-verification.md b/guidelines/prd-tad-adr-verification.md index 2db9d34d..48e4b920 100644 --- a/guidelines/prd-tad-adr-verification.md +++ b/guidelines/prd-tad-adr-verification.md @@ -1,17 +1,19 @@ --- title: "PRD, TAD & ADR Verification & Conformance Module" doc_type: "Guidelines Module" -version: "1.0.0" -date: "2026-08-20" +version: "1.0.1" +date: "2026-09-05" lang: "en-US" frontmatter_contract: "required" owner: "Technical Writer function" local_rung: "spec-complete" delivered_rung: "undocumented" lane: "authoring" -universal_scope: "true" +universal_scope: true parent: "PRD, TAD & ADR Guidelines" -parent_version: "1.9.0" +parent_version: "2.4.0" +runtime_readiness_policy: "fail-closed" +lifecycle_status: "proposed" --- # PRD, TAD & ADR Verification & Conformance Module @@ -241,7 +243,7 @@ Every finding carries exactly six fields: ### Directives -- Treat this enumeration as the single source of truth for **authoring-domain** finding names; execution-domain findings (task, agent, and tool-permission violations) are owned by the Agentic SDLC Guidelines companion set, and the conformance vocabulary is the union of the two. Forbid either set redefining a type the other owns +- Treat this enumeration as the single source of truth for **authoring-domain** finding names; execution-domain findings (task, agent, and tool-permission violations) are owned by the ADLC Guidelines companion set, and the conformance vocabulary is the union of the two. Forbid either set redefining a type the other owns - A check that invents a type string cannot be compared against a prior run - Where a rule states a severity inline, that stated severity governs over the table default - Deduplicate on the triple `(Finding Type, Rule ID, artifact reference)`; one violation is one finding no matter how many passes observe it, and Rule ID granularity keeps two distinct violations in one section distinct @@ -338,7 +340,7 @@ The regression comparison above is meaningless unless two runs over the same inp - [ ] **Check determinism satisfied**: deterministic, order-independent, additive, bounded, comparable, and complete on degraded input - [ ] **Evaluator is a distinct mechanism** from the implementer; role collapse does not extend to the Evaluator - [ ] **Guideline load budget respected**: sections loaded per phase; guideline load cost recorded in the authoring loop's token budget -- [ ] **Execution-domain conformance discharged** against the Agentic SDLC Guidelines companion set; a runtime-readiness claim sourced from this document alone is incomplete +- [ ] **Execution-domain conformance discharged** against the ADLC Guidelines companion set; a runtime-readiness claim sourced from this document alone is incomplete - [ ] **Diagram-domain and canvas-domain conformance discharged** against the diagram companion modules; the finding set is reported as the union of all four domain enumerations, and a canvas-renderability claim sourced from this document alone is incomplete - [ ] **Zero `blocker` findings** before baseline sign-off; `major` and `minor` findings resolved or formally tracked with an owner - [ ] **Finding set compared** against the prior run; any new `blocker` treated as a regression diff --git a/index.html b/index.html index 67136451..6899350e 100644 --- a/index.html +++ b/index.html @@ -3,8 +3,8 @@ - - Agentic SDLC Guidelines + + ADLC Guidelines