# PROVENANCE

`pi-dynamic-workflows-oc-style` is an independently maintained [Pi](https://pi.dev)
extension that was **originally derived from** `@quintinshaw/pi-dynamic-workflows`
(MIT) and has since been substantially extended. This file records the origin,
the relationship to the two engine lineage branches, the peer-engine watchlist,
and the recurring ecosystem-review cadence. The projects have **diverged**:
both lineage branches are treated as **read-only idea sources**, not merge
sources. See [docs/workflow-engine-review.md](./docs/workflow-engine-review.md)
for the full review process, the seven-commit disposition table, and the
verified refs/dates.

## Origin

- **Originally derived from:** https://github.com/QuintinShaw/pi-dynamic-workflows
  ([`@quintinshaw/pi-dynamic-workflows`](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows), MIT)
- **Derivation point:** v2.6.0 (`622f6df`); aligned to upstream v2.7.0 (`b11fdbd`, a version-string-only release with no code changes vs 2.6.0)
- **Original author:** Michael Livs (`pi-dynamic-workflows`); upstream maintainer: QuintinShaw
- **License:** MIT, retained (see [LICENSE](./LICENSE))

## Two engine lineage branches (read-only concept sources)

This project did **not** derive directly from the original engine's current tip,
and neither branch is an *upstream* of this fork — there is no merge/cherry-pick
path. Both are **read-only idea sources**; every candidate concept is adapted
through a bounded GitHub issue against this fork's harness broker/catalog
contract.

### 1. Original engine — `Michaelliv/pi-dynamic-workflows`

The original `pi-dynamic-workflows` by Michael Livs. It ended at two releases and
carries seven commits not contained in the maintained fork at the reviewed ref.

- **Repo:** https://github.com/Michaelliv/pi-dynamic-workflows (MIT) ·
  **npm:** [`pi-dynamic-workflows`](https://www.npmjs.com/package/pi-dynamic-workflows)
- **Reviewed ref:** `v1.0.1`, release commit `31b2aca` (2026-05-31); the `v1.0.1`
  tag object points at `dbc6800`. npm `1.0.1` (2026-05-31). **No newer release as
  of the 2026-08-13 review.**

### 2. Maintained derivation — `QuintinShaw/pi-dynamic-workflows`

The actively maintained fork this project originally derived from. It has
diverged far upstream into a general-purpose workflow engine.

- **Repo:** https://github.com/QuintinShaw/pi-dynamic-workflows (MIT) ·
  **npm:** [`@quintinshaw/pi-dynamic-workflows`](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows)
- **Reviewed ref:** `v3.5.1`, HEAD commit `bab5ad7` (2026-08-05); npm `3.5.1`
  (2026-08-05). **No newer release as of the 2026-08-13 review.**
  (The issue body recorded the date as 2026-08-06; the GitHub API author date is
  2026-08-05 — we record the API-verified date.)

### The seven Michael-original-only commits — disposition

The original branch contains seven commits not contained in `QuintinShaw`
`v3.5.1` (five mechanism commits + the `@earendil-works` namespace rename + the
`v1.0.1` release tag). Dispositioned against current local/QuintinShaw behavior:

| # | Commit | Mechanism | Disposition |
|---|--------|-----------|------------|
| 1 | `4189d2b` (#15) | Forward `modelRegistry`/`model` to workflow subagents | **Already present** (local `WorkflowAgent.sharedRegistry`, `src/agent.ts:932–991`) |
| 2 | `c914116` (#19) | Dynamic workflow phases | **Already present** (local `phase()` global + `meta.phases`, `src/workflow.ts`) |
| 3 | `1c61834` (#21) | Guard results against Promise-clone failures + forgot-to-await error | **Queue** — no explicit non-cloneable-result/forgot-to-await guard on the script return value today |
| 4 | `21bfc79` (#22) | Ambient authoring `.d.ts` for workflow-script globals (IntelliSense) | **Queue** — local ships runtime `dist/index.d.ts` only; no authoring ambient types |
| 5 | `7b34dec` (#23) | AST-aware determinism check (allow mentions, reject execution) | **Queue (minor)** — local runtime `DETERMINISM_PRELUDE` is more advanced; the parse-time `DETERMINISM_BLOCKLIST` regex hint still over-rejects string mentions |
| 6 | `dc6ad26` | Update Pi package namespace to `@earendil-works` | **Not applicable** (this fork is `pi-dynamic-workflows-oc-style`) |
| 7 | `31b2aca` | Release `v1.0.1` | **Not applicable** (release tag, not a mechanism) |

**Summary:** 2 already present, 3 queued as bounded issues, 2 not applicable.
None is rejected on its merits; the three queued items are genuine gaps with
bounded-issue scope. Full evidence and PR-body references:
[docs/workflow-engine-review.md](./docs/workflow-engine-review.md#the-seven-michael-original-only-commits--disposition).

### Maintained-fork review ledger (v3.5.1 → bounded issues)

The v3.5.1 concept audit produced four bounded issues (the prior stale stamp
recorded only the v2.10.0 review):

- **Adopted/proven independently:** current-Pi `ModelRuntime`/session
  compatibility pattern and atomic persistence backup — named accurately in the
  CHANGELOG, not re-credited to upstream.
- **Queued as bounded issues:**
  - [#133](https://github.com/gtnotacoder/pi-dynamic-workflows/issues/133) —
    bounded persisted run-state size + retention (closed).
  - [#134](https://github.com/gtnotacoder/pi-dynamic-workflows/issues/134) —
    fatal sibling cancellation, explicit-model errors, checkpoint resume
    identity (open).
  - [#135](https://github.com/gtnotacoder/pi-dynamic-workflows/issues/135) —
    resource-loader retention + extension-reload handoff (closed).
  - [#136](https://github.com/gtnotacoder/pi-dynamic-workflows/issues/136) —
    explicit workflow control + bounded usage-limit auto-resume (closed).
- **Rejected/deferred:** wholesale merges and upstream architecture that
  conflicts with this fork's harness broker/catalog contract.

## Peer-engine watchlist

A deliberately narrow set of peer Pi workflow engines, each watched for one
**distinct, source-verifiable mechanism** (or materially higher adoption). The
Pi catalog contains many more "workflow"/"multi-agent" packages; this list does
not fan out across all of them. Adding a package requires a source-backed reason.

| Package | Distinct mechanism watched for |
|---|---|
| [`pi-subagents`](https://github.com/nicobailon/pi-subagents) | delegated-agent artifacts/session sharing + mature async runtime |
| [`pi-taskflow`](https://github.com/heggria/taskflow) | statically verified/resumable task DAGs and gates |
| [`@zhushanwen/pi-subagent-workflow`](https://www.npmjs.com/package/@zhushanwen/pi-subagent-workflow) | persistent workflow state machine + execution tracing |
| [`pi-extensible-workflows`](https://github.com/vekexasia/pi-extensible-workflows) | deterministic extensibility + optional Herdr integration (`@piewf/herdr`) |
| [`pi-crew`](https://github.com/baphuongna/pi-crew) | teams, worktrees, schedules, handoffs, TUI observability |
| [`@onlinechefgroep/pi-agent-orchestrator`](https://github.com/OnlineChefGroep/pi-agent-orchestrator) | swarms, schedules, structured handoffs, prompt compression, live terminal observability |
| [`@mjasnikovs/pi-task`](https://github.com/mjasnikovs/pi-task) | local-model-first planning with verify/enforce gates |

Verified versions, publish dates, weekly downloads, and the distinct-mechanism
descriptions for each (as of the 2026-08-13 review):
[docs/workflow-engine-review.md](./docs/workflow-engine-review.md#peer-engine-watchlist).

## Secondary inspiration source — `mattpocock/skills`

Per #132, [Matt Pocock's skills repository](https://github.com/mattpocock/skills)
is a documented **secondary, read-only** inspiration source for workflow/skill
design. It is **not** an upstream and implies no derivation or ownership.
Existing acknowledgements in the `0.2.1`/`0.2.2` changelog and `CONTEXT.md`
remain part of the provenance record.

**Bounded update-review cadence** (defined in
[docs/workflow-engine-review.md](./docs/workflow-engine-review.md)):

- **Inspect at a pinned stable tag/commit** — never an in-progress branch.
  Reviewed 2026-08-13: pinned stable tag `v1.2.3`, release commit `6acc160`
  (2026-08-06); `main` HEAD at review time was `8b78b53` (2026-08-13), recorded
  only for freshness, not for adoption.
- **Read** the source repo's stable skills, changelog, and relevant ADRs at
  that pinned ref.
- **Record** the reviewed ref and review date here and in the engine-review
  doc.
- **Classify** every candidate idea as **adopted** (release-specific credit),
  **queued** (bounded GitHub issue), **rejected**, or **not applicable**.
  Adopted ideas are **adapted** to this architecture, not vendored.
- **Create bounded GitHub issues** before implementing any adopted concept; skip
  `in-progress`/`deprecated` material unless explicitly relevant.
- **Release-specific attribution** is required when an idea is adopted: name
  and link the source, say "adapted", and record the credit in the CHANGELOG or
  release notes — never only in an ephemeral issue comment.

The latest reviewed ref/date is recorded above and in
[docs/workflow-engine-review.md](./docs/workflow-engine-review.md#secondary-inspiration-source--mattpocockskills);
re-verify at the next review, not at adoption time.

## Ecosystem-review cadence

- **Run approximately quarterly**, and additionally **before any broad
  workflow-engine release** of this fork.
- **Pin and record** package/repository version, commit, and review date for
  each candidate.
- **Read source/tests/docs** for candidate mechanics; search snippets and
  package descriptions are **discovery only**.
- **Classify** each candidate as **already present / adopt / queue / reject /
  not applicable**.
- **Adapt via bounded GitHub issues; never merge or cherry-pick wholesale** into
  this diverged fork.
- **Evaluate** security/authority, deterministic resume, context cost,
  worktree/finalization behavior, and harness broker/catalog compatibility
  before adoption.
- **Preserve original licensing/attribution** and give release-specific credit
  for adopted ideas (name/link the source; say *adapted*, not *vendored*). No
  adopted idea may be credited only in an ephemeral issue comment.
- **Strict scope boundary:** the review is a *watch*, not a pipeline. It cannot
  install packages, mutate source/tests/`package.json`, open/merge a PR, or
  change the catalog/workflow-lock. Every adoption flows through a separate
  bounded issue with its own delivery lane.

Full process + the 2026-08-13 verification record:
[docs/workflow-engine-review.md](./docs/workflow-engine-review.md).

## Relationship to upstream

The projects have diverged; a git merge or cherry-pick from either lineage
branch is neither possible nor desirable. Both branches remain general-purpose
workflow engines, while this project has been rebuilt around a different
architecture — a harness-agnostic broker (`harness_type`/`harness_config`),
issue-delivery workflows, run-level worktree isolation, and a catalog/lock-gated
command surface (see the [CHANGELOG](./CHANGELOG.md) and [docs/](./docs/) for
current architecture). Both are kept only as **read-only idea sources**:

```bash
# one-time
git remote add original https://github.com/Michaelliv/pi-dynamic-workflows.git
git remote add upstream https://github.com/QuintinShaw/pi-dynamic-workflows.git

# periodically (~quarterly): read the log, port CONCEPTS as issues — never diffs
git fetch original && git log --oneline main..original/main
git fetch upstream  && git log --oneline main..upstream/main
```

- **Last reviewed:** 2026-08-13. Original at `v1.0.1` (`31b2aca`); upstream at
  `v3.5.1` (`bab5ad7`). Seven original-only commits dispositioned (2 already
  present, 3 queued, 2 N/A); peer-engine watchlist refreshed. Outcomes recorded
  above and in [docs/workflow-engine-review.md](./docs/workflow-engine-review.md).

## Install

Point Pi's agent settings at this checkout, build, and restart Pi:

```jsonc
// ~/.pi/agent/settings.json
{ "packages": [ "/path/to/this/repo" ] }
```

```bash
cd /path/to/this/repo
npm install && npm run build   # tsc -> dist/
# then restart pi
```

## Status

The full `npm test` gate (biome + build + unit) is green; see the
[README](./README.md#status--acknowledgements) for the current test count.