fulcra-tools
AGENTS.md10 starsChanged 2 months agoMITView on GitHub
Your entry point to this repo. Fulcra helps agents know their user, know what's happening in their user's world, work with their user's other agents, and become more helpful over time — the packages here are working examples of all four. This file covers the non-obvious environment and the conventions you can't infer from the source; the README.md tells the top-level story (what each package is, how to install the pieces) and this file does not repeat it. Keep the…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository20 other files it gives its agents.
- coordinator-disciplineSkill
- fulcra-agent-atcSkill
- fulcra-agent-automationSkill
- fulcra-agent-cloud-coordinatorSkill
- fulcra-agent-continuitySkill
- fulcra-agent-directivesSkill
- fulcra-agent-durable-stateSkill
- fulcra-agent-forgeSkill
- fulcra-agent-healthSkill
- fulcra-agent-operatorSkill
- fulcra-agent-presenceSkill
- fulcra-agent-reconcileSkill
- fulcra-agent-reviewSkill
- fulcra-agent-rolesSkill
- fulcra-agent-tasksSkill
- fulcra-content-reviewSkill
- fulcra-fdeSkill
- fulcra-lab-resultsSkill
- map-our-teamSkill
- sealed-secretsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
19 rules. About 0 are common, 6 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 60
README updates are required with every change: Every update to Fulcra Tools or anything in it must update the relevant READMEs in the same …
- Distinctive: line 68
This file is a ship-gate artifact: Every PR that changes agent-facing behavior — CLI verbs, skills, conventions, environment requirements, …
- Distinctive: line 145
Keep status, health, worker and explicit-access error classification consistent: pending/changed reads require a quiet recheck, not another …
- Very specific: line 170
Selected local-source uploads: use Collect's captured Fulcra token, never the CLI's independently stored account.
- Very specific: line 211
All packages, plugins, skills, examples, and release artifacts must be reusable without personal accounts or machine-specific values.
- Distinctive: line 286
Never put synthesized knowledge into two-way sync working files or infer a source grant from a map/manifest.
- Very specific: line 372
Reconcile interrupted notarization before submitting again: Verify the configured profile with notarytool history before a release build.
- Very specific: line 504
Do NOT use --all-extras here: it pulls the macos extra, whose PyObjC wheels build by shelling out to /usr/bin/sw_vers, which does not exist …
- Very specific: line 512
Run tests: uv run pytest packages/ -q (must NOT hit external services).
- Very specific: line 563
No team-particular identity in engine logic.
- Very specific: line 577
When the trusted feed fold still corroborates tasks omitted by a full-scan listing, reconcile fails closed and preserves the current …
- Distinctive: line 584
Do the reader sweep in the same change, and say in the PR which readers you checked — "I did not audit the others" is a finding, not a …
- Very specific: line 601
Every rep at -8d, -9d, -10d, -12d and -15d returned HTTP 500 with an empty body.
- Very specific: line 681
When a role's registered maintainer: is also one of its own lease holders, the alarm cannot reach a supervising identity.
- Very specific: line 918
Read health before anything else: UNKNOWN means the authority itself was untrusted and the rows must not be acted on.
- Very specific: line 968
Prefer if cmd; then …; else ….
- Distinctive: line 969
When reporting a BATCH, count the artifacts on the store rather than tallying exit codes you did not check.
- Very specific: line 985
Legacy Bus-v3 migration is authority/cursor-only: Run coord-engine bus-v3 migrate <team> --dry-run first, then --apply only after every …
- Very specific: line 1109
Slug dedup + delivery rc: Every directive slug carries a payload hash (<title-slug>-<sha256(payload)[:8]>), so identical resends dedupe by …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Fulcra Tools — agent guide
Your entry point to this repo. Fulcra helps agents know their user, know
what's happening in their user's world, work with their user's other agents,
and become more helpful over time — the packages here are working examples of
all four. This file covers the non-obvious environment and the conventions
you can't infer from the source; the README.md tells the
top-level story (what each package is, how to install the pieces) and this
file does not repeat it.
Keep the monorepo framing. These are unofficial, unsupported tools and skills vibe-coded by Fulcra's lawyer to work with Fulcra. Coordination and continuity work independently of Collect. Collect is an optional host for local/source connectors, not a prerequisite for using Fulcra. The root README indexes every package and bundled skill; retain the human introduction and verify release claims.
Coord v5 Codex automatic enrollment: reconcile one shared listener per environment/harness and its exact source/job-to-worker route. Follow the shared listener acceptance checklist. Interactive membership does not finish automatic setup. Keep a linked owned acceptance task or exact blocker until actual invocation, idle worker delivery and independent receiver evidence are verified; never silently substitute a per-worker heartbeat. Preserve monitoring and temporary fallback obligations until a verified replacement exists. This instruction grants no setup authority.
Record each new actionable user request as an owned bus task, or update the matching task. Keep its scope, status, prerequisites, next action, and completion evidence current. A continuity checkpoint is not a substitute for the task backlog.
Coord v5 managed listener enrollment checks current transport tool names/schemas
and existing account-to-principal/source binding. Stale tool identity is unavailable,
not proof of missing credentials or an empty bus. Preserve cursors, deduplication,
pending delivery intents and existing routes; authorized shared enrollment is additive
within the exact listener scope. A verified alternate transport does not prove hosted
connector recovery or scheduled receiver execution. See packages/coord-v5/README.md.
The packaged harness guide now gives centralized-listener recipes across desktop,
CLI, cloud, browser, Gateway and custom-host environments. Keep recommendations,
shipped adapters and verified native capabilities distinct; unavailable dispatch
falls back to durable addressed attention, not per-worker polling or guessed APIs.
Coord V5 has an opt-in parallel transport read-updates route. Use shadow mode
before gated deployment; update watermarks are not record cursors or complete-history
proof. Quiet hints never cancel retained delivery obligations. Preserve the direct
route, private journals and per-source scope; see the package README for audit/fallback limits.
Mesh request attention is distinct from transport cursors. The optional
coord-mesh queue --attention-db ABS durably retains addressed directive/query/message/request
requests before cursor advancement, including previously read rows in the returned
window. Receiver receipt does not dispose of work; a reply requires a committed
claim and exact independently verified response readback. Claimed/ambiguous replies
never retry automatically. This adds no grants, native listener or authority to
execute peer text. New mesh envelopes carry stable per-send mid identities;
attention entries expose reply_to for original IDs and source-qualified historical
mid-less records without changing source envelopes. Schema-v2 legacy ACK reconciliation
records receipt only when in_reply_to is absent; upgrading v1 reopens matching
ACK dispositions while preserving
the source evidence and uncertain claims. Read the coord-mesh README before upgrading
host consumers; stop old writers first, because the version fence applies on open.
README updates are required with every change. Every update to Fulcra Tools or anything in it must update the relevant READMEs in the same PR, including fixes, plugins, installers, commands, and workflows. If a package has no README, update its nearest owning README or add one. Update the root README when the change affects installation, available tools, or release status. Document current behavior and limits; label unfinished work. Reviewers must block a change whose README update is missing or stale. This is a standing repository rule.
This file is a ship-gate artifact. Every PR that changes agent-facing
behavior — CLI verbs, skills, conventions, environment requirements, review
rules — MUST update this file in the same PR. Reviewers: treat a stale
AGENTS.md as a blocking finding. If your change doesn't alter what an agent
needs to know, say so in the PR body ("AGENTS.md: no change needed").
No one-off fixes on coordination or continuity surfaces (operator law,
2026-08-14; earned by twelve strict-consumer incidents,
OUTPUT-CONTRACT.md). Root-cause every
incident and fix it upstream at the surface that produced it, not with a
defensive patch at the consumer. The models reading these surfaces are smart;
what they need from us is surfaces that are durable.
Apple Notes reconciliation/writeback: listing timestamps are not a content baseline. Reconciliation reads tracked vault bodies so edits near a sync are not missed; retain the complete internal change list and cap only report presentation. Partial AppleScript write failures must produce a failed report and failed run. Shared Collect Files text reads must validate a supplied exact-version size as a strict nonnegative integer and compare complete downloaded bytes before UTF-8 decoding, on both direct and signed-storage legs. A short 200/Content-Length prefix must not authorize Notes merge/write/checkpoint; absent metadata is not an independent size proof.
Selected-list task sync: Reminders uses EventKit, with separate read-only
permission checks and explicit permission requests. No lists are selected by
default. Import and source completion must re-check live selection, enabled
state, and preview mode before each write. Task status is open or resolved;
identity and generation fields bind a completion to the source task. Normalize task paths to absolute Fulcra paths at the Files adapter boundary
for both history lookup and upload; the API rejects relative upload paths. Read all
unseen Fulcra file versions so a concurrent bot edit survives an importer write.
Task read_version requires metadata from the latest complete history snapshot;
invalidate it before every listing attempt. Retain each exact version's supplied
strict nonnegative byte size and compare direct/signed HTTP200 body bytes before
decoding or task parse/render/checkpoint. Archive reads remain by ID; never borrow
the current path or another version's size. Size-less older metadata supplies no
independent length proof.
Missing source tasks are never completion evidence. Todoist task-detail lookup
can return checked: true after completion; accept it only with valid explicit
completion evidence. Keep active-list validation separate: a checked task there
still invalidates the snapshot. Recurring writeback is
unsupported until the provider can atomically protect the intended occurrence.
Capture RunContext.config_epoch with settings and pass it into the task engine;
check it in the live selection callback. Configuration and credential transitions
must invalidate pending journals even when no sync runs between the changes.
Save configuration under a cross-process lock and publish it atomically.
Merge each caller's edits against its immutable load/save baseline: enabled
membership, interval keys, and individual plugin-setting keys merge independently.
An unchanged stale value must never undo a disable or remove another caller's
setting. Divergent edits to the same field raise ConfigConflictError before
publication; reload and retry instead of force-saving the stale object.
For explicit user submissions use enable, disable, set_interval, and
update_plugin_settings(plugin_id, values): these preserve intent even when the
submitted value equals the loaded baseline. Direct mapping edits carry only
semantic differences and cannot represent an explicit unchanged-value request.
Interactive Fulcra sign-in/sign-out must persist an account_transition gate and
rotate all plugin epochs before changing the token, then rotate again before
clearing the gate on success. Task callbacks reject the gate as well as stale
epochs. Failure leaves the gate closed until an interactive retry succeeds; normal
configuration saves and automatic token refresh must never clear it.
Automatic Collect token renewal must publish only the closed shared keys
bearer-token and oauth-credentials through set_user_secret_quiet, never
ordinary set_user_secret/keyring.set_password. The disposable mutation child
suppresses legacy interaction and per-query UI, uses bounded private-pipe I/O,
and requires an exact acknowledgement. Keep final account/revision checks and
the consumed-grant no-replay journal; denial/timeout/ambiguous publication
requires reconnecting. Explicit interactive sign-in remains separate. Tests
must inject an isolated quiet backend or fence the native child, and must not
interpret a synthetic quiet-write pass as signed-app Keychain acceptance.
Native credential-helper timeouts are pending/UNKNOWN, not proof of a missing
grant. Keep the outer credential wait longer than the child I/O and cleanup
bounds. Do not signal a completed/reaped helper's old process group, and do not
let cleanup permission errors replace the original read/write failure.
Declare every field a source consumes in its availability/recovery inventory,
including Trakt's optional created_at and expires_in OAuth metadata. Optional
confirmed absence is different from denied or UNKNOWN access. Do not request
another unrelated grant when the source consumes an omitted field.
Keep status, health, worker and explicit-access error classification consistent:
pending/changed reads require a quiet recheck, not another approval. Configure's
recovery surface must include declared OAuth-managed fields outside input steps.
Strict Trakt scans pin one UTC end_at in the shared scan bounds, including
401 restart, while retaining exact pagination/count/ID validation. Do not accept
inconsistent provider totals or treat a fixed date range as a transactional
snapshot; backdated changes still fail closed before delivery/cursor progress. An
explicit Trakt start_at setting narrows the live scan and participates in the
captured settings/epoch/cursor scope. Keep earlier history as a separate owed
reconciliation; do not infer its completion from a ranged run or alter a pending
batch's original settings to make it fit the new range.
Trakt's development backend uses one versioned credential-bundle-v1 Keychain
item for the complete token tuple. Logical field authorization must target that
item, never start a per-field native approval batch. Ordinary snapshots are
read-only; explicit edits and owned refreshes publish one whole bundle with exact
readback. Keep legacy items, no-replay journals, epochs and provider identity pins.
Unknown legacy timing metadata stays explicitly unknown, not guessed from item
creation dates. Explicit PKCE reconnect may create fresh setup only after revoking
the predecessor source; unreadable or corrupt current bundles never fall back to
legacy secrets. Installed signed-upgrade acceptance is separate from source tests.
Public repository privacy
Selected local-source uploads: use Collect's captured Fulcra token, never
the CLI's independently stored account. Use RunContext.collect_token() for
selected-source uploads; its missing/expired token requires reconnecting in Collect.
fulcra_token() is a compatibility alias with the same Collect-only behavior;
see the canonical strict authentication contract.
Capture and compare the stored token as well as the epoch before uploading. Use the bounded
credentials.get_user_secret_fresh() read for capture and final upload guards;
the ordinary cached reader cannot detect another process changing the token. Do not re-canonicalize a selected
folder path on subsequent scans: substituted ancestor/root links must fail closed.
Partition content-hash state by the
authenticated destination account. Before each source read and upload, validate
the captured plugin epoch, source/collection selection, preview mode, enabled
state and account-transition gate. Hold the shared configuration/account lease
through the final consent check and upload. Use descriptor-anchored no-follow
regular-file reads and a private snapshot whose identity, size and hash match
the scan; consumers upload or render that snapshot instead of reopening the
source pathname. Preserve file/traversal byte limits and suppress private paths
and credentials from complete error tracebacks.
Local-source setup health checks capture the current persisted plugin epoch, allow checks before enablement, and validate saved selection/settings plus the account-transition gate before scanning and before each bounded content read. Recheck after the scan; revoked consent must return a failed health result with no preview. Do not use the setup context's empty worker epoch or bypass these guards for local-only previews.
Selected Notion pages: the notion-pages plugin reads only explicitly
selected page roots and ordinary nested blocks. Never add workspace search,
child-page/database traversal, synced-block following or attachment downloads
implicitly. Use omission markers for unsupported content. Keep credentials in
Keychain, preview on by default, content hashes scoped to the destination
account, and captured settings/epoch/credentials checked before reads and
under the shared configuration/account lease before uploads. Use the strict
Collect token and bounded fresh credential checks. Its source-tree registration
is not a claim that the released installer includes it; live provider and
signed-installer verification remain separate release prerequisites. Setup
health probes must capture the current persisted epoch and guard each read too;
allow probes before enablement but abort changed selection/credentials. Reject
missing known block fields and inconsistent pagination instead of saving a
partial page as an empty success.
All packages, plugins, skills, examples, and release artifacts must be reusable
without personal accounts or machine-specific values. Follow
docs/PRIVACY.md before publishing. Run the tracked-tree
privacy guard and credential scan; also review fixture provenance, public
messages, and generated artifacts. Account-specific UUIDs and device names
remain private even in retired-channel fixtures. Adoption claims must use the
authority-checked bus sender; a failed send must not fall back to a hard-coded
channel or write its success marker. Passing a pattern scan is not proof that
all personal information has been removed.
Credential scans use .gitleaks.toml with the default rules and
version pinned in privacy CI. Exemptions require
an exact public identifier AND an enumerated source path; never ignore a whole
path, rule, fingerprint or line. Configured controls must still detect neighboring
synthetic keys, wrong-path and prefix/suffix candidates, and other-rule fixtures;
malformed configuration must fail rather than report a clean scan.
Answers bridge configuration: account IDs and project URLs stay private,
just like credentials. Ship only synthetic examples; the privacy guard rejects
the private account config and credential filenames even inside archives. Select the config with
ANSWERS_LINEAR_CONFIG or --config, require COORD_TEAM, and load credentials
only from LINEAR_API_KEY or an explicit ANSWERS_LINEAR_ENV. Help and local
setup checks must not contact services. Preserve the existing sender, workstream,
and promotion source when migrating an operator's private configuration so a
pending promotion retry keeps its task identity.
Where to start
Zero state — never installed coord-engine, or joining from a fresh / remote /
sandboxed host? Start at
docs/coord/GET-ON-THE-BUS.md — install → auth →
(remote egress) → team bootstrap from zero → join. The probe grid below assumes the
engine is installed and a <team> exists; if coord-engine is command not found
or you have no team yet, the grid can't help you — the quickstart is the entry.
Already on the bus? Run the probes top to bottom, then jump to the layer you're touching. First failing probe is where your setup gap is.
| Probe / question | Command | Passes when | Where to go |
| Engine + auth usable? | coord-engine doctor <team> | exits 0 — tooling present, store reachable | never installed / command not found / no team yet → docs/coord/GET-ON-THE-BUS.md (install → auth → bootstrap → join). Otherwise fix the reported gap (auth: fulcra auth login; missing/old coord-engine: reinstall) |
| On the bus? | coord-engine queue <team> --agent <you> (bus v3; raw get-records if the engine predates v1.7.0), then coord-engine briefing <team> --agent <you> for the durable board | queue read completes — and if it stages a queue-delivery token (cursor schema v2), the probe passes only after every record is classified and queue commit succeeds; briefing prints your identity, role inboxes, reviews owed | Coordinate on the bus — events are the wake surface, the fold is the full picture |
| Two identities joined end to end? | coord-engine acceptance pair <team> --agent <A> --peer <B> | every timed hop prints HOP N PASS and the command ends PASS pair A<->B; any bad nonce, missing checkpoint, stale resume, degraded queue, or failed write exits at FAILED AT HOP N with raw evidence | GET-ON-THE-BUS.md |
| Own worktree? | git worktree list | your cwd is a dedicated worktree, not a shared checkout (no conflict markers or foreign staged files) | Working tree — carve your own before committing |
| Touching Collect / the daemon? | — | — | The daemon (Collect) |
| Touching coord conventions? | — | — | Coordinate on the bus |
| Touching the platform surface? | — | — | Fulcra platform surface & records |
| Touching CI / hooks? | — | — | CI and workspace membership |
Layout
uv-workspace monorepo, macOS-first. Packages under packages/, agent skills
under skills/, each package with its own README, build, and tests.
- Map Our Team —
skills/map-our-teamprovides a shared index of a team's knowledge sources, owners and connection instructions. Its skill covers the steward's map and each teammate's onboarding, checks and offboarding. It uses Fulcra Files and the external connect-our-agents skill; content and access controls stay at their sources. Read its README for installation and validation limits before using it with a real team. Create honors an existing build/save request without another approval, checks inherited map audiences even in an empty account, and separates storage-owner, human operator and verified agent-contact IDs. Lifecycle retries preserve unchanged files/timestamps, and Add verifies the grant before roster publication plus exact map readback. Honor a named writer across chats for the same operator. Gap recovery researches current evidence and useful roles before asking for consequential missing decisions; documenting a role is not appointing an owner. Optional producer manifests advertise connector-owned sources under/knowledge-sources/v1/; the skill works without them. Its maintenance recipe supplies the shared recurring run prompt; template guides link it instead of duplicating the protocol. It installs no scheduler or implicit write authority. Preserve the steward's map writer and producer's source/index writers. Never put synthesized knowledge into two-way sync working files or infer a source grant from a map/manifest. Check reader access and source freshness separately from producer publication; unknown provider namespaces stay unknown. Company-owned installations follow company-deployment.md: company map/connector storage stays separate from member-owned proposal streams and producer instances. Review access is not onward-publication authority; Notion credential kinds and Attio token levels do not replicate provider ACLs into Fulcra copies. Use the first-time setup guide for company/member prompts and the optional public maintainer feedback route. The maintenance recipe optionally polls incoming joins and member proposals; queue-only is the default, explicit exact-member delegation gates acceptance, and proposal mode stages all join effects. Do not install the retired coord listener for this flow. Claim listening only after a real scheduled run. Member check status needs a verified authorized audience too, including inherited root/group/account-wide shares. Unknown or unexpected readers require an already authorized private checkpoint or chat fallback; preserve unrelated grants. - Collect — the local ingest side:
collect(the daemon: control socket + FastAPI onboarding wizard + worker subprocesses),menubar(the macOS menu-bar app, PyObjC / rumps),fulcra-common(shared API client + ingest pipeline), plus the importer packages (dayone,csv-importer,media-helpers,attention,netflix-skill, …). The published Apple-silicon beta is 0.1.5, signed/notarized/stapled from source47fbe9a2d23d906a2f6b7c63710ca61199a69f2b; its public asset bytes match the qualified installer. Use the current download indocs/collect.md. This package acceptance does not complete browser v1 activation, source-host retirement, every interactive flow or complete legacy historical conversion. fulcra-media webhookreadiness is a synchronization contract. Its JSON{"stage":"ready"}lifecycle line is emitted only after the local/healthendpoint has served a request, not merely after bind/listen. A parent may therefore send SIGINT/SIGTERM immediately after reading that line; the command must emit its shutdown line and exit cleanly. Do not move readiness ahead of the serve-loop health probe —BaseServer.shutdown()can deadlock if it racesserve_forever()initialization.packages/gmail(fulcra-gmail) — the local, read-only Gmail relay: multi-account, crash-safe (append-only ledger + contiguous-frontier watermark), landing selected emails in Fulcra Files and relaying matches over the coord bus. The OAuth client MUST be an External, Desktop app client: Internal excludes personal Gmail accounts, and a Web client's secret is confidential and unsuitable for a shipped local relay (Google treats a Desktop client's secret as non-confidential, which is what lets one shared client ship to many installs). The full OAuth clickpath, account caps, logging rules, ledger/relay/pipeline design, and the in-plugin rule builder live inpackages/gmail/README.md— read it before touching the relay.packages/purpleair(fulcra-purpleair) — ascheduled/live_polledCollect plugin polling PurpleAir air-quality sensors (cloud API or a sensor on the LAN). On this development branch it writes per-measure v1 Metric tracks with declared units, guarded pending samples and exact readback. AQI is derived locally using the existing formula; see its limits and rollout status in the PurpleAir guide.- Shipping the Safari app to TestFlight —
packages/attention/safari/scripts/release_testflight.shdoes the whole mechanical path (both JS bundles → archive → payload check → export → validate → upload) and refuses to start without three things a runner must never hold: an Apple Distribution certificate, an App Store Connect app record forcom.fulcra.attention, and an ASC API key passed asASC_KEY_ID/ASC_ISSUER_IDwith the.p8at~/.appstoreconnect/private_keys/AuthKey_<KEYID>.p8.Developer ID Applicationis not a substitute — that signs the notarised.dmgfor direct download, not an App Store build; they are different certificates for different channels and assuming otherwise fails late, looking like a provisioning problem.--dry-runstops after export; any other argument is rejected with exit 2 rather than falling through to an upload, because a consumed build number is not recoverable.CURRENT_PROJECT_VERSIONmust increase on every upload. - The Safari destination step is a requirement. The containing app must
show which "Attention" definition this device writes into and let the user
change it (
DestinationView.swift).EnsureAttention's oldest-first auto-adopt is a DEFAULT, not intent — with two definitions it silently takes the older one and the data lands in the wrong place while validating fine. Do not remove the picker on the grounds that auto-resolution "already works". - Running the Safari Swift tests —
xcodebuild -scheme FulcraAttentionTests -destination 'platform=macOS' test, but build both JS bundles first (npm ci && npm run build && npx vite build --config vite.safari.config.tsinpackages/attention/chrome): the scheme builds the macOS app, which embeds the extension, which copies a built bundle as resources, so a clean checkout fails on missing files unrelated to the tests. Platform-agnostic logic belongs in the macOS app target even when only the extension uses it at runtime — that is what makes it reachable by@testable import FulcraAttention. - Sign the native command launchers explicitly. Briefcase does not discover
the extra
fulcra-collect,fulcra, andfulcra-apiexecutables inContents/MacOS. The release script signs each with Developer ID, a secure timestamp, and hardened runtime before Briefcase seals the outer app. A valid outer resource seal alone does not establish notarization eligibility. - Reconcile interrupted notarization before submitting again. Verify the
configured profile with
notarytool historybefore a release build. A submit command that ends without an ID does not prove that Apple received nothing. Preserve the artifact and private log, check history and native prompts, and reconcile the existing attempt first. Keep receipts, credentials, and machine diagnostics outside the public tree. Do not publish a signed candidate until notarization, stapling, and Gatekeeper acceptance are verified. - Shipping a new plugin in the frozen macOS app — the menubar Briefcase
requiresis the ONLY list you edit, but it is not sufficient on its own: a monorepo package isn't on PyPI, so the release build must also build a local wheel intowheelhouse/and prove it landed (Briefcase can exit 0 with an emptyapp_packages). Both steps derive frompackages/menubar/scripts/bundle_manifest.py, which resolves each workspace package's real import name from its own hatch config (the mapping is not mechanical). Do not reintroduce a hand-written package list inbuild_macos_app.sh;test_registry_manifest.pyfails if you do (this drift shipped once — caught in PR #455 review). - Shipping a new plugin: document it in the same PR.
docs/how-do-i-get-my-data.mdstates that it lists every source Collect can pull from, so an undocumented plugin makes that opening sentence false. The catalogue cites plugins by id in backticks, andpackages/collect/tests/test_docs_coverage.pyfails when a registered plugin appears nowhere in it — so the test tells you at PR time, not a user months later. A plugin that genuinely is not a user-facing source goes in that file's_NOT_USER_FACINGmap with a reason, which is a deliberate statement, not a way to quiet the test. The check is coverage only: it proves the source is mentioned, never that the prose is right (this drifted for real: two shipped plugins were undocumented and one section affirmatively denied a plugin that was registered — the coverage test now catches the first class; only reading the prose catches the second). - coord — the agent-coordination layer. In prose it is coord; the
engine is
packages/coord-engine(a stdlib-only CLI,coord-engine), and the skills underskills/— thefulcra-agent-*family (e.g.fulcra-agent-review,fulcra-agent-continuity,fulcra-agent-automation) pluscoordinator-discipline— are how an agent actually drives it. (Thecoord2codename is fully retired — code, identifiers, and prose all say coord; installers migrate coord2-era on-host artifacts automatically when re-run.) The first-generationfulcra-coordandfulcra-coord-filespackages were retired after their last live annotations surface moved tofulcra-common. Their provenance remains in git history; all coordination work uses coord. packages/coord-tracker-bridge— the alpha, provider-neutral projection core for reflecting coord work into external trackers (normalized snapshots, versioned policy, a pure diff plan, a Linear adapter). Workflow order, lane policy, and adapter contracts:packages/coord-tracker-bridge/README.md.packages/aicq-claude-mod— alpha Claude Code mod (function-hook plugin, not a Python package; excluded from the uv workspace): AICQ in a Claude Code session. It polls connect-our-agents/1, legacy mesh andfulcra.workspaces/1on a timer through thefulcraCLI, groups messages into collaborations with work states, draws/aicq(SVG on desktop), and responds per the four AICQ modes (heartbeats and acks never wake; 4 auto-turns/hour/collaboration cap). Sends read back before claiming delivery./aicq waitingranks human approvals, replies and blocked-on-owner tasks; blocked tasks and local pending drafts remain visible despite age.ignoreAfterDaysdefaults to 5 (0disables ignoring), andaicq_inboxacceptsinclude_stale. The owner principal defaults touser; preserve explicitly configured principals and placement. Session links come only from owner pins, exact app/V5 session matches, or own-accountagent-links/1reports, through the shared allowlist. Alias folding must preserve owner overrides and thread lookup. Interpret coordread-degradedmarkers even at rc 0; report failures and the 80-report read cap as partial coverage. The pane supports terminal and desktop; mobile is not implemented. Gate:claude plugin validate+claude plugin teston a mods-capable build. Install anywhere from the repo's plugin marketplace (.claude-plugin/marketplace.json):/plugin marketplace add ashfulcra/fulcra-tools, then/plugin install aicq@fulcra-tools. Details:packages/aicq-claude-mod/README.md. Filtering presentation never completes work. Second-instance session routing remains an installation acceptance check.- Coord retention is on by default: terminal and quiet proposed tasks archive
after 14 days, settled review families after 7 days, and dead presence shards
are pruned after 7 days.
COORD_RETENTION_DAYS=0orreconcile --retention-days 0is the explicit kill switch; invalid values fail safe to the enabled default. Hot review folds consult a compact settled index instead of repeatedly classifying historical tombstones, and the legacyartifact/namespace is consolidated intoartifacts/. UNKNOWN listings stay hot, moves are copy-verified rather than destructive-only, and archived work reverses throughtask restoreorreview restore. An archived task is owed by nobody: retention writes one bus-v4closetoallfor it after the source delete succeeds (never before — closing hot work hides it); an unreadable bus-v4 config or failed write is av4 close FAILEDwarning, not a rollback, and never "no plane". The close is durable: retention writes a marker under_coord/retention/pending-v4-close/BEFORE it moves any ack/response shard or deletes the source (a task whose marker cannot be written stays hot with every shard in place) and clears it once the close has an answer, and EVERY pass (not only the daily archive pass) retries what is still queued, at most 50 per pass with the rest reported ascap reached. A failed close or a pass killed mid-way is therefore retried, never lost. A retry never closes a task whose doc is hot again: its close may already have landed, so it re-opens from that doc and keeps the marker until the open succeeds, and it keeps the marker while that path is UNKNOWN. A close that races a restore re-reads the hot path afterwards and re-opens from the doc it finds; if that re-open fails or the read is UNKNOWN, it re-writes the marker (the restore may have just cleared it) and the next pass finishes the job.task restoreclears the slug's marker only after its move succeeds, then writes the matching v4openand exits 3 if it cannot. Archives from before this rule left phantom opens in the folds; those need a separate verified cleanup. Note the age thresholds above are necessary, not sufficient: tasks and reviews share ONE per-pass archive cap and tasks are swept first, so a large task backlog defers review archiving indefinitely. When that happens the pass now warnsretention: cap reached ... N review slug(s) not examined this pass— treat that warning as "review retention is not running", not as routine throttling. - The OLD one-shot
migrateexporter and the unused atomichandoffconvenience verb are retired (bus-v3 migrate, described under Coordinate on the bus, is live and unrelated). Reassign live work withtask update --assignee <agent> --next "..."; when another session needs resumable context, write the continuity snapshot first and then reassign the task. - Machine JSON is compact by contract: public non-ATC
--jsondocuments, the single-arraythreadsresult, and_coord/summaries.jsonomit insignificant whitespace while preserving parsed values and degradation markers. Tests and consumers compare parsed JSON unless byte layout is the explicit contract. - Other agent-facing layers (Continuity, Prefs, Vault, FDE, ATC) are described in the README; their skills and READMEs carry the detail.
Setup & tests
- One command:
bash scripts/setup.sh— installs the right Python +uvextras + thefulcraCLI, then runs the suite to verify (macOS-first; the menubar's PyObjC deps are macOS-only). - The manual equivalent is OS-dependent, and the difference is silent —
which is the whole reason this bullet is two paragraphs.
- macOS:
uv sync --all-packages --all-extras. Bareuv syncis NOT enough — pytest lives in each package'sdevextra and PyObjC/rumps in themacosextra, so a bare sync fails tests withFailed to spawn: pytestand the menu-bar can't import. Any sync must keep--all-extrasor it prunes pytest + PyObjC back out. - Linux:
uv sync --all-packages, then select the dev extra at RUN time:uv run --all-packages --extra dev python -m pytest packages/ -q. The Linux CI job (uv-workspace.yml) uses the same extra selection over an explicit list of package test paths. Do NOT use--all-extrashere: it pulls themacosextra, whose PyObjC wheels build by shelling out to/usr/bin/sw_vers, which does not exist on Linux. The build dies withFileNotFoundErrorand nothing is installed. That failure does not look like a failure afterwards: it leaves a.venvcontainingpythonand nothing else, sols .venvsucceeds, the venv "exists", and the next thing to run is a test that cannot import anything. Measured here on 2026-09-05 — the macOS line above was followed on a Linux container and produced exactly that.
- macOS:
- Run tests:
uv run pytest packages/ -q(must NOT hit external services). For targeted package/test runs, useuv run pytest -c pyproject.toml <paths> -q: package-local configs otherwise exclude root fixtures. Root fixtures supply a dummy token, disable native Collect Keychain selection and install the test-only Python network guard. Ordinary external DNS/TCP/UDP calls fail before I/O with a static error; numeric loopback, exactlocalhost, Unix IPC and MockTransport remain available for fixtures. This is a function-scoped Python patch, not an OS or subprocess/native sandbox: collection-time/earlier-fixture I/O, imported aliases and already connected descriptors are outside its scope. Tests replacing guarded calls must install hermetic substitutes. Never run a regression's RED against real credentials or an unmocked external client. Trace the PRE-migration auth path as well as its replacement before actual-caller RED: a legacy token subprocess can escape the parent Python network guard anduv --offline. Fence subprocess/OS shell, network and saved-auth fallbacks before loading the caller, with function-scoped synthetic fixtures restored after each test; never infer historical absence of child credential effects from a blocked parent request. Native integration probes run separately with explicit isolated fixtures. Root fixtures also isolate the OS-user Trakt owner journal and refuse quiet Trakt writes or explicit Trakt authorization unless the test supplies a synthetic backend. They do not make generickeyringgetters/setters safe. Keep private profile/config paths and early child/auth/network tripwires in actual-caller tests, including imported path aliases before any directory/lease mutation. Process tests that may run after threads start must use freshspawnchildren, rather than inheriting a threaded parent withfork. Re-establish private paths and auth/native/network guards in the child before application imports; parent monkeypatches are not inherited. The Trakt process helper demonstrates this test-only containment, which is not an OS sandbox. See the guard tests. - Editable install: the
.venvimports the live workspace source, so a code change is picked up by restarting the daemon, not re-syncing. - A pass/fail count is a property of (sha, interpreter, cwd) — never of the
sha alone. Measuring the engine at one merge commit gave 66 failed,
then 1 failed, then 0 failed, from three cwds over the same source.
From the repo root, the
.venv's editable install resolvedcoord_engineto a DIFFERENT checkout — the 66 failures belonged to a stale working tree, not to the sha under test. From the package directory,coord_engine/sat onsys.path, and the subprocess intest_obligations_engine_absent.py— whose whole job is to assert the engine is NOT importable in its sandbox — inherited that cwd and found it. Only an isolated venv holding a non-editable install, run from a repo root, measured the build actually under test. So printmodule.__file__for the package before you report a number, and say which cwd produced it: a count without that pair is not evidence, and two of those three numbers would have been a false report to the operator. The rule generalizes past Python — whenever a tool resolves an implementation by search path, the search path is part of the measurement. - Pull latest into a checkout with
bash scripts/update.sh(git pull +uv sync --all-packages --all-extras+ restart daemon/menubar). - PyObjC-free logic is split into its own modules so tests run on Linux CI; macOS view-layer tests are marked and skipped off-darwin. Keep new PyObjC imports lazy (inside functions), never at module import time.
- No team-particular identity in engine logic.
review restoregated a whole code path onfiles != ["<one-agent>.md"], so the verb worked for exactly one agent on exactly one team and told everyone else "unexpected archived verdict shape". Predicates belong on the SHAPE (how many shards, is there a doc), never on whose name is in the filename — the repo generalizes, and the team's particulars live on the team's store. continuity snapshotexits 3 and says so when the write did not persist.transport.writereturns False on a transport failure rather than raising; the snapshot path once swallowed that and still printedsnapshot <id>at rc 0 — found live during a store outage, leaving a successor to resume from the PREVIOUS checkpoint believing it current, exactly when parking matters most. Any caller oftransport.writemust treatFalseas failure; it is not a Falsy-but-fine return.- A task-directory listing that returns rc 0 is not automatically complete.
When the trusted feed fold still corroborates tasks omitted by a full-scan
listing,
reconcilefails closed and preserves the current generation, summaries, and index. This catches the live intermittent-empty listing shape; do not turn that disagreement back into authoritative task deletions. - Audit every existing READER before you change what a marker MEANS. A marker's meaning is fixed by everything that acts on it, not by the writer's intent, so a new state or a new field is a change to every consumer at once. Do the reader sweep in the same change, and say in the PR which readers you checked — "I did not audit the others" is a finding, not a footnote.
health's continuity audit reads ONE pointer per agent (continuity/LATEST.json, written only AFTER the snapshot itself persists), not every snapshot — a store listing carries no mtime, so the walk is one read per task and, measured at fleet scale, hundreds of serial reads that repeatedly timedhealthout. A missing pointer is UNKNOWN, never stale — only "has never checkpointed" (proven by one extra listing) is a finding;continuity_unknownreports the rest. A failed pointer update REMOVES the old pointer — with no conditional write, deleting the cache is the only way to stop a stale timestamp being believed; if it can be neither updated nor removed, the verb exits 3. Pointer updates are monotonic: an older snapshot must never move an agent's reported age backwards.data-updatesintermittently answers 200 with an EMPTYfile_changeson a window that otherwise works. MEASURED, at the raw HTTP boundary (GET /data/v1/updates?start_time=&end_time=) and through the CLI, 2026-10-02:-1dreturned 13135 file changes (4.0 MB);-7dreturned 106187 (32.7 MB).- Every rep at
-8d,-9d,-10d,-12dand-15dreturned HTTP 500 with an empty body;-20d/-25dreturned 500 in most reps. - At widths that otherwise answer, some reps returned rc 0 with
file_changes: []and a populateddata_typesmap — seen at-1d,-7dand-25d. The strongest single observation is two consecutive calls on the IDENTICAL range returning0and105768. What is NOT established, and must not be written as if it were: any causal mechanism, and any rate. These samples do not isolate window width from time of day, endpoint state, or anything else, and the-1dfalse empty is direct evidence that a comfortably-working width can fail — so "the endpoint degrades under window size, more often the wider the window" is an inference, not a measurement, and earlier revisions of this paragraph asserted it. Frequency is likewise unestablished: batches of 6 and of 20 came back entirely clean. Observation requiring further measurement: failure frequency looked higher at some wider requests. That is all it is. Consequences a detector over this feed can actually rely on: - An empty
file_changesis never proof of quiet, at ANY window width. It is a well-formed answer indistinguishable from truth by shape.COORD_FEED_EMPTY_CORROBORATION(below) checks it against a recent sub-window, catching every case wider than the corroboration bound and not one narrower than it. - A populated
data_typesbeside an emptyfile_changesis a CANDIDATE signal, not a rule — records-processed and file-changes are different legs and may legitimately diverge over a quiet range. Do not build a hard check on it without measuring that. - Do not raise
COORD_TRANSPORT_TIMEOUTin response to this. Two earlier justifications for that advice were wrong and are withdrawn: a longer bound cannot turn a 500 into a 200 (our transport maps rc != 0 to None = UNKNOWN, correctly), and the width/frequency mechanism above is not established. The reason that survives needs neither: a longer bound lets requests complete that would otherwise be cut client-side, and since an empty answer is indistinguishable from a quiet range, more completed requests means more chances to record a false clear. The original error is worth keeping in view — a timeout-causes-200 mechanism read off one 30s-fails / 120s-returns- empty pair, which repeated sampling showed was the endpoint's intermittency.
healthfreshness is SHARD RECENCY; the advance fact is separate. EVERY reconcile exit writes a health shard, aborts included —_write_health_shardruns before the earlyreturn— so a host that has aborted every pass for hours still renders[ok … 0.02h ago]. Measured onteam/fulcra2026-10-02: the task index had not advanced in ~16h whilehealthreported4/7 host(s) freshwith four[ok]rows, the only trace an unlabelled1 warn. The shard could not have answered either —build_shardrecordedwarningsas a COUNT and droppeddegraded/reasonentirely, so the distinction was unrecorded, not merely unrendered. Shards now carryadvancedplusdegraded_reason, the fold addsadvancing/aborting/unknown_advanceover FRESH hosts only, and the text saysDID NOT ADVANCE: <reason>per host plus a headline. A shard with noadvancedkey is UNKNOWN, never True — a missing field is not evidence a pass succeeded, and during a rollout a pre-upgrade host must read as unknown rather than accused or excused.fresh/stale/healthyand the exit code keep their exact prior meaning (one production reader,cli.cmd_health, audited): whether an all-aborting fleet should fliphealthyis an OPEN REVIEW QUESTION, not something the fold decides. Known imprecision, stated not hidden: an inventory-only generation refusal still writessummaries.jsonas the compatibility cache and its shard call site never sees that reason, so it reportsadvanced: Truewith its warnings — "advanced" means was not aborted and wrote the index, never published a clean generation. The same shard now carriesengine_build, andhealthcompares it with thePIN=line of the store'sadopt-latest.sh: each host reads= pin,NOT the pin, orbuild UNKNOWN, withat_pin/off_pin/unknown_buildrollups over fresh hosts. The version label cannot do this:__version__changes only on a release, so hosts running different commits can report the same version. A missing build is UNKNOWN, never current; "not the pin" may be ahead or behind, so it is never rendered as "behind". The exit code is unchanged.- The
.settledmarker's MERGE EVIDENCE is never overwritten by the tally cache: a settleable tally once stampedstate: APPROVEDoverstate: MERGED+merge_sha— found in production, where the veryreview statusrun to CHECK a closure destroyed it. Both the delete AND the write need the guard (fixing one is the neighbour trap), and the write overwrites ONLY a positively identified CACHE or a positively ABSENT marker — an UNKNOWN one (unreadable, unrecognisedstate:, a FUTURE schema) is preserved and reported. Areview-settled/v2marker written by a newer build must survive an older build's refresh. - Date/clock tests: a module that fixes a top-level
NOWfor its data must also pin the clock — an autousemonkeypatch.setattr(cli, "_now", ...)to aPINNED_NOWat/just afterNOW(template:tests/test_threads.py), deriving relative ages fromPINNED_NOW, never asserting against the real clock. Otherwise the suite flips red once wall-clock passesNOW + window. Enforced bytests/test_clock_pin_convention.py. escalatenever addresses a role's vacancy notice to the party who lapsed. When a role's registeredmaintainer:is also one of its own lease holders, the alarm cannot reach a supervising identity. The notice is still written and counted; it is REPORTED (stderr + directive body) and never rerouted. Fix the role doc'smaintainer:field instead. The undelivered count is recomputed on EVERY sweep, the daily marker is a SUPPRESSOR and is never written for a notice that reached nobody, a closed-loop role re-surfaces every sweep,escalatereportsundelivered=N, and the verb exits 3.escalatedoes not restate a vacancy that is already on the board. The vacancy title embeds the date, so the slug differs every day and the per-slug existence check ondst(a classifiedread_classified(dst)since PR 694; a bareread(dst) is Nonebefore it) can never match across days; the daily marker suppresses only WITHIN a day. A state-change guard (roles.vacancy_already_open) now skips minting while a row for that role is open, and printsALREADY OPENwhen it fires — a suppressor that says nothing is indistinguishable from a sweep that never ran. Three properties are load-bearing and must survive any edit:- Role matching is EXACT, never a prefix. A prefix test would let
reviewersuppressreviewer-2; an identity transform used to suppress an alarm has to be injective or it hides what it was not asked to. - An unreadable listing does NOT suppress. UNKNOWN silencing an alarm is worse than a duplicate row, so the guard falls through to minting and says it skipped.
- Closed-loop vacancies are EXEMPT — that is what the
re-surfaces every sweepclause above is FOR. The notice reached nobody, so there the repeat IS the delivery, and suppressing it would silence the only retry. This is not a change to re-notify:directives.renotifyis "a strict filter OVER inbox", a read-side fold that writes nothing and keeps surfacing ONE unacked directive.escalatewas re-MINTING, which is a different mechanism that shared the name. Suppressing the re-mint costs no visibility, because the standing row is unacked and the fold surfaces it anyway. The skill prose (skills/fulcra-agent-roles/) carries the same condition, since a hand-written inbox drop would re-create the debt the engine guard removes.
- Role matching is EXACT, never a prefix. A prefix test would let
- The
no-team-internalsCI guard PROVES it can fail before it reports clean.scripts/no-team-internals.shruns--self-testfirst: it stages a fixture carrying a public IP and a session ref, asserts the scan flags both, and only then scans the tree. Its first version used\b, which POSIX ERE does not support, sogit grep -Ematched nothing and the check went green on every PR while structurally unable to find its leak class. Never use\bin agit grep -Epattern. A guard's green is only evidence when its red is reachable. - Environment hermeticity: the suite's answer must not depend on who runs
it.
cli.INHERITED_ENVmaps each ambient variable the suite must neutralise to a representative value (identity:FULCRA_COORD_AGENT,FULCRA_COORD_HUMAN; channel:COORD_RECORDS_TYPE) — ONE mapping, so the fixture that clears the keys and the wall that populates them cannot drift. The coord-engine conftest clears them for every test, andtests/test_env_hermeticity.pyre-runs the affected files under both an empty and a populated environment and requires the same outcome (dozens of tests once failed iff an identity was exported — line one of every agent's wake prompt). A test that needs a specific identity or channel sets it in its own body. A variable belongs inINHERITED_ENVwhen the suite reading it makes the ANSWER depend on who ran it; a variable that legitimately changes behaviour a test is about goes inNOT_YET_WALLEDwith the measurement instead. Measure siblings rather than guessing. - Identity and canonical reads have one authority each. Resolve an agent
identity only through
coord_engine.classifier.resolve_identity: explicit argument →FULCRA_COORD_AGENT→ the per-cwd persistedidentities/<realpath-hash>.jsonstate entry → sanitized host. In particular, never let a host-derived id replace an exported session id: two sessions on one host must remain separate actors. An unreadable persisted identity fails closed rather than falling through to host; an absent file is the only state that permits that fallback. Canonical directory reads go throughcanonical_read; a successful empty listing isEMPTY, adata-updateslifecycle deletion isTOMBSTONED, and unreadable or ambiguous evidence isUNKNOWNrather than absence. An unrecognised input shape (including a listed directory) isUNSUPPORTED, not a clean result.
Coordinate on the bus
Durable work — anything another session or agent must see — lives on the coord
bus (Fulcra Files), driven through coord-engine and the fulcra-agent-*
skills. Subagent-only work stays OFF the bus.
IF YOUR MESSAGE ASKS FOR NOTHING, SEND IT --fyi. tell mints a proposed
row that only the RECIPIENT can close, so a report, an ack or an FYI becomes a
permanent open obligation its assignee cannot discharge — there is nothing to do.
A reply sent
with --closes closes its parent AND mints a fresh open row back at the sender,
so two agents who both behave perfectly still net one open row per exchange.
--fyi delivers identically — same durable ptr doc, same companion event, same
appearance in the recipient's queue — but the row is born closed and never enters
the open pile. This is the sibling of the merge-closes-review ruling (PR #561)
one plane over: closure belongs to the terminal event, not to a separate
discipline step nobody performs, and a notification's terminal event is its
delivery. Use a plain tell when you are genuinely asking for work; use --fyi
for everything else.
First time on the bus, or joining from a remote/sandboxed session (Claude
Code cloud, CI)? Follow docs/coord/GET-ON-THE-BUS.md
— it covers the egress allowlist (fulcra.us.auth0.com, api.fulcradynamics.com),
headless device-flow auth (and the fulcra auth login HTTPS_PROXY caveat), the
human-free token-refresh grant, team bootstrap from zero, the join sequence,
role-takeover continuity (continuity resume at claim time), and the ephemeral-host
doctrine (survival invariant + heartbeat duty for long-lived remote sessions). The canonical invocation is the bare
coord-engine binary after uv tool install — uvx/uv tool run cannot resolve
it (not on PyPI).
- Named identities: personas are a convention for human legibility only; bus routing always uses the functional id, and the roster lives on the team's store.
- Wake router — ships in the engine; evaluate acceptance per deployment.
Scheduled wakes + queue reads are the standing pattern (status notes:
README.mdanddocs/coord/BUS-V3.md). The contract, should you deploy one, iswake-router-SPEC.md+wake-router-PLAN.md; deployment (provisioning adapter scripts, scheduling a poller on a host) is a separate, operator-gated step. Bound and prefetch queue-entry reads so a growing queue does not make the reader exceed its wake cadence. Two pieces of doctrine outlive any deployment:- AN ADAPTER'S SUCCESS PROVES THE ADAPTER RAN — never that the AGENT ran. Axis 1, what success proves: a DIRECT adapter re-enters the model session by its contract; an INDIRECT (queued/alignment) adapter only lands a nudge or aligns a schedule, and is a viable wake chain only when its independent consumer — session loop, Routine, heartbeat — exists AND is verified running; a NOTIFYING adapter shows a human a banner, never a wake. Axis 2, is there an implementation on the named executor: registration and implementation are separate, so a route can look configured, validate, enqueue forever, and never deliver. Classify each axis on its own evidence; never collapse them.
- EVERY HARNESS MUST NAME THE THING THAT RE-ENTERS THE AGENT — the
mechanism that runs the model, never a script beside it (an OS scheduler
job runs shell, not the model; see
docs/coord/HARNESS-MAP.md). And never retire a working wake without naming its replacement and proving the replacement RUNS THE AGENT: a standing session loop was once replaced over two weeks by a notifier that woke a human, a headless invoke that could not authenticate, and a peek that never consumed — none ran the agent, while every layer reported success.
bus-v3 tag-provisionnever writes a registry entry withoutagent. One such entry makes every reader reject_coord/bus-v3/tags.json, which untags the whole fleet's events. The verb exits 2 instead, leaves the registry unchanged, and prints the uuids it created for a--tag-id-*retry. Tag names are capped at 30 characters by the platform, so an identity over 24 characters needs a shorter, hand-created agent tag passed as--tag-id-agent; the verb checks names before creating anything.- Durable tooling stash. An agent's operational bundle survives ephemeral
machines via
coord-engine stash push/pull/list: push refreshes amanifest.json(per-file sha256 + exec bit) and runs a fail-closed secrets guard (secret-shaped names and credential-shaped content are refused with the tripped rule named —team/<team>/**is readable by every agent on the bus); pull restores and fails loud on checksum drift. Procedures:fulcra-agent-durable-state. On wake, read your event queue first — bus v3. One bounded
get-recordsquery against the team's coordination annotation. The full read/write contract lives indocs/coord/BUS-V3.md; the agent-actionable core:- Dedupe by record id, keep
v:1payloads addressed to you orall, fetch documents byptr, and fail closed on any error or truncation — an unreadable window is UNKNOWN, never empty. - Zero fresh events is not proof of zero durable work. A successful
text-mode queue read with no event rows and no obligations fold prints a
stderr notice pointing to
coord-engine obligations <team> --agent <you>; run that verb for the terminal durable-work answer. The notice preserves the queue read's rc 0 because its event window was read successfully; an unreadable event window still fails closed as UNKNOWN at rc 3. - Terminal read states are DATA / CLEAR / ABSENT / UNKNOWN / INVALID,
and rc is never inferred: read
state+error_codefrom the single JSON envelope (under--json, success is exactly onequeue-resultobject and every nonzero exit exactly onequeue-errorobject — empty stdout never means anything). INVALID (malformed bytes; human-fixable) is never ABSENT (the engine refuses to auto-recreate over a corrupt document) and never UNKNOWN (*-read-failedmeans retry; a retry never fixes a corrupt file). - A deliberate
queue --consumetakeover of another agent's cursor writes a durable audit doc BEFORE reading and is refused if that write fails; plain reads and--peekwrite nothing. - The read is cheap enough to ride every wake you already have — do not
run a polling loop or resident listener for it. Keep
fulcra-apicurrent whenever you touch coord tooling (same pass, standing rule).
Prove the write path after any install/upgrade — and whenever a recipient says it did not hear you — with
coord-engine doctor <team> --delivery --agent <you>(rc 0: written, ingested, and parsed; rc 2: write refused; rc 3: written but not proven fleet-readable before the deadline). Engine currency. "The pin" (the commit in the store'sadopt-latest.sh— what to install) andcurrent_engine_versionin the bus authority (a SEMVER FLOOR — the minimum engine the fleet accepts, compared at-or-above) are different objects: adoption moves the first and cannot touch the second, so every pin move that ships behavioural change evaluates a floor raise in the same pass, and raising the floor is also what reaches a dark host. Every queue read checks the floor for free and printsqueue: ENGINE STALEwhen the runtime is older. Adoption-script doctrine, each clause earned live: a failed adopt must never leave the host worse than it found it — never force-reinstall a capability that works, self-heal a half-removed install once, and still FAIL when the retry fails; a cached "adopted" marker records what you DID, not what is on disk, so a skip must be bound to the ARTIFACT's own identity (the installed build'sdirect_url.jsonvcs_info.commit_id, PR #598), never a capability every candidate shares, and every unreadable/malformed/absent answer is UNKNOWN and takes the expensive path; when a check reads several evidence sources, define their combined evidence — an UNKNOWN member poisons the whole set; shipped-shell decisions live in functions a test can drive (reading shell proves nothing); and pre-publish acceptance runs on both macOS and Linux, because you cannot know in advance which failures are OS-specific.coord-engine doctor <team> --selfis the currency check on demand and is TRI-STATE: rc 0current; rc 3stale(run the store's adopt-latest, re-run); rc 2unknown(floor unreadable/absent/malformed) — comparison impossible is not current, so never read rc 2 as green; repair only on nonzero.coord-engine briefing <team> --agent <you>remains the fold over durable state — identity, role inboxes, reviews owed — honor every degraded row it prints as UNKNOWN.- Dedupe by record id, keep
- VERIFICATION FAILS DIFFERENTLY FROM CODE, AND IN TWO DISTINCT WAYS. Broken
code usually fails visibly. A broken CHECK hands back an answer that looks
fine, so the failure reads as a clean result rather than as an error — which is
why "verify more carefully" is not the defence. In five logged instances every
agent involved WAS being careful, and each committed the error inside work
whose explicit subject was that error. The two modes need different defences
and neither covers the other:
- A broken INSTRUMENT returns a WELL-FORMED answer. A probe reading the wrong path reports zero rather than erroring; a test harness that collides on its own fixture fails in a way that mimics the bug it hunts; a control that varies an input which short-circuits BEFORE the code under test proves only that the short-circuit works. Defence: check the SHAPE of the result — is this answer plausible at all? — and check it against an earlier, narrower measurement of the same thing. Too clean to believe, or disagreeing with a prior measurement, is the signal; discard the whole run rather than reporting part of it.
- A broken INFERENCE returns a PLAUSIBLE answer. The instrument is fine and the reading is fluent, reasonable, and wrong — "those must be false positives from matching ids against a human-organised document" is the shape. Plausibility cannot catch this, because being plausible is the answer's whole problem. The only defence is going to the SOURCE artifact and reading it. This is the half no heuristic covers, and the half that ships. The trigger is behavioural, not scheduled: the moment you find yourself explaining a result away — reconciling an inconvenient reading with what you expected, ruling a mismatch to be noise, or narrating why a source need not be opened — is the moment to run both defences. That impulse precedes the wrong conclusion in every logged instance, which is what makes it useful: it is available while the answer can still change. Everywhere else a wrong inference is additive and leaves the measurement standing; here it silently deletes the evidence that you were wrong. Corollary for any bug whose subject is a wrong reading: assume your own verification of it carries the same defect, and check the instrument before you trust what it told you.
needs-me --jsonis contract 2: one envelope object, health first. stdout is a SINGLE JSON value —{"contract": 2, "health": DATA|CLEAR|DEGRADED|UNKNOWN, "source", "degraded", "basis", "rows": […]}. Readhealthbefore anything else: UNKNOWN means the authority itself was untrusted and the rows must not be acted on; DEGRADED means rows are a FLOOR (partial coverage — never infer absence); CLEAR is the only health that licenses "nothing for me". rc is a pure function of health (UNKNOWN|DEGRADED → 3, in text mode too). An incomplete parse is UNKNOWN; never truncate an authority read withtail/headand never regex fields out of a cut buffer. Other verbs migrate one PR at a time — a bare array is the contract-1 shape, scan its marker rows as before (docs/coord/OUTPUT-CONTRACT.md).- Class A results flow through the shared v2 outcome spine.
coord_engine.outcome.CommandOutcomeis the internal authority for state, coverage, rows, provenance, and rc; legacy contract-2 envelopes are adapters over that value. A required surface that is not verified isUNKNOWNand therefore rc 3 even when some rows are usable. New Class A folds must build the typed outcome first, then render text or JSON from it; do not recompute health or rc in a serializer. Text coverage lines mark optional surfaces asnon-gating, preserving therequired:falsedistinction carried by JSON. - If your harness truncates output, read the verdict off stderr.
needs-meandbriefingprint their row payload with degraded and source markers inside it, so a truncating reader can lose exactly the part that says whether the read is trustworthy. Both emit one compact envelope line to stderr —needs-me: N item(s), health=…, forge=…, source=…, degraded=N, rc=N— which survives stdout truncation (a courtesy duplicate; the stdout envelope is the authority).needs-me --envelope-onlygives you that verdict with no records at all, same rc. Trust the envelope'shealthandrcover a payload you cannot see the end of;degraded>0orrc=3means UNKNOWN or a floor, never clear. A STATUS YOU PRINT IS NOT A STATUS YOU READ. The same defect the clause above describes shows up in our shell habits, where it is cheaper to commit and harder to see: a script emits a success line without reading the status it claims to report. Three instances in one week, all caught only by looking at the NEXT command's output rather than at the success message itself —
rc=$?after a command substitution containing a pipe, the same after a pipeline, and agit branch -dthat REFUSED while the surrounding script echoedcleanup done(the branch was still there on the next line).Mechanical form: a script that prints an outcome must read the rc it is describing, and where it cannot, it says so rather than asserting. The tell is a success message whose text was decided before the command ran.
The shell mechanics:
rc=$?after a pipeline captures the last stage only —false | trueandfalse | catboth yield0, so the failure is invisible. Same forout=$(cmd | filter).- Capture immediately (
cmd; rc=$?) before any pipe or substitution, or setpipefailfor that stretch. - Our login shell is zsh, where the per-stage array is lowercase
pipestatus— bash'sPIPESTATUSexpands to the empty string here and silently tells you nothing, which is this very rule wearing its own costume. - Prefer
if cmd; then …; else …; fiovercmd; echo done. - When reporting a BATCH, count the artifacts on the store rather than tallying exit codes you did not check.
- Bus-v3 convergence is authority-gated, not a rollout convention. The
shared
_coord/bus-v3/records.jsonatomically declares protocol and cursor schema versions, minimum safe reader/writer engine versions, cursor generation/activation, and the CHANNEL every writer resolves — writers readdata_typefrom it at write time and REFUSE rather than falling back to a name lookup (never resolve a channel by name: a superseded definition can still read as live, so a by-name resolve silently writes where nobody reads).queuewarns on legacy or mixed writer evidence and refuses an unknown/old reader or writer before cursor mutation; cursor v2 is physically isolated from legacy cursors, and after activation legacy activity is a loud health signal, never authoritative coverage. Full authority and activation contract:docs/coord/BUS-V3.md. - Legacy Bus-v3 migration is authority/cursor-only. Run
coord-engine bus-v3 migrate <team> --dry-runfirst, then--applyonly after every cursor isreadable-legacyorabsent; malformed or unreadable state blocks, apply is idempotent and never rewrites legacy cursors, and task/role documents are not a migration target. JSON contract in BUS-V3.md: never branch on rc alone — readstate+error_code, and treatwrites.authority: "ISSUED-BUT-UNPROVEN"as a write whose read-back did not prove the resulting store state. - Cursor v2 is transactional: read → process → commit — commit the token
when the last row is a
queue-delivery. Under an activated schema-v2 authority,queuestages one pending batch and prints aqueue-deliverytoken; it does not advance coverage. Process every surfaced event to a durable terminal classification, then runcoord-engine queue commit <team> --agent <you> --token <token> --result <record-id>=<completed|blocked|superseded|ignored>(repeat--resultfor every staged event; an incomplete or extra set is refused). A crash or missing commit replays the identical token and batch; a stale token is rejected; a repeated successful commit is idempotent. The store transport exposes no conditional write, so schema v2 remains fail-closed until a transport provides a provencompare_and_swap(a write/read-back imitation is not CAS); keep the authority on schema v1 untildoctorproves every active writer compatible and the CAS gate passes. - The Codex safety-net watch checks its literal inbox before briefing
(PR 484): one direct
inbox --jsonread, then the authoritativebriefingread — briefing's inbox subsection is never a substitute for the direct read, and a degraded surface falls back to the documented direct listing before reporting quiet. Deliberate redundancy against a stale or unreadable summaries index. - Retired (2026-07-27, operator-ordered) and REMOVED (2026-08-03, PR #523):
the
listenwatcher as the wake surface — don't hand-roll a replacement. Discovering work by walking the file tree degraded ~9 ticks in 10 at fleet scale and hid work; the v3 queue read (cursored, fail-closed) replaces it. Replies totell/respond/review requestarrive as v3 events on the record queue — read it on your next wake (the send verbs echoreplies:/await verdicts:breadcrumbs; seefulcra-agent-automation§2). Invokinglistenis an argparse error; any survivinglisten-state.jsonshard is historical residue. Presence stays time-dirty rather than feed-cached: each briefing evaluates the roster against the current clock, so an unchanged session shard still becomesLAPSEDwhennow >= until. - Review handshake. Nothing lands without an independent review by a
different agent identity than the author — that review is the control, not
who clicks merge. Where a forge exists the change goes through a PR, never
a direct push to
main. The handshake rides the bus, not the forge:coord-engine review request <team> <slug> --of <artifact> [--head <exact-sha>] --reviewer <role>opens a durable obligation that sits in the reviewer'sneeds-meuntil their verdict file exists at the exact path the command echoes (the required token is the role passed to--reviewer; that token is what the tally credits). The pending row itself carries the artifact: inneeds-me --jsoneveryreview-pendingrow servesofand the exacthead(explicitnullwhen a legacy register genuinely lacks the field), so a reviewer dispatches from the row alone — no second lookup (OUTPUT-CONTRACT OC5). One PR has one review slug (pr-N), across every push: pass the PR URL as--ofand the full 40- or 64-hex commit id as--head; re-requesting the same slug with a NEW head advances the same doc to the next round, verdicts append atverdicts/<head>--<required-token>.md(frontmatter must repeat that exacthead), andreview statusfolds ONLY the active head, ignoring superseded-head verdicts without deleting them. Legacy/non-code reviews may omit--head. A verdict that cannot be counted is REPORTED, never dropped, and the verb exits 3 — a malformed filename, averdict:token outsidereview.accepted_vocabulary(), or a shard whose frontmatter attests a different head each name the rule that skipped them; the failure class is the old affirmativepending_required: [alice]while alice's verdict sat unreadable in the directory. The request is durable-first, not atomic: the doc lands FIRST, then one directive per required reviewer (a verb-opened review fires each reviewer's inbox — never hand-send a review tell); a partial notification failure is loud (rc 1, naming who was and wasn't notified) and re-running the SAME request is idempotent recovery, while a re-request with a differentof/required-set/requester is a loud rc 1 conflict and a present-but-unreadable doc fails closed (never overwritten).coord-engine review status <team> <slug>computes APPROVED/CHANGES/PENDING and gates the merge;coord-engine review merge-ready <team> <slug> [--notify <merger>]adds the forge half before the click (PR head == register head == verdict head, CI green; rc 0 READY / 2 NOT READY / 1 UNKNOWN) and never merges; a host without the GitHub CLI is UNKNOWN without "retry", and aghthat is some other client (itsgh --versiondoes not begingh version) counts as none. The<artifact>is an opaque ref, so the handshake works with any forge or none — a forge-only "Approve" does NOT count (co-located agents often share one forge account); the bus verdict, keyed by agent identity, is the source of truth. The verdict FILE discharges the obligation; the ack is inbox hygiene and targets the review-request directive by its inbox id (review-request-<review-slug>-<hash>), never the bare review slug. Full rules and per-harness wiring:fulcra-agent-reviewandfulcra-agent-automation. - Park for a successor only on pushed-and-verified state. A continuity
checkpoint is a promise: never park asserting repo/artifact state you have
not pushed AND independently verified —
git ls-remotethe exact ref and compare the exact hash (a push--dry-runonly proves write permission, not that the remote has your state; the memory of having pushed proves nothing). If a migration/import is still pending at park time, the snapshot saysIMPORT NOT DONEplus the exact recipe and the access prerequisites; it names ONE canonical home per artifact, never candidates. The parking agent also writes the role doc if it's missing and carries an operator pre-flight checklist (egress, auth tap, repo scoping, write perm) so the successor's setup is one pass, not a serial discovery-by-failure. Full doctrine + checklist template:fulcra-agent-continuity"Parking for a successor"; cloud repo-scoping wall:HARNESS-MAPwall 11. - A lapsed lease is not proof a role is unattended.
roles statusclassifies from lease timestamps alone, so its predicate is "has a lease been renewed" while the alarm reads "is anybody doing this job" — those diverged for four days (a reviewer's lease went stale while it filed verdicts hourly, and the sweep filed a false P1 per role per day). Escalation now takes a TRI-STATEattended: True suppresses it asLEASE LAPSED, ROLE IS BEING SERVED, False escalates asUNATTENDED, and the default None still escalates but must say attendance not checked rather than assert absence. Passroles status --check-attendance(opt-in: one listing per review, budgeted and reported asscanned N/M) before calling any role unattended. The JSONattendancefact distinguishes the unrequestedNOT_RUNstate from a requested, budget-truncatedUNKNOWNscan; that requested incomplete check exits 3 and makes the public-read envelopeUNKNOWN, so automation cannot mistake a nested unknown for a clean role decision.roles statusalso seals lease assignment and holder presence into oneliveness_fact, including both observations and both store-prefix provenance fields. Fresh presence plus a stale lease isLAPSED(orUNKNOWNif the observations cannot be sealed), never confidentlyVACANT. - Park a role, don't mute the sweep by hand. Deliberately leaving a role unattended (a reviewer on leave, seasonal on-call) is an ENGINE fact, not an agent-side convention: set
dormant_until: <ISO>inteam/<team>/roles/<role>.md, and while that date is future the mechanicalescalatesweep suppresses the role's vacancy escalation on every heartbeat host androles statusreportsDORMANT (until <ts>); escalation resumes automatically past the date, a live lease still shows HELD, and a garbagedormant_untilfails OPEN (noted on stderr, escalation still fires) so a typo can't silently mute a role — seefulcra-agent-roles. - Fold text is capped; the task doc is the payload's home. Summaries rows bound
title/descriptiontoCOORD_SUMMARY_TEXT_CAP(default 280 chars, ellipsis-marked), soinbox/briefing/boardshow enough to triage, never the full body of a long directive — read the task doc (team/<team>/task/<slug>.md) before acting on one. Engine surfaces any bus reader must honor. Two invariants a reader lives by:
- Slug dedup + delivery rc. Every directive slug carries a payload hash
(
<title-slug>-<sha256(payload)[:8]>), so identical resends dedupe by construction and distinct messages can never share or clobber a slot: rc 0directive <slug> already deliveredis a deduped identical resend, and rc 1cannot verify delivery, retrymeans the slot was unreadable — never overwritten, safe to retry. - The review/forge legs are projection-first, and they SAY so.
briefing/needs-meserve the reconcile-builtreviews/forgesections of_coord/summaries.jsonin zero extra ops when fresh, and emit a trailingreview-source/forge-sourcerow disclosing it (source: projection+as_of, orsource: raw-scan+ thereason: stale / incomplete / malformed — duplicate slug rows and impossiblesettledcombinations are malformed — / unrecognized). A projection that cannot be served falls back to the full raw scan LOUDLY; it is never silently served as current. Reconcile publishes review + forge as one complete generation: a budget-cut or failed build refuses the compatibility-cache write and leaves the last complete generation current. The publication authority is_coord/projections/current.json: a builder write/read-verifies immutablegenerations/<digest>.jsonfirst, then writes and read-verifies the digest-bound manifest. RequiredUNKNOWN/incomplete sections or an unattested feed frontier stay recovery progress and never advance current; reconcile exits nonzero. Private review/forge recovery is keyed by the content-bearing public projection base, not by a detector watermark or batch digest; positive feed changes invalidate only affected review rows, while forge is rebuilt from current canonical inputs. A transport that proves conditional-write support uses CAS to fence a moved pointer. A transport that explicitly declares CAS unsupported may use one last-writer-wins manifest write only after the complete deterministic immutable generation verifies, and must verify the exact manifest read-back; missing/invalid capability and write/read failure remain nonzero. Because a non-CAS writer can race, the mandatory public-read freshness overlay rejects stale manifests before v2 authority activates.summaries.jsonremains reader compatibility during migration; new readers validate the current generation before use. The shared v2 public-read authority validates the exact current manifest and immutable digest, then obtains one bounded at-least-once feed window over[watermark - epsilon, now - epsilon]. It deduplicates update identities, applies only supported task deltas, and re-reads the mutable pointer before rendering. Unsupported canonical changes, unproven epsilon/feed coverage, a raced pointer, or a skipped overlay are typedUNKNOWN/NOT_RUNand nonzero — never clean. JSON and text name the same generation, source watermark, attested coverage horizon, and sorted surface coverage; JSON is still exactly one value and preserves the domain result beneathresult. Immutable section values are structurally validated before dispatch: inventory records cannot be missing, malformed, outside their canonical namespace, or non-string, and content/frontmatter/type must agree. Presence is exactlypresence/<file>.md; acknowledgments and responses are exactly_coord/acks/<slug>/<file>.mdand_coord/responses/<slug>/<file>.md. Canonical slugs match[a-z0-9]+(?:-[a-z0-9]+)*; canonical leaf names start with an alphanumeric, contain only alphanumerics/_/-, and end in one final.md. Dot/traversal segments, file-shaped intermediate components, hidden leaves, and the legacy singularresponse/namespace are not authoritative coverage.data-updatesrecord counts are detector signals only, never cardinality, a diff, a threshold, or an identity. Livedata-updatesomits zero-record types, so the configured channel absent from a well-formeddata_typesmap is a zero signal; a malformed count or unreadable authority stays UNKNOWN. Live measurements persistently showed2721 -> 9,1444 -> 0, and2737 -> 25count/enumeration pairs. A positive signal therefore requires a bounded attested enumeration with at least one immutable identity; positive-with-none isUNKNOWN/nonzero. A zero signal is not proof of CLEAR: a bounded enumeration must prove the whole outer feed window. The outer feed must attest the exact requested boundary —after, or thestart_timethatfulcra-api data-updates(0.1.46+) actually emits, withthrough/end_timeas its frontier; an envelope with neither takes the named boundary recovery — and the record cursor must repeat that boundary and reach or pass the outer frontier. A missing, lagging, mismatched, or incomparable horizon is UNKNOWN, advances no watermark, and leaves freshness overlay NOT_RUN/nonzero. With today's CLI the record leg is never attested —get-recordsanswers JSONL with noafter/through, so the transport returns no window — and an unavailable or incomplete record window with an attested outer window takes the named full-scan recovery (re-anchoring under the complete-task-read gate). So on current builds every reconcile pass is a full-scan recovery; the trusted incremental path waits for an endpoint that attests the record window. That recovery keeps the tasks whose latest lifecycle state in the attested feed is an upload (collapsed by instant, so an upload later deleted or archived in the same window is not one) as references, so an rc-0 partialtask/listing that omits one fails closed (no publish, no re-anchor). A mismatched or unparseable record window stays non-recoverable. Bootstrap is complete only when an outerafter/start_timesupplies its boundary and the record cursor covers the same full frontier. An EMPTYstart_time/end_timewindow wider than the corroboration bound while corroboration is dormant is UNKNOWN (FEED_WIDE_EMPTY_UNPROVEN) and takes the named full-scan recovery, never a trusted CLEAR;after/throughkeep the dormant default. That recovery re-anchors the persisted cursor to the server-attestedend_time(attested_frontier, never a trusted watermark) only when the task fold is complete — every listed task READ this pass (any read failure keeps the prior cursor; a read-but-unparseable shard is deterministic and does not) — and an aborted or projection-refused pass never writessummaries.json, so it cannot move the cursor either. Boundary/frontier-unknown recoveries keep the prior cursor. Enabling corroboration by default is not built yet. Review projection v3 rows carry the full direct-query tally; one shared validator requiresof/head, unique row slugs, settled invariants, and all three orphan/tombstone slug lists before producer carry, publication, or consumption. V2 carry rows and v1 settled caches are rebuilt before publication. The caller's OWN head is feed-gated too: with a cleandata-updateswindow, only caller-owned slugs named changed since the projection anchor are raw-tallied; unchanged caller-owned slugs are served from the projection. Without positive feed proof, every caller-owned head slug is raw-tallied fail-closed (see the head-budget rule below). No source row at all means the aggregate carries no projection: the pre-projection raw scan. Contract for readers:docs/coord/BUS-V3.md→ "Where a fold's answer came from". Ship-gate: any new projection-served fold emits a source row through the shared renderer. - Honor every degraded row; never read a bounded fold as complete.
briefing/needs-mebound each section underCOORD_BRIEFING_BUDGET(default 60s, cumulative across sections) and emit a{scanned, total, skipped}degraded row per section (review-fold-degraded,forge-degraded,presence-degraded, plus the public-read markers below). On ANY of them, fall back to the section's direct sweep (review statusper slug,forge feedback,presence show— per-section fallbacks infulcra-agent-reviewandfulcra-agent-automation). The review sweep itself fails closed:review statusreturns rc 1 (tally unknown, retry) when the doc, the verdicts listing, or any shard is unreadable, rather than printing a partial APPROVED — a degraded transport can never green-light a merge.
These budgets rest on hard per-op boundedness: every transport subprocess runs in its own process group and is SIGKILLed whole on timeout; the per-op bound is
COORD_TRANSPORT_TIMEOUT(default 30s) — run it TIGHT on a resident bus reader (e.g. 8s). EveryCOORD_*tuning knob, the shared positive-finite parse policy, and theFULCRA_COORD_*legacy-prefix rule are catalogued inpackages/coord-engine/README.md→ Environment / tuning; the mechanics that spend the budgets live incoord_engine/budget.py. Ship-gate: a NEW bounded fan-out usesbudget.Deadlinefor its deadline check (never a hand-rolledtime.monotonic() >= deadline) andbudget.degraded_rowfor its marker, so the whole family keeps one>=boundary and one degraded shape. Undecodable CLI stdout/stderr is normalized toTransportError, never replacement-decoded; classified reads reporterror, not content or absence. A malformed source remains unreadable and needs repair; this does not prove a clean fold.- Slug dedup + delivery rc. Every directive slug carries a payload hash
(
- Ship-gate: a verb that mutates durable state does not ship on decision-function tests alone.
It ships with at least one test that invokes the ACTUATOR end to end, or with a recorded live dry
run against a real team.
review residueshipped its decision function under thirteen passing tests while the command itself was dead on aNameError—modelis imported locally incli.pyand the verb used it unqualified. Nothing in the suite touched the command, so a green suite sat over a completely broken verb; only running it against the real team found it. A green suite over a broken command is the same false-clear as an empty queue over 257 owed obligations: the instrument answered a question nobody asked. When you add such a test, VERIFY IT DISCRIMINATES — neuter the wiring and watch it fail — because a test that passes either way is the thing it was written to prevent. - The public-read failure contract — UNKNOWN is loud, never a clean-empty. Every aggregate-backed
public read (
status,board,needs-me,search,inbox, theagents/digest/asks/briefingbundles) folds the summaries index via_load_rows_status, whoseokbit is False when the index/listing is UNKNOWN — as distinct from a genuinely-ABSENT index (a fresh team), which is a real, readable empty. A read whoseokis False must NEVER return a clean-empty result: it emits the shared marker_read_degraded_row(reason)={"type": "read-degraded", "reason": …}(inside the one--jsonvalue; a stderr notice in text mode) while retaining any partial rows, andreasonpreserves every independent failure in the pass. The hazard it closes: a silently-empty fold reading "all clear" while a live unacked directive is merely unreadable. Ship-gate: a new aggregate-backed read consumes_load_rows_status(never a fold that drops itsokbit) and surfaces the marker onok is False, with a red-first test asserting no clean-empty under a degraded transport. --jsonpurity: stdout is ALWAYS one parseable value. Under--json, NO prose ever reaches stdout — every degraded/notice line becomes a JSON row or a reserved key, or goes to stderr. Each fold verb's--jsonbranch is exactly onejson.dumpsof the single result;threadsemits a single JSON array (the dropped list + a trailingthreads-degradedelement), NOT JSON-Lines. Ship-gate: a new--jsonpath is onejson.dumps, with a red-first test thatjson.loads(stdout)yields exactly one value on every degraded path. Enforced by PARSER DISCOVERY, not a hand-kept list:test_json_purity.pywalks the real parser for every--jsonpath and fails until each is in_JSON_PINNED(smoke-run under a corrupt index AND squeezed budgets) or_JSON_EXEMPTwith a stated reason —_JSON_EXEMPTis empty today, pinned paths must print SOMETHING, and the widened sweep immediately found a live leak (headroom --jsonprinted prose on its no-accounts early return).- Digest uncertainty travels with the payload.
digesttext, stored body and timeline note must carry the same read-degraded reason and last-known/unverified row warning as JSON; an unreadable index never licenses "no open work". Its additive source timestamp/age uses summariesgenerated_ator, on the validated generation path, the attested coverage horizon, never the render clock as a fallback. Preserve first-written window snapshots, but withhold their pending unqualified historical timeline body while the current read is degraded; render a current warned note instead, preserving same-ID retries and already-confirmed emissions. A False store/emit-marker write or mismatched readback cannot be reported as confirmed persistence; UNKNOWN marker reads preserve existing history and withhold emission. - A finished review does not close its request row unless something closes it.
The review store and task board need explicit closure propagation. The DECISION verbs (
review close,review conclude) close their own rows at settle time — best-effort and loud, because the marker is durable truth and bookkeeping must not fail a verified closure, but a silent skip rebuilds the backlog. Thereview residueverb (DRY RUN by default) closes the rest on a schedule. It is permanent infrastructure, not a backfill: a review that settles through the fold's APPROVED cache is settled by a pure build path that must not mutate task state (projection.pycallstransport.writeexactly once in the whole module and never touchestask/), so those rows have no decision verb to hook. Retiring it needs the successor where the cache writers EMIT and reconcile folds the close — and when that lands,review residueis deleted, not kept as a second reader. - Ask
review_gc.TERMINAL_MARKERS, never a marker filename. There are three —.gc-closed,.concluded, and.settled— and.settledis deliberately outside that set because it carries an APPROVED CLAIM that some readers act on rather than merely skipping. Hard-coding names is what hid.gc-closedfor a whole round; it then hid.concludedfrom a residue census written by someone reading the very comment that forbids it. A reader that acts on.settled's claim goes throughreview.settle_shortcircuit; presence alone closes nothing. .settledcarries TWO things and only one of them is disposable.state: APPROVEDis a tally CACHE — cheap to recompute, safe to drop.state: MERGED+merge_shais merge EVIDENCE written byreview close, and nothing recomputes it.review statusdeletes a stale cache but never a MERGED marker; an unreadable marker is left alone, and an unclassifiable one (including an unrecognisedstate:from a future writer) is PRESERVED, reported on stderr, rc 3 — only a POSITIVELY identified cache may be deleted. If you add a writer to a shared marker path, audit every existing deleter of it in the same change.- A cache may only bind to evidence it can actually fingerprint, and EVERY reader applies the same
rule. The
.settledcache carries anevidencedigest over the verdict shard NAMES, recomputed from the current listing before it is honoured — but a name digest cannot see an in-place rewrite of a plain<head>--<reviewer>.mdshard, and this store exposes no etag or content hash in a listing. So a directory holding any plain shard gets no cache at all (folded for real, every time; append-only directories keep the fast path), both writers refuse to stamp a marker no reader may honour, and every reader goes through ONE decision function,review.settle_shortcircuit— the fan-out once skipped on marker PRESENCE alone and hid a pending reviewer's obligation. MERGED markers short-circuit unconditionally. The projection tier ABOVE the readers is a reader too: its zero-op settled carry may only be taken by a row whoseev_bindableis True; everything else demotes to one listing whose fingerprint compares name+size+mtime per shard and refuses any unclosed minute. When you add a validation rule to a reader, enumerate every tier that can answer BEFORE it. escalateattendance: one shared scan, and partial coverage is NOT an incident. The vacancy sweep answers "did a holder file a verdict recently" from ONE_verdict_activity_indexpass built before the role loop, bounded by BOTH a count (budget, 40) and a wall clock (COORD_ATTENDANCE_SCAN_BUDGET, 30s) — a count alone cannot bound time. The review register is far larger than the budget, so coverage is always partial by design: the stderr envelope reportsattendance=N/Mrather than alarming, and rc 3 is reserved for a WALL-CLOCK cut — a real anomaly.- Prior freshness affects fold cost. A STALE prior requires additional reads
and may exhaust the budget. Because forge completeness follows the review fold,
a stale prior can leave both aggregates incomplete. A SMALL unknown remainder is retried
once inside the same pass (
RETRY_UNKNOWN_MAX, bounded by the SAME deadline object); a tolerance that calls one-short complete was explicitly REJECTED — it manufactures the false-clear this file keeps warning about. A fold "stuck" at n-1 of n is usually a transient, not a broken record. - Never hand two builders ONE budget object. A single
Deadlineshared by the review and forge projections let the review fold spend it first, so forge was not slow — it was never built: a section that always runs last inside a shared budget starves deterministically and silently. Each builder opens its own (COORD_PROJECTION_BUILD_BUDGET,COORD_FORGE_BUILD_BUDGET); worst-case pass duration is their SUM, stated rather than hidden. Completeness coupling is different from budget coupling and must not be "fixed" with it — forge'scompletestill follows the review fold's. - A DELIVERY path may never lose coverage to a FORMATTING failure. A queue renderer that raised
on a malformed event once skipped the cursor save, wedging the cursor on the same poison event
forever without an error report. Two layers, because the field fix alone
guards the instance and leaves the class: rendering is PER EVENT and cannot raise — poison renders
as an explicit, COUNTED POISON line (trading a crash for a disappearance is the worse bug) — and
the cursor save lives in a
finally: once a window has been READ, coverage is a fact about what the process RECEIVED.peekstays the one exit that deliberately does not advance. When you add a step between a read and its acknowledgement, ask what happens to the acknowledgement if that step throws. - Head-of-line: a budget cut may only ever truncate the TAIL — never the head. The work-discovery
folds do live per-op transport at query time over an unbounded population; under budget pressure the cut
must land on the lowest-priority tail, so an agent's OWN assigned work and any decision parked on a
human can never be the thing that goes invisible. Two structural heads enforce this:
- Blocked-on-human is the reserved FIRST section, and it is FREE.
briefingandneeds-merender open rows blocked on a human first, computed byquery.blocked_on_humanPURELY from aggregate rows already in memory — zero extra transport ops, and free is what makes it un-starvable.--on-userTYPES the block asblocked_on: user:<name>(additive; legacy plain values resolve against the caller's already-loaded identity set), and ambiguity resolves toward SURFACING — a hidden human-blocked item is the incident, a false positive only noise. - The caller's own reviews are the review-fold head, on a budget earlier legs cannot have spent.
_pending_reviews_forderives the caller-assigned review slugs for free from the review-request directive rows and scans them FIRST under a DEDICATEDdeadline_seconds, NOT the shared briefing budget's drained remainder (the fix for a livescanned 0/N: the leg used to start already expired on a busy board). The tail keeps the shared budget; truncating it is expected and reportsreview-fold-degraded. A head that STILL cannot complete is UNKNOWN and gets its OWN DISTINCT markerreview-head-degraded— on ANY non-complete outcome: a budget cut, an unreadable review doc, a per-slugTransportError, or a caller-directive slug absent from the listing (fail closed — negative membership in a listing is not proof the obligation is gone; missing slugs are named in amissingfield). The two markers carry PHASE-LOCAL counts and never borrow each other's numbers (an UNKNOWN head reads0/1, never0/0or1/1); a HEAD-only incident emitsreview-head-degradedand NOTHING else. Ship-gate: a new bounded work-discovery fold puts blocked-on-human and caller-assigned work at the head (free where the data is already loaded; a dedicated budget where it is not), proves the head completes under a spent shared budget, and gives "head could not complete" a marker distinct from "tail truncated." - Every marker must RENDER, not just exist:
briefingandneeds-metype-dispatch every review row type they can receive through ONE shared helper (_review_row_line), so an identical row type can never diverge between the two verbs. An unknown/typeless row must NEVER reach the generic task line (which prints[ ?] ? Noneon a marker shape); a degraded/UNKNOWN marker is always shown and NEVER counted as a pending item. Ship-gate: a new review row type joins the shared dispatch with a red-first test that both verbs show its real line and that an UNKNOWN marker is not tallied as pending.
- Blocked-on-human is the reserved FIRST section, and it is FREE.
- Role routing is the same contract, one layer in — a role you hold is an address. A directive
assigned to a ROLE is directed at whoever holds a fresh lease on it, so
briefing,inbox, andneeds-meall fold role-routed work into the holder's queue (that is what makes role-based identity outlive a session). ONE resolver:cli._held_roles_for_rows— never resolve roles a second way, or the folds silently disagree about a lease. It returns(held, unresolved), andunresolvedis the load-bearing half: a role whose lease state is UNKNOWN (transport failure, unreadable lease shard, unparseable role doc, an explicitly invalidsla_hours, or a budget cut) is neither held nor not-held — folding it into an empty held-set renders a clean, role-blind queue indistinguishable from "you have no role work". Every caller surfaces it as_role_degraded_row={"type": "role-degraded", "roles": […]}plus the text line. Ship-gate: a new fold that answers "what needs this agent" resolves roles through that one helper and surfacesunresolved, with a red-first test proving a failed lookup is visible. Only a complete, successfully parsed listing is negative membership evidence — a failed read and a failed parse are the same fact, and the rule reaches into the FIELD: an explicitly invalid value is UNKNOWN (a default is never a substitute for a value someone set and got wrong), while an absent/blank optional field means the default IS the stated intent. Fold that distinction ONCE, inroles.py, and let callers fail closed onNone. The ship-gate extends to write paths:continuity parkonce swallowed a failed listing as "you hold no roles", printed "nothing to park", and exited 0 — silently discarding the checkpoint the next session resumes from._held_rolesnow returns(held, ok); onok is Falsepark fails non-zero saying the checkpoint was NOT written, and a complete fold proving zero fresh roles exits rc 2CHECKPOINT NOT WRITTEN— a command that ACTS on the roles you hold refuses to act on UNKNOWN rather than treating it as "nothing to do". The fold's candidate set is the union of role documents and role-lease directories, deduplicated by role; a lease directory whose role document is absent/unreadable is UNKNOWN, not evidence that no role exists. If any selected role snapshot or checkpoint-ref write fails, park exits non-zero after attempting the remaining roles; rc 0 certifies that every selected save completed. The fold's cost is oneroles/listing + a few ops per role the open work references, and it runs under one cumulativeCOORD_ROLE_FOLD_BUDGET(default 20s) — a cut marks every unfinished candidateunresolved, never "not held". - Presence engagement is an additive, defensively-parsed schema. A presence shard MAY carry an
engagementobject with exactly four qualified names:engagement.mode(resident|session|occasional),engagement.until,engagement.state(active|lapsed),engagement.lapsed_at. Absentengagementreads asresident+active— every legacy shard is unchanged, and a beat with no--engagementflag writes NO engagement field (byte-identical legacy shard, pinned).--engagement sessiondefaultsuntilto beat time + 8h;--untilis meaningful ONLY forsession(anything else is rc 2, nothing written). A beat is REFRESH-SAFE and must never manufacture liveness: a session beat reads its own prior shard first — an ABSENT prior (disproven by one parent listing; the transport read is None-on-any-failure, so the listing is the disambiguator) is a fresh session; an UNKNOWN prior (listed-but-unreadable shard, failed listing) FAILS CLOSED at rc 1, so a transient read failure never lets fresh active engagement replace a sweep-marked lapsed session; a readable prior with malformed engagement self-heals as fresh. A continuing session's resolveduntilis PRESERVED (recomputed only for a genuinely new session; an explicit--untilwins) — sliding it forward on every beat would make a session never lapse. The beat never writesengagement.state/engagement.lapsed_atto a non-default value — those two names are written ONLY by the lapse sweep (below), and clearinglapsedtakes an explicit session re-declaration. Every fold PARSES engagement through the ONE defensive seampresence.parse_engagement(fm)— any malformed input (non-dict, unknownmode/state, unparseable timestamps, asessionwith no resolveduntil) degrades to the legacyresident/activedefault AND sets a visible_engagement_degradedmarker, never raises — and only the liveness combiner (below) acts on it; the pureclassifynever consults it. Ship-gate: any engagement read goes throughparse_engagement(never a raw dict-walk); any new bad-input class gets a red-first degrades-with-marker test; no write path but the lapse sweep setsstate/lapsed_at. - Activity implies liveness. Every engine bus WRITE verb refreshes the
actor's presence timestamp, so a working agent is provably live — distinct from a dead session
whose launchd beat still ticks (the liveness combiner consumes this as proof). Membership is a DENYLIST:
every verb refreshes EXCEPT the declared reads (
status/board/search/needs-me/briefing,presence show,review status,queue,health,doctor,obligations,roles status,continuity resume) and the plainpresence beat. It was once an ALLOWLIST of functions, which could not keep this paragraph's promise — a verb added later was simply absent, and absence there is indistinguishable from "this agent is not working". Many write verbs had drifted outside it (review close,escalate,continuity snapshot/park,roles claim/release,answer,bus-v3 send,stash push…), so an agent whose job IS reviewing renderedstale — nudgewhile working. Roster liveness can trigger follow-up work, so active writers must not be omitted from coverage. The work axis. Verb coverage alone cannot see work that never passes through a verb (report docs are written straight to the store), sopresence.livenessalso takeswork_ts(newest work-artifact time, read-derived by the caller) plus a three-valuedwork_scan(NONE|COMPLETE|PARTIAL): NONE → byte-identical legacy behaviour; COMPLETE → absence is a real finding (no work found); PARTIAL (budget ran out, unreadable listing) → no imperative at all, because the refuting artifact may be in the unscanned part —list_dircannot tell an empty directory from an unreadable one, so only a COMPLETED scan licenses an absence reading.presence showandbriefingmeasure, both bounded (COORD_PRESENCE_WORK_BUDGET, default 20s; NBenv_floatis POSITIVE-finite — a0falls back to the default, it does not disable). Scan order is load-bearing: agent reports (a handful of listings) run BEFORE the review sweep (hundreds) — with reviews first, the sweep consumed the whole budget and PARTIAL muted the nudge fleet-wide. The sweep is now the POINTER-LESS FALLBACK only: per-agent work EVENTS (_coord/agents/<agent>/work/<iso>-<digest>.json) answer the read-side question in one listing + one read per agent, and are IMMUTABLE ON PURPOSE — the store has no conditional or versioned write, so a shared mutable pointer cannot be defended (review reproduced an older stamp clobbering a newer one, and a delete-on-failure that could erase another host's fresh write). A writer only CREATES its own event, "newest" is a deterministic fold over ISO-led names, and a failed write leaves prior events intact (slightly stale, never wrong) — NEVER add a delete-on-failure here. Four pinned rules: ONE write site (the activity chokepoint, so a new write verb stamps by default); refusal semantics (stamped only onrc == 0, monotonic, missing/corrupt is UNKNOWN and never "did nothing"); transitional (a pointer-less agent falls back to the sweep); attributable (kind+path). NB the pointer is keyed by the RAW agent name, NOTtasks.agent_key()— the hashed form would file every pointer where no reader lists. The continuity audit deliberately does NOT consume work evidence: "working but not snapshotting" is precisely its finding, and the asymmetry is chosen. Classification is PER-OPERATION, not per-function. Several handlers serve both a read and a write:queue TEAMvsqueue commit TEAM(and--consume, which advances ANOTHER agent's cursor),inbox TEAMvsinbox --ack,digest TEAMvsdigest --store. Keyed on the function alone these were wrong in BOTH directions at once —queue commitrecorded durable classifications without counting as activity, whileinboxanddigestrefreshed presence merely by being VIEWED._MIXED_MODE_ACTIVITYmaps such a handler to a predicate over the PARSED ARGS, and_is_activity_invocation(args)— not the function-only helper — is what dispatch calls. Verdict shards are APPEND-ONLY (standing ruling). Two forms are first-class, permanently:<head>--<reviewer>.md(hand-writers, unchanged) and<head>--<reviewer>--<iso>-<digest>.md(the verb) — the store has no create-if-absent and no versioned write, so writing a SHARED name is check-then-write and cannot protect evidence (a concurrent CHANGES was reproducibly overwritten by APPROVE at rc 0); a unique name touches no existing file. Every register reader folds newest per (head, reviewer), ties break on the name, and supersession is never silent (superseded_verdictsis reported). A correction is a NEW shard, and a new verdict INVALIDATES the settle cache — only the cache (the evidence-binding rules above); astate: MERGEDmarker survives a late verdict. Every reader dates a plain shard the same way: filename ts, then frontmatter ts, then normalized listing mtime.review verdictexists so that filing a verdict IS an engine write (it was the one act with no verb, which left reviewers invisible to every liveness fix). It is SUGAR over the same artifact — it writes the append-only<head>--<reviewer>--<iso>-<digest>.mdform in the round's verdicts directory, and DIRECT shard-writing of the plain form stays valid. It never overwrites: the name is unique, so a second filing is a NEW shard that supersedes the prior one (below), never a replacement of evidence a merge may rest on; a changed head is a new round. Every registered command must be CLASSIFIED, read or write or mixed:tests/test_activity_covers_every_write_verb.pywalks the real argparse tree and fails on any unclassified command (a regex cannot decide this — several verbs persist only through helpers)._ACTIVITY_READ_FUNCSis completed at module end, after the extracted command modules import — assembled earlier, it let view verbs refresh presence merely by being READ, the worse direction because it suppresses the nudge for an agent who really is gone. The hook lives at the single dispatch chokepoint, fires only onrc == 0, and the actor is the WRITER (--from/FULCRA_COORD_AGENT; the anonymous reconcile fallback is not a presence identity). Two pinned constraints: THROTTLE — at most ONE presence write perpresence.ACTIVITY_REFRESH_INTERVAL(60s) per process, via a monotonic-clock memo; and FAILURE ISOLATION — a refresh failure never fails the successful bus write (one stderr note,rcuntouched). The refresh is a TIMESTAMP BUMP, not a beat re-run: it rewrites ONLY the top-leveltimestampline and preserves every other byte verbatim, so it never slides a session'suntiland never writesstate/lapsed_at(sweep-owned). The minimal-beat fallback fires ONLY onlist_dir-CONFIRMED absence and FAILS CLOSED on any UNKNOWN — failure isolation never means destructive fallback. Ship-gate: the throttle memo is process-global state — reset it between tests; a new write verb is activity by default (denylist), a new READ verb joins_ACTIVITY_READ_FUNCS, and a mixed handler joins_MIXED_MODE_ACTIVITY; the preserve-everything-but-timestamp rule stays red-first pinned. - A CHANGES is lifted only by a shard that NAMES it (
supersedes:), never by the clock (2026-09-05, codex-coder, review-winning-envelope r4). Client timestamps cannot carry the correction contract: a CHANGES filed later from a host whose clock is behind sorts EARLIER, the old APPROVE wins, and a ship gate validates withdrawn consent. The fold is now: a shard is RESOLVED when another shard of the same reviewer names it insupersedes:(validated against shards that exist); any UNRESOLVED CHANGES dominates regardless of timestamp; otherwise the newest live shard wins; equal keys and unnamed conflicts fail closed to CHANGES.review verdictnames every prior shard of yours it can list; if the listing is degraded it names NOTHING and says so (your prior CHANGES keeps dominating until you re-file). A hand-written APPROVE must carrysupersedes:itself. Only the STORE can supply causality (r8, both codex reviewers): a name is predictable, and a client-written nonce is editable frontmatter at a mutable path (a plain CHANGES rewritten in place kept its nonce and an old edge still resolved it; a predeclared nonce was matched by a later CHANGES). An edgename@sha256:<digest>is honoured only when the digest matches the target's CURRENT bytes AND the store's server-assigned mtime proves the target strictly earlier than the superseder — same minute or unknown fails closed; a bare legacy name needs the same mtime proof. The verb quotes the content digest of each prior it can list AND read; a prior it cannot read is not named; on a degraded listing it names NOTHING (if you cannot enumerate the priors you cannot claim to supersede them). The randomnonce:also feeds the digest in the shard NAME, so identical same-second filings cannot collide. Invalid edges: a shard can never resolve ITSELF (a self-link let a CHANGES erase its own withdrawal); self-links and names that resolve nothing are reported in the tally asmalformed_supersedes, never folded around silently; a cycle fails closed to CHANGES; a forward edge cannot be forged (the name embeds a content digest). This amends ruling b99fb8da (newest-wins): constraint 5 — a stale CHANGES must not block forever — is satisfied by the link the verb writes, not by the order of the clock. - Same-second verdict shards order by chronology, not digest (2026-09-05, both codex reviewers,
coord-fold round 12). The append-only name has SECOND precision plus a content digest, and the
fold broke same-second ties on the name — so an earlier APPROVE could outrank a later CHANGES from
the same reviewer (reproduced: digest
feb86aeeover058ddb93). Nowreview verdictwrites a microsecondts:in the shard frontmatter and the fold orders every shard byreview.canonical_sort_key— the second from the ACL-controlled NAME (frontmatter can never move a shard across seconds), the fraction from frontmatter only within that second,.000000for shards without one so legacy and new compare in ONE format.review status --jsonnow carrieswinning: {reviewer: {name, verdict, sort_key}}— the exact shard the fold kept. A downstream consumer (a ship gate) readswinning; it never refolds filenames itself. The projection (projection.py) uses the SAME key and recordswinningin each generation row, and the generation-backedreview statusfails closed (rc 3) on a row without it — two canonical readers must not answer differently about one directory. Caveats, pinned by test: two legacy shards with nots:in the same second still tie on the name; the verb samples the clock ONCE for both the name's second and the frontmatter fraction (two samples let a verdict straddle a second and lose to an earlier same-second shard); and the resulting order is client-timestamp order, not a provable arrival chronology — cross-host clock skew is out of the fold's reach, and two shards with equal microseconds tie deterministically on the name. - Engagement-aware liveness is a combiner over two ORTHOGONAL axes.
classify(ts, now)stays PURE — freshness only (live/idle/stale), a function of the timestamp alone. The truth table is layered on top bypresence.liveness(shard, now=…), which returns{state, freshness, annotation, engagement}. STALENESS (timestamp freshness) and DORMANCY (asessionpast itsuntil, boundary-inclusive, OR a durable sweep-writtenengagement.state: lapsed) are INDEPENDENT and rendered as two facts, NEVER a merged label: a dormant shard renders primary state LAPSED — distinct from stale/dead, EXPLAINED, ROLE-RETAINING — with the freshness axis in the annotation (a session overrunning its window while beating is honestly LAPSED+active, a nudge to extend, NEVER silently live). A degraded engagement reads as the legacy default and can never manufacture dormancy; all agent lookups match by EXACT id (no substring/fuzzy). The verdict rides ADDITIVELY: roster rows keepliveness= the pure freshness band (existing callers read it; its meaning must not shift) and gainstate/freshness/annotation.engagement gate <team>is the deterministic mixed-fleet gate: every LIVE roster agent is COVERED iff it beats with well-formedengagementOR appears in the operator map_coord/router/engagement-defaults.json; PASS iff all live agents COVERED. READ-CONTRACT LENS (mandatory):transport.readreturnsNoneon BOTH missing and failure, and alist_dirdegradation must never fold to empty, so a falsy read/listing is NEVER "confirmed absent" on its own — an UNKNOWN on either of the gate's reads (the defaults file, or the presence ROSTER via_presence_shards_status, which preserves degradation instead of swallowing aTransportErrorto[]) is DEGRADED, fail closed — never PASS on unknown coverage (an empty gate passes vacuously, so an UNKNOWN roster must never look confirmed-empty; an unparseable shard is UNKNOWN coverage, never a synthesized phantom row). Only a CONFIRMED enumeration may PASS; a confirmed-EMPTY roster still passes vacuously. The vacancy/escalation SEMANTIC change is gated, and the gate ships dormant by default — enable it explicitly: LAPSED rendering lands unconditionally, but reading a LAPSED session role-holder as EXPLAINED ABSENCE (suppress the vacancy escalation with a note) activates ONLY when_engagement_gate_passes(team); otherwise behavior is today's, verbatim. BOTH branches are red-first pinned. Ship-gate:classifystays pure; any new dormancy/coverage input class gets a red-first test; the gate fails closed on any UNKNOWN; the gated semantic change keeps both branches pinned until the gate is satisfied fleet-wide. - The zero-token lapse sweep writes two fields and nothing else.
coord-engine engagement sweep <team>is a host-tick, model-free pass that marks a session past itsuntilas LAPSED by writing EXACTLYengagement.state: lapsed+engagement.lapsed_atinto the presence shard — the ONE sanctioned exception to agent-owned presence writes, scoped to those two names. MARK predicate (presence.sweep_decision, the pure read-only seam, viaparse_engagement): mark iffmode == sessionANDuntilpresent ANDnow ≥ untilANDstate == activeAND engagement WELL-FORMED; anything else SKIPs (fail-closed — a malformed shard NEVER manufactures a lapse), and an already-lapsed session is an idempotent NOOP. The write preserves everything but the two fields —timestampNOT bumped,untilNOT slid, body verbatim — and NEVER parks, NEVER releases roles (operator decision: park is explicit-only). If enumeration raises, the roster is UNKNOWN and the sweep is DEGRADED — loud, rc 1, never a clean0 marked; a per-shard failed read SKIPs into thedegradedbucket (a failed read must NEVER cause a write); a per-shard write failure is reported and the sweep continues.--dry-runpreviews and writes nothing; rc 0 only on a clean sweep. Downstream consumers (e.g. a deployed router) read the marker for reduced-cadence check-ins;lapsed → activeclears only via an explicit session re-declaration in the beat. Ship-gate: the sweep writes ONLYstate/lapsed_at; the mark predicate stays fail-closed; enumeration-degrade is loud + rc-nonzero; idempotency and the two-field-only / never-park / never-release invariants stay red-first pinned. - The rc / error register a bus reader parses. Machine
typefields ride the degraded fold rows (*-degraded); the single-slug verify paths are prose at rc 1, where the convention is load-bearing: the prose ends in "…, retry" iff the failure is retryable (a transient unknown — e.g.review statustally unknown, retry,roles statuslease state unknown … retry,tellcannot verify delivery, retry) and names a tombstone or ABSENT iff terminal (areview statuson a soft-deleted review, or on a slug that was never created — a retry never changes either). An UNEXPECTED exception is neither: the top-level guard emits a registered envelopecoord-engine: error: command=<cmd> type=<Exc>: <msg>(rc 1) — theerror:token distinguishes an engine fault from a retryable degrade. Views never lie past the current read — the index-freshness invariant. Two mechanisms keep
status/board/inboxhonest between heartbeats, so a same-minute close or a between-tick directive can't leave a surface stale:- Same-minute-touched docs are reparsed, not reused. The store
file listmtime is minute-granular, so reconcile reuses a prior summaries row only when the doc is unchanged by mtime AND byte size AND its mtime-minute is provably closed before the last reconcile read; a row stamped by an olderROW_SCHEMA_VERSIONis likewise reparsed once, so a projection change self-heals the whole index within one full pass. - A feed delta surfaces new docs THIS read. Healthy-path folds combine the aggregate with
team-filtered
data-updateschanges and read only the changed task docs; on any doubt the legacy freshness overlay lists the task dir once, bounded (COORD_OVERLAY_CAP/COORD_OVERLAY_BUDGET) and degrading theinboxsource visibly when capped — never silent truncation. - Acks are folded change-driven, and reuse needs positive evidence. Reconcile asks the store
what changed since the ack fold's OWN anchor (
acks_folded_through, notgenerated_at) and re-folds only those slugs; a prioracked_byis reused ONLY when the store answered and did not name that slug — every unknown falls back to the full fold and logs why. No false advance: a fold that couldn't read what it meant to leaves the anchor in place, a failed listing preserves the prioracked_byrather than un-acking, and a forced full fold everyCOORD_ACKS_FULL_EVERYpasses (default 72) bounds anything the query could miss. - Reconcile's own pass is a feed delta, not a directory scan. It consumes
data-updatessince a durable cursor (reconcile_cursor— watermark + processed ledger) and reads ONLY the changed shards. The fulllist_dir(task/)scan stays as (a) a scheduled drift self-check (everyCOORD_RECONCILE_FULL_EVERYpasses) whose divergences are logged LOUD and rebuilt from the full scan, never silently absorbed and (b) one named recovery for an established cursor when the outer feed coverage boundary/frontier alone is unavailable or unparseable. Thatdetector-full-scanrecovery is visible in the result/log, rebuilds canonical sections (including absent generation substrate), seals the rebuilt snapshot into generation identity, and preserves the old proven watermark; it fabricates no feed advance. An absent manifest cold-starts exactly one generation; an identical later recovery reuses that generation rather than minting a chain whose only change isprior_generation_id. Every other detector UNKNOWN aborts before listing canonical tasks. An incremental row is stamped byte-identically to a full-scan row. Ship-gate: a new reconcile fast path keeps the periodic drift check, restricts recovery to that exact reason family with a prior proven watermark, and its cursor key is cut frombuild_aggregate's passthrough and recomputed in full every pass. - summaries.json is one shared doc written by many hosts at many versions — a top-level key
added in version N is wiped by any host older than N, which rebuilds the document from the
key set it knows and writes it over everyone else's (this is how
acks_folded_throughkept vanishing while any pre-passthrough host still reconciled).build_aggregatenow carries unknown top-level keys through. A preserving older host that carries the projection-publication fence but cannot mint its section bindings is fail-closed by newer readers; a host older than the passthrough can still remove any fence. A general new top-level key is live only once the whole fleet is upgraded — checkhealthbefore assuming a fold-state key is doing anything, and never rebuild the aggregate from a fixed key set. The same last-writer-wins shape applies toreconcile_cursor: a pass writes the cursor it STARTED from (or advances it), so a pass that began before another host's re-anchor would roll that cursor back. Immediately before publishing — on every path, including the no-change fast path —reconcilere-reads the store's cursor; if its watermark is strictly newer than the one this pass started from, the pass skips its generation + summaries write and its health shard readsadvanced: false,degraded_reason: superseded by a newer cursor in the store(never "keep the newer cursor over my rows" — those rows never saw the changes in between). Equal/older writes as before; an unreadable store cursor writes as before and logs it. This is a narrowing, not a fence (no compare-and-swap, so a write can still race the re-read), and it protects only against hosts running the build that has it.
Mechanics (stamping, deterministic cut, the reconcile reuse anchor) live with the engine —
fulcra-agent-reconcileandpackages/coord-engine.- Same-minute-touched docs are reparsed, not reused. The store
- Idle-agent parking (standing, operator-set). An agent with 48h of no
work in its queue parks a continuity checkpoint to the bus
(
coord-engine continuity park <team> --agent <self> --objective "<what you watch>" --next "resume on directed wake or new assignment") and drops to a coarse daily check; a directed wake or new assignment resumes it (continuity resume). Dormant watchers must not burn compute indefinitely; the parked checkpoint loses nothing. Applies to every agent, the coordinator included.continuity parkexits rc 2 when no fresh role is held and writes no checkpoint — treat that as "not parked", never as a clean no-op. snapshotis the routine save;parkmeans you are LEAVING. Both write a checkpoint, so it is easy to treat them as interchangeable and reach for the one a rule happens to name. They are not interchangeable:continuity snapshot <team> <agent> <slug>— a PROGRESS save. This is the form forcheckpoint-on-every-wake: you did material work, you are still here, here is the state you left.continuity park <team> --agent <self>— a SESSION-EXIT save (its own help says so): you are going away, so snapshot every held role at once and set thecheckpoint_refs. Use it at genuine handoff, at dormancy (above), and on the wake youroles claimso the new role starts with a checkpoint. Do not park on every wake — it announces a handoff you are not making, repeatedly, and drains the meaning from the one signal that should mean "this agent has stepped away".
- park's rc 2 proves only that NO FRESH HELD ROLE WAS FOUND — nothing more.
That one exit code covers two opposite situations and the fix differs: an
assigned/expected role whose lease lapsed →
roles claim(left unfixed the role sits VACANT past SLA and role-routed work reaches no holder); intentionally role-less (the steady state for most workers) → usecontinuity snapshotfor progress saves, and do NOT fabricate a role merely to makeparksucceed. Checkroles status <team> <role>before concluding which case you are in: rc 2 is a lease diagnostic, not an identity verdict.continuity resumealways reports the checkpoint age (JSONcheckpoint_age_seconds); use--max-age 1hwhen a wake or acceptance run must fail rc 2 on stale state — JSONerror_codeseparates invalid duration, unknown age, and stale; small future clock skew clamps to zero, farther-future checkpoints fail loud. - Delivery rule. The human-visible report is a turn's (or tick's) terminal output — composed last, after every tool call. Text followed by more tool activity may never render ("sent" is not "delivered"), so anything that MUST reach a recipient (human or agent) goes on the bus as a durable artifact (ask, review doc, snapshot), never only in session text.
- Backlog. A "do later" item goes ON THE BUS:
coord-engine later <team> "<title>" -s "<context>"parks it on the@backlogaudience (durable, visible on theboard, spams no inbox); route it later with the ordinary assignment verbs. Backlog in session memory alone dies at compaction. - Intent-capture doctrine — a spoken commitment is filed the SAME turn. When
the operator states an intent to ANY agent ("later today", "I'll enumerate
that list", any commitment they own), that agent captures it immediately with
coord-engine intent <team> "<text>" --for <principal> [--by <when>]— an uncaptured commitment is the drop nobody can see. Two surfaces back this:coord-engine intent <team> "<text>" --for <principal> [--by <when>]— sugar over the directive path (writes anintent:<principal>item,intent_byfrontmatter, hash-slug delivery + read-back inherited). Identity is text + assignee only —--byis EXCLUDED. So an identical restatement dedupes (rc 0intent already captured), while a restatement with a DIFFERENT--byis a verified in-place window update on the same doc (rc 0intent window updated, read-back-checked; unverifiable → rc 1, retry — never a stale deadline, never a forked item). A relative--by(5d/36h/10m) re-resolves from now on each restatement.coord-engine threads <team> --for <principal> [--json]— the dropped-work fold, three mutually-exclusive modes (first match wins): started-then-silent (an item the principal owns/last-touched, quiet past--silence-days, default 3); blocked-on-operator (progress waits on the principal —assignee: <principal>, ablocked-on:<principal>tag, or aneeds:humanblock naming them — surfaced immediately, no aging); intent-never-started (anintent:<principal>item past its window and not followed up). A terminal item (done/abandoned) is NEVER a dropped thread in any mode — the fold refuses it and reads the authoritative status from the task doc, not the summaries index (a same-minute close can leave the index stale). Athreads-degradedrow means the fold saw only PART of the store — sweep or wait, never trust it as complete;--jsonis ONE array, not JSON-Lines. The coordinator role typically runs this fold in its loop and owns the curation/push call.
- Blocked-on-operator doctrine — a harness approval-gate is a bus event (operator order). When work waits on an operator/harness approval that only a human can grant (a "nod before you build", a deploy sign-off, an entered credential, any approval you cannot self-serve), the blocked agent does THREE things the same turn, not one: (1) immediately post a P1 BLOCKED-ON-OPERATOR shard to the coordinator role naming the EXACT approval and the EXACT artifact it gates (PR #, slug, host) — so the block is a visible, routable bus item, not a private wait; (2) continue all non-blocked work — the block scopes to the gated artifact, never to the agent; idle-while-blocked on one item when other work is ready is itself a failure; (3) keep beating — a blocked agent is still live and must stay so. Silence-while-blocked is a protocol violation: never let an operator approval turn into an invisible stall (the failure this codifies). The operator's absence is never approval — surface the block loudly and persistently, and take the other ready work meanwhile.
- ATC (air-traffic control, alpha). On a subscription-cap fleet, consult
coord-engine route <team> --needs <tags>before a dispatch to pick the cheapest model that covers the work, and log the outcome after withcoord-engine usage log; the ledger feeds the headroom fold and demotes a model that keeps failing a task class. Rubric, routing procedure, and the coordinator-join surface (atc harvest, bindings,route --for-role):fulcra-agent-atc. - Timeline projection (opt-in).
coord-engine annotate resolution <team> transitions(defaultoff) makes the heartbeat project task transitions onto your Fulcra timeline model-free, right after each reconcile;annotate status <team>shows the level + cursor. It is the successor to the legacy first-generation annotations writer, which is now retired (see Fulcra platform surface). Projection needs the typed-record writer (fulcra-common) installed beside coord-engine (uv tool install … --with fulcra-common); without it the step is an explicit exit-0 no-op. Setup + install recipe:docs/coord/GET-ON-THE-BUS.mdandfulcra-agent-automation.
Operator knowledge: vault + prefs
Long-running work with the operator accumulates knowledge about them. Store it on Fulcra the turn it is stated (the same capture doctrine that applies to intents), split by kind:
- Facts about the operator's world — people, companies, places, pets,
routines, the semantics of their Fulcra data ("a hike on X road is always a
dog walk") — go in
fulcra-vault: a markdown knowledge vault in Fulcra Files (live today; it also hosts the meeting CRM). Write an owned section under your agent id, add a log line,reindex; give entities their own wikilink-able notes. The CLI works from any authed host. - Preferences — how the operator wants to be served: tone, format, defaults,
per-platform overrides — are
fulcra-prefssignals (typed, decaying, confidence-weighted, deterministically compiled). Iffulcra-prefs capturefails (the layer is alpha), do NOT drop the signal: store the statement as a vault note and queue the signal keys there for capture once the layer is up. - Retrieval, today: both layers inject at session start — vault
install-hooksloadsHOT.md, prefs compiles per-platform docs into the boot context. Beyond the hot set, the convention is judgment-based: when a person, company, place, or project is named in your work, consult the vault (fulcra-vault read MAP.md,backlinks) before asking the operator or guessing. Deeper retrieval (search/MCP) is future work — storage now is what makes it possible later.
Coord-engine 2.0 truthfulness boundary
The separate coord-v5 alpha is the new work-core release track, not an upgrade of the installed Python engine or an activation of the v4 cutover. Its release status separates packaging, usable operations, agent acceptance, and upstream release. Do not change an existing team's authority, schedules, or historical work when trying the alpha. Its Node runtime and explicit enrollment requirements belong to that package only; Collect and the web application are not prerequisites.
For new v5 enrollment, use the package's onboarding guide
and capability-evidenced coord-v5 enrollment plan; keep one native listener
registration per environment/harness. A worker keeps its own native wake until that
environment's listener wake is verified end to end, and keeps it afterwards as a
coarse backstop; never retire a worker wake on registration or delivery evidence
alone (harness guide). Its plan is not an installed schedule or
a membership grant. Current verified event ingress selects native-event without
requiring a schedule/loop when read, publish, checkpoint, dispatch and explicit
unattended opt-in are satisfied; a verified schedule is a backstop. A reporting
listener routes attention to separate workers, while deliberate self-ticking
owned-task execution is a separate opt-in mode. Planner mode is not event-adapter
support or idle-wake proof. enrollment instructions accepts optional
instruction_mode: worker|listener|executor; omitted and explicit worker modes
produce the same managed block. Regeneration updates older managed prose while
preserving surrounding text. Apply listener/executor blocks only in their own local/session
instructions, not shared repository-wide worker instructions. The listener reports
its own reads/routes/conflicts/reconciliation, not worker progress/completion or
fabricated receiver acknowledgment. Executor work needs explicit task ownership
and recovery context; a wake is not authority to adopt work. No instruction mode
installs a schedule or grants permissions; self-ticking requires separate authorization.
Generation/CLI tests are not proof of agent obedience. Preserve the distinction between contact, inbox observation,
progress and checkpoint clocks. Role claims survive in annotation history but
are not distributed locks; partial source views cannot authorize exclusive
takeover. Keep private descriptors and managed workspace instructions local.
In v5, current source health can recover after a strictly newer successful read;
historical errors remain in the observation journal and coverage remains partial.
coord-v5 transport read journals failed observations and preserves cached work,
but exits nonzero when the current read is unavailable; clean partial reads remain
nonfatal and never imply absence.
Use checkpoint prepare to obtain normalized checkpoint content and its canonical
digest before publication; raw artifact integrity and canonical body integrity
are separate checks. A receiver can run coord-v5 checkpoint verify --artifact ABS
--publication ABS on private local files to measure exact raw SHA256, normalized
body digest, and scope/identity bindings; this is not remote retrieval, access,
native-wake, or source-completeness proof. Artifact bytes are capped at 256 KiB,
publication JSON at 64 KiB, and validated checkpoint content at 128 KiB.
Native action generation is not evidence of a delivered wake.
The v5 runtime's explicit host-injected dispatchCodexWake supports only scope
harness codex and privately bound desktop thread/host targets. Trusted native
read/send callbacks are required; injection does not prove authority or grants.
It requires exact idle preflight by default. A host may explicitly opt into
allowColdWake:true for exact native notLoaded evidence after verifying its
existing sender can load the enrolled target; this is not idle or event-ingress
proof. Busy/error/unknown evidence still holds delivery. It commits a SQLite
claim before sending once,
and retains claimed/uncertain attempts without automatic retry. Each callback
has a bounded observation timeout, not cancellation. Acceptance is not receiver
acknowledgment or work completion; synthetic tests are not live acceptance.
See the Codex dispatcher contract.
The v5 listener's opt-in dispatch-claude command resumes a privately bound
claude-code target {kind:"claude-code",sessionId:UUID,cwd:ABS} using a trusted
absolute operator-supplied executable; pass the prepared action's .arguments
on stdin. It fixes flags requesting full model ID claude-haiku-4-5-20251001
and a $0.25 provider budget, with safe-mode/tool-free/strict-empty-MCP flags.
It claims before spawning and bounds runtime/output. Exact argv does not
guarantee the served model or provider
billing: inspect actual assistant-model telemetry, not auxiliary modelUsage.
The served model may differ from the requested model ID; sub-budget success does
not prove a hard spend ceiling. Only exact native success is accepted,
never acknowledgment or lifecycle proof. Claimed/uncertain invocations never
retry automatically; reconcile exact receipts after confirming the old process
is no longer executing. The same-session fence covers one local journal/scope,
not other processes/journals/scopes. Keep native routes and CWDs private; do not
sign in, create sessions, change credentials or force takeover as dispatch setup.
Synthetic fixture success is not authenticated native acceptance. See the
dispatcher contract.
coord-v5 handoff verification import --config ABS --db ABS --receipt ABS
retains a private, scope-bound operator attestation through restart. The receipt
envelope is {schema:"handoff-verification/1",principal_id,workspace_id,
workstream_id,stream_id,package,verification}; package bytes bind the offer
digest and exact access-requirement set, and referenced ready/offer/publication
events must already be in the authenticated local journal. Views consume valid
retained checks automatically, fail unavailable on tampering, and refuse expired
pending readiness. A historically accepted owner is not revoked merely because
checks expire later: with multiple ready events, preserve only proofs in the
replay-accepted transfer's causal history. Identical authenticated source copies
count once for receipt bindings; differing event content under one ID fails
closed. Import does not independently verify remote artifact bytes,
remote permissions, native wakes, or source completeness; do not describe it as
a verifier adapter or use partial coverage to claim all-clear or takeover.
Current proof validity is its own fact, never merged into handoff state. Every
handoff row carries verification: {state:"valid"|"expired"|"absent"|"unknown",valid_until,
ready_event_id}. An accepted row binds this fact to the exact ready event named
by its accepted event, which may differ from the first retained ready displayed
on the row. Causal acceptance and proof validity are orthogonal: a clock must
never un-accept a causal event, so an accepted handoff whose checks lapsed keeps
state:"accepted", unchanged ownership and no recheck diagnostic, while
reporting verification.state:"expired". Pure replay defaults the verification
clock to asOf; an explicitly malformed verificationAsOf yields unknown
while preserving causal state and ownership. Replay returns early without an
asOf, so no row claims validity without a causal clock. absent means no
retained receipt resolved and only occurs before readiness.
2.0.0 ships the truthfulness spine only: typed command outcomes, exit status
that agrees with the body, deterministic identity precedence, and distinct
empty, tombstoned, unreadable, and unknown states. Those direct canonical-read
paths are the required fleet-adoption target.
Generation-backed public serving is dormant in 2.0.0. Do not run or require
the cancelled epsilon measurement, set public_read_epsilon_verified, treat a
current generation as public authority, or infer that authority from the release version.
Cursor schema 2 remains a separate activation that requires its own fleet
version fence and proven CAS transport.
The 2.0.0 tag set FulcraFileTransport.public_read_v2_enabled to true, so
migrated folds entered the unverified generation wrapper and returned
UNKNOWN before their canonical handlers ran. 2.0.1 and later set it to
false, making dormant serving real; adopt a later release, never 2.0.0.
This is a source fact, not evidence of which build any live host runs.
Fleet adoption is functional, not epsilon-based. Every live host within the
recorded SLA must run the exact released build (with named, evidenced
exclusions), and at least two credentialed hosts must verify queue,
needs-me, review, forge, roles, presence, and reconcile through the direct
canonical paths. Any required UNKNOWN, degraded fallback, or nonzero result
blocks the adoption claim. Release, adoption, generation serving, and cursor-v2
activation are four separate facts; never use one as evidence for another.
Working tree
Prefer a per-agent git worktree, not a shared checkout — concurrent
sessions sharing one working tree clobber each other's index/HEAD
(interleaved commits, orphaned merge conflicts). Each session gets its own tree
(and its own per-cwd identity): git worktree add ../<repo>-<purpose> -b
<vendor>/<purpose> origin/main. Conflict markers or staged files you didn't
create mean you're sharing a checkout — move out before committing.
A worktree does NOT isolate the stash stack. Stashes live in the shared
.git, so git stash in your own worktree reaches into the same stack every
other session uses. A git stash push with a pathspec that matches nothing
succeeds silently and stashes NOTHING — and the git stash pop you pair it with
then pops somebody else's entry into your tree, as a conflict you did not cause.
If that happens: git checkout HEAD -- <their paths> to restore, and CHECK
git stash list afterwards to confirm their entry survived. Prefer a scratch
commit on your own branch over git stash entirely.
Commits
End the commit message with the trailer
Co-Authored-By: <your model> <user@example.com> (e.g.
Co-Authored-By: Claude Opus 4.8 (1M context) <user@example.com>).
Credential custody (bot tokens)
Where a team runs a machine (bot) forge account, its credential custody is team-store material, not repo material. The generic doctrine:
- A bot PAT is read at runtime from a secret store, never embedded — never
in an OS scheduler plist (plaintext at rest) and never in argv (visible in
psand shell history). - Rotation is stage → verify → promote: verify the candidate under a staging name before overwriting the incumbent — a piped empty value can wipe a keychain entry silently and still exit 0, so always paste at the interactive prompt — and rotate EVERY home the credential lives in BEFORE revoking the old token.
- Agents cannot mint tokens — an expiring token needs an armed operator reminder on the team bus. Never let a token value reach argv, stdout, shell history, a repo file, a scheduler plist, a log, or a chat transcript.
Documentation rules (standing, operator-set)
Public documentation uses synthetic identities, account IDs, host names, and data. Keep personal content, team rosters, live measurements, deployment incident records, and private approval history in the team's own storage. Examples must let a new user configure their own team and recipients without inheriting a live account.
Write installation and plugin setup for the person using the tool, including someone who has never opened Terminal. Agent and contributor guides can assume their stated technical context. In both cases, readers should be able to follow the instructions without knowing the maintainer's machine or account.
Standing rules:
- Truth over aspiration. Document live, verified behavior; stamp verification dates and drift headers where the platform moves faster than the repo (the FULCRA-PRIMITIVES pattern). Doc claims get adversarially reviewed like code.
- Exact commands, exact paths, canonical form. Bare
coord-engine, neveruv tool run coord-engine(not on PyPI). One wrong documented filename made role-gated reviews structurally unapprovable (v1.6.4 fix) — path precision is correctness, not style. - No dead or broken references (operator rule, 2026-07-14): relative links must resolve, referenced files/commands/sections must exist, and mentions of real repo things should BE links. Sweep on every docs QA pass.
- Teach fail-loud, never fail-quiet. No documented pattern may swallow errors; if a leg degrades to a no-op without its backend, the doc says so in bold (the silent-writer darkness).
- Docs ship with the change, same PR, dual-green. Docs debt is in scope, never a follow-up. This file is the ship-gate.
- One canonical home per fact; everything else links to it. Scattered version pins and duplicated doctrine are drift bombs.
- Historical docs (proposals/, superseded designs) carry a historical banner instead of being rewritten; broken references get fixed even there.
Writing for upstream (issues & PRs to fulcradynamics/*)
Findings go to Linear, never to GitHub issues (operator rule, 2026-10-01). File findings as Linear tickets on the appropriate board (Platform/PLAT unless clearly another team). Never open GitHub issues on fulcradynamics repos. Why: the engineers triage in Linear, and an issue opened on a product repository lands outside their queue and has to be migrated by hand (fulcra-api-python issue 115 was, on the day this rule was written). This covers every agent and courier on the fleet, whatever account it files under. Pull requests upstream are still allowed where a session has the access; the writing rules below apply to those and to the Linear ticket text.
Upstream reports must be understandable without reading this repository.
- Succinct. First sentence states the bug. Repro, expected, actual, one self-contained piece of evidence (a curl, a traceback). Ten lines.
- Their vocabulary only. No fulcra-tools terms, codenames, or links — evidence must reproduce from their code alone.
- Everything else — discovery story, fleet impact, workarounds — stays here.
Filed by a courier, and it says so. Most sessions cannot reach repos outside the one they were launched against, so upstream work is filed by a session that can — which means the only identity upstream sees belongs to the carrier, not the author. Close that with the last lines of every upstream PR or issue body, above the Claude Code footer:
Filed by `<courier>` on behalf of `<originator>` — automated agents operating on one maintainer's account. Replies reach the originator.One name and no "on behalf of" when they are the same agent. Attribution here is ROUTING, not credit: it tells upstream who can answer and tells us whose work is in that thread. Identities only — no internal paths, task ids, or topology; the rule above still applies to this line.
- Name the access level before promising delivery. Report what the API says — pull/push/maintain/admin — and which of file, merge, approve-CI it permits. Filing from a fork needs read; merging needs write. "I have access" is not an answer.
CI and workspace membership
- macOS CI is path-filtered and bills at 10×, so it only runs on changes
under
packages/**,skills/fulcra-agent-automation/**, the workflow file itself, and the dependency manifests (pyproject.toml,uv.lock) — see.github/workflows/macos.yml;test_ci_trigger_coverage.pyfails if trigger and coverage drift apart. Everything on Linux (uv-workspace.yml) runs on every push/PR tomain. Both gates retain their full selections and report interpreter/cwd/module paths, test nodes and slow setup/call/teardown phases. Their finite job bounds and completed-run evidence live in the workflows. These measurements do not guarantee future runtimes. A timeout is an incomplete run, never a passing gate; investigate it before changing coverage or the bound. The upshot: for anything outside the macOS trigger set (docs, most skills), the local run is the only pre-merge macOS check — run the relevant suite before you push. - Local verification.
coord-engineis CI-gated on both runners, but still run its pytest suite locally before pushing. - Workspace exclude. Any directory under
packages/*that is NOT a uv member (nopyproject.toml) must be added to[tool.uv.workspace] excludein the rootpyproject.toml, or it breaksuv sync/uv run/uv tool installfor everyone (theuv-workspaceCI guards this).packages/web-ui(a frontend, nopyproject.toml) is excluded for this reason.
Fulcra platform surface & records
Collect v1 migration (in progress, 2026-10-23). Actual v1 custom types are
Event/<UUID> and Metric/<UUID>; an /ingest/v1 endpoint writing annotations
is still a legacy datatype path. New opt-in shared builders/transport live in
fulcra_common.v1, documented in
the shared library README.
The SDK floor is 0.1.54 (workspace lock 0.1.56). Validate served custom schemas,
use explicit v1 destination IDs/version, preserve primary source identity and
verify readback before claiming an import landed. Do not blindly retry an
uncertain POST or silently fall back to legacy annotations. Caller migration
is tracked by the implementation plan;
do not claim all Collect/browser writers have switched yet. Unrelated
coordination/prefs/vault streams are not implicitly converted through this
shared library change.
V1 destination creation uses the account-bound resolver and durable
CreationJournal in data_types.py.
Keep its private SQLite file across process/host changes: a pending creation
with no response is reconciled by owned type/schema readback, never by
repeating the POST because the next listing looks empty. New schema versions
and destination changes require an explicit reconciled mapping. Base-only types
omit the optional custom schema fragment (empty fragments are rejected by the
live API). An explicit HTTP 422 permits a corrected specification, while an
identical rejected request or an uncertain outcome is never automatically retried.
Creation now captures a durable reservation nonce and retains a known full UUID
from JSON or a same-origin 303 Location before later proof; never follow its
alias redirect or substitute a different type after failed readback. Keep the
format-1 journal’s binding provenance, reservations and receipt audit together;
missing/conflicting evidence holds. Stop older writers before upgrading it.
Legacy readonly inspection and writable migration rules live in the
shared creation boundary
and its receipt regressions.
Owned custom-type resolution, exclusion discovery and the Collect picker use
the shared direct input-service reader, including retired types. Do not replace
it with aggregate catalog emptiness/uniqueness: that aggregate can silently omit
backend failures. Exact endpoint, account proof, bounds and failure rules live
in fulcra-common's v1 boundary.
Collect-side v1 writers use CollectRecordSession
for strict Collect-only auth, captured settings/epoch checks, request-time token
rechecks and leased progress commits. PurpleAir is the first migrated family:
its account/epoch-bound pending outbox is reconciled before fetching new samples,
and exact v1 readback precedes receipts/cursors. Retain legacy state for historical
mapping and both private state journals during host cutover. The reusable
V1RecordOutbox retains immutable
batches in the dedicated record_outboxes table until exact visibility. Schema
v8 keeps this 16 MiB-per-batch store separate from 64 KiB cursor KV; workers bind
outbox_get/outbox_set to the plugin namespace. Preserve pre-upgrade backups
and subsequent pending payloads when rolling back to older binaries. Drain before
fetching a new sample and never overwrite pending data. New shared and PurpleAir
pending envelopes carry dispatch_version=1: an immutable scope/payload binding,
exact issued source subset/body hash, and retained exact positive IDs. The
source dispatch controller
checkpoints prepared to issued through the actual before_submit seam after
validation/serialization. An issued missing/partial payload is UNKNOWN, never
permission for another source POST. Later exact visibility reconciles without
resubmission. Existing newly prepared same-ID correction behavior is retained;
issued/legacy mismatches cannot overwrite. Positive source evidence persists
before native repair can erase it. An issued excluded ID without that evidence
cannot complete from absence. Legacy envelopes are preserved without adoption;
missing evidence holds, while exact allowed rows can reconcile without POST.
The lease covers pending read through guarded clear, including checkpoints.
Collect source delivery requires this durable controller; no direct untracked
source ingestion is permitted. Native repair remains a separate durability gate.
DB version9 is a protocol marker that makes restarted version8 binaries refuse
the upgraded state. Stop every older daemon/worker before upgrade: a process
with an existing cached DB connection is not retroactively fenced. Never roll
an older app onto versioned pending state. A consistent pre-upgrade backup and
subsequent original pending evidence are necessary for rollback, but restoring
that backup can erase issued evidence and permit replay. Reconcile unresolved
source effects and establish a safe writer disposition before any downgrade;
never strip the marker or treat a backup alone as proof replay is safe.
Batched v1 ID/source readers use bounded matcher groups
inside one selector (binary vector OR is unsupported). Tag creation intents
are shared by account/name across plugins in the same private journal; a lost
receipt requires current-account lookup before recovery. A saturated source read
is unknown coverage, not an empty/matching-complete result. All 16 bundled media
plugins and the retained Spotify IFTTT backfill entrypoint now use the guarded
v1 media runtime on this branch. All fourteen standalone media import routes listed in the package guide now
use guarded v1 Events; the standalone webhook server now shares that authority.
The vendored Netflix importer now uses the
installed canonical console/script adapter with a versioned shared capability
check before auth/source. Skill-folder-only copies support stdlib check-only;
no PEP 723 live upload/install or annotation fallback remains. Its cli-netflix
authority uses independent CLI auth, optional Event pin and the shared Watched
spec/journal; account/profile/pin/spec changes hold pending. All original targets
are proved before recovery, which precedes source access. Whole new input gets
local/schema/current-primary conflict proof before serial <=500-record chunks;
only the in-flight chunk is durable. Exact complete-group current counts remain
separate from recovery/exclusions, and --no-verify is refused. Slim source IDs
lack profile identity and cannot prove arbitrary overlap correspondence. Personal
import finishes independently of optional legacy all-annotation sharing; native
share propagation and historical conversion are UNKNOWN. See the
Netflix agent guide.
The released app has not switched. The guarded media runtime
requires explicit v1 mappings for existing annotation selections, preserves user
tags/provenance/declared enrichment on source corrections, and refuses primary
identity collisions. Preview does not create destinations/tags or drain queues.
Daemon media cursors live in account/epoch/raw-settings-scoped KV envelopes; legacy
watermarks remain untouched and cannot prove v1 delivery. The private
v1-media-twins.sqlite stores account/destination-scoped high-confidence record
IDs, and each hint needs matching current-account record readback before an
auto-discard skip. The old global JSON cache cannot authorize a v1 skip.
Retain the new index during host cutover. Threaded webhook requests serialize
on their shared writer/outbox; preview reports would_post, and only the
outbox visibility commit emits a v1 receipt. The webhook proves its owned
destination before listening, reports typed destination/verified/preview counts,
and closes the server on loop exit. Its bearer credential is optional only for
loopback binding. The daemon rereads configuration each tick and retires service
workers on epoch/raw-settings revision changes; replacement waits for confirmed
exit, with an owned-group forced stop after a 10-second monotonic grace checked
on ticks. Unknown configuration/account transitions pause new scheduled work and
retire services. Host cutover and real source QA gates remain. See the
media contract
and service policy.
The standalone media configuration and adapter
now route those fourteen commands through fixed cli-media profile-local
authority with separate CLI/env authentication, never Collect sign-in fallback. Bootstrap atomically saves
cli-media-v1.json; every retained legacy category needs an explicit Event/UUID
mapping before metadata creation. Saved account proof precedes original pending
recovery, which precedes configuration changes and migrated source resolution,
discovery and parsing. Preserve creation receipts, pending evidence and legacy selections on every hold; reset is
retired for every flag combination. Status is cached read-only inspection of v1,
retained_legacy and pending, exposing retained payload size/digest only. UNKNOWN
is never all clear. Detached preview cannot drain pending work or prove caught-up
coverage. Standalone webhook routing now uses the owner described below; this intermediate source
branch is not rollout. See the configuration tests
and adapter tests.
The five standalone v1 poll commands
now select strict scans and private scoped cursors. The five daemon polls have
a separate strict progress contract:
fresh v2 scopes never adopt annotation or pre-strict v1 cursors, and final quiet
credential checks precede a second authority guard and exact KV readback.
Standalone recovery precedes bounded source-credential reads. Current verified
delivery precedes cursor commit; configured caps, malformed skips and source
changes withhold advancement. Both strict poll paths require HTTP 200 and refuse
any Content-Range, multipart byte-range body or mismatched declared raw length
at their shared source reader before parsing; duplicate/coalesced content types
are ambiguous and refused too. A parseable partial response cannot authorize
current delivery, cursor progress or history success; preserve
the prior cursor and report failure. Legacy watermarks never seed v1 cursors. Public
envelopes append a closed cursor state/reason or null; withheld success is not
caught-up proof. The observed import progress seam
lets all fourteen migrated CLI routes retain known counts after cleanup.
It is a last serialized
invocation's lower-bound snapshot, never a receipt or authority; shared concurrent
handlers cannot use it for caller attribution. A helper test is not evidence
that a route or installed app switched.
The standalone CSV contract now uses explicit
owned full Event/Metric targets, strict CLI parsing and a dedicated cli-csv
namespace. Recover original pending rows before opening new input; preview is
local and does not recover. Preserve primary-source identity and compatible
cloud enrichment; Metric units are exact destination metadata. Bootstrap's
same-name durable intent cannot be bypassed by changing parameters. Known
complete-group progress survives later failures; UNKNOWN is not empty. Legacy
export/admin remain separate, and old client record methods refuse before auth.
Pure parser/media consumers retain defaults. The CSV skill
describes setup/recovery probes; helper tests do not establish installed rollout.
The labs importer now uses actual v1 Metric records
through dedicated cli-labs authority, with existing clinical validation and
source hashes unchanged. Selected retained legacy markers require explicit
--marker-target MARKER=Metric/UUID pins. Recover original pending before new
JSON/PDF access; prove all actual pending targets from private exact marker/spec
witnesses, then retain per-group kernel recovery validation. Whole new batches
get full schema and existing-primary conflict proof before staging. Optional
record unit is omitted; exact immutable Metric metadata owns canonical unit,
while nullable raw_unit preserves source spelling. Counts are complete-group
lower bounds; current completed evidence and recovery remain separate, and
unsupported marker attribution is UNKNOWN. Cached status is local evidence,
never remote series counts. Original legacy cache/PDFs remain; old write seams
refuse. The labs skill teaches stateful
recovery and unchanged two-pass/operator-review gates. Source tests do not prove
installed app acceptance, real reports or historical conversion.
The standalone webhook contract
uses fulcra-media webhook --port 8766 --json, preserving default 8765 and explicit
selection without fallback. Startup recovers pending work and prepares all three
categories before bind. One private thread opens, uses and closes CLI authority;
profile leases last through cleanup. HTTP handlers submit defensive snapshots and
receive their own settled results. Closing rejects new jobs, drains accepted work
and joins cleanup; late parsers cannot access released authority. Health is cached
liveness, not fresh ownership proof. Ready follows signal installation and the
real-loop health handshake; successful shutdown follows cleanup. These actual
synthetic HTTP/lifecycle tests do not establish an installed receiver or sender
reachability. Keep the daemon's service lifecycle separate.
The unbound media writer retirement
removes the obsolete annotation/wrapped/typed pipeline and orphan CLI helper.
Four public writer seams refuse before auth/input/empty/cache/preview effects;
construction, read/admin and tag compatibility remain. Keep the captured Collect
bridge and native namespace classification; do not restore legacy record fallback.
The standalone Trakt policy contract
uses read-only prompt inspection and immutable exact offered pairs intersected
with fresh shared proof. Existing hints require owned readback/exclusions;
excluded current-input highs cannot justify skips. Choices never mutate saved
authority. Explicit ask is rejected in JSON/non-TTY before source; omitted twins
keep and warn only for candidates there. Post-cluster totals include policy skips;
Trakt has no cursor. Default None preserves Collect config/default precedence.
The actual Trakt CLI and ordinary Keychain-backed daemon worker now require a
complete bounded source scan
before current-input delivery. All four pagination headers, effective clamped
limit, exact page cardinality and unique integer history IDs must agree; missing
evidence fails instead of implying one page or empty history. One private
cooperative budget spans auth and the single keychain 401 restart, with rotated
tokens persisted before a late deadline refusal. Other five poll interfaces and
Trakt source IDs/normalization/cluster/twin policies remain. Original pending
recovery may already precede a failed current source. This proves self-consistent
returned pagination, not an immutable account snapshot. The
Trakt source owner
adds exact local credential/consent generations, one shared OS-user consumed-grant
journal and recoverable secret receipts. Ordinary workers never implicitly select
the legacy CLI file on missing/partial/UNKNOWN/disconnected Keychain state; a
direct wrapped-plugin file fixture is not worker selection proof. Preserve the
source journal/receipt lineage across profiles and never remove claims to retry.
Manual pair edits credit only verified exact supplied values, not failed intent;
refresh/recovery binds only its own exact consent-preserving successor. Explicit
Keychain authorization runs outside short control locks; bounded quiet mutation
then rechecks its still-current edit/profile. Stale OAuth results cannot overwrite
newer setup. The wrapper registers current
source guards only after original recovery and retains them through final cursor
handling, with local-only checks at nested mutation boundaries. Background Trakt
receipt/mirror writes use the quiet child,
not generic interactive setters. The current provider-identity contract
adds exact selected-credential probes before/after history and a terminal proof
before normalization, policy, writes and progress. A selection-keyed durable pin
survives credential/profile changes; a mismatch stays held without automatic reset.
Source journal version 2 preserves valid v1 entries on upgrade; older v1 readers
fail closed. Fence older participating writers before upgrade and preserve the
whole journal/receipts. First pinning gives no historical attribution. Installed/
signed access, live-provider acceptance and old-writer/copied-grant retirement
across hosts remain gates. No hard interruption of an in-flight grant is promised.
Migrated producers expose Plugin.record_data_types(settings) and destination
steps name SetupStep.record_slot (single-slot producers may omit it). Their
authenticated setup uses the owned v1 catalog/schema and saves full IDs in
v1_destination_ids; legacy annotation binding routes reject these producers.
Rebinding checks pending uploads both before resolution and under the account/
settings commit fence, rotates the source epoch and retains old annotation state.
A producer with a custom pending format must provide Plugin.record_pending;
otherwise setup checks the shared v1_pending_records outbox. Raw saved-settings
fingerprints fence pending batches even across manual TOML edits. The picker
shows one latest entry within 30 days, not complete history. See the
setup contract.
Same-account silent token refresh is accepted with request-time auth replacement;
account/epoch changes cancel work and cross-origin redirects are rejected. See its
delivery contract.
RunContext.fulcra_token() is now a compatibility alias for Collect-only
collect_token(), including file-producing plugins: neither adopts environment
or default CLI credentials. Silent renewal checks the existing/candidate/final
keychain principal and fresh expiry, holds an account-shared lease through its
final write and yields to a newer interactive sign-in. Missing identity or a
durable account-transition gate cannot be repaired by automatic CLI sign-in.
401 retries pass their original request token to prevent an old operation from
retrying under a newly selected account. Gmail/Reminders/Todoist reject missing
Collect auth before source/writer construction. The auth contract
is shared by these plugin paths; standalone CLI authentication remains separate.
FULCRA-PRIMITIVES.md is the field guide to the whole
platform surface (auth, files, annotations, queries, MCP), organized by agent
capability tier — CLI/lib, raw HTTP, or MCP-only. Read it before re-researching
anything about the platform, and check the installed fulcra-api version,
not the repo (the CLI ships ahead of its git main on PyPI).
- Spec-backed raw endpoints are first-class. Anything in the published
Fulcra OpenAPI (
api.fulcradynamics.com) is fair game when it makes the work easier — a documented raw REST call is a legitimate tool, not a last resort. Still prefer thefulcraCLI / Python lib when you have a shell and a verb exists; the MCP server is read-only. - Records have CLI verbs as of 0.1.37 (2026-07-15) —
fulcra record DATA_TYPE [VALUE]andfulcra delete DATA_TYPE [RECORD_ID], both with-f/--fileand JSON/JSONL on stdin for batch;fulcra catalog --recordable-onlylists the types they accept, and the lib gainedrecord_data_type/validate_records. Use them when you have a shell rather than hand-rolling ingest POSTs. The raw ingest endpoints (POST /ingest/v1/record/{data_type}, typed and preferred; the wrappedDataRecordV1legacy path; the unpublished/batch) are still first-class when you need them — the primitives doc covers all three and the custom-typesourcescaveat. deleteis a tombstone, not an erasure — the CLI implements it by recording aDeletedRecordthrough the same ingest path, and there is no record-delete lib method. There is no hard delete and no dedicated update/replace verb. True-v1 Event same-ID timestamp/content updates, Metric same-ID value updates, Event/Metric deletion visibility and Event post-delete replay revival were separately verified 2026-10-23: see the mutation contract. Replays can revive deleted records, and native tombstones are not queryable; keep an independent durable disposition/audit and check it before replay. The sharedV1DataClientrequires explicit canonical record UUIDs and offers nativedelete_recordswith a durably captured action UUID; its receipt is submission evidence only. Prove replay exclusions and target absence before claiming deletion. Media copied- record source aliases count as existing data; opaque source IDs alone do not prove a different-importer fingerprint twin.RecordExclusionsadds an opt-in owned Event policy keyed by full target type/UUID. It verifies policy visibility, retains a visible prior exclusion and fails closed on malformed/unknown reads. No restore or cross-host write lock is implied; callers keep durable action audits and check policy before/after source writes. Media/PurpleAir now check this policy before duplicate shortcuts and around queued writes on the development branch. Observed revivals need native deletion and absence proof before progress; excluded rows never count as posted/verified or seed media twin hints. Media chunk planning through delivery shares the local per-account record lease across processes and threads. Browser hosts are outside that lock; historical replay floors, controlled cutoff, other writers and durable Undo actions remain rollout gates. The catalog does not retain our datatype creation metadata key/schema fragment. Preserve the private account/key creation journal through host migration; unbound control lookup discovers owned served schemas (64 candidates/10s scan, up to 8s per schema HTTP request). A missing bound control, unknown schema or ambiguous match fails closed. Setup proves/binds the control before saving a source destination; previews cannot create or repair control state.ActionJournaladds opt-in private, immutable interactive intents plus transition evidence. Global action IDs cannot be reassigned to another account/epoch/request; submitted is not verified. Account-only old-epoch inspection and bounded, filter-bound recovery pages grant no mutation authority; unfiltered reads fail on unknown statuses.QuickRecordActorcaptures dispatch intent after schema validation, never resubmits an uncertain create, and requires a verified original for a new native Undo action with permanent exclusion and absence proof. An uncertain original remains submitted. Shared v1 record/native-tombstone POSTs reject redirects to prevent automatic body resubmission after a 307/308 response.QuickRecordSessionregisters a separate interactive epoch and requires the captured account/epoch without enabling a plugin. Registered contexts use shared leases; initial registration releases SH before acquiring EX and re-proves identity. Generic setup ingestion stays gated. The opt-inquick_record_v2daemon envelope and authenticated/api/quick-record/v2expose the protocol2 contract: captured scope/action identity, owned per-track Event bindings, account-scoped revisioned pin diffs, durable first timer stops, native Undo, paginated action / timer discovery, and snapshot-based stop reconciliation after a crash. Receipt failures under valid authority return saved pending metadata, not auth refresh. Legacy favorites remain unadopted and untouched, including during legacy definition metadata deletion. Preserve scoped pins and v1 destination bindings too; definition management is separate from native record Undo. The native client workflow captures immutable bounded requests before socket IO in a separate private client journal. Timeout/restart retries keep the original body and scope; response proofs must match the original action/timer and first stop time. One global timer-to-stop binding preserves the first local stop across later clicks; pending replies cannot change an observed record ID or datatype. Protocol2 socket replies are bounded at 8 MiB; requests and legacy replies stay at 64 KiB. Development native popover/preferences and web favorites now use protocol2 by default and are included in the published 0.1.5 beta. Complete packaged interactive acceptance and explicit old-epoch recovery remain separate. Unversioned commands/old authenticated HTTP routes return refresh-required before Collect auth or effects; their legacy serializers/sentinel Undo are removed. Native checks validate saved/observed action and timer proofs; local saved intents reuse their exact request. Bounded pending-action pages discover work beyond recent 20, including old-epoch rows that grant no replay authority. Drafts survive rerenders within their account/epoch/choice/timer scope; only a durably captured row clears. Busy refresh invalidates queued stale-account results and schedules a new handshake. Pin edits are additive CAS diffs from one complete scoped choice/revision view; logical/scope failures never count as success. Cached Preferences refreshes on reopen and Annotations selection, with deferred fresh reads after busy loads. Hidden and legacy pins stay intact. Client schema1 fails on incomplete/unversioned/future state instead of healing empty. New GUI imports stay lazy. The refresh host uses a Python AppKit subclass because plain NSView cannot carry its callback. Dynamic native rows must call detach_view before removal, releasing only our targets so retained callbacks/snapshots do not grow per rerender. Explicit old-epoch reauthorization and packaged QA remain release gates. Tag names are limited to 30 characters on creation. Collect reuses saved owned tag UUIDs through renames; new long/slashed or dot-segment source labels get stable short tag names without shortening record enrichment. Unknown creation remains fenced. Media validates raw declared fields before notes/metadata, reuses a codec validator, and compares UTC instants for durations, order, windows and receipts across DST changes. Full media nullable/nested/Unicode/multiple-tag parity and same-ID Metric timestamp updates are live-verified; see the mutation evidence.snapshot_jsonrejects non-string object keys at every depth, invalid Unicode and non-finite values before v1 metadata, action/outbox storage or transport. Do not rely on a bare JSON round-trip: Python can stringify nested keys and silently merge them. Valid zero/false/null values and Unicode content remain unchanged.- Projection is the sole timeline-annotation writer. Use the heartbeat
projection fold (
coord-engine annotate resolution <team> transitions). Its deterministic ids converge because typed ingest upserts matching explicit ids (live-verified 2026-07-14). The retired first-generation writer minted different ids and was removed after causing duplicate-record proliferation.
Attention v1 contract (development)
Attention's opt-in v1 contract and encoders have shared Python/TypeScript/Swift synthetic vectors; installed/default browser senders still use legacy transport. Preserve the existing v3 primary source and use the common UUID5 full-destination mapping. New URL inputs are already-scrubbed JS capture keys within the linked shared boundary; hold unsupported inputs instead of applying a second native URL normalization. New capture payloads retain milliseconds; history retains its stored precision. Reject malformed or nonzero submillisecond bounds, not silent rounding. The schema permits historical null device identity, but new contexts require an installation slug. The initial owned spec fingerprint is pinned; semantic changes need a new version. Pure codec checks grant no account/destination/replay authority. Complete the linked owned-resolver, immutable-queue, readback/exclusion, native-protocol, active-visit and installed-state transition gates before changing default browser writers.
Attention's opt-in browser journal uses IndexedDB compare-and-set for account/generation transitions and publishes Event creation intents durably before a future POST. Unknown creation remains pending across restart; never reset it to create again. Reconcile the original intent under fresh same-account authority. Journal state is not API-principal proof or upload permission. Existing auth/default senders are not wired to it; actual browser persistence and Safari sharing remain rollout gates.
Its IndexedDB v2 upgrade retains the v1 gate, generation history and Event
intents, and adds account/label tag intents with unique account/create-name
reservation. Tag resolution
uses the same bounded alias naming as Python, records intent before POST and
explicitly refuses . and .. labels before lookup path normalization. It
records a returned UUID as submitted before name readback. A submitted UUID
cannot be substituted; an unknown attempt never authorizes another create.
Only a target lookup's positive 404 permits creation: identity-endpoint failures
carry a separate HTTP error code. Resolved tag UUIDs survive cloud renames as
historical ownership bindings, not live-tag or upload proof. Name collisions,
unreadable state, unsupported strict durability and full journals refuse; never
evict pending work. Defaults remain unchanged. See the
synthetic migration/race tests.
The opt-in v1 HTTP boundary
captures one account/generation and request JSON before awaiting. A fresh token's
candidate UUID must agree with that gate AND /user/v1alpha1/info; JWT/display
claims alone cannot authorize a request. Every provider/body await is followed
by current token/gate checks; a late result cannot acknowledge a changed scope.
Same-account token renewal is allowed, while this helper performs no credential
writes or refresh. Its caller must publish generation changes before changing
capture account. Only allowlisted production routes, no redirects/cookies,
bounded fetch/body waits (abort timer plus absolute monotonic checks) and finite
Unicode JSON are accepted; mutations are
never blindly retried. Disabled capture cannot ingest. Browser fetch supplies
DECODED bytes: its retained-body cap is not a raw-wire/decompression bound.
This transport grants no schema/creation/queue/exclusion proof and is not called
by default senders yet. Keep account/schema/durable-delivery rollout gates.
The opt-in browser owned-type inventory
uses the direct caller-owned input endpoint and rejects a partial, redirected,
paged or malformed whole list. Identity/proof fetches request no browser cache;
wrong-scope 404s cannot become tag-creation permission. Frozen inventory entries
are not schema proof or destination bindings. The shared
authority contract
and browser tests
describe the bounds; actual browser auth/CORS/upgrade gates stay open.
The pure Attention schema proof
requires the closed supported Event/Attention schema family, rejecting unknown
assertions/references instead of assuming a matching field subset is sufficient.
It freezes the parsed schema before hashing and retains the exact serialized
text whose UTF-8 digest is checked. Keep that text with its digest; do not call
it raw-wire proof or assume arbitrary JSON serializers reproduce it. The
development contract
defines supported shapes/bounds. This pure check grants no owned binding or
upload authority; defaults remain unchanged.
The opt-in Attention destination binder
requires fresh direct ownership, BOTH authoritative input/served-schema proof,
and a final unchanged-input/active-type check before its journal commit. It is
explicit setup with local effects, not a preview. Keep transport and effects on
the identical journal handle per operation. Pins survive renames; unknown type
creation never authorizes another POST, and known returned UUIDs persist as
submitted before further network work. Older binaries that cannot read that
state must hold it, never clear it. Exact proof/known immutable base-transform
handling and tests
live in the development contract.
No default UI/sender, capture, queue or exclusion authority is enabled by it.
The Attention binder also exposes verifyAttentionV1: read-only fresh proof of
an already resolved original local destination. It checks complete owned input,
closed input/served schemas, unchanged final input, then the exact original
reservation generation via requireCreation; missing/submitted/pending or changed
intent never heals. Verification returns the original reservation generation;
setup's existing result shape stays compatible with queued captures. First
binding still requires a unique canonical candidate: a submitted UUID receipt
alone does not disambiguate siblings, while explicit/prior-resolved pins retain
rename semantics. Setup and verification share one <=10s monotonic/timer budget,
<=8s/remaining HTTP reads and a terminal cancellation flag. Setup passes an
AbortSignal through creation transactions: check resumed callbacks and abort an
active uncommitted transaction on cancellation; detach listeners on settlement.
A verified receipt already returned by HTTP may still be retained historically
after outer expiry/account change. A response rejected inside HTTP remains
UNKNOWN; do not claim its UUID was retained. The
binder tests
cover ambiguity, readonly tuples, same-account gate rotation, cancellation after
actual add/put and returned-receipt retention. This grants no delivery authority.
The opt-in Attention outbox is local pending capture only. Its IndexedDB v3 upgrade retains v1/v2 stores. Capture freezes account/generation, full destination/specification, both schema texts/digests, installation, original event, primary, flat record/tags and exact serialized payload before strict commit. The transaction requires the enabled current gate and resolved local datatype/tag bindings; every read reproves the stored envelope and rechecks the gate after hashing. Same identity with different content or generation is held, never overwritten or implicitly rebound. The 5,000-entry/32 MiB aggregate envelope limit and quota failures reject without eviction. No POST/settlement/deletion API, legacy adoption, active-visit checkpoint or default wiring is supplied. Digests are local integrity/reproduction evidence, not provider receipts. Bounds and synthetic queue tests live with the development contract; actual browser persistence, quota, upgrade and Safari sharing remain gates.
The network-free browser mutation journal adds atomic IndexedDB v4 ownership for one pending logical operation per account. Upgrade preserves v1/v2/v3 data and rejects malformed old structures. Retain both history and the terminal current pointer: their count/byte frontier detects lost metadata; expiry never releases uncertain work. Current/requested rows receive digest reproof; older unrequested history is covered by count/frontier checks, not a fresh content audit. Request hashes bind original account, generation, action, operation and exact request bytes. Prepared/issued work cannot move to a new consent generation. Issue is a single-winner CAS; reopening an issued intent grants no second issue. Verification stores immutable caller evidence, not independently checked remote truth. It cannot authorize HTTP, native deletion or queue removal. Future actors need issued-once phases for each physical effect under continuous ownership and exact, atomically bound queue settlement. Legacy requests and all proofs are limited to64 KiB; phased request limits are described below. History permits100,000 total actions and32 MiB retained request/proof bytes per account, with proof headroom reserved beforehand. Capacity/quota failures preserve all work; there is no eviction/reset/release API. Ownership tests cover upgrades, corruption, deadlines, races and restart. The development contract records the remaining actor, native browser and default rollout gates.
The same journal now uses
an IndexedDB v5 version fence while preserving existing v4 payload rows/pointers
byte for byte. Legacy intent format1 stays network-free and cannot acquire
phases implicitly. New closed format2 captures a fixed complete manifest before
reservation: deliver then repair, or policy then delete. Old manifest1
retains its64 KiB cap; manifest2 bounds and references are described below.
Inline JSONL has at most32 records per body. Phase CAS has
one issue winner; prior phases must be proven before later phases advance.
Immutable phase caller-proof hashes bind original request, role/index and body.
Separate final logical proof retains the owner until every phase is verified.
Reserve headroom for both phase proofs plus final proof, count actual bytes once,
and deep-detach/freeze nested states. Explicit preexisting/not-needed evidence
avoids inventing a dispatch. This is storage only: phase plans receive finite
JSON/route shape checks, not served-schema, policy or provider validation. A
typed HTTP transport itself wins issueGuardedEffect immediately before its one
fetch, categorically refuses legacy rows, and holds uncertain POSTs without reissue.
Phase tests cover
legacy byte preservation, phase order, corruption, asynchronous input races,
capacity headroom, quota and deadlines. No sender/default/queue removal follows.
All mutation APIs accept optional cancellation after the absolute deadline;
active uncommitted writes abort, while a committed issued phase never resets.
The guarded CAS requires exact original resolved creation/tag tuples retained
before reservation in details.dispatchAuthority, then rechecks those tuples
inside the same strict gate/owner/history/body transaction. A fresh replacement
cannot substitute for original authority. Exact code-unit sorting preserves
Unicode labels and allows property/array reordering. Original reservation
generations can predate the action. Legacy guardless requests refuse guarded
issue; plain issueEffect is storage-only compatibility and forbidden to HTTP
actors. verifyGuardedEffect similarly checks the exact original tuples in the
same transaction before phase-proof publication or reuse, and requires the
original nonterminal logical owner still held. Terminal old actions refuse
guarded reuse; plain verifyEffect remains storage-only historical compatibility.
See the proof tests.
These remain caller evidence and local predicates, never provider truth or
queue settlement. Typed submission adds fresh schema/type/tag proof;
replay policy and sufficient action guards remain actor duties. The64 KiB details cap can hold
large guard sets even when the queued record fits; full admitted-row delivery
coverage remains a rollout gate. See the
dispatch tests.
The opt-in action actor
reconciles only an original retained delivery/exclusion intent. Fresh owned
target/control/tag/native-schema checks bracket exact source and canonical policy
reads, including zero-POST reuse. Closed immutable phase evidence binds original
account/generation/action/body/authority and schema hashes. Issued source absence
stays UNKNOWN without another application submission; a later policy permits
prepared repair only after positive original source evidence. A consumed
not-needed repair cannot become a deletion, and native revival holds. Results
are frozen as-of-read observations: success retains the owner and queue; UNKNOWN
asserts no current ownership. Default integration is still pending.
V1Http.withReadCancellation preserves the original transport configuration and
all inherited cancellation signals for nested reads. The actor has one 30-second
maximum budget; repeated authority GETs can exhaust it on a slow service and need
real-service acceptance before rollout. One guarded CAS/application fetch is
not a one-wire-attempt guarantee: isolated Chrome repeated an HTTP POST after
an empty response without a second application fetch. Never infer backend job
quiescence from the local phase, receipt or an absence read. See the
actor tests.
The opt-in decision authority contract
now shares one closed target/control/schema/tag/native inventory pair per
snapshot, with fresh A → exact policy/source → fresh B observations. Opaque
capabilities remain bound to the exact journal/HTTP root, bearer, original
request/dispatch and cancellation/deadline. Public helpers stay independently
safe. Standalone callers must publish a new gate generation before every bearer
replacement. The source-only Chrome worker auth owner
adds a bounded same-account renewal exception with exact predecessor/successor,
retained response, fresh API principal proof and exclusive owned lifetimes.
Unannounced token-only replacement remains unsupported. In v1-held both drains
stay disabled; versioned worker commands own settings/auth, with noncredential
settings atomically stored in broker IndexedDB. Read-only page settings commands
wait for local worker initialization without online recovery or direct page
authority creation; controls wait for settings and surface failed reads as held.
The canonical contract also requires the separate once-only initialization
witness: missing database/witness stays UNKNOWN, without reimport/reset. Local
revocation/display cannot wait on online recovery. Pause retains selected auth
with action admission closed; resume uses fresh consent/generation and sign-out
clears selection. Legacy state stays original evidence. Source-only
held capture ingress
retains actual visits/backfill with strict atomic serialized-row accounting and
no eviction. Null positive descriptors keep actual input unattributed; durable
local evidence is never an uploaded count. Preserve category privacy, original
scrubbed keys, restart/scope gaps and legacy old/new observations; missing input
or unreadable accounting stays UNKNOWN. Completed setup publication, actual
draining, installed sender fencing and Safari native integration remain gates.
The guarded issue CAS stays the last authority await before application fetch;
no cached proof bypasses journal predicates. Actual isolated synthetic Chrome
checks are separate from provider latency, installed auth and default activation.
The source-only explicit browser protection command
installs the concrete fixed DNR policy only on null-payload protection-setup
under an already admitted worker-owned lease. Do not install on boot, start
online admission or supply a protector/ready flag from a page. Preserve original
state/credential/gate and lifetime checks, including a synchronous cancellation
check immediately before native update. A timed-out/revoked native promise retains
its installer reservation until actual settlement; effects remain UNKNOWN and
must not trigger compensating cleanup. Its as-of-read result leaves capture and
drains held. Task 4 permits source preparation; actual native procedure, original
C0/browser obligations, real account/destination and Safari gates remain separate.
The inert browser candidate presentation adapter
can display bounded, strictly shaped full Event ID/name candidates through the
Wizard's versioned page seam. Account matching is presentation scoping only.
The actual worker still reports SETUP_HELD; no protected production listing,
selection/setup write, descriptor publication or drain activation is added.
Candidates have no default choice and late/unmounted results are discarded.
Preserve Task 4/C0/native sequencing, installed evidence and Safari gates; synthetic
message/Chrome/IndexedDB tests do not certify production listing. Shared Chrome
test setup denies global fetch before imports and each case, reestablishing it
after global restoration while permitting later synthetic fixture overrides.
This is a JavaScript fetch-seam guard, not an OS/socket/native-browser sandbox;
follow the linked fixture-reset limits. Candidate labels, IDs and raw response
errors must not enter logs.
The unused bounded local evidence APIs keep read cancellation separate from writer completion and use noncreating exact-version handles with shared monotonic/record/byte budgets. Raw capture records and original owner snapshots grant no setup, origin or action authority. Preserve private credentials, full original-input validation and strict writer predicates; native QA and later activation remain gates.
settleV1Action adds opt-in atomic settlement with one maximum30-second budget
from history through actual actor and local commit. A private observation
capability binds fresh evidence to the exact journal and original budget. Its
strict transaction rechecks original authority/generations/history/phase proofs
and exact referenced queue bytes, then commits terminal receipt/pointer and
removes only that original row together. Inline exclusion performs zero queue
writes; inline delivery holds. Historical receipt lookup precedes body/provider
access: already-settled leaves newer owners/requeued same-ID rows untouched and
asserts no current provider freshness. Lost completion is UNKNOWN with
localCommit: unknown, not a promise all local data remains. Precommit aborts
roll back; confirmed commit survives late cancellation. See the
settlement tests.
Default draining, bounded terminal archival and installed-browser acceptance
remain gates. Chrome npm test/watch use two workers to prevent measured host
oversubscription from exhausting operation deadlines; tests retain their limits.
New phase manifest2 uses a256 KiB total request/128 KiB inline-body cap; legacy
logical requests and old phase manifest1 remain64 KiB, with all proofs64 KiB.
reserveReferencedMutation binds exactly one original Attention outbox row in
phase0 (deliver), keeping repair inline. Account/generation/full type/record
physical key and envelope hash/bytes are distinct from exact transmitted UTF8
JSONL hash/bytes. The existing4 MiB queue-envelope limit bounds its body without
duplicating it in operation history. The body helper
and outbox reuse one pure queue codec
for complete original scope/schema/source/record reproduction. Outer metadata
alone cannot relabel a hashed payload to a new account/generation. Reference
rows share the owner/gate transaction snapshot, reproof outside IDB, then exact
final state recheck; missing/replaced unfinished bodies hold. Only fully verified
logical/phase proofs permit terminal metadata reads without the old body;
readEffect refuses terminal operations. Missing queue data is never itself a
settlement receipt. A later sameUUID/newpayload cannot acknowledge an old body.
New reserve APIs emit manifest2; recover manifest1 through original stored reads
and phase CAS, never reserialize it or change its nonce. The
reference tests
cover admitted large events, large policy encoding, restart, both scope relabels,
body replacement/loss, version bounds, quota and deadlines. Default sender
integration and bounded terminal archival remain integration gates.
The opt-in typed JSONL receipt transport
seals generic json() ingest and itself materializes original body, fresh-proves
owned target/control schemas and original bindings, and requires live UUID tags
with matching owner metadata. Missing tag ownership holds; UUID liveness alone
is insufficient. Typed preflight
reproduces referenced Attention/canonical policy records and the complete fixed
native action plan; unknown native served-schema assertions hold. Arbitrary inline
source records cannot bypass capture reproduction. Pin and API-prove the exact
POST bearer before guarded CAS; that CAS is the last authority await before one
fetch. Use exact original JSONL, canonical Event/DeletedRecord path, sole
api_version=v1, no redirects or retry. Recheck current gate/JWT, same pinned
API principal and native protection after complete receipt parsing. A whole
monotonic/timer deadline and cancellation prevent late issuance.200/201/202 with
bounded string upload_id returns a receipt only; loss/ambiguity retains
issued/UNKNOWN. It never verifies phases or removes queue rows.
Native receipt DNR protects Event hex/hyphen suffixes as a deliberate superset under the exact HTTPS API/literalroute/POST/owninitiator/query; full UUID regexes exceeded Chrome's compiled-memory bound. Strict canonical UUID authority remains in transport/journal. Require all four native rules; no unprotected fallback. Synthetic temporary-extension reload cleared dynamic rules and required explicit fixture setup, so production installation persistence is unproven. Native QA must include a protected-vs-unprotected identical encoded-response differential, not only fake fetch headers or rule readback. The typed tests cover identity, exact large bodies, once-only issue, native identity/schema, receipt ambiguity and timeout. Policy permission/reuse, before/after policy checks, exact readback, atomic settlement, backend quiescence and default/Safari integration remain separate gates. A receipt never proves delivery/absence.
Exact browser row-level userid/fulcra_userid, when exposed, must each match
the captured account. A contradiction is UNKNOWN, never silently dropped into
absence. Submitted-field matching uses the admitted payload's 4 MiB UTF-8 bound.
The opt-in exact browser record reader uses full Event/Metric plus exact UUID instant selectors, at most 32 IDs per operation, under V1Http's captured account and current API-principal checks. Only a complete successful JSONL 200 can return absence. Partial/paged responses, conflicting exposed owner/totals, malformed suffixes, duplicate keys or identities, unrequested rows and stream errors fail closed. Keep decoded-body/deadline bounds and static errors; never expose parser payload fragments. Frozen results and submitted-field/time comparison are one-read evidence only. No queue clear, POST, replay policy or historical coverage follows from them. The development contract and synthetic tests carry bounds and supported semantics; default writers remain unchanged.
The permanent exclusion specification has one packaged contract shared by Python and browser pure helpers. Preserve its existing creation fingerprint and required-field order. Attention and exclusions use the same closed Event proof with only those two static families; the exact exclusion-reason string set is order-independent but cannot gain a restore state. Pure schema/spec checks create no policy, owned binding, exclusion/absence evidence or upload authority. Run both contract/schema suites when changing this resource or shared proof; verify the Python wheel includes the JSON before packaging the app.
The pure browser exclusion codec shares Python's stable target primary, UUID5 and flat point-record fields. It permits canonical Event/Metric targets, forbids self-control/restore, and captures action/time/evidence before hashing. Encoding grants no current policy or durable-action proof. The development contract defines evidence/JSON limits and the shared synthetic Python/browser vectors. The lossless instant helper supports Python microsecond timestamps for control records and generic readback; Attention capture retains its millisecond-only fence. Never round an existing control timestamp or reject it merely because Python retained microseconds.
The opt-in browser control binder discovers renamed policies from the complete input inventory and closed input schemas, never a name-only catalog miss. Unpinned discovery scans at most64 Event schemas including retired rows; unreadable/plausible incompatible policy or ambiguity holds creation. Explicit/private original full UUID pins retain fresh ownership, input/served proof and final unchanged-input checks. New bindings repeat discovery before publication. Use one <=10s monotonic budget and <=8s/remaining HTTP reads; overrides cannot extend the HTTP instance budget. An overall timer bounds local waits; deadline checks inside journal callbacks guard local creation writes. A submitted receipt retains identity but cannot bypass first-binding discovery on retry. Preserve known receipts and unresolved intents; never retry a possibly dispatched create or replace a known UUID with a new empty policy. The binding tests define recovery and race behavior. This grants no current replay permission, native absence proof or default sender authority.
Both browser binders retain verified creation receipts against their original durable reservation even after an account transition. This historical write never creates an intent or resolves authority. It requires the original account, specification fingerprint and reservation generation. A contradictory known UUID commits a durable conflict retaining both identities before returning an error; ordinary reads/resolution/replay refuse it and no reset is provided.
The opt-in browser policy reader
requires already resolved original authority and uses read-only
verifyExclusionV1 before and after protected exact policy reads. It never calls
setup to repair missing/downgraded intent. The journal's requireCreation
predicate checks account/gate/key/fingerprint/control/original generation inside
one read transaction. Reconstruct every returned policy row, reject supplied
owner contradictions, and require unchanged schema/reservation context. The
development contract and
tests
define limits and late-callback behavior. Results are one-read evidence; writers
still require before/after-write policy checks and a mutation lease. No deletion,
queue settlement or default sender integration follows from this helper.
Python's shared v1 record reader uses the same response-completeness gate for exact IDs, source windows and latest previews: require exact requested scope and unambiguous 200; reject redirects/history, partial/paging markers and conflicting exposed owner/totals. Request identity encoding and reject encoded replies; eager gzip decoding may return empty or complete-looking data without a valid trailer. Never turn a degraded read into absence or replay permission. Strict JSONL parsing rejects duplicate keys, malformed suffixes, nonfinite values and invalid Unicode; only ASCII blank framing is ignored. The buffered parsing contract explains the limits: eager HTTP loading/decompression has already happened, so these checks are not a raw-wire/allocation/deadline bound. Run the shared reader tests and source/policy integration suites when changing this gate.
Python's permanent policy helper
captures an exposed canonical store.account_id and checks it around lookups,
including empty results. Supplied policy-row owner metadata must match that
known scope; unknown scope or contradictions hold. Generic record enrichment
comparison elsewhere remains separate. The
creation journal validates
intent states/full destinations and atomically prevents concurrent resolution
from replacing an original UUID or healing malformed state. The
shared contract
and its linked policy/journal tests define this setup behavior.
Collect policy transport now
uses a separate read-only verifier around each policy GET/POST, including
checks after source uploads: existing resolved fingerprint/full UUID, current
owned/served proof, final owned/account/local-binding recheck and unchanged
schema hash across transport. A cached string alone never proves absence;
reads never run setup/adoption or recreate a lost journal. Run the
authority integration tests
when changing this boundary. Writer mutation leases and controlled old-writer
cutoff remain separate requirements.
Owned-list and served-schema proofs share strict identity-only, no-redirect
JSON reads with exact endpoint/owner/partial checks. Duplicate keys, nonfinite
values, numeric assertions changed by parsing and malformed supplied input
schema hold; a supplied userid must
agree with the captured account too. The
canonical contract
documents the decoded parsing caps and remaining limits. These schema reads
must not fall back to a generic response.json() or a redirected alias.
The shared v1 client has an optional
expected_schema keyword on validate_records and ingest. A supplied full
schema requires an explicit nonempty captured account_id; None keeps the
default behavior and ignores that account argument. The public
strict served-schema reader
owns token-account proof. Each nonempty pinned call compares and validates one
fresh full served snapshot; locally checked empty calls perform no I/O and
prove no remote equality. The
canonical contract
defines bounded input capture, full JSON equality, representation version and
remaining limits. No production caller is activated and no historical replay
authority is granted. Run the shared seam tests,
public proof-reader tests and
Collect session/policy authority
integration suites when changing this seam.
The opt-in Python transport observers retain actual strict record/schema/receipt facts through the shared v1 and schema boundaries. They require explicit original/account/ID context, the same guard and budget at every SDK/HTTP leaf, exact sink acknowledgement and a retained-attempt event allowance of at most 128 slots across reopen. Receipt and issued-checkpoint capacity are separate; complete buffered responses retain their pre-reserved audit slot after expiry without a fresh authority/token/network guard. No later action follows from that retention. Canonical bytes, inert policy/assessment/history types and stored retention modes grant no coverage, ownership or production replay authority. Production SDK hidden refresh/retry accounting, real retained persistence, B1p owned-policy producers, production historical reconciliation and Collect wrappers remain held; this component activates no production caller. The canonical contract documents exact call shapes, context projections, body/schema hash distinctions, header allowlist, strict observed receipts and buffered/outer-envelope limits. Run the observation tests, reader/default tests, schema/import tests and existing session/policy integration suites when changing this unused surface. Preserve ordinary/default and Task A pin behavior, one final served-schema snapshot and one POST/no retry.
The inactive historical verifier capture now shares the existing read-only verifier and actual observed HTTP leaves. Its private transport constructors unconditionally refuse; tests alone compose synthetic storage/admission/gates. Runtime capture/inspection returns untrusted bytes and facts, never an owned-policy issuer. Preserve the exact7+2+7 charges, same served schema and retained attempt allowance; transcript attachments occupy the started proof slot and uncertain writes never refund it. Whole-chain bytes are checked before each fixture storage mutation, and staged linkage compares exact canonical bytes. The canonical README owns raw-byte/linkage/limit details and H1–H5 production holds, including the still-unqualified original journal opener and auth revision/gate. Run the new transport/transcript regressions and common/Collect suites when changing these seams. No Collect constructor/caller, production namespace, real auth gate or historical apply is activated; ordinary/default methods stay supported.
The unused synthetic historical reconciler
now consumes B1a observations and re-exports the same existing HistoricalDelivery.
It is singleton-only, defaults to no submission, retains separate control/target
assessments and checks the same guard/budget through every nested request. Matching
original-payload positives remain disqualifying across attempts, terminal outcomes,
audit retention and later deletion; a mismatch is retained conflict evidence.
Every normal return requires one outcome callback with fresh retained history,
atomic fixture CAS and independent event/slot/state readback. Issued/outcome,
assessment and observation events share the retained maximum 128-slot allowance;
uncertain persistence propagates without retry, refund or a clean result.
All owned binding factories/resolvers, authority, external history, fencing and
lifecycle persistence implementations remain solely in the
test fixture. The fixture-only
exclusions.binding_proof capability is required at entry; production
RecordExclusions does not implement it. Its full-row validator is the one private
pure core shared with the unchanged live policy read. No production caller,
authority issuer, policy observer, real persistence/CAS (C), driver (D) or actual
historical apply is activated. The canonical linked contract owns exact signatures,
classification, hash domains and limitations. Run the historical/policy tests plus
the existing common and Collect session/policy/outbox suites before shipping a
change to this seam; ordinary live repair and replay behavior must stay unchanged.
Chrome v1 record reads require verified
identity/encoded-response protection.
Fetch accepts some truncated gzip streams, so decoded EOF cannot prove absence.
Explicit setup owns fixed rule IDs1002/1003 for this extension's production
record GETs and1004/1005 for typed ingest POST receipts. Reads and writes assert
the complete four-rule state without installing it.
Only the exact Auth0 rule 1001 may coexist; unknown/session/static rules refuse.
Never silently clear other policy or downgrade on unsupported Chrome response
conditions. Keep protection checks inside the HTTP deadline and around body
consumption; a late or encoded result cannot acknowledge queued work. Before
records can be read, the typed reader must select this protected JSONL leg;
generic JSON permits only canonical catalog paths under /data/v1/ and refuses
encoded path aliases before fetching. Before
setup changes, publish the caller's new account/config generation. Safari needs
its own native transport proof. The
development contract and
tests
define the API support and bounds; default senders remain unchanged.
Historical Collect migration (development)
The offline foundation
binds an immutable account/source/target/schema/codec/range plan to a separate
private ledger. A separate read-only raw HTTP reader
now retains bounded private response artifacts. A separate
paired export driver
adds bounded library orchestration; production export/apply/CLI and runtime
account authority remain separate work. Supply a captured
client and fresh consent/origin guard returning the expected account UUID; never
instantiate an ambient fallback client. Reads enforce the production HTTPS API,
explicit account/type/range, no redirects, a 64 MiB raw-body cap and default
30-second request deadline/socket timeout. A pass UUID cannot change plan scope.
Each request gets a new private attempt with a fsynced manifest before HTTP,
raw bytes before parsing, and a hash/EOF receipt only after full flush. Request
identity encoding; retain encoded responses without decompressing and refuse
them. Check deadlines on raw chunks, including compressed empty-output blocks.
Recheck retained size/hash against the EOF digest before parsing the same bytes.
Scan each raw object before JSON allocation (1 MiB, 64 container levels), and
bound parsed snapshots to 4,000 rows/16 MiB canonical row JSON. Larger responses
stay raw artifacts needing a narrower read, never silently discarded rows.
Preserve failed/partial attempts; never reuse an orphan body as a complete read.
JSON wrappers, duplicate keys, lossy/non-finite numbers or invalid Unicode fail
visibly. A receipt/result always has coverage_complete: false; EOF is not
provider coverage. No credentials or arbitrary header values enter artifacts.
Version-3 receipts retain known partial-header names, bounded total/length
counts, and the optional canonical response account UUID (or absence/invalid
marker). An explicit malformed, duplicate or other-account response header
refuses body access; retain its incomplete receipt with no transport EOF or
decoded-body claim. Absence preserves request/guard authority and adds no account
proof. Explicit partial/pagination evidence or malformed/contradictory counts
refuse initial reads and later artifact consumption; verification rechecks the
account fact and binds the original receipt hash as well as the body.
The driver requires an explicit, externally justified provider contract
(version: 1, semantics: complete-below-row-cap, row_cap: 1..4000, nonempty
basis); it supplies no default. The public legacy endpoint has no cursor/total
count/ceiling attestation, and matching two reads cannot invent one. Pass UUID,
plan, contract and export protocol bind immutable version-3 pass/proof tables in
the private ledger. Old v1/v2 evidence may have discarded response-account facts
and cannot resume or certify current-format coverage; a new pass
refuses existing unbound windows. Preserve old artifacts; use a fresh authorized
pass/ledger for new evidence. Indexed next-open reads
avoid prefix-rescan starvation; a nonblocking owned-file lease serializes runs.
Reopen and hash/scope-check both raw artifacts before consuming them. Equal
multisets below the asserted cap conditionally seal; capped/unequal pairs split
with overlap, minimum saturated/unstable or failed reads stay open. Retain all
distinct versions from successfully committed pairs, including parent versions
missing from later children (at most 8,000 versions/32 MiB canonical JSON per
pair). Pair proof + raw versions + seal/split are one transaction. Metadata proof
reads do not audit artifacts afresh. Runs reserve both request timeouts, cap at
64 windows/300 seconds and report queue progress, never final coverage. The
ledger coverage fold is conditional on the supplied provider assertion. Its
lower-level status can still summarize old stored windows; that metadata is not
current-format proof or raw-account/integrity verification. The versioned driver
guard is mandatory before reuse. Final raw audit, cutoff/queue/late-delta and
disposition gates remain mandatory.
Raw variants and overlapping observations are retained; missing IDs quarantine.
Never treat an HTTP 200, capped read or observation count alone as coverage:
sealed windows bind the exact integer ordinal sequence 0, 1, …, count−1 and
ordered observation/raw hashes (fractional ordinals fail sealing and resume);
explicit narrower children replace saturated parents, and complete leaves must
cover the whole range without open reads. One-row capture does not scan all
windows; the coverage fold has a 100,000-window limit. Whole-window capture/seal
is atomic (1 MiB per row, 16 MiB total), as is child creation plus parent split.
Raw response artifacts must be retained first; a caller assertion is not provider
proof. Split operations read only the parent/children; window(id) gives scoped
resume metadata with no raw-audit claim. Unknown schemas/statuses
fail visibly, not empty. Canonical raw rows cap at 1 MiB; oversized input fails
without sealing, so export orchestration must preserve its raw artifact.
historical_complete stays false until actual conversion, cutoff/queue and late
sweep gates are implemented and verified. Original remote records remain intact.
Status says raw_integrity: "not-scanned"; coverage receipts do not certify a
fresh raw-content audit. entry() hash-verifies raw content before consumption.
Window bounds reject inexpressible submicrosecond instants and invalid timezone
offsets; shared v1 readback compares fractional RFC3339 instants exactly without
datetime truncation. Media codec v1 supports flat typed DurationAnnotation;
v2 supports the API reader DTO with strict account/definition/prefixed-source
proofs and declared legacy_record provenance. Default media specs stay frozen;
media_history_spec is a separate opt-in key/name, not a silent schema edit.
Both preserve declared fields and the shared live/history UUID mapping. Unknown
envelopes/markers, ambiguous identities and lossy output quarantine; unfrozen
schema references fail without network retrieval.
Schema 2 retains converted proposals with recomputable codec proofs; conflicting
payloads for one target atomically quarantine every prepared variant (group
bound 1,000 rows/4 MiB), while identical proposals converge. Every peer is
codec-verified before equality decisions; converted reads recheck conflicts. A prior returned proposal is
never upload authority: later variants can invalidate it. See the linked
README for supported codecs, boundaries and remaining completion gates.
The static codec registry
retains the eight media IDs and lazily loads the optional
Journal reader codec.
Unknown/unavailable codecs fail before conversion row work; raw-only export and
reopen remain possible. The new UNIFIED_JOURNAL_SPEC is opt-in local revision 2,
still an API v1 Event: existing JOURNAL_SPEC, writer defaults, creation
fingerprint, pins and pending recovery remain unchanged. Do not activate it by
relabeling cached destinations or use nullable historical enrichment to weaken
live-source validation. Its complete raw provenance, independent payload bound
and all-branch reference rejection are documented in the canonical Day One
guide. Pure conversion grants no schema creation, apply or completeness claim.
The daemon (Collect)
- Foreground without native menu auto-launch: use
fulcra-collect daemon --no-menubarfor source/server QA, following the source invocation for workspace dependencies. Ordinarydaemonkeeps auto-launch enabled. This invocation-only option skips the native menu startup hook; profile ownership, control socket, web server, quiet authentication preflight, scheduler/worker config and consent checks, and shutdown continue normally. It is not an offline, no-auth, or no-network mode. - Single cooperating daemon per effective profile (development branch):
profile ownership
uses the persistent private
daemon.lockbefore migration/control/auth/dispatch. A busy lease exits 75 with a static diagnostic; unavailable ownership exits 1. Busy is not holder-health proof. Ownership lasts until process exit even ifserve()unwinds; do not restart in-process or delete/truncate the lock file for recovery. No stale PID authorizes takeover. Stop/reconcile older unleased daemons and workers before adoption. The local cooperative guarantee excludes direct/legacy writers, detached orphans and cross-host writes; it neither proves quiescence nor retires workers. Launchd KeepAlive/systemd Restart remain unchanged and can retry a duplicate. Source verification is separate from signed-app/runtime acceptance. - Persistent service failure status (development branch): the
cached-status contract
records owned nonzero exits through
ServiceSupervisor.tick(on_exit=...)and OS launch failures through original-revision local fences. Use the atomic status-only writer; never retry an uncertain increment, infer provider health from an exit, or expose unscoped old-account state after dropping an UNKNOWN overlay. The overlay is volatile; restart is not durable reconciliation. Status/observer paths must stay free of credential and provider reads.
Trakt's current setup separates developer API apps from Connected Apps. See the
canonical media guide
for current and legacy links, Client-ID-only PKCE at auth.trakt.tv, retained
legacy refresh credentials and exact saved callbacks. Choose a Development
app for Collect's exact local HTTP callback; Production requires HTTPS.
Deployed form support is verified; actual new/legacy account sign-in remains
release QA.
- Day One v1 (development branch): the Journal writer
uses
v1_destination_ids.journal, strict Collect auth, immutable pending batches and replay exclusions. It preserves import-once behavior and the case-sensitive legacy source hash; reruns do not overwrite cloud edits. Old annotation selections need explicit mapping. Preview creates no metadata or receipts. Attachments remain unuploaded. The writer is included in the published 0.1.5 app; source-specific live acceptance and historical conversion remain separate. The standalone CLI now shares the v1 writer with explicit CLI/env auth and fresh API account proof; Collect authentication remains strict and separate.--destination Event/<UUID>selects an owned compatible target; legacy bare IDs require explicit mapping. Real invocations use fixed profile-localcli-dayonestate, a bounded invocation lease and shared task/account-record leases. Resume original pending work before reading/discovering sources, empty returns or metadata. Changed account/options hold without discarding pending evidence; issued absence never permits resend. Default--local-dbbinds a selector, discovers the current default only after recovery, and may select another DB later; explicit--db-pathbinds an absolute path. Dry-run reads local input only, without auth/profile/DB/provider work. The annotation-definition/GenericEvent Python API raises migration errors; useDayOneFulcraClient.open(settings)andJournalWriter.resume()/run_import()with original entries. The explicit runtime pins the profile before state access and uses the same DB9 rollback protocol; its serialization does not extend across profiles/hosts. Ordinary Day One tests deny external HTTP and use synthetic transports. - Gmail account/delivery (development branch): the captured transport
binds Google reads, Files, canonical coord companions and local receipts to
fresh Collect/source consent. The app bundles
coord-engine; never restore default CLI credentials or a subprocess relay. Exact directive-file readback precedes relay-done; an empty search envelope is not delivery evidence. Ledgers/cursors include the destination principal and actual action target; old source-only state is retained, never adopted as proof for a new target. - Reminders/Todoist account/read consent (development branch): the
task engine contract
checks captured read consent in preview as well as live runs. Actual callers
use
CollectRecordSessionand inject shared Files HTTP into the task vault. incomplete HTTP reads remain UNKNOWN and cannot authorize file or checkpoint writes. Never restore a frozen bearer or selection-only guard. Retain task generations, completion journals and the final mutation leases. Todoist guards each HTTP request/chunk and observation checkpoint; Reminders guards each bounded bridge invocation. In-flight native calls can finish; revoked results are discarded. - Apple Notes: included in the macOS bundle and registry fallback. Use the wizard for Full Disk Access verification and one-way import. Snapshots use a bounded SQLite online-backup subprocess; entity IDs are resolved from Z_PRIMARYKEY. Preserve unowned Markdown and refuse missing/ambiguous fences. Keep real library metrics and source data out of public code, tests, commits, and reports. On the development branch, account/consent binding uses an explicitly injected Collect Files adapter in sync/reconcile/writeback, never default CLI credentials. Guards cover source reads, each Files request and final leased writes (including native writeback); reconciliation caches include destination account. Local-only sync preview stays cloud-free; reconciliation reads require Collect sign-in. It remains Files-only.
- Bundled runtime: the Briefcase app supports --collect and --fulcra CLI
dispatch plus an internal --notes-snapshot worker. Build-generated sibling
launchers supply fulcra-collect, fulcra, and fulcra-api without a developer
venv. Workers must use the bundled launcher, never Python -m flags on the
native app executable. The build installs these before signing. Before any
bundled dispatch, the entry point
sets
SSL_CERT_FILEto the includedcertifiroots only when neither CA-file nor CA-directory override is present. Embedded Python may lack OpenSSL default roots; urllib/Auth0 needs this explicit default. Preserve operator trust overrides and TLS/hostname verification; never work around this with disabled verification. Missing roots fail before auth. Source/venv trust is unchanged. - Public-input bundle QA: follow the invocation-bound stages
and stage helper, with
canonical sanitizer at the existing
raw/postbuild/check-only positions. Prepare BEFORE CREATE; local launchers retain
the exact legacy tuple, while cloud uses the closed source-owned
cloud-xcode16.4-arm64-v1qualifier andcontrolled-install-and-bindfor PREPARED generation1 → BOUND generation2 before raw sanitize. Profile/tool cross-binding is mandatory at start/context/current/native entries. The cloud ownership bootstrap consumes a durable attempt before full recipe validation; any later UNKNOWN requires a fresh nonce/run directory/app namespace after inactive-lock recovery, never retry or saved-proof adoption. First admission needs the live one-use witness; descendants use their independently owned digest chain. The typed observer alone allows256MiB/file, with544MiB/60s for two OS passes plus six ordinary128MiB tool passes; actual toolsets that cannot fit fail before producer effects. One original300s deadline starts before ownership bootstrap and spans all reads, sweeps, publication and final admission; nested operations never renew it, and commands reserve kill/reap time within it. Every presented live witness is revoked even on early source/selector failure. The exact source-owned Python b10 linker-data requirement stays outside the unchanged privacy catalog: owned expected alias selection requires its presence, regular type, mode and bytes at local/cloud binding and full verification, plus exact support-member consumption before the config skip. Only the additional canonical Collect outer alias activates the two fixed PyObjC debug companions: their complete wheel/member/fixed-slice origin and current bytes stay exact, including full-hash signing snapshots before native parsing. Only these selected exact data leaves leave the native target set; full inventories, privacy and framework/app verification remain. See the linked package contract and pure source-data record. Exact limits, pinned environment/installer, SDK scope and local compatibility live in the linked package contract. Actual cloud app/N1 qualification remains required; pure tests do not grant it. Preserve the stage ordering; only the controlled BUILD/sign wrappers can mint a signed generation. Current I/H live in trusted entry/completion plumbing (COLLECT_PROVENANCE_CONTEXT), never candidate receipts or saved old contexts. Its schema2 envelope is capped at 32 KiB and independently binds immutable metadata (0600/write-once/8 MiB/no head); remaining head growth through gen64 and current environment/argv capacity are checked before receipt publication. The build uses a fresh external private run directory and parent-owned private completion FD (COLLECT_PROVENANCE_RUN_DIR,COLLECT_PROVENANCE_COMPLETION_FD) whenCOLLECT_PROVENANCE_REQUESTselects the constrained path. It must be a writable pipe, concurrently drained through bounded length framing and EOF; regular files/partial frames fail, and old full contexts require fresh entry. Lost authority restarts fresh; no receipt adoption or scope-lock stealing. Preserve strict no-provenance fallback, source/wheel/support/inventory gates, and independent review. Exact current app inventories precede broader transform comparisons; only whole unchanged public intervals receive marker permission. Framework parent-file aliases require component-by-component ordinary-inventory proof inside the same framework before complete inventory emission; canceled links/missing paths, temporary escapes, non-file leaves or changed identities remain UNKNOWN. Qualification grants no content exception or actual-app acceptance. Source-derived ad-hoc per-target policy and fresh absolute codesign observations are required. Bind framework/nested-app executable aliases to pinned origin Info.plist and exact scoped paths/version links; all final alias policy fields agree in both BUILD/sign sets. Unknown geometry stops before mutation; unknown compiler/tool/ entitlement forms stop UNKNOWN. Runtime/help/cache boundaries mark mutations DIRTY and require controlled re-sign/fresh final signed checks. Receipts/inventories are 0600 write-once, capped at 256 KiB/8 MiB; native verification 30s/command,300s total,1 MiB/command; BUILD900s/16 MiB; timeout/cap kills and reaps the whole group. Actual cloud N1 remains UNKNOWN: pure/fake-tool GREEN is neither native qualification nor release permission. - AppleScript writeback is experimental: it additionally requires explicit writeback_enabled = true and refuses all attachment types. Do not enable it as part of ordinary Notes setup.
- Plex/Jellyfin receiver port: setup exposes
portas a typed port setting (default8765) on the common topology step; both local and LAN URL examples instruct the user to substitute their selected port. Preserve the LAN token guard. See the receiver plugin. - Setup does not imply sync consent: entering the final wizard step must
never enable or run a plugin. Use its explicit start action, persist the
displayed preview mode before enabling, and fail closed if settings cannot
be saved. Run
node --test packages/web-ui/tests/*.test.cjswhen changing wizard navigation or first-run behavior. Next displays Saving… and coalesces duplicate clicks while a save is pending; navigation releases Next on the new step and invalidates late advancement and subsequent Enable/Run requests. Preserve both onboarding/Configure bindings and the navigation regressions when changing the wizard controller. - Worker deadlines cover process exit and both pipe EOFs. The runner uses one monotonic budget, bounded output tails and no drain threads. On timeout or failed draining it stops the owned process group even if its leader exited, with at most 0.5s direct-child reaping. Escaped separate-session helpers are not chased; their pipe handles cannot extend the deadline. Keep the real descendant regressions.
- Run it durably as a launchd agent, NOT a backgrounded shell process — a
foreground/
&daemon dies when its terminal or session ends. Install + load:uv run fulcra-collect install, thenlaunchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.fulcra.collect.plist. Restart:launchctl kickstart -k gui/$(id -u)/com.fulcra.collect. Stop:launchctl bootout gui/$(id -u)/com.fulcra.collect. Logs:~/Library/Logs/fulcra-collect/. - Subcommands:
daemon install status run enable disable set-credential set-setting set-interval plugin doctor. There is nostart;doctorruns the pre-flight diagnostic. set-credential(keychain) andset-setting(config.toml) are the headless pair for configuring a plugin without the wizard.set-settingvalidates against the plugin's declaredrequired_settingsand refuses any key declared as aCredential— every mistake it could otherwise make (typo'd plugin id or key, out-of-range enum) writes successfully and is then never read, so it must fail loudly at the CLI or not at all.- Config dir
~/.config/fulcra-collect/:control.sock(the UDS the menu-bar- CLI use),
web-url(defaulthttp://127.0.0.1:9292),web-token(Bearer for the web API).
- CLI use),
- Control socket paths are
bounded to 104 filesystem-encoded bytes including the terminator. Long or
multibyte profile paths retain a
control.socksymlink to a private per-UID socket. The completed system-temp candidate must fit; otherwise/tmpis used. The selected per-UID child must be an ordinary current-user-owned directory before chmod/socket replacement; aliases and foreign owners fail visibly. Keep directory mode 0700/socket mode 0600 and client indirection. - Plugin authors needing independent durable cursors/state use RunContext's
kv_get/kv_set/kv_update/kv_deleteAPI. It is isolated by plugin ID and backed bystate.db; values must be JSON (64 KiB maximum, 256 UTF-8-byte keys). Usekv_updateonly for quick, side-effect-free atomic transforms because it holds SQLite's writer lock while the callback runs.
Freshness: run status cannot tell you a source has died
last_run / last_outcome / consecutive_failures answer did the plugin
run, never did it collect anything — a source whose upstream goes quiet
keeps exiting cleanly with last_outcome="done", so every health signal stays
green while the data stops. freshness.py supplies the missing half from two
independent clocks: last_yield_at (daemon clock — catches "runs fine,
produces nothing") and newest_item_at (source clock, monotonic so a
backfill cannot drag it backwards — catches a plugin that keeps writing while
upstream is frozen). Plugin authors: pass observed_at=<ISO source timestamp>
to ctx.annotation(...) (only the plugin knows when the thing happened
upstream), and opt in with freshness=FreshnessExpectation(max_yield_silence=…,
max_upstream_lag=…) — monitoring is opt-in by design (a bound guessed
from default_interval would cry wolf on legitimately rare sources; set
max_upstream_lag above normal quiet periods). A plugin that has never
yielded reports UNKNOWN — deliberately neither healthy nor stale; collapsing
"we have not looked" into "we looked and it is fine" is what let a four-day
outage read as green.
launchd PATH gotcha
launchd runs the daemon with a restricted PATH
(/usr/bin:/bin:/usr/sbin:/sbin) and does NOT source your shell profile — so
~/.local/bin (where uv tool install fulcra-api puts the fulcra CLI) is
invisible. Any code shelling out to the fulcra CLI must resolve it via
credentials._find_fulcra_cli() (PATH → ~/.local/bin → homebrew), never
bare shutil.which("fulcra").
Second-order gotcha (bit the gmail relay twice): resolving your OWN binary
to an absolute path is not enough if that binary shells out further —
coord-engine itself execs fulcra-api by bare name, so under the daemon's
PATH every relay emit silently no-oped for five days. When you shell out to a
tool that itself shells out, pass an env whose PATH includes the install
dirs AND set EnvironmentVariables.PATH in the daemon's launchd plist.
The development Gmail relay removes that subprocess chain: it embeds the
bundled engine with an explicit Collect transport; see its
account/delivery contract.
HTTPS trust in packaged Collect
fulcra-collectbootstraps missing compiled-in OpenSSL CA paths locally before subcommands, using the installed certifi bundle forSSL_CERT_FILEand an unsetREQUESTS_CA_BUNDLE. Workers and CLI children inherit the environment. Preserve operator-supplied values and certificate verification; do not solve bundle trust failures by disabling TLS checks. Existing platform CA locations are left alone. This does not repair Keychain ACLs or prove signed-app HTTPS; see the Collect README.
Keychain
- User secrets live in service
fulcra-collect:user; plugin secrets usefulcra-collect:<plugin-id>. Native macOS background reads usemacos_keychain.pyin a disposable child using the same executable/signing identity. Modern per-query flags alone do not suppress legacy file-Keychain ACL prompts: the child also disables interaction for its own lifetime. The daemon/UI process's setting stays unchanged. Only item-not-found is absent; denied, locked, pending and unreadable items remain UNKNOWN. Configured non-nativekeyringbackends retain their own behavior. credentials.pybounds reads to 3 seconds, one pending OS call per item and 16 per process. Timed-out calls retain their slots until completion; fresh auth guards never reuse a late result. Local writes/cache invalidation fence older reads. Optional source credentials stay optional for modes that do not use them.- An authenticated explicit
POST /api/plugin/<id>/credential/<key>/authorize(control commandauthorize_credential) validates declared key/scope and requests access to the existing item. Configure shows Allow Keychain access for unknown credentials. A subsequent quiet read must succeed; one-time Allow alone does not prove background access. Always Allow remembers the current app identity. No secret value is returned or replaced. - Core sign-in access recovery uses the separate authenticated explicit
POST /api/fulcra/auth/keychain_access, restricted tobearer-tokenandoauth-credentials. Unknown auth status routes to Settings for access recovery; it must not imply expired or missing credentials. Reinstallation or a changed signing identity may require another explicit grant. Preserve existing items rather than deleting them to repair an access problem.
Collect distribution resources
Collect distribution builds require complete prebuilt SPA/docs inputs. The
canonical package contract
and build hook define the archive-only
_build_resources snapshot, existing wheel _bundled layout, lexical archive
markers and fail-closed missing/symlink/special-file handling. Never temporarily
stage assets under fulcra_collect/_bundled: its presence changes running resource
selection. Build tools may reject/read malformed PKG-INFO before this hook, so
backend errors are not hook-execution evidence. Use the
disposable packaging tests for build
parity/failure proofs; do not delete/chmod/rename live assets to make a negative
case. Input immutability, cached offline backend, frontend preparation and later
signed-app/installed acceptance remain distinct prerequisites/gates.
Menu-bar app
- Launch from a GUI (Aqua) session:
uv run --package fulcra-menubar python -m fulcra_menubar. Not from SSH/detached shells, or the status item won't appear. Under Homebrew Python the bundle id isorg.python.python(use that for computer-use / TCC grants, notcom.apple.python3). - It talks ONLY to the daemon over the control socket; it never reads the keychain. Auth state, tracks, and plugin status all come from the daemon — a stale UI usually just needs a relaunch / reopened popover.
- Bundle-requiring macOS APIs (
UNUserNotificationCenter, etc.) raise an uncatchable NSException when run unbundled (python -mfrom a venv) —try/exceptcan't recover it. Guard with_notify_macos.running_in_app_bundle(). The shipped app is bundled via Briefcase.
Sign-in & first run
Full first-run walkthrough + troubleshooting: docs/TESTING.md.
Diagnose a live install with uv run fulcra-collect doctor.
Its coverage contract
includes a static WARN for unchecked v1 destination schemas and delivery;
configured writers own that validation/readback. Exit 0 means no diagnostic
FAIL, not acceptance of a source's schema or records.
coord-fold — the coord-on-annotations fold engine (packages/coord-fold)
Canonical home for the durable facts about packages/coord-fold (its plan docs/superpowers/plans/2026-09-04-coord-fold.md and spec docs/superpowers/specs/2026-09-04-coord-annotation-bus-design.md exist only on the unmerged coord-fold-plan branch, not on main). Ship-gate rule: every PR touching the package updates this section or states "no change needed".
What it is. A SEPARATE package (not a module inside coord-engine): coord_fold/{events,transport,channel,checkpoint,fold,cli}.py, each owning exactly the symbols the ownership manifest in tests/test_structural.py names. Its import graph never reaches coord_engine; pyproject.toml declares no dependency on it. Dependency direction is one way: coord-engine's old side (Tasks 12–14: seed export, dual-emit, comparator) may import nothing from here and here imports nothing from there.
The reader/writer boundary (spec §3.4, corrected). The transport is a two-method Protocol; CliPointerReader and CliPointerWriter are unrelated classes with disjoint surfaces and NO enumeration method. §3.4's original wording implied that the type "stops os.listdir"; corrected: a type stops a method call, not os.listdir — nothing in a Python type prevents a caller from enumerating. The guarantee that enumeration does not happen is G29, below, not the type.
Six verbs, three exit codes (coord_fold/cli.py): emit, fold, claim, release, close, status. RC_OK=0, RC_REFUSED=2, RC_UNKNOWN=3. Refused means the verb declined on evidence it read; UNKNOWN means a read did not answer and nothing was concluded. A capped fold pass is NOT an error (G25): it applies what it read, advances the cursor to the last applied event, reports unread_events: N and exits 0 — a remainder bounded by new events, not a failure. The only fold error is zero progress while events exist. The string degraded never appears on any output path (G11; tests/test_no_degraded_vocabulary.py enforces it): unreadable_pointers: [slug] is UNKNOWN (exit 3); unread_events: N is a remainder (exit 0). An unknown never reads as clear.
Cursor rules (G26, G31). The cursor is the recorded_at of the last OBSERVED record before the first UNAPPLIED RELEVANT event — never now, never past a gap. Records that are unparseable, foreign-schema, or addressed to someone else are observed and passed, never re-read. Checkable consequence, made a test: re-running a fold from the stored cursor yields the same open set. Lost-update detection, not CAS (G27): the store has no compare-and-swap; the checkpoint carries writer and a monotonic generation, the fold re-reads before writing and refuses by name if the generation moved. No compaction, never delete events (G28).
Relevance rule (RULING 2026-09-05, coord-boss blocker a0927018). An obligation belongs to its ASSIGNEE. An event applies to an agent's fold when it is addressed to that agent or to all, OR when the agent itself sent it and it is a claim/release/close (the assignee's own action on an obligation it holds — those are addressed to the open's sender but performed by the assignee, and the assignee's fold must see them or a closed row would stay open forever). An open or note the agent SENT never opens for the sender: a sender's waiting is bookkeeping, not an obligation. The earlier rule applied every sender event too, so every seed leaked into its senders' folds (coord-boss saw 54 of coord-maintainer's opens, coord-maintainer 137 of coord-boss's) and no coordinator could ever AGREE. Both sides — the old plane's obligations/compare-to-fold and coord-fold — ask the question this way. Checkpoint rows carry to (the recipient) since 2026-09-05 so a divergence classifies from the row alone; the field is ADDITIVE, rows written before it lack the key and stay valid, and SCHEMA_VERSION did not move because a bump makes every existing checkpoint load as corrupt and refuses the fleet's next fold. Two residual edges (coord-boss 6f8121fc, 2026-09-05): a broadcast (to: all) opens for every agent EXCEPT its sender; and the mirror turns a v3 directive into a v4 open only when the task doc it points at names an assignee (read once at write time; an unreadable doc mirrors anyway, over-capture over a silent hole) and never for an FYI, because neither opens an obligation on the old plane. Class C (coord-boss 24d545b0): a row already in a terminal status (model.TERMINAL_STATUSES) when its open is emitted — a DONE report born done — opens nothing either, or it would carry an open with no close forever. A checkpoint computed under the old rule is repaired with coord-fold fold <team> --agent <a> --rebuild: it replays the whole stream under the current rule (events are never deleted, G28) and keeps the generation/writer so a concurrent writer is still refused (G27).
Pointer resolution (coord-boss finding 2026-09-05). Emitters write ptr TEAM-RELATIVE (task/<slug>.md); the store holds team/<team>/task/<slug>.md. The READER resolves: coord_fold/pointers.py::qualify(team, ptr) prefixes team/<team>/ onto a bare pointer and passes an already-qualified one through, and both pointer reads (fold --verify-pointers, close --evidence) go through it. Read verbatim, every open row came back absent (a legitimate answer, so nothing flagged it) and the flag whose job is to prove pointers resolve reported 339 of 339 unreadable. No migration of emitted events; every other consumer of this plane (the Linear bridge already does) must resolve the same way.
Record write shape (G13 drill finding, 2026-09-05). coord-fold's writer invokes the real CLI exactly as the engine's record_write does: record <data_type> --api-version <v> --source <sender> with only {note, recorded_at} on stdin. The first cut passed no positional and five stdin keys; the real CLI refused every write (rc 2, Missing argument 'DATA_TYPE') while the proof's fake accepted it, so every coord-fold emit/claim/release/close on the live store returned UNKNOWN until the drill tried one. The proof's store server now refuses the same shapes the CLI refuses; a fake that accepts what the real thing rejects proves nothing.
The four gate files (CI: the always-on Linux uv-workspace.yml test step, plus macOS pytest packages/; and scripts/materialize_plan.py GATES): tests/test_structural.py (ownership manifest, no enumeration, import graph, two-method Protocol, disjoint reader/writer), tests/test_tripwire.py, tests/test_ship_check.py, tests/test_ci_wiring.py; plus tests/test_file_size_ceiling.py (G8: 400 lines per .py under coord_fold/, recursive; the ceiling is documented in packages/coord-fold/README.md) and tests/test_no_degraded_vocabulary.py.
The tripwire is demoted (G30). tests/test_tripwire.py is a syntactic scan for enumeration identifiers and modules (os.listdir, iterdir, glob, …). It catches the plain spelling and nothing else — an alias, a getattr-built name, or a subprocess escapes it by construction. It is kept because it is cheap and true about what it names; it is NOT the guarantee and a green tripwire proves nothing about behaviour.
THE GUARANTEE, in G29's words. The guarantee is behavioural, OS-enforced, and observed at a process boundary. tests/proof/run_proof.py starts a store server OUTSIDE the sandbox (tests/proof/store_server.py: the corpus lives in that process, loaded from a file the sandbox cannot read; it answers only the five fixed request shapes — file stat, file download, get-records, record, file upload — refuses and logs everything else, and logs each get-records with its channel, its since, and the count returned), then runs the PRODUCTION CliPointerReader/CliPointerWriter through all six verbs INSIDE a macOS seatbelt sandbox that denies at the kernel every network endpoint except the store's socket, every exec except the interpreter, every file read outside the interpreter, the package tree and its own temp dir, and every file write outside that temp dir. Five phases: the clean run asserts the exact request sequence with paths, a path allowlist, per-shape bounds, and that no get-records asks from before the cursor the store held at that moment minus the overlap; the attack battery; a file list mutation; the epoch-rewrite mutation; the point-probe mutation — the last three must be FLAGGED. What it proves and no more: in that run the fold reached no store except through observed requests — these specific capabilities were denied by the kernel and the fold still completed. NOT "the fold ran with no capabilities". What it does not claim: that enumeration is impossible to write, that the fold cannot detect it is under test, or that a Python process can hide anything from code running inside it. The measured profile is allow-default with kernel denies on the capabilities that matter, because deny-default aborts the interpreter at startup on the proof host (measured, rc 134). The driver exits 3 (UNKNOWN) where no OS sandbox exists — never green by absence, never softened to a skip; the final line prints host, platform and UTC time. The proof needs a macOS runner: .github/workflows/coord-fold-proof.yml has two steps — one asserts the host has a sandbox (else it is the wrong host, not a pass), one runs the proof and treats exit 3 as a failed job. Linux CI is UNKNOWN by design. No bwrap profile is written until it can be measured.
Trust model of the ship gate (r34). It defends against the mutable tool environment, PATH/env resolution, and world-writable or cross-user temp locations. It does not defend against a concurrent same-user process on the gate host (which could replace the gate itself), and claims no pathname binding against one. Its temp root is a gate-created 0700 directory under ~/.local/state/coord-fold/tmp (an inherited TMPDIR is ignored); the engine child gets its CLI as an absolute path in FULCRA_CLI_COMMAND with an empty PATH; downloaded bodies are checked for owner, mode and non-link status immediately before being read.
Ship gates (ruling 6bb7fa0f, 2026-09-05). Task 1b (the proof) and Task 16 (scripts/ship_check.py: the engine's folded APPROVED result on the EXACT commit, both required reviewers' winning shards quoting git rev-parse HEAD:packages/coord-fold, an approved+pinned engine attested by the gate's own interpreter through a verified-bytes importer, trust roots stated as absolute paths --git/--fulcra-api) gate SHIPMENT, never the start of work. G24: a plan revision is filed only with Task 0 (scripts/materialize_plan.py) green.
coord bus-v4 bridge — Tasks 12–14 of the coord-fold plan (2026-09-05)
The old bus (bus-v3) and the new annotation-native plane (bus-v4, folded by packages/coord-fold) run in
parallel until cutover. Three engine verbs make the parallel run measurable; none of them changes what the fleet
acts on today.
- Channel. bus-v4 is the data type named in
team/<team>/_coord/bus-v4/records.json(data_type,api_version). No config → nothing mirrors, nothing seeds. Never hardcode it. - Dual-emit (Task 13).
coord_engine/dual_emit.py::mirroris called once at the end ofrecords.emit_event, the engine's single write chokepoint, so every bus write is mirrored without any verb opting in:directive→open,response→close,claim→claim,verdict→note, eight-field payload{v, at, from, to, kind, slug, pri, ptr}. A mirror failure never fails the v3 write. - Seed (Task 12).
obligations <team> --agent <a> --export-openwrites one bus-v4openper slug the old fold says the agent owes AS ASSIGNEE (row assignee is the agent,@agent,*, or a role the agent holds — rows the agent merely sent are not its obligations; ruling a0927018; RULING f9f5823b 2026-09-05: a broadcast, assignee*, is an obligation of EVERY recipient except its owner, so_old_open_setadds open star rows whose owner is not the agent — needs-me never lists them — matching the fold'sto == all and from != agent; RULING 13a58789 2026-09-05: broadcast closes are PER-RECIPIENT — the row's single status is the OWNER's disposition, never a recipient's close, so a broadcast stays open for every non-owner until THAT agent acks it (acked_byon the row, or the ack doc at_coord/acks/<slug>/<agent_key>.md); an unreadable ack reads as no ack; RULING 55b1056b 2026-09-06: the OWNER's terminal status (router.TERMINAL_STATUSES) ends a broadcast for EVERYONE — it is open for nobody, on the old set and on the seed — while a recipient's ack still closes it for that recipient only;respondon a broadcast writes the responder's ack record itself. RULING 316ef7ab 2026-09-06: a broadcast's status moves ONLY by its owner — a non-owner'srespondrecords the shard, writes its own ack, and closes only its own fold (the first recipient's answer had been flipping the row to done and, under 55b1056b(1), discharging every other recipient). Only the OWNER's terminal transition mirrors its v4closetoall(the v3 record still goes to the owner): the old plane drops a terminal broadcast for every recipient, so the new plane must close it in every recipient's fold too (measured 2026-09-06 05:03Z: a close addressed to the owner alone left every other fold reading only_new). DUAL-RUN RULE:coord-fold closeon a broadcast is half a close — coord-fold stays old-plane-free by design, so pair it withcoord-engine inbox <team> --ack <slug> --agent <you>until cutover, or the old plane reads only_old), idempotent via_coord/bus-v4/seeded/<agent>.md(--forcere-seeds). A re-seed RECONCILES: every slug open in the agent's coord-fold checkpoint that the correct set no longer contains gets a bus-v4close(ptr = the seed marker), so a leaked open is retired on the stream rather than deleted (G28); an unreadable checkpoint makes the whole seed UNKNOWN (rc 3), never a silent partial reconcile. Each row the seed would export is CONFIRMED against the doc its pointer names (one pointed read per row, no enumeration; coord-boss 8a280028, 2026-09-06): the needs-me projection lags the doc until reconcile, so a row closed seconds earlier was re-exported open and out-ordered its own close on v4; a terminal doc skips the row (skipped_terminal_docin the marker), an unreadable doc keeps the projection's answer (over-capture). Refuses on an UNKNOWN old fold — a seed from a partial answer would enshrine the gap as absence. Classified as a WRITE. - Comparator (Task 14).
compare-to-fold <team> --agent <a>: the old open set vs the coord-fold checkpoint (team/<team>/member/<agent>/fold/checkpoint.json) as(slug, pri, ptr)tuples; printsAGREE n=korDIVERGE slugs=[…]; appends one JSON line to_coord/bus-v4/compare/<agent>.jsonl. rc 0/2/3 = agree/diverge/ UNKNOWN. A WRITE (it logs). - Cutover check (Task 14).
cutover-ready <team> --agent <a>exits 0 only when the trailing AGREE run is ≥--min-run(24) over ≥--min-hours(24), the open set both grew and shrank within it, the divergence/ recovery drill is recorded at_coord/bus-v4/drill/<agent>.md(G13), and--ship-check-rc 0carries the rc of the runbook'sscripts/ship_check.py fulcra <HEAD> --git <abs> --fulcra-api <abs>. The window flags exist so the operator can compress the window deliberately, never silently. A read. - The flip (coord_engine.cutover, 2026-09-06).
cutover show <team>/cutover set <team> --serve fold|files --reason … --agent <a>read and write ONE switch document,_coord/bus-v4/cutover.json({"v":1,"serve":"fold"|"files","at","by","reason"}).needs-meandobligationsread it FIRST, before any file-plane work, on every invocation (nothing is cached). Three states: absent → files, today's answer, so the flip cannot happen by accident; unreadable or malformed → UNKNOWN (rc 3) and nothing is consulted — a host that cannot read the switch after the flip must not answer from files and report clean (split-brain; codex-reviewer P0, engine-ship-gate-6445cde8);serve: fold→ the agent's coord-fold checkpoint IS the answer and the task index, role resolution and review listing are never invoked (codex-coder P0, same register; sentinel tests prove it); a checkpoint that is absent, unreadable or corrupt is UNKNOWN (rc 3), never CLEAR — an identity that has not seeded its fold does not thereby owe nothing. Under fold,taskscarries every open,directivesthe non-review ones,reviewsthe review-request rows,blocks/reminders/role_dutiesare consulted-and-subsumed (their opens are in the fold), andforge_feedbackis served from the forge PROJECTION section of the summaries document by pointed reads only (one document read, one ack read per item,changed_slugsempty so nothing re-lists a feedback directory); a projection that is absent, stale, incomplete or malformed is UNKNOWN, never a raw scan (codex-coder P0, engine-ship-gate-c4a8410a; alist_dirsentinel in the tests proves the fold path never enumerates). The checkpoint's own health survives the serving boundary:unread_events > 0, a non-emptyunreadable_pointers, or malformed health fields make both public reads UNKNOWN (rc 3) with the known rows retained as partial data (codex-reviewer P0, same register). Rollback is--serve files, one write, fleet-wide.cutoveris MIXED:showis a read,setis activity. - Forge projection cost (ruling 30be1f8e, 2026-09-05).
build_forge_projectionlists the parent_coord/forge/feedback/ONCE and lists per PR only the PRs that appear there; measured on the live store 125 responsible PRs cost ~77 s of per-PR listings that almost all returned empty, against a sub-second parent listing naming two directories. An EMPTY or FAILED parent listing proves nothing (a listing answers identically for a real empty dir and a bad path) and falls back to the per-PR loop unchanged: the pruning only removes work it has positive evidence for.COORD_FORGE_BUILD_BUDGET(default 300 s, raised from 60 on 2026-09-07) is then a ceiling, not a requirement; the reconciling host carries 180 in its launchd plist. - Activity classification.
obligationsis MIXED:--export-open,--repair-unknownand--seed-checkpointeach write (two of those already did while the verb classified as a read).
Collect browser reconnect
Collect's current availability contract uses a bounded fresh quiet bearer read, never cached positive readiness. Local readability is separate from server/principal/provider/worker success; unknown, pending, missing and transition are distinct and preserve saved credentials. Only explicit authenticated, closed-scope recovery may request UI, followed by quiet confirmation. A missing optional refresh item is compatible with a manual bearer; never promise automatic refresh from it. Pending reads must not spawn duplicate prompts. Keep the existing executable/helper identity and quiet no-fallback policy; native denial causes and grants require their own evidence. Worker scope metadata comes from declared read sites, is checked against the original/current configuration and auth revision, and routes hydration errors to Configure versus shared bearer errors to Fulcra Settings. After restart/stale scope, report UNKNOWN; do not infer authority from traceback wording. Recovery navigation must not enable/run a source or overwrite/delete credentials.
Onboarding and Settings share the browser-link helper
and Collect-owned SDK actor.
The historical cli_login_start/cli_login_poll route names now speak protocol
2: a durable attempt UUID and captured device-code hash authorize one bounded
SDK grant request per poll. No CLI execution, output parsing, or terminal
credential adoption occurs. Old unscoped completion/classic requests return
409 before effects; a CLI rc 0 never proves approval. Availability is independent
of PATH. Keep authorization-origin/code checks and explicit protocol/success
checks together; pending replies alone cannot advance onboarding or reconnect.
Preserve the private auth-attempt journal through restart. It contains hashes/order metadata, never device codes or credentials. New start, paste, signout and cancellation fence stale callbacks; credential commits rotate source epochs under the account-transition gate, which opens only after credentials AND the journal revision commit. Incomplete transitions report unauthenticated/reconnect required. Renewal status updates compare current auth revision/token, so stale failures cannot relabel a newer successful sign-in. A claimed device grant or rotating refresh grant with an unknown outcome requires a fresh sign-in, never an automatic replay. Access/refresh credentials live in Collect's OS Keychain service. Same-account renewal preserves source epochs; manual tokens have no implicit CLI renewal. The prior principal-checked CLI renewal path remains only for pre-upgrade credentials with no committed owned-auth revision, and a newer interactive revision revokes it. Do not remove that compatibility path without a documented fresh-sign-in migration.
Interactive auth journal lease precedes account-transition/config leases.
Refresh may already run inside an account-shared caller scope: it MUST use the
journal's SQLite-only revision/claim methods, never the interactive auth lease
(which may be waiting for account EX). Committed auth revision changes inside
account EX; final refresh commit holds account SH plus its SQL transaction.
Network requests run outside newly acquired account/config leases; the separate
cross-process refresh lease serializes rotating grants. SDK polling loops are
not used. Run the auth suites and node --test packages/web-ui/tests/*.test.cjs
when changing these paths. Packaged, signed Keychain/restart QA is still required
before release; source tests do not establish that evidence.
Daemon CLI SIGTERM must unwind startup and running-loop ownership cleanup. Quiet Keychain helper lifetime is bound to the private-pipe requester; owner death exits the helper itself, never a reused foreign process group. Retain UNKNOWN for interrupted writes and the existing consumed-grant no-replay journal.
Controlled manual backfills may use fulcra-collect run PLUGIN
--timeout-seconds N (integer 1–7200). The ordinary scheduled budget and shared
in-flight guard remain unchanged. Keep the captured full source scope until
its original pending batches reconcile; restoring a live range cannot credit
earlier historical coverage or silently rebind pending work.
Collect shutdown closes scheduled-worker admission at the Popen/registration boundary and retains accepted launch threads until their owned children are terminated and reaped. Cancellation remains a shutdown condition, not source success. Keep process-group identity reserved through TERM/KILL, and never signal a reaped process identity. Trakt status and hydration sample one tuple per operation; retain physical bundle/legacy error origin through worker validation. Absent-bundle legacy denial routes to explicit reconnect, not bundle authorization or per-field grants. Current bundle denial permits one grant; pending/changed access permits quiet recheck only. Do not widen logical credential write routes to accept the physical bundle key.
Fresh Collect account and Trakt bundle credential reads share the same uncached boundary and may recheck pending availability quietly at most three times within 15 seconds, reserving the complete existing native wait before another observation. No cached value is accepted; the original credential revision must remain current before and after each attempt. Do not treat this as approval, renewal-grant or mutation replay. Denied/changed reads stop and exhausted pending reads remain UNKNOWN.
Apple Podcasts libraries can omit cleaned-title and duration columns. Both import and health use the same closed schema adaptation. Unknown duration stays null in source metadata and produces a point Event at the known last-played timestamp, without inventing elapsed listening time; stable source identity is unchanged.
A missing Podcast duration must not erase a previously verified interval for the same primary play and endpoint. Preserve its known duration; reject conflicting/malformed prior timing. A prior guessed interval with null source duration is not authoritative. Preserve raw source snapshots and distinguish their fields from canonical retained enrichment.
Development media chunk planning retains prior unindexed rows only when their source identities intersect the current chunk. This preserves cross-chunk aliases and twins while avoiding repeated policy reads over unrelated earlier history; current candidates and relevant aliases still receive fresh exclusion checks.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

