Add iso-timeline package

Author: AceGreenman

.github/workflows/ci.yml

@@ -68,6 +68,9 @@ jobs:
           - workspace: "@razroo/iso-canon"
             node: "20.6.0"
             extra: ""
+          - workspace: "@razroo/iso-timeline"
+            node: "20.6.0"
+            extra: ""
           - workspace: "@razroo/iso-preflight"
             node: "20.6.0"
             extra: ""
@@ -223,6 +226,13 @@ jobs:
           node packages/iso-canon/dist/cli.js key company-role --company "Anthropic, PBC" --role "Senior SWE, AI Platform - Remote US" --config packages/iso-canon/examples/jobforge-canon.json --profile jobforge
           node packages/iso-canon/dist/cli.js compare company "OpenAI, Inc." "Open AI" --config packages/iso-canon/examples/jobforge-canon.json --profile jobforge
 
+      - name: iso-timeline example plan/check
+        run: |
+          node packages/iso-timeline/dist/cli.js plan --config packages/iso-timeline/examples/jobforge-timeline.json --events packages/iso-timeline/examples/jobforge-events.jsonl --now 2026-04-27T00:00:00.000Z --out /tmp/jobforge.iso-timeline.json
+          node packages/iso-timeline/dist/cli.js due --config packages/iso-timeline/examples/jobforge-timeline.json --events packages/iso-timeline/examples/jobforge-events.jsonl --now 2026-04-27T00:00:00.000Z
+          node packages/iso-timeline/dist/cli.js verify --timeline /tmp/jobforge.iso-timeline.json
+          node packages/iso-timeline/dist/cli.js check --config packages/iso-timeline/examples/jobforge-timeline.json --events packages/iso-timeline/examples/jobforge-events.jsonl --now 2026-04-27T00:00:00.000Z --fail-on none
+
       - name: iso-preflight example plan/check
         run: |
           node packages/iso-preflight/dist/cli.js plan --config packages/iso-preflight/examples/jobforge-preflight.json --candidates packages/iso-preflight/examples/jobforge-candidates.json

.github/workflows/iso-timeline-release.yml

@@ -0,0 +1,48 @@
+name: iso-timeline Release to npm
+
+on:
+  release:
+    types: [published]
+
+defaults:
+  run:
+    working-directory: packages/iso-timeline
+
+jobs:
+  publish:
+    if: startsWith(github.ref_name, 'iso-timeline-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Set version from release tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#iso-timeline-v}"
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+
+      - name: Verify required CI passed for release commit
+        uses: ./.github/actions/verify-release-gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify package.json version matches release tag
+        run: npm run release:check-source -- "$VERSION"
+
+      - name: Install (workspace root)
+        run: npm ci
+        working-directory: .
+
+      - name: Publish to npm (with provenance)
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-This repo ships twenty-two packages that **work on their own** but are **designed
+This repo ships twenty-three packages that **work on their own** but are **designed
 to compose**. The planned cross-package compositions listed here are already
 shipped, so this file now serves as:
 
@@ -269,6 +269,19 @@ or threshold checks.
 
 ---
 
+## 19. `iso-timeline` ← deterministic time-based next-action policy for domain packages — **DONE**
+
+Introduced as a standalone package. `iso-timeline` does not import JobForge,
+`iso-ledger`, `iso-facts`, `iso-index`, or any other domain package; it
+provides the on-disk JSON timeline policy and dated event formats that domain
+tools can share. JobForge-style examples cover application follow-ups,
+interview thank-yous, and stale pipeline items, but the package remains
+generic: compute upcoming, due, overdue, suppressed, and blocked actions from
+dated events without asking a model to reason over date math or growing
+tracker files.
+
+---
+
 ## Design questions that are *not* open integrations
 
 The following look like integrations but are deliberately decoupled —
@@ -331,6 +344,11 @@ don't "fix" them without a conversation first.
   rubric dimensions, evidence policy, score freshness, source precedence, and
   whether a gate routes to preflight, ledger recording, human review, or
   another workflow step.
+- **`iso-timeline` does not decide what a domain should follow up on.** It
+  evaluates configured dated-event policy. Domain packages still own event
+  extraction, source precedence, business calendars, stale-action retention,
+  and whether due actions route to prompts, ledgers, notifications, or
+  workflow dispatch.
 - **`iso-postflight` does not decide how a domain collects observations.**
   It settles explicit plan/outcome/artifact/step records. Domain packages
   still own whether those observations come from TSV files, ledger events,

README.md

@@ -30,11 +30,11 @@ Today, agent workflow reliability is fragmented on three axes:
    unstructured rationale all drop silently at 7B. You don't find out
    until the agent misbehaves in production.
 3. **Runtime fragmentation.** Workflows rely on fragile prompt prose for
-  fan-out limits, context loading, artifact reuse, fact extraction, identity keys, rubric scoring, project upgrades, role permissions, output shape, duplicate checks, post-dispatch settlement, redaction, and
+  fan-out limits, context loading, artifact reuse, fact extraction, identity keys, rubric scoring, time-based next actions, project upgrades, role permissions, output shape, duplicate checks, post-dispatch settlement, redaction, and
   "what already happened." Those invariants belong in deterministic local packages,
   not in repeatedly re-tokenized instructions.
 
-Twenty-two packages solve that in one pipeline with runtime control and a
+Twenty-three packages solve that in one pipeline with runtime control and a
 feedback loop:
 
 - **Four build-time tools** turn your authored source into every harness's file layout:
@@ -44,7 +44,7 @@ feedback loop:
   [`@razroo/iso-route`](./packages/iso-route) compiles *one model policy* into each harness's config.
 - **One wrapper** runs the whole build chain:
   [`@razroo/iso`](./packages/iso) chains the above into a single `iso build`.
-- **Fourteen runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, fact materialization, identity canonicalization, deterministic scoring, preflight dispatch planning, postflight settlement, redaction, project migration, role capabilities, artifact shape, and operational truth:
+- **Fifteen runtime-control libraries** handle durable execution, context selection, artifact caching, artifact lookup, fact materialization, identity canonicalization, deterministic scoring, time-based next-action planning, preflight dispatch planning, postflight settlement, redaction, project migration, role capabilities, artifact shape, and operational truth:
   [`@razroo/iso-orchestrator`](./packages/iso-orchestrator) provides resumable
   steps, keyed mutexes, and bounded fan-out for side-effectful agent workflows,
   [`@razroo/iso-context`](./packages/iso-context) resolves context bundles,
@@ -59,6 +59,9 @@ feedback loop:
   company, role, and company-role keys for duplicate checks,
   [`@razroo/iso-score`](./packages/iso-score) computes weighted rubric
   scores, bands, comparisons, and gate decisions from structured evidence,
+  [`@razroo/iso-timeline`](./packages/iso-timeline) computes due,
+  overdue, suppressed, and blocked next actions from dated events and
+  cadence policy,
   [`@razroo/iso-preflight`](./packages/iso-preflight) validates
   source-backed candidate facts, applies gates, and produces bounded
   dispatch rounds before tool-heavy work starts,
@@ -95,6 +98,7 @@ feedback loop:
                                                                                                      │                      │    iso-facts ─▶ fact materialization
                                                                                                      │                      │    iso-canon ─▶ identity keys
                                                                                                      │                      │    iso-score ─▶ rubric gates
+                                                                                                     │                      │    iso-timeline ─▶ due next actions
                                                                                                      │                      │    iso-preflight ─▶ dispatch plan
                                                                                                      │                      │    iso-postflight ─▶ settlement gate
                                                                                                      │                      │    iso-redact ─▶ safe exports
@@ -158,6 +162,9 @@ the repo now supports a tighter loop:
   instead of repeatedly restating URL, company, and role matching rules.
 - `iso-score compute/check/gate` keeps weighted rubric scoring local
   instead of asking a model to redo arithmetic, bands, and threshold checks.
+- `iso-timeline plan/due/check` keeps follow-up, stale-item, retry, and
+  other dated next-action policy local instead of asking a model to reason
+  over dates from growing tracker files.
 - `iso-preflight plan/check` keeps dispatch eligibility and batching local
   instead of relying on prompt prose for source-backed facts and fan-out rules.
 - `iso-postflight status/check` keeps dispatch settlement local instead of
@@ -206,6 +213,9 @@ of the prompt:
 - `iso-score` makes rubric scoring executable: structured dimension scores
   compile into weighted totals, bands, comparisons, and gate decisions with
   deterministic ids and local verification.
+- `iso-timeline` makes time-based next-action policy executable: dated
+  events compile into upcoming, due, overdue, suppressed, and blocked
+  actions with deterministic ids and local verification.
 - `iso-preflight` makes dispatch planning executable: validate required
   file-backed facts, apply skip/block gates, avoid same-key overlap inside
   rounds, and emit pre/post steps before tool-heavy work starts.
@@ -341,6 +351,12 @@ of the prompt:
   content-derived result ids from structured dimension inputs so domain
   packages can keep arithmetic and threshold checks out of prompt prose.
 
+- **[`packages/iso-timeline`](./packages/iso-timeline)** — [`@razroo/iso-timeline`](https://www.npmjs.com/package/@razroo/iso-timeline)
+  Deterministic time-based next-action planning for agent workflows.
+  Computes upcoming, due, overdue, suppressed, and blocked actions from
+  dated events plus local cadence policy so domain packages can keep
+  follow-up, retry, and stale-item date math out of prompt prose.
+
 - **[`packages/iso-preflight`](./packages/iso-preflight)** — [`@razroo/iso-preflight`](https://www.npmjs.com/package/@razroo/iso-preflight)
   Deterministic preflight planning for agent workflows. Validates
   source-backed candidate facts, applies precomputed skip/block gates,
@@ -564,6 +580,16 @@ iso-score compare --config score.json --left evaluation.json --right evaluation-
 iso-score explain --config score.json
 ```
 
+### `@razroo/iso-timeline` — what is due now?
+
+```bash
+iso-timeline plan --config timeline.json --events events.jsonl --now 2026-04-27T00:00:00Z
+iso-timeline due --config timeline.json --events events.jsonl --now 2026-04-27T00:00:00Z
+iso-timeline check --config timeline.json --events events.jsonl --fail-on overdue
+iso-timeline verify --timeline timeline-result.json
+iso-timeline explain --config timeline.json
+```
+
 ### `@razroo/iso-preflight` — is this workflow safe to dispatch?
 
 ```bash
@@ -640,6 +666,7 @@ iso/
     ├── iso-facts/        # deterministic source-backed fact materialization
     ├── iso-canon/        # deterministic identity canonicalization
     ├── iso-score/        # deterministic weighted rubric scoring
+    ├── iso-timeline/     # deterministic time-based next-action planning
     ├── iso-preflight/    # deterministic preflight dispatch planning
     ├── iso-postflight/   # deterministic postflight settlement
     ├── iso-redact/       # deterministic sensitive-data redaction
@@ -668,6 +695,7 @@ npm --workspace @razroo/iso-index run test      # iso-index artifact lookup test
 npm --workspace @razroo/iso-facts run test      # iso-facts materialization tests
 npm --workspace @razroo/iso-canon run test      # iso-canon identity key tests
 npm --workspace @razroo/iso-score run test      # iso-score rubric scoring tests
+npm --workspace @razroo/iso-timeline run test   # iso-timeline next-action tests
 npm --workspace @razroo/iso-preflight run test  # iso-preflight dispatch planning tests
 npm --workspace @razroo/iso-postflight run test # iso-postflight settlement tests
 npm --workspace @razroo/iso-redact run test     # iso-redact policy/redaction tests
@@ -709,7 +737,7 @@ build, and `npm publish --provenance`.
 ## End-to-end example
 
 [`examples/pipeline/`](./examples/pipeline) is an executable demonstration
-that exercises **seven of the twenty-two packages end-to-end** in one `npm run
+that exercises **seven of the twenty-three packages end-to-end** in one `npm run
 test:pipeline` invocation: `agentmd lint` + `render` → `isolint lint` →
 `iso-route build` (from a bundled `models.yaml` that extends the
 `standard` preset) → `iso-harness build` (which consumes iso-route's
@@ -728,7 +756,7 @@ downstream repo would use.
 
 `npm run test:pack` goes one level further: it packs the local workspaces into
 tarballs, installs them into fresh temp projects, and smoke-tests the packaged
-`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `iso-facts`, `iso-canon`, `iso-score`, `iso-preflight`, `iso-postflight`, `iso-redact`, `iso-migrate`, `iso-contract`, and `iso-capabilities`
+`iso-harness`, `iso`, `iso-eval`, `iso-trace`, `iso-route`, `iso-guard`, `iso-ledger`, `iso-context`, `iso-cache`, `iso-index`, `iso-facts`, `iso-canon`, `iso-score`, `iso-timeline`, `iso-preflight`, `iso-postflight`, `iso-redact`, `iso-migrate`, `iso-contract`, and `iso-capabilities`
 CLIs. This guards against packaging regressions that workspace-only tests can
 miss.
 

package-lock.json

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razroo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/iso-timeline/LICENSE

@@ -0,0 +1,87 @@
+# @razroo/iso-timeline
+
+Deterministic time-based next-action planning for agent workflows.
+
+`iso-timeline` turns dated domain events plus a local JSON policy into a
+compact action queue: upcoming, due, overdue, suppressed, and blocked items.
+It is MCP-free and model-free, so a domain package can answer "what needs
+attention now?" without asking an agent to reread growing trackers or reason
+manually over dates.
+
+## Install
+
+```bash
+npm install @razroo/iso-timeline
+```
+
+## CLI
+
+```bash
+iso-timeline plan --config timeline.json --events events.jsonl --now 2026-04-27T00:00:00Z
+iso-timeline due --config timeline.json --events events.jsonl --now 2026-04-27T00:00:00Z
+iso-timeline check --config timeline.json --events events.jsonl --fail-on overdue
+iso-timeline verify --timeline timeline-result.json
+iso-timeline explain --config timeline.json
+```
+
+Events may be a JSON array, an object with an `events` array, or JSONL with
+one event per line.
+
+## Policy Shape
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "overdueAfter": "7d",
+    "latestOnly": true
+  },
+  "rules": [
+    {
+      "id": "applied-follow-up",
+      "action": "send_follow_up",
+      "match": {
+        "type": "application.status",
+        "where": { "data.status": "Applied" }
+      },
+      "after": "7d",
+      "suppressWhen": [
+        { "type": ["application.follow_up", "application.rejected"] }
+      ]
+    }
+  ]
+}
+```
+
+Each rule selects matching events, computes `dueAt = event.at + after`, marks
+items overdue after `overdueAfter`, and suppresses or blocks actions when later
+same-key events match `suppressWhen` or `blockWhen`.
+
+## Library
+
+```ts
+import {
+  checkTimeline,
+  loadTimelineConfig,
+  loadTimelineEvents,
+  planTimeline,
+} from "@razroo/iso-timeline";
+
+const config = loadTimelineConfig(policyJson);
+const events = loadTimelineEvents(eventJson);
+
+const plan = planTimeline(config, events, {
+  now: "2026-04-27T00:00:00.000Z",
+});
+
+const check = checkTimeline(config, events, {
+  now: "2026-04-27T00:00:00.000Z",
+  failOn: "overdue",
+});
+```
+
+## Design Boundary
+
+`iso-timeline` does not decide what a domain considers important. The domain
+owns the event types, source precedence, and cadence rules. This package only
+provides the deterministic local planner that evaluates those rules.