From 38a4553257365e16a4508a5fe23545eebd998b8d Mon Sep 17 00:00:00 2001 From: leynos Date: Tue, 3 Nov 2026 12:45:45 +0100 Subject: [PATCH] Adopt documentation style guide ADR naming Import the latest documentation style guide and apply its four-digit RFC and ADR naming conventions. Move all four ADRs into the canonical directory, use title-derived slugs, and update references throughout docs and workflow prompts. Regenerate the ODW artefact from its TypeScript source. --- ...hes-for-codex-oriented-df12-build-runs.md} | 2 +- ...ial-task-branches-before-fresh-restart.md} | 2 +- ...emetry-observability-for-workshop-runs.md} | 2 +- .../adr-0004-oxlint-rules-for-odw-source.md} | 4 +- docs/architecture.md | 13 +- docs/contents.md | 16 +- docs/developers-guide.md | 29 +- docs/documentation-style-guide.md | 283 +++++++++++++++--- docs/execplans/5-1-1-otel-support.md | 56 ++-- .../adr-002-partial-task-branch-assessment.md | 35 +-- docs/execplans/odw-compilation.md | 4 +- docs/failure-resume-design.md | 14 +- docs/roadmap.md | 26 +- docs/users-guide.md | 4 +- docs/workflow-observability-contract.md | 16 +- skills/df12-build-supervisor/SKILL.md | 2 +- src/workflows/df12-build-odw/assessment.ts | 16 +- src/workflows/df12-build-odw/config.ts | 2 +- src/workflows/df12-build-odw/main.ts | 6 +- src/workflows/df12-build-odw/run-task.ts | 6 +- src/workflows/df12-build-odw/schemas.ts | 6 +- tests/df12-build-odw-assessment.test.mjs | 2 +- tests/df12-build-odw-recovery.test.mjs | 10 +- .../prompts/recovery-resume-code-review.txt | 2 +- .../prompts/recovery-resume-expert-review.txt | 2 +- .../prompts/recovery-resume-integrate.txt | 2 +- tests/fixtures/recovery-mock-agent.mjs | 2 +- tests/fixtures/recovery-repo.mjs | 4 +- tests/fixtures/run-odw-simulation.mjs | 2 +- tests/modules/assessment.test.ts | 4 +- tests/modules/schemas.test.ts | 2 +- workflows/df12-build-odw.js | 6 +- workflows/df12-build.js | 2 +- 33 files changed, 392 insertions(+), 192 deletions(-) rename docs/{adr-001-adopt-odw-sidecar-launches.md => adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md} (97%) rename docs/{adr-002-assess-partial-task-branches.md => adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md} (99%) rename docs/{adr-003-opentelemetry-observability.md => adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md} (99%) rename docs/{adr-004-linting-strategy.md => adrs/adr-0004-oxlint-rules-for-odw-source.md} (96%) diff --git a/docs/adr-001-adopt-odw-sidecar-launches.md b/docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md similarity index 97% rename from docs/adr-001-adopt-odw-sidecar-launches.md rename to docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md index 0ba51c51..31988dc0 100644 --- a/docs/adr-001-adopt-odw-sidecar-launches.md +++ b/docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md @@ -1,4 +1,4 @@ -# ADR 001: Adopt ODW sidecar launches for Codex-oriented df12-build runs +# Architectural decision record (ADR) 0001: Adopt ODW sidecar launches for Codex-oriented df12-build runs ## Status diff --git a/docs/adr-002-assess-partial-task-branches.md b/docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md similarity index 99% rename from docs/adr-002-assess-partial-task-branches.md rename to docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md index cfbaaa99..ee8c7776 100644 --- a/docs/adr-002-assess-partial-task-branches.md +++ b/docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md @@ -1,4 +1,4 @@ -# ADR 002: Assess partial task branches before fresh restart +# Architectural decision record (ADR) 0002: Assess partial task branches before fresh restart ## Status diff --git a/docs/adr-003-opentelemetry-observability.md b/docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md similarity index 99% rename from docs/adr-003-opentelemetry-observability.md rename to docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md index 1fb9cb76..23b23b1f 100644 --- a/docs/adr-003-opentelemetry-observability.md +++ b/docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md @@ -1,4 +1,4 @@ -# Architectural decision record (ADR) 003: correlation-first OpenTelemetry observability for workshop runs +# Architectural decision record (ADR) 0003: Correlation-first OpenTelemetry observability for workshop runs ## Status diff --git a/docs/adr-004-linting-strategy.md b/docs/adrs/adr-0004-oxlint-rules-for-odw-source.md similarity index 96% rename from docs/adr-004-linting-strategy.md rename to docs/adrs/adr-0004-oxlint-rules-for-odw-source.md index 03c2ccd6..fcb4feeb 100644 --- a/docs/adr-004-linting-strategy.md +++ b/docs/adrs/adr-0004-oxlint-rules-for-odw-source.md @@ -1,4 +1,4 @@ -# Architectural decision record (ADR) 004: Oxlint rules for ODW source +# Architectural decision record (ADR) 0004: Oxlint rules for ODW source ## Status @@ -34,7 +34,7 @@ artefacts as if they were authored source. ## Decision outcome `make lint` runs Oxlint against `src/` using -[`oxlint.config.mjs`](../oxlint.config.mjs). The configuration enables the +[`oxlint.config.mjs`](../../oxlint.config.mjs). The configuration enables the Unicorn plug-in rules supported by the pinned Oxlint release, imports the recommended `ai-deslop` rules, enables type-aware linting, and turns the other Oxlint categories off. It excludes `workflows/**`. Tests remain outside this diff --git a/docs/architecture.md b/docs/architecture.md index 4fc45dd2..50c39b34 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,7 +44,7 @@ handoff mechanism. The workflow follows this high-level sequence: - Run fresh-run recovery when `resumePartialBranches=true`: discover surviving - `roadmap-*` branches from durable Git state, assess them through the ADR 002 + `roadmap-*` branches from durable Git state, assess them through the ADR 0002 contract, and either report them (assess mode) or route eligible clean `adopt-complete` branches into the ordinary review and integration path (review mode). Discovered ids are held out of normal selection for the rest @@ -289,11 +289,12 @@ The sidecar contract is documented at three levels: external services, prompt-injection surface, and sandbox profiles. - `docs/developers-guide.md` explains how contributors change the workflow and keep documentation synchronized. -- `docs/adr-001-adopt-odw-sidecar-launches.md` records the architectural - decision to use ODW sidecar launches for Codex- and Claude-oriented runs. -- `docs/adr-002-assess-partial-task-branches.md` records the accepted - assessment stage for preserving useful partial task branches without resuming - transient agent transcripts. +- `docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md` + records the architectural decision to use ODW sidecar launches for Codex- and + Claude-oriented runs. +- `docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md` + records the accepted assessment stage for preserving useful partial task + branches without resuming transient agent transcripts. Changes to launch behaviour, sidecar artefacts, configuration arguments, or agent-routing defaults must update all affected layers in the same branch. diff --git a/docs/contents.md b/docs/contents.md index f05c3771..767efcf9 100644 --- a/docs/contents.md +++ b/docs/contents.md @@ -42,24 +42,24 @@ workflow assets, or understanding why the system is shaped the way it is. ## Decision records -- [ADR 001: Adopt ODW sidecar launches](adr-001-adopt-odw-sidecar-launches.md): +- [ADR 0001: Adopt ODW sidecar launches](adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md): records the decision to launch Codex-oriented runs from a sidecar directory. -- [ADR 002: Assess partial task branches](adr-002-assess-partial-task-branches.md): +- [ADR 0002: Assess partial task branches](adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md): records the decision to assess surviving task branches before a fresh restart. -- [ADR 003: Correlation-first OpenTelemetry observability](adr-003-opentelemetry-observability.md): +- [ADR 0003: Correlation-first OpenTelemetry observability](adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md): records the accepted decision to correlate workflow nodes and agent telemetry through dispatch-time identity, a local OTLP collector, and a SQLite store. -- [ADR 004: Oxlint source rules](adr-004-linting-strategy.md): records the - pinned Unicorn and deslop profiles for authored ODW source and the workflow - artefact exclusion. +- [ADR 0004: Oxlint source rules](adrs/adr-0004-oxlint-rules-for-odw-source.md): + records the pinned Unicorn and deslop profiles for authored ODW source and + the workflow artefact exclusion. ## Plans - [Execution plans](execplans/): self-contained execution plans for larger pieces of work. - - [ADR 002 partial task branch assessment](execplans/adr-002-partial-task-branch-assessment.md): + - [ADR 0002 partial task branch assessment](execplans/adr-002-partial-task-branch-assessment.md): the plan behind the partial-branch assessment behaviour. - [ODW compilation](execplans/odw-compilation.md): the plan behind the compile-time testing and artefact build. - [Workflow observability contract (5.1.1)](execplans/5-1-1-otel-support.md): - the plan for defining the identity and schema contract behind ADR 003. + the plan for defining the identity and schema contract behind ADR 0003. diff --git a/docs/developers-guide.md b/docs/developers-guide.md index 454fd910..17c9a890 100644 --- a/docs/developers-guide.md +++ b/docs/developers-guide.md @@ -13,12 +13,12 @@ Read these before changing launch or workflow behaviour: boundaries. - `docs/security-and-permissions.md` for runtime permissions, external service access, prompt-injection risk, and sandbox recommendations. -- `docs/adr-001-adopt-odw-sidecar-launches.md` for the accepted sidecar launch - decision. -- `docs/adr-002-assess-partial-task-branches.md` for the accepted partial - branch assessment and adoption model. -- `docs/adr-003-opentelemetry-observability.md` for the accepted - correlation-first observability fabric, and +- `docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md` + for the accepted sidecar launch decision. +- `docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md` for + the accepted partial branch assessment and adoption model. +- `docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md` + for the accepted correlation-first observability fabric, and `docs/workflow-observability-contract.md` for the version-1 identity model, attribute registry, envelope, and binding schemas that later steps build against. @@ -86,13 +86,14 @@ Relevant paths: - `docs/security-and-permissions.md`: runtime permissions and sandbox guide. - `docs/developers-guide.md`: contributor-facing maintenance guide. - `docs/architecture.md`: design-level sidecar and workflow contract. -- `docs/adr-001-adopt-odw-sidecar-launches.md`: accepted launch decision. -- `docs/adr-002-assess-partial-task-branches.md`: accepted recovery assessment - decision. -- `docs/adr-003-opentelemetry-observability.md`: accepted observability - decision, with `docs/workflow-observability-contract.md` and - `schemas/observability/` as its normative contract and machine-readable - schemas. +- `docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md`: + accepted launch decision. +- `docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md`: + accepted recovery assessment decision. +- `docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md`: + accepted observability decision, with + `docs/workflow-observability-contract.md` and `schemas/observability/` as its + normative contract and machine-readable schemas. Tick the matching roadmap task and update the relevant ExecPlan whenever a branch lands planned work. @@ -790,7 +791,7 @@ what stops `make all`'s lenient verification quietly skipping in CI. `oxlint.config.mjs` applies the supported Unicorn recommended rules and the recommended `ai-deslop` rules with type-aware checks. Its exact dependency pins, the Unicorn/deslop rule conflict, and scoped ODW rule exceptions are -recorded in `docs/adr-004-linting-strategy.md`. +recorded in `docs/adrs/adr-0004-oxlint-rules-for-odw-source.md`. The workflow artefacts in `workflows/` are excluded from Oxlint. They are object code: `make workflow-parse` checks their workflow syntax and diff --git a/docs/documentation-style-guide.md b/docs/documentation-style-guide.md index 7461d9d7..2ad7ba7a 100644 --- a/docs/documentation-style-guide.md +++ b/docs/documentation-style-guide.md @@ -21,7 +21,12 @@ consistent, and easy to maintain across projects. - and so forth. - The words **"outwith"** and **"caveat"** are acceptable. - Keep United States (US) spelling when used in an API, for example, `color`. + Wrap such API names in backticks: the spelling gate ignores backticked spans, + so quoting an identifier both documents its origin and exempts it from the + Oxford-spelling check. - The project uses the filename `LICENSE` for community consistency. +- Markdown prose is checked against this spelling policy with + [`typos`](https://github.com/crate-ci/typos). ## Punctuation and grammar @@ -34,7 +39,19 @@ consistent, and easy to maintain across projects. ## Headings -- Write headings in sentence case. +- Write headings in sentence case: capitalize only the first word and any + proper nouns, acronyms, or other words that are always capitalized, for + example `Context and problem statement` and `RFC number`. +- Treat a bold label in a list of required or conditional sections as a + heading for this rule because readers write it as the section heading. Spell + it in sentence case and match the corresponding template heading. +- Where such a label offers alternatives separated by a slash, for example + `Proposed design / proposed change`, treat the whole label as one heading. + Capitalize only its first word and any proper nouns or acronyms, and use one + alternative consistently within the document. +- Labels that describe a metadata field or give guidance rather than name a + heading, such as `Title` or `Opening section`, are prose and are exempt from + this rule. - Use Markdown headings (`#`, `##`, `###`, and so on) in order without skipping levels. @@ -62,6 +79,9 @@ consistent, and easy to maintain across projects. - Do not wrap tables. - Use GitHub-flavoured numeric footnotes referenced as `[^1]`. - Footnotes must be numbered in order of appearance in the document. +- Exception: roadmap-shaped Markdown processed by the `mapsplice` tool must + cite references with inline links instead of footnotes, because the + `mapsplice` roadmap grammar rejects footnote references. - Caption every table, and caption every diagram. ## Standard document types @@ -70,13 +90,15 @@ Repositories that adopt this documentation style should keep a small set of high-value documents with clearly separated audiences and responsibilities. These document types are complementary: the contents file helps readers find material, the user's guide explains how to use the project, the developer's -guide explains how to work on the project, the design document explains why the -system is shaped the way it is, and the repository layout document explains -where important things live. For discoverability, use canonical filenames -unless a stronger repository-specific constraint applies: `docs/contents.md`, +guide explains how to work on the project, the migration guide carries a reader +across one release boundary, the design document explains why the system is +shaped the way it is, and the repository layout document explains where +important things live. For discoverability, use canonical filenames unless a +stronger repository-specific constraint applies: `docs/contents.md`, `docs/users-guide.md`, `docs/developers-guide.md`, `docs/repository-layout.md`, -and a primary design document with an explicit product or topic name such as -`docs/theoremc-design.md` or `docs/query-planner-design.md`. +and `docs/documentation-style-guide.md`, plus a primary design document under +`docs/*-design.md`, for example `docs/query-planner-design.md`, and one +migration guide per release that changes observable behaviour. ### Contents file @@ -126,6 +148,129 @@ this means operators, end users, or integrators. otherwise overload the guide. - Exclude maintainer-only concerns such as internal layering debates, future refactor plans, or enforcement tooling unless they directly affect users. +- **Empathy.** Follow the example set by the Netsuke user's guide: open by + naming the exact release and stating plainly when it is an early-adopter + release whose interfaces may change, so a reader can decide whether to pin + the version. Phrase headings as imperative statements of the reader's task, + for example "Run the first build", "Author a manifest", and "Interpret + failures". Answer the question a reader is about to ask at the point they ask + it, cover a complete setup for every supported platform rather than assuming + one, and state honestly where a feature is unimplemented in the current + release. +- **Accessibility.** Treat accessibility as two related concerns. Document the + project's accessible behaviour as a first-class topic: how accessible output + is selected, by flag and by environment variable; that meaning is never + carried by colour or glyph alone, so semantic text labels are always present; + and how output streams are separated so redirection and assistive technology + behave predictably. Apply the same care to the document itself: expand + acronyms, use descriptive link text, give tables headers, and describe + diagrams. +- **Comprehensiveness.** Cover the whole user-facing surface in one place, in + the order a reader meets it: install, first run, the model, authoring, the + command-line interface, configuration, diagnostics, output control, network + access, failure interpretation, the safety boundary, complete worked + examples, and where to look next. Place reference material beside the feature + it governs. State the safety and privacy boundary explicitly, including what + the project deliberately does not record. +- **Tested correctness.** Make every fenced example in a user-facing document + executable and exercised by the test suite. Precede each fence immediately + with a marker comment carrying a stable identifier, written + ``. Load the examples from the published + document with a shared loader, rather than a copied fixture, so the tests + exercise the shipped text; fail the build on an unmarked fence, an + unterminated fence, a missing identifier, or a duplicate identifier. Share + that loader between integration tests and behaviour-driven scenarios, so a + documented example becomes a contract the implementation must satisfy and + cannot drift from the behaviour it claims. + +### Migration guide + +Use a migration guide, named `docs/v---migration-guide.md` +with dots written as dashes, for a release that changes observable behaviour. A +repository vendoring a library's guide prefixes the filename with the library +name, for example `docs/rstest-bdd-v0-5-0-migration-guide.md`. + +- Cover exactly one step, from the previous release to the named release. A + guide is never a cumulative "upgrade from any earlier version" document. A + reader crossing several releases follows the guides in sequence, one per + release. Keep each guide small enough to review against a single changelog + and correct forever; a cumulative document decays as later releases change + the ground it already described. +- Skip the guide only when a release changes nothing observable. A tiny + release that does change observable behaviour still gets its own guide, + however short. +- Title the guide with both endpoints, for example + `# Migration guide: v0.8.0 to v0.9.0`. +- Sequence the guide's sections in this order: + - **Who should read this:** state which callers are affected and + summarize what changes. + - **Impact at a glance:** a table classifying every item by obligation. + - **Numbered task sections:** one section per required or recommended + change, in the order the reader should perform them. + - **What does not need to change:** an explicit statement of unaffected + behaviour, even when short. + - **Migration checklist:** a Markdown task list so a reader can track + progress. + - **Common errors and fixes:** the exact diagnostic text a reader will + encounter, paired with its fix. +- Classify every impact-table item by obligation, using this vocabulary: + Required, Required if called, Review if enabled, Recommended, Optional. Do + not interleave required work with optional adoption in the same list. +- Show a mechanical change as a Before and After pair of fenced code blocks, + not as a prose description. +- Quote the exact diagnostic text a reader will encounter, so pasting a + compiler or runtime error into a search finds the fix. +- Write the checklist with Markdown task-list syntax (`- [ ]`) so a reader can + track progress. +- Link rationale to the accepted ADR or RFC that decided it rather than + restating the reasoning. +- Hold the guide's examples to the same tested-correctness rule the user's + guide follows, rather than restating that rule here. + +#### Migration guide skeleton + +````markdown +# Migration guide: v0.8.0 to v0.9.0 + +## Who should read this + + + +## Impact at a glance + +| Priority | Area | What to do | +| -------- | ------ | ---------- | +| Required | | | + +_Table 1: Obligations when moving from v0.8.0 to v0.9.0._ + +## 1. + +### Before + +```rust,no_run + +``` + +### After + +```rust,no_run + +``` + +## What does not need to change + + + +## Migration checklist + +- [ ] + +## Common errors and fixes + +- **Error:** `` + - **Fix:** +```` ### Developer's guide @@ -135,8 +280,9 @@ the existing system, not as the place for the project's primary design document. - Open with one short paragraph that states the audience and the operational scope of the guide. -- Link early to the design document, accepted decision records, and other - normative references that explain architecture or rationale in depth. +- Link early to the design document, repository layout document, accepted + decision records, and other normative references that explain architecture or + rationale in depth. - Put maintainer-facing implementation guidance here, for example build, test, lint, release, debugging, extension, and contribution workflows. - Use numbered sections for long-form technical documents to improve @@ -148,6 +294,9 @@ the existing system, not as the place for the project's primary design document. - Keep subsystem descriptions focused on current responsibilities, integration points, and operational expectations. Put design rationale, major trade-offs, and proposed architecture in design documents instead. +- Do not embed repository-layout guidance here. The canonical location for + file-tree and path-responsibility documentation is + `docs/repository-layout.md`. - Keep the document synchronized with decision records, roadmap items, and the codebase. A stale developer's guide is worse than a shorter one. @@ -212,16 +361,26 @@ user's guide or developer's guide. Use RFCs for proposed changes that need technical review before they become binding. Store them under `docs/rfcs/`. -### RFC naming convention +#### RFC naming convention -Name RFC files using the pattern `0001-short-topic.md`, where `0001` is a -zero-padded sequence number. Place RFCs in the `docs/rfcs/` directory. +Name RFC files using the pattern `rfcs/rfc-nnnn-title-slug.md`, relative to the +`docs/` directory, for example `docs/rfcs/rfc-0007-streaming-step-results.md`. +- `nnnn` is a four-digit, zero-padded serial number, unique among the RFCs in + the repository. RFC and ADR numbers are allocated independently, so + `rfc-0003` and `adr-0003` may both exist. +- `title-slug` is a kebab-case American Standard Code for Information + Interchange (ASCII) rendering of the RFC title, without the `RFC nnnn:` + prefix: lowercase letters, digits, and single hyphens only, with no leading + or trailing hyphen. Transliterate accented letters to their ASCII base + letters, and drop other punctuation and symbols. - Number RFCs sequentially in allocation order rather than by date. - Do not renumber existing RFCs after publication. Gaps are acceptable when numbers are reserved, drafted on another branch, or intentionally skipped. +- Keep the slug stable once the RFC is published. If the title changes + materially, rename the file, keep the number, and update every inbound link. -### RFC required sections +#### RFC required sections Every RFC must include the following sections in order: @@ -236,31 +395,31 @@ Every RFC must include the following sections in order: `## Summary`, `## Executive summary`, or `## Problem` are all acceptable if used consistently within the document. -### RFC conditional sections +#### RFC conditional sections Include these sections as appropriate to the scope and complexity of the proposal: - **Problem:** Describe the deficiency, risk, or missing capability that motivates the RFC. -- **Current State:** Explain the relevant current behaviour or architecture when +- **Current state:** Explain the relevant current behaviour or architecture when the proposal depends on existing constraints. -- **Goals and Non-goals:** Clarify what the RFC intends to change and what it +- **Goals and non-goals:** Clarify what the RFC intends to change and what it deliberately leaves out of scope. -- **Proposed Design / Proposed Change:** Describe the recommended design with +- **Proposed design / proposed change:** Describe the recommended design with enough detail to support implementation review. - **Requirements:** Separate functional, technical, safety, or operational requirements when the proposal has multiple kinds of constraints. -- **Compatibility and Migration:** Explain rollout expectations, compatibility +- **Compatibility and migration:** Explain rollout expectations, compatibility impact, and migration sequencing when adoption is not trivial. -- **Alternatives Considered:** Record rejected options and the reasons they +- **Alternatives considered:** Record rejected options and the reasons they were not chosen. -- **Open Questions / Outstanding Decisions:** Identify unresolved issues that +- **Open questions / outstanding decisions:** Identify unresolved issues that still need reviewing before the proposal can be treated as settled. - **Recommendation:** End with a clear statement of the preferred direction when the preceding analysis presents multiple viable choices. -### RFC formatting guidance +#### RFC formatting guidance - Use second-level headings (`##`) for major sections. - Use third-level headings (`###`) for subsections such as phases, options, @@ -275,7 +434,7 @@ proposal: - Update links when RFC filenames change, especially cross-references from one RFC to another. -### RFC template +#### RFC template ```markdown # RFC 0001: @@ -337,6 +496,12 @@ proposal: <Description, consequences, and trade-offs.> +| Topic | Option A | Option B | +| --------- | -------- | -------- | +| <Factor> | <Value> | <Value> | + +_Table 1: Comparison of options._ + ## Open questions - <Open question 1> @@ -355,9 +520,16 @@ providing a historical record for future maintainers. ### Naming convention -Name ADR files using the pattern `adr-NNN-short-description.md`, where `NNN` is -a zero-padded sequence number (e.g. `adr-001-async-fixtures-and-tests.md`). -Place ADRs in the `docs/` directory. +Name ADR files using the pattern `adrs/adr-nnnn-title-slug.md`, relative to the +`docs/` directory, for example `docs/adrs/adr-0001-async-fixtures-and-tests.md`. + +- `nnnn` is a four-digit, zero-padded serial number, unique among the ADRs in + the repository and allocated independently of RFC numbers. +- `title-slug` is a kebab-case ASCII rendering of the ADR title, without the + `Architectural decision record (ADR) nnnn:` prefix, following the same slug + rules as RFC filenames. +- Number ADRs sequentially in allocation order rather than by date, and do not + renumber an ADR after publication. ### Required sections @@ -366,32 +538,36 @@ Every ADR must include the following sections in order: - **Status:** One of `Proposed`, `Accepted`, `Superseded`, or `Deprecated`. For `Accepted` status, include the date and a brief summary of what was decided. - **Date:** The date the ADR was created or last updated (format: YYYY-MM-DD). -- **Context and Problem Statement:** Describe the situation, constraints, and +- **Context and problem statement:** Describe the situation, constraints, and the problem or question that prompted the decision. Include enough background for readers unfamiliar with the history. +When an accepted ADR needs a targeted correction rather than replacement, add an +`Amended by ADR-nnnn (YYYY-MM-DD)` banner to its Status section and an +`## Amendments` section that preserves the original decision as history. + ### Conditional sections Include these sections as appropriate to the decision's complexity: -- **Decision Drivers:** Key factors, requirements, or constraints that +- **Decision drivers:** Key factors, requirements, or constraints that influenced the decision. Use bullet points. - **Requirements:** For complex decisions, separate functional and technical requirements into subsections. -- **Options Considered:** Describe the alternatives evaluated. Use a comparison +- **Options considered:** Describe the alternatives evaluated. Use a comparison table when contrasting multiple options across several dimensions. -- **Decision Outcome / Proposed Direction:** State the chosen approach and +- **Decision outcome / proposed direction:** State the chosen approach and summarize the rationale. For `Proposed` ADRs, describe the recommended direction. -- **Goals and Non-Goals:** Clarify what the decision aims to achieve and what +- **Goals and non-goals:** Clarify what the decision aims to achieve and what is explicitly out of scope. -- **Migration Plan:** For decisions requiring phased implementation, break the +- **Migration plan:** For decisions requiring phased implementation, break the work into numbered phases with clear goals and deliverables. -- **Known Risks and Limitations:** Document trade-offs, potential issues, and +- **Known risks and limitations:** Document trade-offs, potential issues, and constraints of the chosen approach. -- **Outstanding Decisions:** For `Proposed` ADRs, list open questions that must +- **Outstanding decisions:** For `Proposed` ADRs, list open questions that must be resolved before acceptance. -- **Architectural Rationale:** Explain how the decision aligns with broader +- **Architectural rationale:** Explain how the decision aligns with broader architectural principles and project goals. ### Formatting guidance @@ -401,15 +577,18 @@ Include these sections as appropriate to the decision's complexity: - Use tables to compare options when multiple dimensions are relevant. Include a caption below the table (e.g. “_Table 1: Trade-offs between X and Y._”). - Include code snippets with language identifiers when illustrating technical - approaches. Use `no_run` for illustrative Rust code that should not be - executed. + approaches. In Rustdoc, `no_run` still compiles the snippet, so reserve it + for complete Rust code that compiles but does not execute, for example + because it needs external resources, environment-specific setup, or a + long-running service. Use `ignore` for an incomplete snippet or one that + cannot compile: `ignore` skips both compilation and execution. - Add screen reader descriptions before complex diagrams or code blocks. - Reference external sources using inline links or footnotes. ### ADR template ```markdown -# Architectural decision record (ADR) NNN: <title> +# Architectural decision record (ADR) nnnn: <title> ## Status @@ -423,7 +602,7 @@ YYYY-MM-DD. <Describe the situation, constraints, and the question being addressed.> -## Decision Drivers +## Decision drivers - <Driver 1> - <Driver 2> @@ -483,14 +662,19 @@ implementation is required.> - <Open question 1> - <Open question 2> + +## Architectural rationale + +<Explain how the decision aligns with broader architectural principles +and project goals.> ``` -### Repository layout document +## Repository layout document Use a repository layout document, canonically `docs/repository-layout.md`, to -explain the shape of the tree and the responsibilities of its major paths. This -may be a standalone document or a clearly labelled section within the -developer's guide, provided readers can find it easily from the contents file. +explain the shape of the tree and the responsibilities of its major paths. Use +this standalone document as the canonical location for repository-layout +guidance rather than embedding that material in the developer's guide. - Document the top-level directories and any critical subdirectories that a new contributor must understand quickly. @@ -504,6 +688,8 @@ developer's guide, provided readers can find it easily from the contents file. long-lived reference documents belong. - Call out any directories with unusual constraints, such as generated output, fixtures, snapshots, or capability-restricted paths. +- Ensure the contents file links directly to `docs/repository-layout.md` so + readers can find it without scanning the developer's guide. - Update the layout document when the repository structure changes enough that a contributor could otherwise follow outdated guidance. @@ -527,8 +713,15 @@ contents of the manual. argument. - Document the return value with `# Returns`. - Document any panics or errors with `# Panics` or `# Errors` as appropriate. -- Place examples under `# Examples` and mark the code block with `no_run`, so - they do not execute during documentation tests. +- Place examples under `# Examples`. Let examples run as documentation tests + when they can execute correctly, so the compiler verifies that they compile + and behave as documented. +- Use `no_run` for complete examples that must compile but must not execute, + such as examples that require external resources, environment-specific setup, + or a long-running service. +- Use `ignore` for examples that are incomplete or otherwise cannot compile. + `no_run` only suppresses execution, so it cannot carry uncompilable code; + `ignore` skips both compilation and execution. - Put function attributes after the doc comment. ```rust,no_run @@ -543,7 +736,7 @@ contents of the manual. /// /// # Examples /// -/// ```rust,no_run +/// ```rust /// assert_eq!(add(2, 3), 5); /// ``` #[inline] diff --git a/docs/execplans/5-1-1-otel-support.md b/docs/execplans/5-1-1-otel-support.md index ab6ba28f..04420e83 100644 --- a/docs/execplans/5-1-1-otel-support.md +++ b/docs/execplans/5-1-1-otel-support.md @@ -8,18 +8,17 @@ Status: COMPLETE ## Purpose / big picture -After this change, every producer in the observability design of -`docs/adr-003-opentelemetry-observability.md` — the Open Dynamic Workflows -(ODW) runtime, the df12-build workflow, the Claude Code and Codex command-line -interfaces (CLIs), the `workflow-telemetryd` collector, and sibling workflows -such as Dakar — has one written contract to build against: which identifiers -exist, who mints them, which attribute names carry them, what the context -envelope passed between workflows looks like, and which correlation headers a -collector must validate. The contract is observable as a versioned design -document plus machine-readable JSON Schemas, with fixture tests that fail on -non-conforming envelopes and identity keys. Nothing else in roadmap phase 5 -(steps 5.2 through 5.5) can start safely before this narrow waist is fixed, -because ODW, the collector, and Dakar all consume it. +After this change, every producer in the observability design of ADR 0003 — the +Open Dynamic Workflows (ODW) runtime, the df12-build workflow, the Claude Code +and Codex command-line interfaces (CLIs), the `workflow-telemetryd` collector, +and sibling workflows such as Dakar — has one written contract to build +against: which identifiers exist, who mints them, which attribute names carry +them, what the context envelope passed between workflows looks like, and which +correlation headers a collector must validate. The contract is observable as a +versioned design document plus machine-readable JSON Schemas, with fixture +tests that fail on non-conforming envelopes and identity keys. Nothing else in +roadmap phase 5 (steps 5.2 through 5.5) can start safely before this narrow +waist is fixed, because ODW, the collector, and Dakar all consume it. This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). @@ -28,7 +27,7 @@ This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). - Do not modify `src/workflows/df12-build-odw/`, `workflows/df12-build-odw.js`, or `workflows/df12-build.js`; this task defines the contract only. Instrumentation lands under later tasks (5.2.1 and 5.3.x). -- The contract must match ADR 003 exactly where the ADR is explicit: three +- The contract must match ADR 0003 exactly where the ADR is explicit: three distinct identifiers (correlation id, workflow invocation id, node attempt id), agent invocation and process ids below them, the three-layer namespace (`gen_ai.*`, `leynos.*`, `df12.*`/`dakar.*`), binding confidence levels @@ -48,12 +47,12 @@ This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). escalate. - Dependencies: one JSON Schema validator development dependency (for example `ajv`) is expected; any further new dependency requires escalation. -- Conflict: if writing the contract exposes a contradiction inside ADR 003 +- Conflict: if writing the contract exposes a contradiction inside ADR 0003 (for example between the identity model and the Dakar envelope), stop, record it in the `Decision Log`, and escalate rather than resolving it silently. - Iterations: if the fixture tests still fail after three fix attempts, stop and escalate. -- Ambiguity: naming marked "outstanding" in ADR 003 (namespace and header +- Ambiguity: naming marked "outstanding" in ADR 0003 (namespace and header prefixes) is decided provisionally here and recorded; if the choice would leak into an external interface beyond documents and schemas, escalate instead. @@ -69,7 +68,7 @@ This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). contract while still in Development status. Severity: low. Likelihood: high. Mitigation: the contract names convention fields only in the canonical projection section and requires queries to target the projection, exactly as - ADR 003 prescribes. + ADR 0003 prescribes. - Risk: JSON Schema alone cannot express some rules (for example header consistency with envelope fields). Severity: low. Likelihood: medium. Mitigation: encode such rules as fixture tests beside the schemas and state @@ -77,7 +76,7 @@ This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). ## Progress -- [x] (2026-07-18) ExecPlan drafted alongside ADR 003 and roadmap phase 5. +- [x] (2026-07-18) ExecPlan drafted alongside ADR 0003 and roadmap phase 5. - [x] (2026-07-18) ExecPlan rewritten after the source design conversation replaced the events-bridge approach with the correlation-first gateway; task 5.1.1 re-scoped from "build a bridge" to "define the contract". @@ -94,7 +93,7 @@ This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). `schemas/observability/`. Contract test passes 31/31; the full module suite (397 tests) and `tsc` pass. Two schema-shaping decisions surfaced (union scalar types, nanosecond string timestamps) — see Surprises. -- [x] (2026-07-19) Milestone 4: cross-linked the contract from ADR 003, the +- [x] (2026-07-19) Milestone 4: cross-linked the contract from ADR 0003, the developers' guide, and the contents index; ticked 5.1.1 in the roadmap; ran the full gate and a CodeRabbit review. - [x] (2026-07-29) Review follow-up: hardened the schemas after review, so @@ -104,16 +103,16 @@ This delivers roadmap task 5.1.1 (see `docs/roadmap.md` phase 5). - [x] (2026-08-01) Second review round: bounded the nanosecond timestamps to the signed 64-bit maximum in canonical decimal form, required a non-empty well-formed authority on the sink endpoint, and tightened the collector's - batch validation to the whole correlation tuple. ADR 003 moved from Proposed - to Accepted, matching how ADR 001 and ADR 002 were accepted in the pull + batch validation to the whole correlation tuple. ADR 0003 moved from Proposed + to Accepted, matching how ADR 0001 and ADR 0002 were accepted in the pull request that implemented them. Suite now 54 tests. - [x] (2026-08-03) Third review round: gave both test modules `/** @file … */` docblocks and added them to the `DOCSTRING_MODULES` gate; added `tests/modules/observability-contract.property.test.ts`, a fast-check suite that decides accept/reject with oracles computed independently of the schema - patterns; refreshed the stale "proposed" references to ADR 003 and documented - the contract artefacts for contributors. Suite now 77 tests across the two - modules. + patterns; refreshed the stale "proposed" references to ADR 0003 and + documented the contract artefacts for contributors. Suite now 77 tests across + the two modules. The counts above are the totals at those dates; the current total is in `Outcomes & retrospective`. @@ -222,7 +221,7 @@ consolidated fixture set, and a validation suite (`tests/modules/observability-contract.test.ts` and its fast-check companion `observability-contract.property.test.ts`, 77 tests) that exercises every documented rule — including the sink credential rule, the source-to-confidence -binding conditional, and the logical node key grammar. ADR 003, the roadmap, +binding conditional, and the logical node key grammar. ADR 0003, the roadmap, the contents index, and the developers' guide now link the contract, and roadmap task 5.1.1 is marked complete. @@ -246,7 +245,8 @@ Lessons for the next steps: `df12-build` ships workflow assets that drive a "workshop": a long multi-agent run in which the ODW runtime dispatches Codex and Claude Code processes against -a target project. ADR 003 (`docs/adr-003-opentelemetry-observability.md`) +a target project. ADR 0003 +(`docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md`) decides how this system becomes observable: ODW mints an opaque agent invocation id at dispatch, Claude inherits trace context through the `TRACEPARENT` environment variable, Codex carries the identity in OpenTelemetry @@ -295,7 +295,7 @@ Milestone 3 (green): create `schemas/observability/` containing development dependency, exact-pinned) and make the milestone 2 tests pass with the smallest schemas that honour the contract document. -Milestone 4 (integrate): cross-link the contract from ADR 003 and from roadmap +Milestone 4 (integrate): cross-link the contract from ADR 0003 and from roadmap step 5.1; update `docs/developers-guide.md` with a short pointer; run the full gates; update this plan's living sections and mark 5.1.1 complete in `docs/roadmap.md` only when every milestone is checked. @@ -328,7 +328,7 @@ node keys match the documented pattern and malformed keys fail; and `make all` passes, proving the contract document survives the Markdown and spelling gates. Quality criteria: every identifier, attribute, header, and event field named in -ADR 003's decision sections appears in the contract document exactly once as a +ADR 0003's decision sections appears in the contract document exactly once as a normative definition, and the schemas carry `schemaVersion` 1. ## Idempotence and recovery @@ -358,7 +358,7 @@ to environment references), and an `attributes` map of scalar values. ## Revision note 2026-07-18: rewritten in full. The original plan implemented a post-hoc -`events.jsonl` → OTLP bridge; the source design conversation behind ADR 003 +`events.jsonl` → OTLP bridge; the source design conversation behind ADR 0003 replaced that approach with a correlation-first gateway, and task 5.1.1 is now the contract-definition task that precedes collector, ODW, and Dakar work. All sections were rewritten to match; no implementation had started, so no code is diff --git a/docs/execplans/adr-002-partial-task-branch-assessment.md b/docs/execplans/adr-002-partial-task-branch-assessment.md index df52f9f6..5b12bccd 100644 --- a/docs/execplans/adr-002-partial-task-branch-assessment.md +++ b/docs/execplans/adr-002-partial-task-branch-assessment.md @@ -16,7 +16,7 @@ The first implementation only reports the recommendation; it must not automatically merge or cherry-pick partial work. Success is visible in the ODW result JSON. A task that fails after worktree -creation has an `assessment` object with a classification from ADR 002, the +creation has an `assessment` object with a classification from ADR 0002, the branch/worktree identity, evidence summaries, missing evidence, and a bounded recommendation. Auth failures and pre-worktree failures do not get assessed. @@ -95,7 +95,7 @@ conflict in `Decision Log`, and ask for direction. ## Progress -- [x] (2026-06-30T15:12:48Z) Read ADR 002, the ODW workflow, and the repository +- [x] (2026-06-30T15:12:48Z) Read ADR 0002, the ODW workflow, and the repository documentation that defines the sidecar, state, validation, and supervisor contracts. - [x] (2026-06-30T15:12:48Z) Drafted this ExecPlan in `docs/execplans/`. @@ -113,14 +113,14 @@ conflict in `Decision Log`, and ask for direction. collection, result wiring, and top-level `assessments` summary. - [x] (2026-06-30T15:35:32Z) Ran the focused green test: `node --test tests/df12-build-odw-assessment.test.mjs` passed 4 tests. -- [x] (2026-06-30T15:35:32Z) Updated ADR 002, user guide, +- [x] (2026-06-30T15:35:32Z) Updated ADR 0002, user guide, architecture, developer guide, security guide, and supervisor skill for the report-only assessment behaviour. - [x] (2026-06-30T15:47:19Z) Ran `make all`; diff check, Markdown lint, ODW wrapper parse, Nixie diagram validation, and Node assessment tests all passed. - [x] (2026-06-30T16:11:11Z) Verified three review findings against current code: auth-shaped implementation issues were not fatal, assessment evidence - fields were optional in the schema, and two docs still called ADR 002 + fields were optional in the schema, and two docs still called ADR 0002 proposed. - [x] (2026-06-30T16:11:11Z) Patched the still-valid findings and extended focused tests for auth-shaped implementation issues, both implementation @@ -153,7 +153,7 @@ conflict in `Decision Log`, and ask for direction. `workflows/df12-build.js`. - Observation: Claude Code workflows resume only within the same Claude Code - session, while ADR 002 requires fresh restart from durable git state. + session, while ADR 0002 requires fresh restart from durable git state. Evidence: Firecrawl scrape of `https://code.claude.com/docs/en/workflows`. Impact: The assessment stage must not use session resume semantics as part of recovery, even though Claude Code dynamic workflows expose a same-session @@ -172,7 +172,7 @@ conflict in `Decision Log`, and ask for direction. ## Decision log - Decision: Implement a report-only assessment stage first. - Rationale: ADR 002 says automatic adoption should wait until the manual + Rationale: ADR 0002 says automatic adoption should wait until the manual recommendation path has been dogfooded. Reporting keeps recovery observable without adding a new merge path. Date/Author: 2026-06-30T15:12:48Z / Codex. @@ -198,7 +198,7 @@ conflict in `Decision Log`, and ask for direction. than control flow. Date/Author: 2026-06-30T15:12:48Z / Codex. - Decision: Do not use Claude Code same-session workflow resume as prior art - for this recovery path. Rationale: ADR 002 explicitly chooses git-state + for this recovery path. Rationale: ADR 0002 explicitly chooses git-state recovery after system failure or token exhaustion. Same-session transcript or journal resume is a different reliability model and can disappear across process/session boundaries. Date/Author: 2026-06-30T15:12:48Z / Codex. @@ -212,11 +212,11 @@ conflict in `Decision Log`, and ask for direction. - Decision: Assess unhandled post-worktree agent errors inside `runTask`. Rationale: A thrown agent call after worktree creation is still a failure with a durable branch. Catching it inside `runTask` preserves the worktree - context so ADR 002 assessment can run; auth-shaped failures still bypass + context so ADR 0002 assessment can run; auth-shaped failures still bypass assessment. Date/Author: 2026-06-30T15:35:32Z / Codex. - Decision: Treat auth-shaped implementation issues as fatal before any review - or integration fallback. Rationale: ADR 002 says auth failures remain fatal, + or integration fallback. Rationale: ADR 0002 says auth failures remain fatal, and authentication failures are not useful partial-branch evidence. Both normal and addendum implementation results now share the same auth detector and return `fatal-auth` before deferred-review handling or mergeability @@ -226,7 +226,7 @@ conflict in `Decision Log`, and ask for direction. the schema. Rationale: The schema is the hard contract between the assessment agent and the workflow host. `taskScoped`, `execPlan`, `roadmap`, `validation`, `rationale`, and `nextActions` must be present so an operator - does not receive a bare classification without the evidence ADR 002 relies + does not receive a bare classification without the evidence ADR 0002 relies on. Date/Author: 2026-06-30T16:11:11Z / Codex. ## Outcomes & retrospective @@ -266,9 +266,10 @@ worktrees for target-project tasks, plans and implements work inside those worktrees, reviews the result, and serializes integration with a JavaScript merge lock. -ADR 002, `docs/adr-002-assess-partial-task-branches.md`, decides that failed -task branches should be assessed through durable git state, not through an old -agent transcript. It defines four classifications: +ADR 0002, +`docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md`, +decides that failed task branches should be assessed through durable git state, +not through an old agent transcript. It defines four classifications: - `adopt-complete`: the branch appears to satisfy the task and could continue through the ordinary review and integration path after all gates are proven. @@ -329,7 +330,7 @@ Stage A preserves the existing ODW contract and adds tests first. Create and returns only the assessment helpers under test. It must not call `agent()` or run the workflow control loop. Add red tests for these behaviours: -- `ASSESSMENT_SCHEMA` contains only the four ADR 002 classifications. +- `ASSESSMENT_SCHEMA` contains only the four ADR 0002 classifications. - `shouldAssessFailure(result, wt)` returns true for `failed` and `halted` results that have a branch and worktree after worktree creation. - `shouldAssessFailure(result, wt)` returns false for worktree-creation @@ -394,7 +395,7 @@ operations. It is not a Claude Code workflow portability claim. Add `assessmentPrompt(task, wt, result, evidence)`. The prompt must be read-only and evidence-first. It must instruct the agent to inspect the worktree and git state, read the ExecPlan and roadmap if present, review -validation evidence, and classify using only the ADR 002 enum. It must +validation evidence, and classify using only the ADR 0002 enum. It must explicitly say not to edit, commit, stash, merge, push, mark roadmap checkboxes, or resume the failed agent's transcript. @@ -529,7 +530,7 @@ Red test evidence: ```plaintext $ node --test tests/df12-build-odw-assessment.test.mjs -not ok 1 - assessment schema exposes only ADR 002 classifications +not ok 1 - assessment schema exposes only ADR 0002 classifications ReferenceError: ASSESSMENT_CLASSIFICATIONS is not defined ``` @@ -621,7 +622,7 @@ field, but it must stay within the constraints and classifications above. ## Revision note -Initial draft created from ADR 002 and the current ODW workflow. It scopes the +Initial draft created from ADR 0002 and the current ODW workflow. It scopes the first implementation to report-only partial-branch assessment, defines the test-first path, and leaves all automatic adoption behaviour for a later approved plan. diff --git a/docs/execplans/odw-compilation.md b/docs/execplans/odw-compilation.md index 978f606e..3502dcd3 100644 --- a/docs/execplans/odw-compilation.md +++ b/docs/execplans/odw-compilation.md @@ -139,7 +139,7 @@ Planned work: `schemas.ts`; `types.ts` names `RoadmapTask`, `SelectedTask`, `RecoveryCandidate`, and `FaultMetrics`. New direct-import contract suite `tests/modules/schemas.test.ts` (red-then-green): closed-object and - required-exists checks over every schema, enum ↔ ADR 002 classification, + required-exists checks over every schema, enum ↔ ADR 0002 classification, mock-satisfiability of `dirtyState`. Milestone 0's CodeRabbit review returned zero findings before this milestone began. - [x] (2026-07-05 21:05Z) Milestone 2: roadmap parsing and selection peeled @@ -220,7 +220,7 @@ Planned work: guard as direct exports; `makeAssessment({ preamble, assessPartialBranches, assessmentAgentOptions, withInfraRetry })` - returning the two ADR 002 prompts, `assessRecoveryCandidate`, + returning the two ADR 0002 prompts, `assessRecoveryCandidate`, `shouldAssessFailure`, and `attachAssessment`) and `remediation.ts` (`TRIAGE_SCHEMA`, `stepOf` direct; `makeRemediation({ preamble, base, roadmap, triageAgentOptions })` returning diff --git a/docs/failure-resume-design.md b/docs/failure-resume-design.md index d1e45457..ff43e003 100644 --- a/docs/failure-resume-design.md +++ b/docs/failure-resume-design.md @@ -7,8 +7,8 @@ supervising ODW workshops, and reviewers checking recovery behaviour. Companion documents: -- `docs/adr-001-adopt-odw-sidecar-launches.md` -- `docs/adr-002-assess-partial-task-branches.md` +- `docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md` +- `docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md` - `docs/architecture.md` - `docs/security-and-permissions.md` - `docs/users-guide.md` @@ -16,7 +16,7 @@ Companion documents: ## Problem -ADR 002 added report-only assessment for task branches that fail or halt after +ADR 0002 added report-only assessment for task branches that fail or halt after a worktree exists. That helps an operator decide what to do with a surviving branch, but it does not make a fresh run discover that branch or re-enter the workflow at a safe stage. @@ -51,7 +51,7 @@ References are listed at the end of this document. ## Goals - Discover surviving `roadmap-*` branches and worktrees on a fresh ODW launch. -- Reuse the ADR 002 assessment schema and evidence collector wherever possible. +- Reuse the ADR 0002 assessment schema and evidence collector wherever possible. - Default to assess-only behaviour, with no writes to the target project. - Allow explicit review-mode resume for clean `adopt-complete` branches. - Allow explicit accepted-ExecPlan reuse for open, unbuilt roadmap tasks whose @@ -84,7 +84,7 @@ least powerful recovery action that preserves correctness. | Term | Meaning | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Recovery candidate | A surviving task branch or worktree whose name maps to a roadmap id. | -| Assessment | The ADR 002 schema-bound classification and evidence summary. | +| Assessment | The ADR 0002 schema-bound classification and evidence summary. | | Resume mode | The maximum action the workflow may take for recovery candidates. | | Assess-only | Discovery plus assessment, returning JSON only. | | Review resume | Re-entering the existing review and integration path for an `adopt-complete` branch. | @@ -567,5 +567,5 @@ target project. `https://github.com/xz1220/open-dynamic-workflows/blob/main/README.md`. - Claude Code dynamic workflows: `https://code.claude.com/docs/en/workflows`. -- ADR 002: - `docs/adr-002-assess-partial-task-branches.md`. +- ADR 0002: + `docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md`. diff --git a/docs/roadmap.md b/docs/roadmap.md index cc5ee197..e0a9616d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,6 +1,6 @@ # df12-build roadmap -This roadmap translates `docs/failure-resume-design.md` and ADR 002 into a +This roadmap translates `docs/failure-resume-design.md` and ADR 0002 into a short delivery sequence for failure resume in the ODW workflow. It does not promise dates. Each phase carries one GIST idea, each step answers a delivery question, and each task is intended to be review-sized. @@ -67,7 +67,7 @@ later review-mode resume. - Success: an assess-only run reports candidates, skipped branches, and assessment outcomes without changing `processed`. -### 1.3. Reuse ADR 002 assessment for recovered candidates +### 1.3. Reuse ADR 0002 assessment for recovered candidates This step answers whether fresh-run discovery can share the existing assessment contract instead of creating a second recovery classifier. @@ -76,7 +76,7 @@ contract instead of creating a second recovery classifier. evidence collector and schema. - Requires 1.2.1. - See `docs/failure-resume-design.md` section "Assessment reuse" and - `docs/adr-002-assess-partial-task-branches.md`. + `docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md`. - Note: the assessment feature now also salvages task-scoped `docs/execplans/*.md` artefacts for `continue-manual` and `adopt-partial` classifications, and for infra-fault handoffs (schema-retry exhaustion) @@ -271,7 +271,7 @@ collector that stores them beside a versioned relational projection, operators can cross-reference workflow nodes and agent telemetry exactly, even under parallelism, retries, and recovery. -This phase implements ADR 003. Correlation is identity-first: labels, phases, +This phase implements ADR 0003. Correlation is identity-first: labels, phases, and timestamps are evidence, never primary join keys. Telemetry is advisory and must never alter workflow control flow. @@ -283,7 +283,9 @@ df12-build, the providers, and sibling workflows all depend on, so it must settle before the substrate work starts. - [x] 5.1.1. Define the workflow observability contract. - - See `docs/adr-003-opentelemetry-observability.md` sections "Identity + - See + `docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md` + sections "Identity model", "Attribute namespaces and span model", and "Cross-workflow contract". - Cover the identity model (correlation id, workflow invocation id, node @@ -300,7 +302,7 @@ settle before the substrate work starts. identity keys deterministically. - [ ] 5.1.2. Implement the `workflow-telemetryd` OTLP receiver over SQLite. Requires 5.1.1. - - See ADR 003 section "Collector and store". + - See ADR 0003 section "Collector and store". - Accept OTLP/HTTP JSON on `/v1/traces`, `/v1/logs`, and `/v1/metrics`; validate correlation headers against registered invocations; store raw `otel_*` records in one transaction per batch; spool to JSONL on write @@ -309,7 +311,7 @@ settle before the substrate work starts. the raw tables with their bindings, and a rejected write spools and replays without loss. - [ ] 5.1.3. Add the canonical relational projection. Requires 5.1.2. - - See ADR 003 section "Collector and store". + - See ADR 0003 section "Collector and store". - Create `correlation`, `workflow_invocation`, `workflow_invocation_edge`, `workflow_node_attempt`, `agent_invocation`, `agent_process`, `telemetry_binding`, and `artifact`, with confidence-tagged bindings and @@ -327,7 +329,7 @@ breaking existing workflows. - [ ] 5.2.1. Extend ODW with dispatch identity and telemetry context. Requires 5.1.1. - - See ADR 003 sections "Identity model" and "Migration plan". + - See ADR 0003 sections "Identity model" and "Migration plan". - Generate agent invocation and process ids and CLI attempt numbers; add them to `agent_started`, `agent_finished`, and `agent_failed` events; add a per-invocation environment layer to the adapter bridge; inject @@ -344,7 +346,7 @@ exact agent bindings, using the substrate rather than bespoke wiring. - [ ] 5.3.1. Instrument df12-build nodes with a `withNode` helper. Requires 5.2.1. - - See ADR 003 section "Migration plan". + - See ADR 0003 section "Migration plan". - Wrap selection and recovery decisions, worktree creation and writable-root checks, plan and design-review rounds, ExecPlan work items, host gates, CodeScene and CodeRabbit, review and fix rounds, @@ -355,7 +357,7 @@ exact agent bindings, using the substrate rather than bespoke wiring. stage, with parallel reviewers under one review node. - [ ] 5.3.2. Wire provider exporters for exact correlation. Requires 5.2.1 and 5.1.2. - - See ADR 003 section "Propagation". + - See ADR 0003 section "Propagation". - Claude: enable telemetry and beta traces, direct OTLP to the local receiver, inherit trace context, and disable session and account metric attributes. Codex: configure OTLP/HTTP JSON exporters with @@ -371,7 +373,7 @@ id, reach every downstream execution fact without archaeology. - [ ] 5.4.1. Add query views and the `df12-obs` CLI. Requires 5.1.3 and 5.3.2. - - See ADR 003 section "Migration plan". + - See ADR 0003 section "Migration plan". - Create `v_task_timeline`, `v_agent_usage`, `v_failure_chain`, and `v_recovery_lineage`, plus CLI verbs for runs, tasks, invocations, tool calls, commits, failures, and lineage. @@ -386,7 +388,7 @@ by carrying identity and sink through a Dakar call. - [ ] 5.5.1. Pass the observability context through Dakar calls. Requires 5.1.3. - - See ADR 003 section "Cross-workflow contract". + - See ADR 0003 section "Cross-workflow contract". - Add `--correlation-id`, `--telemetry-sink`, and `--observability-context` to the Dakar CLI with the documented precedence; propagate identity through workflow arguments and inherited diff --git a/docs/users-guide.md b/docs/users-guide.md index bbbf646d..0bcd101b 100644 --- a/docs/users-guide.md +++ b/docs/users-guide.md @@ -655,7 +655,7 @@ Example `args.json`: "base": "main", "roadmap": "docs/roadmap.md", "projectRoot": "/home/example/Projects/example-project", - "designDocs": "docs/architecture.md, docs/adr-001-adopt-odw-sidecar-launches.md, docs/users-guide.md, docs/developers-guide.md", + "designDocs": "docs/adrs/adr-0001-adopt-odw-sidecar-launches-for-codex-oriented-df12-build-runs.md", "searchBackend": "grepai", "grepaiWorkspace": "Projects", "grepaiProject": "example-project", @@ -933,7 +933,7 @@ Set `resumePartialBranches=true` and choose the maximum action with - **Assess-only** (`resumeMode="assess"`, the default): the workflow maps surviving `roadmap-*` branches back to roadmap ids, assesses each candidate - with the same ADR 002 contract used for in-run failures, and reports the + with the same ADR 0002 contract used for in-run failures, and reports the outcome in a top-level `recovery` object. Nothing is merged, pushed, ticked, or deleted, and `processed` is unchanged. Use this mode first: it guarantees the target project is not written to, though recovered branch content still diff --git a/docs/workflow-observability-contract.md b/docs/workflow-observability-contract.md index 2d27be27..ccc455db 100644 --- a/docs/workflow-observability-contract.md +++ b/docs/workflow-observability-contract.md @@ -6,9 +6,10 @@ - Audience: implementers of the `workflow-telemetryd` collector, the Open Dynamic Workflows (ODW) correlation substrate, the df12-build node instrumentation, and sibling workflows such as `leynos/dakar`. -- Precedence: `docs/adr-003-opentelemetry-observability.md` is the governing - decision. Where this contract and the ADR disagree, the ADR wins and this - document must be corrected. +- Precedence: + `docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md` + is the governing decision. Where this contract and the ADR disagree, the ADR + wins and this document must be corrected. This document fixes the shared identity model, attribute names, span topology, cross-workflow envelope, correlation headers, event extensions, binding @@ -91,7 +92,7 @@ keys hash normalized checklist text rather than relying on index position, so an edited execution plan (ExecPlan) cannot silently make "work item 3" refer to something else. -Reserved-field rules, restated from ADR 003 so consumers do not reintroduce +Reserved-field rules, restated from ADR 0003 so consumers do not reintroduce them: - `gen_ai.agent.id` must not carry `agentInvocationId`; the convention @@ -114,7 +115,7 @@ least one surface. - OTel attributes: dotted lower snake within the `leynos.*` namespace (`leynos.agent.invocation.id`). This follows OTel attribute conventions. - Binding rows: snake_case (`binding_type`). They mirror the SQLite columns - in ADR 003. + in ADR 0003. The same logical identifier therefore appears under three spellings — `agentInvocationId` in the envelope, `agent_invocation_id` in an event, and @@ -235,7 +236,7 @@ migrations; a workflow must not open the SQLite store directly. - `sink.endpoint` is an OTLP collector uniform resource identifier (URI) with the scheme `otlp+http://` or `otlp+https://`. A filesystem path or a `file://`, `sqlite:`, or bare `http://` value is invalid. The `otlp+unix://` - scheme is reserved for a future transport (ADR 003 outstanding decision) and + scheme is reserved for a future transport (ADR 0003 outstanding decision) and is not valid in version 1. The endpoint must not carry URI userinfo: a value such as `otlp+http://user:password@host:4318` is rejected, because it would otherwise smuggle a credential past the rule below. The endpoint must also @@ -409,7 +410,8 @@ unsupported envelope version without consulting the file name. ## 14. References _(informative)_ -- `docs/adr-003-opentelemetry-observability.md`: the governing decision. +- `docs/adrs/adr-0003-correlation-first-opentelemetry-observability-for-workshop-runs.md`: + the governing decision. - `docs/roadmap.md` phase 5: the delivery sequence this contract unblocks. - `docs/execplans/5-1-1-otel-support.md`: the plan that produced this contract. diff --git a/skills/df12-build-supervisor/SKILL.md b/skills/df12-build-supervisor/SKILL.md index b5134bd0..0639f701 100644 --- a/skills/df12-build-supervisor/SKILL.md +++ b/skills/df12-build-supervisor/SKILL.md @@ -700,7 +700,7 @@ reviewer. branches, and BLOCKED plans are reported for you instead. 2. **Assess-first relaunch:** relaunch with `resumePartialBranches=true` (default `resumeMode="assess"`). The fresh run discovers surviving - `roadmap-*` branches, assesses each against ADR 002, and reports them in + `roadmap-*` branches, assesses each against ADR 0002, and reports them in the top-level `recovery` object without mutating anything. Read the classifications, then decide per branch: enable `resumeMode="review"` on a follow-up run to let clean `adopt-complete` branches re-enter review diff --git a/src/workflows/df12-build-odw/assessment.ts b/src/workflows/df12-build-odw/assessment.ts index dca928e1..15dff2d2 100644 --- a/src/workflows/df12-build-odw/assessment.ts +++ b/src/workflows/df12-build-odw/assessment.ts @@ -1,5 +1,5 @@ /** - * ADR 002 partial-branch assessment: deferred-review classification, the + * ADR 0002 partial-branch assessment: deferred-review classification, the * manual-merge handoff guard, the assessment gate, and the report-only * assessment agents. Assessment output NEVER merges, pushes, or ticks the * roadmap; classification is advice for the operator, and host-collected @@ -24,7 +24,7 @@ import type { RecoveryCandidate } from './types.ts' // States in which the assessed branch is KEPT (not fully adopted), so any // untracked task-scoped ExecPlan/review artefact is worth durably committing // onto the branch before later cleanup: -// - `adopt-partial` — ADR 002 preserves work "only through Git state", which +// - `adopt-partial` — ADR 0002 preserves work "only through Git state", which // is exactly a branch-local commit; // - `continue-manual` — hands the branch to an operator who needs the planning // artefacts intact; @@ -134,7 +134,7 @@ export interface ImplementationReport { openIssues?: readonly string[] } -/** A task result eligible for ADR 002 assessment: its status, stage, detail, and open issues. */ +/** A task result eligible for ADR 0002 assessment: its status, stage, detail, and open issues. */ export interface AssessableResult extends Record<string, unknown> { /** Terminal task status; only 'failed'/'halted' branches are assessment candidates. */ status?: string @@ -416,7 +416,7 @@ function assessmentModelTier(evidence: Pick<PartialAssessmentEvidence, 'changedF } /** - * Bind the ADR 002 assessment run wiring once (preamble, adapter routing, + * Bind the ADR 0002 assessment run wiring once (preamble, adapter routing, * escalation model, retry, enable switch) and return the assessment surface: * prompt builders, the recovery-candidate assessor, the assessment-eligibility * gate, and `attachAssessment`, which also drives artefact salvage. Assessment @@ -426,7 +426,7 @@ function assessmentModelTier(evidence: Pick<PartialAssessmentEvidence, 'changedF * @returns `{ assessmentPrompt, recoveryAssessmentPrompt, assessRecoveryCandidate, shouldAssessFailure, attachAssessment }`. */ export function makeAssessment({ preamble, assessPartialBranches, assessmentAgentOptions, assessmentEscalationModel, withInfraRetry }: AssessmentDeps) { - // Shared ADR 002 assessment prompt body — the classification contract is ONE + // Shared ADR 0002 assessment prompt body — the classification contract is ONE // contract: in-run failure assessment and fresh-run recovery assessment feed // the same schema, enum, and evidence expectations. Only the task header and // the context block differ between the two entry points. @@ -443,7 +443,7 @@ export function makeAssessment({ preamble, assessPartialBranches, assessmentAgen '', 'This is a READ-ONLY recovery assessment. Do not edit files, commit, stash, merge, cherry-pick, push, delete worktrees, mark roadmap checkboxes, or run any command that mutates repository state. Do not resume or rely on the failed agent transcript. Inspect only durable state that exists on disk or in Git.', '', - 'Use ADR 002 (`docs/adr-002-assess-partial-task-branches.md`) as the classification contract. Return exactly one classification:', + 'Use ADR 0002 (`docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md`) as the classification contract. Return exactly one classification:', '- `adopt-complete`: the branch satisfies the roadmap task success criterion, has an up-to-date ExecPlan, required gates are green, and can proceed through the ordinary review and integration path.', '- `adopt-partial`: the branch contains a coherent useful slice, but the roadmap task must remain unchecked and the work should be preserved only through Git state.', '- `continue-manual`: the branch is promising, but scope, roadmap state, validation, or review evidence needs operator judgement before any merge.', @@ -532,7 +532,7 @@ export function makeAssessment({ preamble, assessPartialBranches, assessmentAgen return { ...assessment, assessmentTier: tier } } - // Route a discovered candidate through the SAME ADR 002 assessment contract as + // Route a discovered candidate through the SAME ADR 0002 assessment contract as // in-run failures: same evidence collector, same schema, same adapter routing. async function assessRecoveryCandidate(candidate: RecoveryCandidate) { const task = { id: candidate.taskId, title: candidate.taskTitle } @@ -676,7 +676,7 @@ export function makeAssessment({ preamble, assessPartialBranches, assessmentAgen assessmentPrompt, /** Build the fresh-run recovery-assessment prompt (transcript unavailable by design). */ recoveryAssessmentPrompt, - /** Assess a discovered recovery candidate through the ADR 002 contract. */ + /** Assess a discovered recovery candidate through the ADR 0002 contract. */ assessRecoveryCandidate, /** The eligibility gate: whether a failed result's branch reaches model assessment. */ shouldAssessFailure, diff --git a/src/workflows/df12-build-odw/config.ts b/src/workflows/df12-build-odw/config.ts index be50c2ef..5d51c931 100644 --- a/src/workflows/df12-build-odw/config.ts +++ b/src/workflows/df12-build-odw/config.ts @@ -402,7 +402,7 @@ export function makeConfig(rawArgs: unknown): WorkflowConfig { const PROJECT_ROOT = cfg.projectRoot || process.cwd() const BASE = cfg.base || 'main' // integration branch: rebase + squash-merge target, roadmap source of truth const ROADMAP = cfg.roadmap || 'docs/roadmap.md' - const DESIGN_DOCS = cfg.designDocs || 'the design document(s) and the ADRs (docs/adr-*.md) under docs/' // project design sources cited in prompts + const DESIGN_DOCS = cfg.designDocs || 'the design document(s) and the ADRs (docs/adrs/*.md) under docs/' // project design sources cited in prompts const RESEARCH_NOTE = cfg.researchNote || null // optional project-specific external-library research note (e.g. a vendored lib source path to verify against) const ONLY_TASK = cfg.taskId || null // process exactly one named roadmap id (e.g. "1.2.1") const MAX_TASKS = ONLY_TASK ? 1 : cfg.maxTasks || 12 // hard ceiling on roadmap steps per run diff --git a/src/workflows/df12-build-odw/main.ts b/src/workflows/df12-build-odw/main.ts index 323d6d7d..ff65020d 100644 --- a/src/workflows/df12-build-odw/main.ts +++ b/src/workflows/df12-build-odw/main.ts @@ -267,7 +267,7 @@ const { runTaskAgentWritePreflight, ensureTaskAgentWriteAccess } = makeWritePref targets: writeProbeTargets, }) -// ADR 002 assessment and remediation triage with the run wiring bound once +// ADR 0002 assessment and remediation triage with the run wiring bound once // (see assessment.ts and remediation.ts). const { assessmentPrompt, @@ -497,7 +497,7 @@ async function executeResume( if (built.kind === 'failure') return checkedTaskOutcome(built.fail) impl = built.impl } else { - // Carry the ADR 002 assessment's advisory residual risk forward into the + // Carry the ADR 0002 assessment's advisory residual risk forward into the // synthetic implementation report so the resumed reviewer/integrator sees // the caveats — without the resume having been blocked for them (#23). const synthetic = await syntheticRecoveryImpl(enriched, evidence, residualRisk) @@ -664,7 +664,7 @@ async function runRecovery(root: string, mergeLock: MergeLockFn = null): Promise } // --- Resume: re-enter the ordinary pipeline at the dispatched stage. The - // committed ExecPlan (continue mode) or the ADR 002 assessment (review + // committed ExecPlan (continue mode) or the ADR 0002 assessment (review // mode) chose the entry point; the pipeline's own gates remain decisive, // and integration ticks the roadmap under the merge lock. const stage = decision.stage || 'review' diff --git a/src/workflows/df12-build-odw/run-task.ts b/src/workflows/df12-build-odw/run-task.ts index 23d38554..0c75c9e5 100644 --- a/src/workflows/df12-build-odw/run-task.ts +++ b/src/workflows/df12-build-odw/run-task.ts @@ -52,7 +52,7 @@ export interface StagePlan extends Record<string, unknown> { /** * The implementation stage's product: the build agent's (or work-item build * loop's) report on the committed work. Carries the advisory, non-blocking - * `residualRisk` list forward from an ADR 002 recovery assessment so the + * `residualRisk` list forward from an ADR 0002 recovery assessment so the * dual review and integration prompts can render it as context (#23). * Extends `Record<string, unknown>` because the implementation agent's * structured response may carry additional fields the pipeline does not @@ -69,7 +69,7 @@ export interface StageImpl extends Record<string, unknown> { openIssues?: string[] /** Commit subjects reported by the schema-validated implementation agent. */ commits?: string[] - // Advisory, non-blocking residual risk carried forward from an ADR 002 + // Advisory, non-blocking residual risk carried forward from an ADR 0002 // recovery assessment; rendered as review/integration context only (#23). /** Advisory, non-blocking risks carried into review and integration. */ residualRisk?: string[] @@ -250,7 +250,7 @@ export interface TaskPipelineDeps { hostGateLock: Lock /** Retry infrastructure-classified agent failures. */ withInfraRetry: <T>(run: () => Promise<T>, label: string) => Promise<T> - /** Attach an ADR 002 assessment to a task result. */ + /** Attach an ADR 0002 assessment to a task result. */ attachAssessment: (task: SelectedTask, wt: { branch?: string; worktreePath?: string; baseSha?: string }, result: StageResult) => Promise<StageResult> /** Verify that configured task agents can write to the worktree. */ ensureTaskAgentWriteAccess: (worktree: string, tag: string) => Promise<{ diff --git a/src/workflows/df12-build-odw/schemas.ts b/src/workflows/df12-build-odw/schemas.ts index 23057435..0f5894c5 100644 --- a/src/workflows/df12-build-odw/schemas.ts +++ b/src/workflows/df12-build-odw/schemas.ts @@ -1,7 +1,7 @@ /** * JSON Schema contracts for every structured agent hand-off in the * df12-build-odw workflow: plan, design verdict, implementation, dual review, - * fix rounds, integration, post-merge audit, and the ADR 002 partial-branch + * fix rounds, integration, post-merge audit, and the ADR 0002 partial-branch * assessment. Downstream JavaScript dereferences `required` fields without * optional chaining, and iterates keys assuming `additionalProperties` is * false, so treat these as contracts, not documentation; @@ -204,7 +204,7 @@ export const AUDIT_SCHEMA = { } /** - * The enum of allowed classification strings for an ADR 002 partial-branch + * The enum of allowed classification strings for an ADR 0002 partial-branch * assessment: `adopt-complete`, `adopt-partial`, `continue-manual`, and * `discard`. Referenced by `ASSESSMENT_SCHEMA`'s `classification` property, * so treat this as a contract, not documentation. @@ -218,7 +218,7 @@ export const ASSESSMENT_CLASSIFICATIONS = [ ] /** - * The ADR 002 partial-branch assessment: the resume `classification`, + * The ADR 0002 partial-branch assessment: the resume `classification`, * branch/worktree identity, and two carry-forward channels — the * `missingEvidence` BLOCKING channel (genuinely missing validation/review * evidence that must prevent an adopt-complete resume) and the diff --git a/tests/df12-build-odw-assessment.test.mjs b/tests/df12-build-odw-assessment.test.mjs index 5a2b4e13..1b7f69db 100644 --- a/tests/df12-build-odw-assessment.test.mjs +++ b/tests/df12-build-odw-assessment.test.mjs @@ -112,7 +112,7 @@ function makeRepo() { return { dir, baseSha, branch: 'roadmap-1-2-3' } } -test('assessment schema exposes only ADR 002 classifications', async () => { +test('assessment schema exposes only ADR 0002 classifications', async () => { const surface = await loadAssessmentSurface() assert.deepEqual(surface.ASSESSMENT_CLASSIFICATIONS, [ diff --git a/tests/df12-build-odw-recovery.test.mjs b/tests/df12-build-odw-recovery.test.mjs index 8c8527fe..96328193 100644 --- a/tests/df12-build-odw-recovery.test.mjs +++ b/tests/df12-build-odw-recovery.test.mjs @@ -1,5 +1,5 @@ // Tests for fresh-run recovery (failure-resume phases 1-2): configuration, -// candidate discovery, ADR 002 assessment reuse, the resumeMode decision +// candidate discovery, ADR 0002 assessment reuse, the resumeMode decision // table (including an exhaustive domain sweep), review-mode resume wiring, // and the assess-only no-mutation guarantee, against throwaway git fixtures // from tests/fixtures/recovery-repo.mjs. @@ -305,7 +305,7 @@ function sampleCandidate(repo) { } } -test('recovery and failure assessments share one ADR 002 prompt contract', async () => { +test('recovery and failure assessments share one ADR 0002 prompt contract', async () => { const surface = await loadRecoverySurface({}) const task = { id: '1.2.3', title: 'Implement the parser state machine.' } const evidence = { taskId: '1.2.3' } @@ -322,9 +322,9 @@ test('recovery and failure assessments share one ADR 002 prompt contract', async ) const contractOf = (prompt) => { - const start = prompt.indexOf('Use ADR 002') + const start = prompt.indexOf('Use ADR 0002') const end = prompt.indexOf('Host-collected git evidence:') - assert.ok(start !== -1 && end > start, 'prompt should carry the ADR 002 contract block') + assert.ok(start !== -1 && end > start, 'prompt should carry the ADR 0002 contract block') return prompt.slice(start, end) } assert.equal(contractOf(recoveryPrompt), contractOf(failurePrompt)) @@ -345,7 +345,7 @@ test('recovered candidates reuse the assessment evidence collector and schema', const outcome = await surface.assessRecoveryCandidate(candidate) assert.equal(calls.length, 1) - assert.equal(calls[0].opts.schema, surface.ASSESSMENT_SCHEMA, 'recovery must reuse the ADR 002 schema object') + assert.equal(calls[0].opts.schema, surface.ASSESSMENT_SCHEMA, 'recovery must reuse the ADR 0002 schema object') assert.equal(calls[0].opts.label, 'recover-assess:1.2.3') assert.equal(calls[0].opts.phase, 'Recovery') assert.equal(outcome.assessmentError, '') diff --git a/tests/fixtures/prompts/recovery-resume-code-review.txt b/tests/fixtures/prompts/recovery-resume-code-review.txt index e329fd3e..af2016e5 100644 --- a/tests/fixtures/prompts/recovery-resume-code-review.txt +++ b/tests/fixtures/prompts/recovery-resume-code-review.txt @@ -7,7 +7,7 @@ Standing rules (apply to every step, no exceptions): - Use `leta` for symbol navigation, references, call graphs, and branch-local verification (leta show / refs / grep / files) instead of ad-hoc ripgrep or read-file. If Leta is unavailable because its daemon or workspace tooling fails, record the exact failure and fall back to precise file inspection for the current task; do not add a hard implementation blocker solely for a transient Leta startup failure. Leta unavailability is not a valid reason to set ExecPlan status to BLOCKED. - Use `sem` for codebase history navigation (semantic, entity-level diffs and blame) instead of raw git log/blame. - Load the appropriate language router skill for any code you touch: python-router for Python, rust-router for Rust, and the matching router for other languages. Follow the smaller skills it routes you to. -- Treat docs/ as the source of truth: the design document(s) and the ADRs (docs/adr-*.md) under docs/, the developers guide, any users guide present, the coding/scripting standards, and AGENTS.md. Obey AGENTS.md quality gates and the en-GB Oxford-spelling ("-ize"/"-yse"/"-our") convention in all prose, comments, and commits. +- Treat docs/ as the source of truth: the design document(s) and the ADRs (docs/adrs/*.md) under docs/, the developers guide, any users guide present, the coding/scripting standards, and AGENTS.md. Obey AGENTS.md quality gates and the en-GB Oxford-spelling ("-ize"/"-yse"/"-our") convention in all prose, comments, and commits. - The deterministic commit gates for this run are `make all`. AGENTS.md is authoritative for the gate set: if AGENTS.md names different or additional gate targets (for example sequential `make check-fmt`, `make typecheck`, `make lint`, `make test`), run those named targets as well — NEVER assume `make all` aggregates them, and never report gates as green unless every project-required gate passed at HEAD. - The integration branch is "main"; treat origin/main as canonical. The roadmap lives at docs/roadmap.md. - Format ONLY the files you changed: run the markdown formatter on the specific paths you touched (`mdtablefix … <files>` then `markdownlint-cli2 --fix <files>`), then gate. Do NOT run a repo-global format such as `make fmt` / `mdformat-all` that reformats unrelated files — that churn only has to be parked and discarded. diff --git a/tests/fixtures/prompts/recovery-resume-expert-review.txt b/tests/fixtures/prompts/recovery-resume-expert-review.txt index 756c6656..c75440e2 100644 --- a/tests/fixtures/prompts/recovery-resume-expert-review.txt +++ b/tests/fixtures/prompts/recovery-resume-expert-review.txt @@ -7,7 +7,7 @@ Standing rules (apply to every step, no exceptions): - Use `leta` for symbol navigation, references, call graphs, and branch-local verification (leta show / refs / grep / files) instead of ad-hoc ripgrep or read-file. If Leta is unavailable because its daemon or workspace tooling fails, record the exact failure and fall back to precise file inspection for the current task; do not add a hard implementation blocker solely for a transient Leta startup failure. Leta unavailability is not a valid reason to set ExecPlan status to BLOCKED. - Use `sem` for codebase history navigation (semantic, entity-level diffs and blame) instead of raw git log/blame. - Load the appropriate language router skill for any code you touch: python-router for Python, rust-router for Rust, and the matching router for other languages. Follow the smaller skills it routes you to. -- Treat docs/ as the source of truth: the design document(s) and the ADRs (docs/adr-*.md) under docs/, the developers guide, any users guide present, the coding/scripting standards, and AGENTS.md. Obey AGENTS.md quality gates and the en-GB Oxford-spelling ("-ize"/"-yse"/"-our") convention in all prose, comments, and commits. +- Treat docs/ as the source of truth: the design document(s) and the ADRs (docs/adrs/*.md) under docs/, the developers guide, any users guide present, the coding/scripting standards, and AGENTS.md. Obey AGENTS.md quality gates and the en-GB Oxford-spelling ("-ize"/"-yse"/"-our") convention in all prose, comments, and commits. - The deterministic commit gates for this run are `make all`. AGENTS.md is authoritative for the gate set: if AGENTS.md names different or additional gate targets (for example sequential `make check-fmt`, `make typecheck`, `make lint`, `make test`), run those named targets as well — NEVER assume `make all` aggregates them, and never report gates as green unless every project-required gate passed at HEAD. - The integration branch is "main"; treat origin/main as canonical. The roadmap lives at docs/roadmap.md. - Format ONLY the files you changed: run the markdown formatter on the specific paths you touched (`mdtablefix … <files>` then `markdownlint-cli2 --fix <files>`), then gate. Do NOT run a repo-global format such as `make fmt` / `mdformat-all` that reformats unrelated files — that churn only has to be parked and discarded. diff --git a/tests/fixtures/prompts/recovery-resume-integrate.txt b/tests/fixtures/prompts/recovery-resume-integrate.txt index 703673c9..a93286ab 100644 --- a/tests/fixtures/prompts/recovery-resume-integrate.txt +++ b/tests/fixtures/prompts/recovery-resume-integrate.txt @@ -7,7 +7,7 @@ Standing rules (apply to every step, no exceptions): - Use `leta` for symbol navigation, references, call graphs, and branch-local verification (leta show / refs / grep / files) instead of ad-hoc ripgrep or read-file. If Leta is unavailable because its daemon or workspace tooling fails, record the exact failure and fall back to precise file inspection for the current task; do not add a hard implementation blocker solely for a transient Leta startup failure. Leta unavailability is not a valid reason to set ExecPlan status to BLOCKED. - Use `sem` for codebase history navigation (semantic, entity-level diffs and blame) instead of raw git log/blame. - Load the appropriate language router skill for any code you touch: python-router for Python, rust-router for Rust, and the matching router for other languages. Follow the smaller skills it routes you to. -- Treat docs/ as the source of truth: the design document(s) and the ADRs (docs/adr-*.md) under docs/, the developers guide, any users guide present, the coding/scripting standards, and AGENTS.md. Obey AGENTS.md quality gates and the en-GB Oxford-spelling ("-ize"/"-yse"/"-our") convention in all prose, comments, and commits. +- Treat docs/ as the source of truth: the design document(s) and the ADRs (docs/adrs/*.md) under docs/, the developers guide, any users guide present, the coding/scripting standards, and AGENTS.md. Obey AGENTS.md quality gates and the en-GB Oxford-spelling ("-ize"/"-yse"/"-our") convention in all prose, comments, and commits. - The deterministic commit gates for this run are `make all`. AGENTS.md is authoritative for the gate set: if AGENTS.md names different or additional gate targets (for example sequential `make check-fmt`, `make typecheck`, `make lint`, `make test`), run those named targets as well — NEVER assume `make all` aggregates them, and never report gates as green unless every project-required gate passed at HEAD. - The integration branch is "main"; treat origin/main as canonical. The roadmap lives at docs/roadmap.md. - Format ONLY the files you changed: run the markdown formatter on the specific paths you touched (`mdtablefix … <files>` then `markdownlint-cli2 --fix <files>`), then gate. Do NOT run a repo-global format such as `make fmt` / `mdformat-all` that reformats unrelated files — that churn only has to be parked and discarded. diff --git a/tests/fixtures/recovery-mock-agent.mjs b/tests/fixtures/recovery-mock-agent.mjs index 3c274314..e5a8e694 100644 --- a/tests/fixtures/recovery-mock-agent.mjs +++ b/tests/fixtures/recovery-mock-agent.mjs @@ -4,7 +4,7 @@ * layer 6). Reads the prompt from stdin, extracts the JSON Schema the ODW * bridge appends, and switches on schema fingerprints — never prompt prose: * - * classification -> an eligible ADR 002 assessment (clean, scoped, valid) + * classification -> an eligible ADR 0002 assessment (clean, scoped, valid) * verdict -> a passing review * roadmapMarkedDone -> a successful integration claim * anything else -> a minimal valid instance / stub text diff --git a/tests/fixtures/recovery-repo.mjs b/tests/fixtures/recovery-repo.mjs index a08155ee..a63762df 100644 --- a/tests/fixtures/recovery-repo.mjs +++ b/tests/fixtures/recovery-repo.mjs @@ -1,7 +1,7 @@ // Shared git fixtures for the recovery test suites: a throwaway repository // with an `origin` remote, surviving roadmap-* branches, live worktrees with // committed canonical ExecPlans, a durable-state snapshot helper for the -// no-mutation assertions, and a complete eligible ADR 002 assessment reply. +// no-mutation assertions, and a complete eligible ADR 0002 assessment reply. // Consumed by tests/df12-build-odw-recovery*.test.mjs and // tests/df12-build-odw-write-preflight.test.mjs. @@ -155,7 +155,7 @@ export function repoStateSnapshot(repo) { } } -// A complete, eligible ADR 002 assessment reply; override fields per scenario. +// A complete, eligible ADR 0002 assessment reply; override fields per scenario. export function sampleAssessment(overrides = {}) { return { classification: 'adopt-complete', diff --git a/tests/fixtures/run-odw-simulation.mjs b/tests/fixtures/run-odw-simulation.mjs index 0c528813..b9ba85dd 100644 --- a/tests/fixtures/run-odw-simulation.mjs +++ b/tests/fixtures/run-odw-simulation.mjs @@ -11,7 +11,7 @@ * Scenario: { * args: {...workflow args...}, * pathPrefix?: "<dir prepended to PATH before the body runs>", - * assessment?: {...overrides for the scripted ADR 002 assessment reply...}, + * assessment?: {...overrides for the scripted ADR 0002 assessment reply...}, * review?: {...full scripted reply for code-review/expert-review labels...}, * fix?: {...full scripted reply for fix: labels...}, * failures?: { "<exact label>": { error?: "<message>", times?: N } } diff --git a/tests/modules/assessment.test.ts b/tests/modules/assessment.test.ts index e358c84e..7b1d531c 100644 --- a/tests/modules/assessment.test.ts +++ b/tests/modules/assessment.test.ts @@ -1,4 +1,4 @@ -// Module tests for the ADR 002 assessment surface (decomposition milestone +// Module tests for the ADR 0002 assessment surface (decomposition milestone // 8): deferred-review classification, the manual-merge handoff guard, the // assessment gate, and the attach path with scripted agents over a real // fixture repo. @@ -25,7 +25,7 @@ globals.log = () => {} globals.phase = () => {} // Both assessment entry points (assessmentPrompt and recoveryAssessmentPrompt) -// share the ADR 002 classification contract via assessmentPromptLines: blocking +// share the ADR 0002 classification contract via assessmentPromptLines: blocking // gaps route to `missingEvidence`, advisory caveats to `residualRisk`, and an // eligible adopt-complete is never held back for advisory risk alone (#23). // Pin that instructional wording so a regression that weakens it fails loudly. diff --git a/tests/modules/schemas.test.ts b/tests/modules/schemas.test.ts index 1289214b..5e5608e9 100644 --- a/tests/modules/schemas.test.ts +++ b/tests/modules/schemas.test.ts @@ -40,7 +40,7 @@ describe('agent schema contracts', () => { } }) - test('assessment classification enum matches the ADR 002 contract', () => { + test('assessment classification enum matches the ADR 0002 contract', () => { expect(ASSESSMENT_SCHEMA.properties.classification.enum).toEqual(ASSESSMENT_CLASSIFICATIONS) expect(ASSESSMENT_CLASSIFICATIONS).toEqual([ 'adopt-complete', diff --git a/workflows/df12-build-odw.js b/workflows/df12-build-odw.js index 9a7fd04b..0844640d 100644 --- a/workflows/df12-build-odw.js +++ b/workflows/df12-build-odw.js @@ -1288,7 +1288,7 @@ function makeConfig(rawArgs) { const PROJECT_ROOT2 = cfg.projectRoot || process.cwd(); const BASE2 = cfg.base || "main"; const ROADMAP2 = cfg.roadmap || "docs/roadmap.md"; - const DESIGN_DOCS = cfg.designDocs || "the design document(s) and the ADRs (docs/adr-*.md) under docs/"; + const DESIGN_DOCS = cfg.designDocs || "the design document(s) and the ADRs (docs/adrs/*.md) under docs/"; const RESEARCH_NOTE = cfg.researchNote || null; const ONLY_TASK2 = cfg.taskId || null; const MAX_TASKS2 = ONLY_TASK2 ? 1 : cfg.maxTasks || 12; @@ -2441,7 +2441,7 @@ function makeAssessment({ preamble: preamble2, assessPartialBranches, assessment "", "This is a READ-ONLY recovery assessment. Do not edit files, commit, stash, merge, cherry-pick, push, delete worktrees, mark roadmap checkboxes, or run any command that mutates repository state. Do not resume or rely on the failed agent transcript. Inspect only durable state that exists on disk or in Git.", "", - "Use ADR 002 (`docs/adr-002-assess-partial-task-branches.md`) as the classification contract. Return exactly one classification:", + "Use ADR 0002 (`docs/adrs/adr-0002-assess-partial-task-branches-before-fresh-restart.md`) as the classification contract. Return exactly one classification:", "- `adopt-complete`: the branch satisfies the roadmap task success criterion, has an up-to-date ExecPlan, required gates are green, and can proceed through the ordinary review and integration path.", "- `adopt-partial`: the branch contains a coherent useful slice, but the roadmap task must remain unchecked and the work should be preserved only through Git state.", "- `continue-manual`: the branch is promising, but scope, roadmap state, validation, or review evidence needs operator judgement before any merge.", @@ -2611,7 +2611,7 @@ function makeAssessment({ preamble: preamble2, assessPartialBranches, assessment assessmentPrompt: assessmentPrompt2, /** Build the fresh-run recovery-assessment prompt (transcript unavailable by design). */ recoveryAssessmentPrompt: recoveryAssessmentPrompt2, - /** Assess a discovered recovery candidate through the ADR 002 contract. */ + /** Assess a discovered recovery candidate through the ADR 0002 contract. */ assessRecoveryCandidate: assessRecoveryCandidate2, /** The eligibility gate: whether a failed result's branch reaches model assessment. */ shouldAssessFailure: shouldAssessFailure2, diff --git a/workflows/df12-build.js b/workflows/df12-build.js index 5655170e..506a0d73 100644 --- a/workflows/df12-build.js +++ b/workflows/df12-build.js @@ -24,7 +24,7 @@ export const meta = { const cfg = args || {} const BASE = cfg.base || 'main' // integration branch: rebase + squash-merge target, roadmap source of truth const ROADMAP = cfg.roadmap || 'docs/roadmap.md' -const DESIGN_DOCS = cfg.designDocs || 'the design document(s) and the ADRs (docs/adr-*.md) under docs/' // project design sources cited in prompts +const DESIGN_DOCS = cfg.designDocs || 'the design document(s) and the ADRs (docs/adrs/*.md) under docs/' // project design sources cited in prompts const RESEARCH_NOTE = cfg.researchNote || null // optional project-specific external-library research note (e.g. a vendored lib source path to verify against) const ONLY_TASK = cfg.taskId || null // process exactly one named roadmap id (e.g. "1.2.1") const MAX_TASKS = ONLY_TASK ? 1 : cfg.maxTasks || 12 // hard ceiling on roadmap steps per run