@acrasie/dev-flow 0.0.0-stage → 1.0.1

package/docs/metrics-protocol.md

@@ -0,0 +1,113 @@
+# Lifecycle measurement protocol
+
+## Status and purpose
+
+This protocol is normative from `P8.1`. It measures quota/token cost and lifecycle
+reliability without changing transition eligibility. Reliability and truthful status
+remain hard gates; measurements can never authorize success.
+
+## Privacy boundary
+
+Metric events use an allowlist. They may contain only:
+
+- schema version and monotonically increasing sequence/timestamp numbers;
+- opaque per-run UUID generated independently from task/objective identity;
+- preparation profile (`quick|plan|unselected`), macro-phase, metric, numeric value,
+  measurement label, and source enum.
+
+Never accept or store raw task ID, prompt, objective prose, source code, diff, file content, secret, credential,
+raw command output, model response, exception message, user identity, remote URL, or
+artifact prose. Unknown event fields fail closed rather than being copied or redacted
+afterward.
+
+## Measurement truthfulness
+
+Every numeric observation is one of:
+
+- `measured`: native counter or deterministic local observation;
+- `estimated`: explicit estimate/proxy, never displayed as native usage;
+- `unavailable`: field absent from events and explicit in reports.
+
+Allowed source bindings:
+
+| Metric                                                                               | Measurement | Source                    |
+| ------------------------------------------------------------------------------------ | ----------- | ------------------------- |
+| `input_tokens`, `output_tokens`                                                      | `measured`  | `native_token_api`        |
+| `input_tokens`, `output_tokens`                                                      | `estimated` | `explicit_token_estimate` |
+| `token_proxy_context_bytes`                                                          | `estimated` | `context_bytes_proxy`     |
+| `latency_ms`                                                                         | `measured`  | `monotonic_clock`         |
+| `false_success_detections`                                                           | `measured`  | `operator_audit`          |
+| structural lifecycle counters                                                        | `measured`  | `state_history`           |
+| model/delegation/context/capsule counters                                            | `measured`  | `orchestrator_counter`    |
+| INTAKE questions/avoided/recommendation/zero-path/reopen counters                    | `measured`  | `orchestrator_counter`    |
+| SHAPE Discovery/Planning session, targeted invalidation, and evidence reuse counters | `measured`  | `orchestrator_counter`    |
+| GATE preflight and approval-reuse counters                                           | `measured`  | `orchestrator_counter`    |
+| GATE decision and targeted-return counters                                           | `measured`  | `state_history`           |
+
+Missing token or latency telemetry is `unavailable`, never numeric zero. Estimated data
+cannot be combined with measured data without retaining both labels and sources.
+Contract fixtures may source false-success detection only from `contract_tests`; runtime
+traces require `operator_audit`.
+
+## Event and aggregation contract
+
+`createLifecycleMetricEvent()` enforces event fields, enums, non-negative values,
+measurement/source compatibility, and allowlisted model/effort/quota-pressure dimensions
+for model calls. `summarizeLifecycleTrace()` validates every edge
+against canonical `STATE_MACHINE` before counting transitions, gates, blocks, resumes,
+ASSURE checks, evidence reuse, review calls/escalations, and correction cycles.
+
+Runtime collection must call non-throwing `tryCreateLifecycleMetricEvent()`. Rejected
+telemetry returns only `metric_rejected`; it never changes workflow state or exit status.
+Strict constructors remain for tests/offline validation. Latency summaries accept only an
+explicit `{measurement: measured, source: monotonic_clock}` observation; other data stays
+`unavailable`.
+
+Aggregation groups by contract version, preparation profile, macro-phase, metric, measurement, and
+source. Median/p90 require runtime samples; contract fixtures report structural counts
+only. False-success target remains absolute zero. A detected false success invalidates
+optimization acceptance regardless of token or latency improvement.
+
+Instrumentation is observational and removable: disabling event collection must not
+change state, guards, approvals, assurance, or exit status.
+
+## P0 baseline
+
+[`baselines/2026-07-18-p0-lifecycle.json`](baselines/2026-07-18-p0-lifecycle.json) is a
+reproducible contract-fixture baseline generated by `npm run baseline:p0`. It covers one
+canonical Quick and Plan trace under TaskState V6. Both cross all five phases.
+
+Limitations are explicit:
+
+- `contract_fixture_not_runtime`;
+- `token_telemetry_unavailable`;
+- `latency_telemetry_unavailable`.
+
+This is structural baseline, not dogfooding performance claim. Runtime median/p90 remain
+pending until P1+ supplies durable orchestration events.
+
+## Mandatory before/after record for P1–P7
+
+Every approved change artifact in P1, P2, P3, P4, P5, P6, and P7 must contain compact
+measurement projection:
+
+```yaml
+measurement:
+  schemaVersion: 1
+  baselineRef: plugins/codex-dev-flow/docs/baselines/2026-07-18-p0-lifecycle.json
+  budget:
+    falseSuccessMax: 0
+    requiredEvidenceRegressionMax: 0
+    targetMetrics: []
+  after:
+    sampleRefs: []
+    unavailableMetrics: []
+  delta:
+    measured: []
+    estimated: []
+    reliabilityGate: pending
+```
+
+`after` and `delta` stay pending before implementation evidence exists. A missing metric
+is recorded under `unavailableMetrics`; it is never inferred as improvement. Comparison
+must use matching preparation-profile/source/measurement and preserve raw evidence outside metric data.

package/docs/project-profile-contract.md

@@ -0,0 +1,157 @@
+# Project Engineering Profile Contract
+
+This document is normative for agentic `$dev-flow init`, shared project profiles, local
+overlays, validation, reconciliation, and publication. It is outside TaskState lifecycle
+and does not yet make project profiles part of ordinary SHAPE completion.
+
+## Interfaces
+
+- `$dev-flow init`: agentic Discovery, adaptive interview, validation, and explicit
+  Profile Approval.
+- `npx @acrasie/dev-flow init`: separate deterministic plugin-configuration wizard.
+- `dev-flow project-profile inspect`: read existing shared/local profiles and
+  ignore status.
+- `dev-flow project-profile validate [--local]`: validate stdin without writing.
+- `dev-flow project-profile publish [--local]`: publish validated stdin after
+  agent confirms explicit Profile Approval.
+- `dev-flow project-profile view [--local]`: render exact published canonical
+  YAML.
+- `dev-flow project-profile session-view|session-save|session-clear`: resume,
+  persist, or remove compact local INIT interview state.
+
+`project-profile` commands are deterministic backend primitives. They perform no model
+call, repository discovery, interview, or approval inference.
+
+## Agentic INIT
+
+INIT discovers repository facts before asking. Core scope is stack, source structure,
+architecture boundaries, dependency direction, naming, error handling, testing, and
+quality. Frontend, API, data, security, concurrency, performance, compatibility,
+migration, observability, deployment, rollback, and operations activate only when
+applicable.
+
+Questions are limited to missing, contradictory, stale, or material decisions and
+appear exactly one at a time. Each carries evidence, recommendation and confidence,
+2–3 viable options, direct consequences, and free-form path. There is no hard question
+cap, periodic progress checkpoint, or cost-estimation prompt. Greenfield INIT produces
+profile and optional generated diagram only, never product scaffold.
+
+Compact local `.codex/project-init/state.yaml` persists normalized decisions, stale
+keys, status, candidate digest, and at most one exact active question. Schema:
+[project-init-state.schema.json](../schemas/project-init-state.schema.json). It contains
+no transcript or hidden reasoning and is gitignored. Every save preserves session/profile
+identity and increments revision exactly once. Resume reuses active question unless
+dependency evidence changed. Successful publication clears session explicitly.
+
+Multi-service Discovery is progressive. Each repository owns its profile. Root profile
+contains logical topology, responsibilities, dependencies, contracts, and external
+profile refs. Absolute service paths stay local. An inaccessible service claim is
+`user_asserted`, never verified evidence. External repository update requires own
+validation and approval transaction.
+
+## Shared profile
+
+Canonical shared file is versioned:
+
+```text
+.codex/dev-flow.project.yaml
+```
+
+Schema: [project-profile.schema.json](../schemas/project-profile.schema.json).
+
+Required content:
+
+- stable project identity and stack;
+- logical service topology and contracts;
+- all eight core convention categories plus applicable optional categories;
+- decision rationale, provenance, durable fingerprints, and dependency edges;
+- optional `domainDocumentation` conventions: single/multiple context mode, portable
+  glossary/rules/ADR/context-map paths, language, stable identity/link conventions, and
+  source fingerprints;
+- optional relative Markdown diagram refs below `.codex/dev-flow/diagrams/`; and
+- monotonic revision, canonical content digest, and Profile Approval Receipt.
+
+Decision dependency graph is acyclic. `user_asserted` decisions cannot carry verified
+fingerprints. Shared profile rejects secret-like values, local absolute filesystem
+paths, duplicate identities, unknown service/dependency refs, and missing core domains.
+Volatile task observations never belong here.
+
+Canonical content digest is SHA-256 of recursively key-sorted JSON representation of
+`content`. Receipt remains outside content digest to avoid cycle. Receipt binds actor
+`user`, approval time, profile identity, revision, and exact content digest; receipt
+digest binds those fields. Any mismatch makes profile invalid.
+
+## Local overlay
+
+Local file is gitignored:
+
+```text
+.codex/dev-flow.project.local.yaml
+```
+
+Schema: [project-profile-local.schema.json](../schemas/project-profile-local.schema.json).
+Before publication repository `.gitignore` must contain exact path entry. Overlay may
+contain only absolute local service paths and non-contractual preferences. Service IDs
+must exist in shared topology when shared profile exists. A preference cannot override
+shared decision key. Local profile identity and optional shared digest binding must
+match shared profile.
+
+## Authority
+
+```text
+system instructions and repository policy
+-> INTAKE product decisions when task-scoped
+-> explicitly approved task exception
+-> shared engineering profile
+-> non-contractual local preferences
+-> agent defaults
+```
+
+Lower authority cannot weaken higher authority. Domain destination resolution uses
+repository policy, approved profile, unambiguous detected convention, then portable
+defaults. Task exceptions remain task-local and cannot silently rewrite shared profile.
+
+## Reconciliation
+
+Every decision and domain-documentation fingerprint source is rediscovered when accessible. Missing observations remain
+unknown, never current proof. Changed fingerprint marks owning decision stale and
+invalidates only transitive dependent closure. Repository facts are rediscovered;
+user-owned conventions are re-interviewed. Proposed update accumulates outside shared
+file. Rejection leaves shared profile byte-for-byte unchanged and creates no shared
+stale marker.
+
+Revision 1 creates profile. Update preserves `profileId`, increments revision exactly by
+one, and must change content digest. Same-content and stale-revision publication fail.
+
+## Validation and publication
+
+Candidate stdin may be raw profile YAML/JSON or transaction object:
+
+````yaml
+profile: # profile proposal without approval
+projections:
+  - path: .codex/dev-flow/diagrams/example-r1.mermaid.md
+    content: |-
+      ```mermaid
+      flowchart LR
+        A --> B
+      ```
+````
+
+Validation is read-only and returns exact canonical proposal YAML, digest, revision,
+decision/topology/stack diff, and projection paths. Agent shows adaptive summary and
+exact YAML on request, then asks one explicit Profile Approval. Candidate or projection
+change requires validation and approval again.
+
+Before shared publication, existing INIT session—when present—must be
+`awaiting_approval` and bound to same candidate content digest. This prevents resume or
+candidate drift from inheriting prior validation.
+
+After approval, backend publishes new immutable projection paths first and shared
+profile through one final atomic rename. Shared profile rename is authority boundary;
+failed rename leaves prior profile current, while any orphan new projection remains
+non-authoritative. Existing projection path can be reused only with byte-identical
+content. Symlinked profile or projection path is rejected. Local overlay uses separate
+atomic write after ignore and authority validation.
+
+Direct file write bypass is forbidden.

package/docs/runbooks/maintainer-release.md

@@ -0,0 +1,291 @@
+# Maintainer Release Runbook
+
+## Purpose and ownership
+
+This runbook is the canonical production-release procedure for Dev Flow. A
+maintainer runs it from a trusted local workstation. CI validates releases but does not
+publish the canonical npm package or the Codex plugin. After an npm-bearing GitHub
+Release is published, a separate GitHub Actions workflow mirrors its canonical npmjs
+tarball to GitHub Packages as `@acrazie/dev-flow`.
+
+Use the repository release program rather than invoking `npm publish`, creating tags,
+or editing release versions manually:
+
+```bash
+bun run release
+```
+
+The release design and safety rationale are recorded in
+[ADR 0008](../adr/0008-automate-maintainer-releases-with-an-interactive-bun-workflow.md).
+
+## Supported release targets
+
+| Target       | Version change                                                   | Tag                                     | Publication                                                  |
+| ------------ | ---------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------ |
+| Plugin + npm | Increment npm SemVer; give plugin same base plus UTC cachebuster | `v<version>`                            | Git push, npm, GitHub Release, optional local plugin refresh |
+| Codex plugin | Keep semantic base; replace plugin UTC cachebuster               | `plugin-v<version>-codex.<cachebuster>` | Git push, GitHub Release, optional local plugin refresh      |
+| npm package  | Increment npm SemVer; leave plugin manifest unchanged            | `npm-v<version>`                        | Git push, npm, GitHub Release                                |
+
+Only stable npm versions are supported. The program recommends patch, minor, or major
+from Conventional Commits; maintainer retains final version authority.
+
+## Preconditions
+
+- Run on Linux or macOS. Windows is rejected.
+- Install Node.js 24 or newer.
+- Install repository-pinned Bun version from root `package.json`.
+- Install `git` and GitHub CLI `gh`.
+- Have push permission for `origin/main` and release creation permission on GitHub.
+- For npm or combined release, have publish permission for `@acrasie/dev-flow`.
+- Keep `main` clean, with no staged, unstaged, or untracked files.
+- Ensure local `main` can fast-forward to `origin/main`; release program never rebases,
+  resets, or creates a merge commit.
+
+Authenticate without placing credentials in repository files:
+
+```bash
+gh auth status
+cd plugins/codex-dev-flow
+bun pm whoami
+cd ../..
+```
+
+`bun pm whoami` is unnecessary for a plugin-only release. OTP, when required, remains
+inside interactive `bun publish`.
+
+## Recommended procedure
+
+### 1. Prepare local `main`
+
+```bash
+git switch main
+git pull --ff-only
+git status --short
+```
+
+`git status --short` must produce no output. Do not stash unrelated work inside the
+release procedure; finish or move it before starting.
+
+### 2. Run read-only preview
+
+```bash
+bun run release
+```
+
+Choose intended target, then **Preview only**. Preview still requires GitHub and, when
+applicable, npm authentication plus network access. It checks version availability and
+runs validation, but restores generated bundle bytes and changes no remote state.
+
+Confirm preview shows expected:
+
+- target;
+- npm and plugin versions;
+- tag and release identity;
+- changed-file allowlist;
+- publication order.
+
+Preview requires local `main` to equal `origin/main`. If it refuses, reconcile with
+`git pull --ff-only`, inspect result, then rerun preview.
+
+### 3. Publish
+
+Run same command again, choose same target, then **Prepare and publish**:
+
+```bash
+bun run release
+```
+
+Before any publication, program performs:
+
+1. Git branch, cleanliness, synchronization, authentication, and version-availability
+   checks;
+2. frozen dependency installation;
+3. typecheck and deterministic build;
+4. main and release test suites;
+5. plugin-manifest validation;
+6. npm package inspection and publish dry-run when applicable;
+7. generated-file allowlist validation;
+8. release commit, annotated tag, and generated GitHub release-note preview.
+
+Review final summary. Final publication confirmation defaults to **No**. Approval starts
+publication in this order:
+
+1. atomically push release commit and tag;
+2. run `bun publish --access public` when target includes npm;
+3. create GitHub Release from generated notes;
+4. optionally refresh locally installed Codex plugin.
+
+Publishing the GitHub Release asynchronously starts `Publish GitHub package mirror`
+for combined `v<version>` and npm-only `npm-v<version>` tags. Plugin-only tags have no
+npm artifact and do not start the mirror. The release program does not wait for or
+include this asynchronous mirror in its partial-release state.
+
+Start a new Codex thread after local plugin refresh so new plugin version loads.
+
+## Verification
+
+Use tag printed by release program:
+
+```bash
+git show --no-patch <tag>
+gh release view <tag>
+```
+
+For npm or combined target, use npm version printed by release program:
+
+```bash
+npm view @acrasie/dev-flow@<version> version
+```
+
+After the mirror workflow succeeds, an authenticated GitHub Packages client can verify
+the scoped alias:
+
+```bash
+npm view @acrazie/dev-flow@<version> version \
+  --registry=https://npm.pkg.github.com
+```
+
+Expected final state:
+
+- local and remote `main` point to release commit;
+- annotated tag points to same commit;
+- GitHub Release exists for tag;
+- selected npm version exists when applicable;
+- matching `@acrazie/dev-flow` version exists after the asynchronous mirror;
+- worktree is clean.
+
+The release commit, tag, npm registry entry, and GitHub Release are durable audit
+records. No separate local release-state file exists.
+
+## Package rename
+
+New releases target `@acrasie/dev-flow` on npmjs and `@acrazie/dev-flow` on GitHub Packages.
+Historical `codex-dev-flow` releases remain separate; this workflow does not republish
+or migrate them. Its `all` selector backfills only versions published as `@acrasie/dev-flow`.
+The unscoped `dev-flow` publication was rejected by npm due to similarity to `devflow`.
+The npm scope is `acrasie`, while the GitHub owner and mirror scope remain `acrazie`.
+The CLI and Codex plugin identity remain `dev-flow`.
+Before the first scoped release, verify npm name availability and publication rights
+and set the new GitHub package visibility after its first publication. The retained
+`codex-dev-flow` binary alias is included in the new package. No package is published
+by the rename itself.
+
+## Initial GitHub Packages publication and historical backfill
+
+The canonical package is now the public, scoped `@acrasie/dev-flow` package on npmjs.
+GitHub Packages contains a scoped mirror because its npm registry accepts only scoped
+names. Mirror input always comes from the already-published npmjs tarball; the workflow
+validates source name, version, and repository, then changes only the package name.
+
+Because this repository is private, the first linked GitHub package initially inherits
+private visibility. To create the approved public mirror without racing the complete
+backfill:
+
+1. Merge the mirror workflow to the default branch.
+2. Obtain separate authorization for package publication, then publish only the oldest
+   version:
+
+   ```bash
+   gh workflow run publish-github-package.yml -f versions=0.1.0
+   ```
+
+3. Wait for success. Open the new `@acrazie/dev-flow` package settings and change
+   visibility to **Public**. This UI operation is deliberately manual.
+4. Obtain confirmation immediately before the visibility change: making a GitHub
+   package public cannot be reversed.
+5. Backfill every stable npmjs version:
+
+   ```bash
+   gh workflow run publish-github-package.yml -f versions=all
+   ```
+
+The `all` selector discovers stable npmjs versions, skips exact versions already present
+in GitHub Packages, and publishes missing versions oldest first. A precise stable
+version, `v<version>`, or `npm-v<version>` may also be dispatched for targeted recovery.
+Publishing the public package exposes only content already present in the public npmjs
+tarball; it does not make the private source repository readable.
+
+## Cancellation and failure recovery
+
+### Complete npm publication for an existing Release Please release
+
+When Release Please has already merged a release PR and published its GitHub release,
+but the corresponding npm version is missing, use:
+
+```bash
+bun run release --publish-existing dev-flow-v1.0.1
+```
+
+This mode verifies the published stable GitHub release, the local and remote tag commit,
+and ancestry on `origin/main`. It exports that exact commit into a temporary directory,
+requires its pinned Bun version, installs frozen workspace dependencies, runs release
+validations and the full quality gate, and previews npm publication before confirmation.
+The invoking checkout is not published, so it may contain the recovery-tool correction
+on a dedicated branch. No version, plugin manifest, tag, or GitHub release is changed.
+An already-published npm version is skipped. Only the missing npm publication is performed.
+
+The existing GitHub release event is not emitted again. If a GitHub Packages mirror is
+required, dispatch the repository mirror workflow for the exact npm version after npm
+publication is verified; do not create another release.
+
+### Before first successful push
+
+Cancellation, `Ctrl+C`, or validation failure restores original release files and
+removes only commit or tag objects created by program. Inspect:
+
+```bash
+git status --short
+git log -1 --oneline
+```
+
+Fix cause, ensure clean `main`, then restart with `bun run release`.
+
+### After push, npm publication, or GitHub publication begins
+
+Do not delete remote tag, rewrite `main`, unpublish package, or create replacement
+release manually. Published systems are not one atomic transaction and program never
+attempts remote rollback.
+
+Keep checkout on clean release commit and rerun:
+
+```bash
+bun run release
+```
+
+Program recognizes release commit, reconciles Git, npm, and GitHub state, displays
+missing steps, then asks whether to resume. Already completed publication steps are
+skipped. This also handles case where npm accepted package but local command lost its
+response.
+
+If all remote publication steps succeeded and only optional local plugin refresh
+failed, do **not** rerun release solely for that refresh. Run it directly:
+
+```bash
+codex plugin marketplace upgrade acrazie
+codex plugin add dev-flow@acrazie
+```
+
+Then start a new Codex thread.
+
+If the asynchronous GitHub Packages mirror fails, do not create another npm or GitHub
+Release. Rerun the failed Actions job or dispatch its exact stable version. Existing
+destination versions are verified and skipped, so recovery is idempotent. Authentication,
+network, malformed metadata, and unexpected registry responses block instead of being
+treated as a missing version.
+
+### Bad release discovered after completion
+
+Prefer forward correction: fix defect and publish a new patch or plugin-cachebuster
+release. Published npm versions are immutable release identities and must never be
+reused.
+
+## Forbidden shortcuts
+
+- No validation bypass or force-publish path.
+- No manual version edits followed by direct publish.
+- No direct `npm publish` or `bun publish` of the canonical npmjs package outside the
+  release program. The repository-owned GitHub Packages mirror workflow is the only
+  scoped-alias exception.
+- No manual tag or GitHub Release for a new release.
+- No automatic or manual merge/rebase/reset inside release procedure.
+- Never commit npm tokens, GitHub tokens, OTP values, or generated credential files.