Thin repo pulse
Contract
| Field |
Bound contract |
| Trigger |
A scheduled or watcher tick fires and a lightweight pulse must capture current external state. |
| Authority |
Reversible local: writes only named local snapshot and marker artifacts; rollback is file deletion. No remote mutation. |
| Side effect |
One bounded snapshot file plus one run marker in the configured output directory. No source, label, workflow, merge, or issue state change. |
| Done |
The snapshot file exists, the run marker attributes it to exactly one run with status: success or status: empty, the snapshot contains the requested state (empty when the source returned no matching state), and zero action side effects were produced. A run with status: error does not satisfy Done. |
Inputs
- Snapshot source (required): the external endpoint, API, or command whose state the pulse captures.
- Output directory (required): local path where the snapshot and run marker are written.
- Scope filter (optional): a selector or query that narrows which state is captured. When omitted, the pulse captures the full available state.
- Run marker path (optional): defaults to
<output-directory>/.last-run.json.
Refusals
- Will not trigger downstream workflows, open issues, update labels, or mutate the source.
- Will not write to an alternate path if the primary write fails.
- Will not retry a failed source query; record the failure in the run marker and stop.
Procedure
- Generate a unique run identifier from the current timestamp and a random suffix. Done when: the run identifier is generated.
- Read the snapshot source configuration. If the source is unreachable or the configuration is malformed, stop and record the failure in the run marker. Done when: the source configuration is valid and reachable.
- Query the configured source for its current state, applying the scope filter if supplied. Capture the raw response without transformation. Done when: the raw state is captured or a failure is recorded.
- Write the captured state to
<output-directory>/snapshot.json. An empty result is a valid snapshot. If the write fails, stop immediately; do not write to an alternate path. Done when: snapshot.json is written to disk.
- Write the run marker to the configured marker path. The marker contains:
run_id, timestamp, source, status (success, empty, or error), snapshot_bytes, and reason (the failure description when status is error; omitted otherwise). Done when: the run marker is written with all fields appropriate to its status.
- Verify both artifacts exist on disk. If the marker status is
success or empty, the run is verified. If either artifact is missing or the marker status is error, classify the run as error and rewrite the marker with the reason. Done when: both artifacts are verified on disk with a status of success or empty.
- Stop. Do not trigger downstream workflows, open issues, update labels, or mutate the source. Done when: the pulse is complete with zero action side effects.
Failure and recovery
| Failure class |
Behavior |
| Source query failure |
Write a run marker with status: error and the failure reason. Do not retry. The snapshot file is not created. |
| Empty snapshot |
Write the empty snapshot file and a marker with status: empty. The empty result is evidence that the source had no matching state, not a skill failure. |
| Write failure (permissions, disk space) |
Stop immediately. Do not write partial artifacts or fall back to an alternate directory. The run is incomplete. |
| Rollback |
Delete the snapshot file for the current run. Before deleting the run marker, read it and confirm its run_id matches the current run; if a subsequent run has overwritten the shared .last-run.json marker, leave it in place. To avoid the conflict entirely, use a per-run marker path (<output-directory>/.last-run-<run_id>.json) instead of the shared default. |
Output
Two artifacts in the configured output directory: snapshot.json (captured external state, empty when the source returned no matching state) and .last-run.json (run metadata: run_id, timestamp, source, status, snapshot_bytes, and reason when status is error), ordering: snapshot first, then marker.
1---2name: thin-repo-pulse3description: Use when a scheduled or watcher tick fires and a lightweight pulse must capture current external state. Not for remote, credential, publish, deploy, or irreversible changes.4---56# Thin repo pulse78## Contract910| Field | Bound contract |11|---|---|12| Trigger | A scheduled or watcher tick fires and a lightweight pulse must capture current external state. |13| Authority | Reversible local: writes only named local snapshot and marker artifacts; rollback is file deletion. No remote mutation. |14| Side effect | One bounded snapshot file plus one run marker in the configured output directory. No source, label, workflow, merge, or issue state change. |15| Done | The snapshot file exists, the run marker attributes it to exactly one run with `status: success` or `status: empty`, the snapshot contains the requested state (empty when the source returned no matching state), and zero action side effects were produced. A run with `status: error` does not satisfy Done. |1617## Inputs18191. **Snapshot source** (required): the external endpoint, API, or command whose state the pulse captures.202. **Output directory** (required): local path where the snapshot and run marker are written.213. **Scope filter** (optional): a selector or query that narrows which state is captured. When omitted, the pulse captures the full available state.224. **Run marker path** (optional): defaults to `<output-directory>/.last-run.json`.2324## Refusals2526- Will not trigger downstream workflows, open issues, update labels, or mutate the source.27- Will not write to an alternate path if the primary write fails.28- Will not retry a failed source query; record the failure in the run marker and stop.2930## Procedure31321. Generate a unique run identifier from the current timestamp and a random suffix. **Done when:** the run identifier is generated.332. Read the snapshot source configuration. If the source is unreachable or the configuration is malformed, stop and record the failure in the run marker. **Done when:** the source configuration is valid and reachable.343. Query the configured source for its current state, applying the scope filter if supplied. Capture the raw response without transformation. **Done when:** the raw state is captured or a failure is recorded.354. Write the captured state to `<output-directory>/snapshot.json`. An empty result is a valid snapshot. If the write fails, stop immediately; do not write to an alternate path. **Done when:** snapshot.json is written to disk.365. Write the run marker to the configured marker path. The marker contains: `run_id`, `timestamp`, `source`, `status` (`success`, `empty`, or `error`), `snapshot_bytes`, and `reason` (the failure description when `status` is `error`; omitted otherwise). **Done when:** the run marker is written with all fields appropriate to its status.376. Verify both artifacts exist on disk. If the marker status is `success` or `empty`, the run is verified. If either artifact is missing or the marker status is `error`, classify the run as `error` and rewrite the marker with the reason. **Done when:** both artifacts are verified on disk with a status of `success` or `empty`.387. Stop. Do not trigger downstream workflows, open issues, update labels, or mutate the source. **Done when:** the pulse is complete with zero action side effects.3940## Failure and recovery4142| Failure class | Behavior |43|---|---|44| Source query failure | Write a run marker with `status: error` and the failure reason. Do not retry. The snapshot file is not created. |45| Empty snapshot | Write the empty snapshot file and a marker with `status: empty`. The empty result is evidence that the source had no matching state, not a skill failure. |46| Write failure (permissions, disk space) | Stop immediately. Do not write partial artifacts or fall back to an alternate directory. The run is incomplete. |47| Rollback | Delete the snapshot file for the current run. Before deleting the run marker, read it and confirm its `run_id` matches the current run; if a subsequent run has overwritten the shared `.last-run.json` marker, leave it in place. To avoid the conflict entirely, use a per-run marker path (`<output-directory>/.last-run-<run_id>.json`) instead of the shared default. |4849## Output5051Two artifacts in the configured output directory: `snapshot.json` (captured external state, empty when the source returned no matching state) and `.last-run.json` (run metadata: run_id, timestamp, source, status, snapshot_bytes, and reason when status is error), ordering: snapshot first, then marker.
OutlineDriven