ssdavidai/alfred/alfred-commitment-register

Alfred — Commitment register

A commitment is a promise with an accountable party and an evidence handle. This skill holds every one of them for a matter so Sir never has to reconstruct who owes what from memory.

Canonical state lives in `commitment/` vault records. Notes, Canvases, dashboards and briefings are projections, regenerated from the records every run. A projection is never authority, and stale projection prose must never override a record.

Switching it on

The matter's frontmatter carries the config. One word is enough:

commitment_register: true

Everything else is derived:

`<matter-slug>` is the matter's filename without `.md`. Nothing else.

Read it off the record's path: matter/neoterra-ai-consulting-ntpos-build.md gives neoterra-ai-consulting-ntpos-build. Do not derive it by slugifying the name field. A matter's display name drifts — it gets retitled when a product is renamed — while its filename does not, so the two often disagree.

A live example: a matter whose file is matter/neoterra-ai-consulting-ntpos-build.md carries the name NeoTerra AI Consulting Ken Build. Slugifying the name produced ...-ken-build-commitment-register.md, a projection at a path nothing else would ever look for. The filename is the stable identifier; the name is prose.

Use that one string for the projection path, the policy-note path, and the commitment_scope.

This is not cosmetic. A derived path is only useful if it is predictable: anything that later resolves a register by constructing its path — a rollup, a digest, the next reconciliation — looks for the slug form. A title-cased filename is not lost, but it is unaddressable by the rule meant to find it, and a check that trusts the convention will silently report one fewer register than exists.

Verify by constructing the path, not by listing the directory. After writing the projection, read it back at the exact derived path. A read-back that locates the file by any other means passes while the derivation is broken — which is precisely how this went unnoticed.

Use the object form only to override a derived value that is wrong — a prefix collision, a participant the matter does not list, a different destination:

commitment_register:
  enabled: true
  prefix: ACME
  participants: [...]
  projection: slack:workbench-acme   # opt-in; default is the vault note

enabled: false, or the key's absence, means this skill does not act on the matter — so a matter with a bespoke wrapper skill keeps running on it.

Record the resolved values in the policy note, marking which were derived. A later run cannot otherwise distinguish an intentional override from a drifted default.

Invocation contract — "create a commitment register"

When Sir says create, build, set up or stand up a commitment register for a matter, that authorises and requires the complete system now — not a report, not a schema proposal, not a note, and not stopping after the records:

1. Full initial evidence reconciliation across the available sources.
2. The policy note, from templates/commitment-policy-note.md.
3. Canonical commitment/ records with stable IDs, evidence, states and

dependencies.

1. The projection — a vault note by default — generated from the records and

read back.

1. A weekday reconciliation schedule, unless Sir said on-demand only.
2. An immediate end-to-end test of that schedule.

Do not ask whether he wants the projection or the automation after he used that phrase; they are the product. Ask only when a genuinely irretrievable choice blocks implementation — two equally plausible matters, or no way to identify the intended people.

A request to review, summarise, inspect or reconcile an existing register does not authorise creating a new destination or schedule. Follow the existing configuration.

Use references/bootstrap-verification.md for the read-back matrix and the schedule proof standard.

Before creating anything

1. Search the vault for an existing policy, commitment IDs, records and

aliases. Search the bare ID stem (ACME-COM-2026-), not a quoted-string grep — YAML quoting varies and an exact match silently undercounts. Count only type: commitment records with a valid ID and the expected commitment_scope.

1. Search existing skills and scheduled jobs so you do not build a duplicate.
2. Read every candidate record before modifying it.
3. Find existing projections and classify each as canonical, private, or

client-facing.

1. Preserve valid fields and links — patch deltas, never replace wholesale.

Record contract

One commitment/ record per commitment:

• commitment_id — <PREFIX>-COM-YYYY-NNN, allocated sequentially
• commitment_scope — the matter slug
• commitment_kind — principal_promise, client_request,

internal_request, or a documented local type

• commitment_state — see the lifecycle below
• requested_by, accountable_party, next_action
• source_type, source_ref, source_quote
• last_verified_at
• matter_ref — matter/<slug>.md. Commitments hang off matters; the matter

is the ongoing concern and the commitments are the promises inside it.

• depends_on, blocked_by, blocked_on where relevant
• delivery_evidence, client_acknowledgement or equivalent
• tags commitment and the matter slug

Optional: due, not_before, pending_confirmation, acceptance_criteria, released_by, release_evidence, supersedes, superseded_by, projection_visibility.

When writing raw YAML, quote any scalar containing `#`, `: `, or brackets — otherwise an issue reference like #319 truncates next_action at the comment marker. Read back and repair before generating the projection.

Lifecycle

captured → accepted → in_progress → ready_to_deliver
         → delivered_awaiting_acceptance → fulfilled

Holding: waiting_on_principal, waiting_on_alfred, waiting_on_client, blocked. Terminal exceptions: released, superseded.

Coarse status mapping — the vault's four-value vocabulary:

released and superseded keep status: blocked or done as appropriate and carry the truth in commitment_state. If the coarse status cannot express the real state, preserve truth in `commitment_state` — never force a false closure.

Capture rules

1. A commitment needs an obligation, an accountable party, and an evidence

handle.

1. Brainstorming, possibilities, FYIs and aspirations are not commitments.
2. Ambiguous obligations may be captured with pending_confirmation: true —

and must not be presented as agreed work.

1. Deduplicate by obligation, requester, deliverable, source and outcome.
2. Preserve the source quote faithfully. Never strengthen the wording.
3. Preparation is not delivery. Delivery is not acceptance.
4. Close only on delivery evidence plus acceptance, an explicit release, or

governing-instrument evidence proving nothing is outstanding. Contract-based closure cites the clause and is never described as client acceptance.

1. A client-owned prerequisite is a blocker on the record — do not invent a

phantom record owned by someone outside the system.

1. Scope changes supersede. Preserve the old record; link both directions.
2. Record dependency chains explicitly; detect missing targets and cycles.
3. Before turning any overage, capacity variance, renewal, penalty or payment

shortfall into a decision for Sir, follow references/contract-authority.md. A timesheet can quantify a variance; it cannot create an obligation.

Reconcile

When Sir asks whether commitments were delivered, accepted or paid in a named source, inspect that source directly in the same turn — follow references/direct-delivery-evidence.md. Do not let a stale record body, session summary or projection override direct source evidence.

For routine reconciliation:

1. Read the policy note and every record for the scope. If the policy still

demands a retired section or superseded rule, repair that narrow drift and read it back first — a stale policy must not reintroduce a layout the current format forbids.

1. Take the oldest active `last_verified_at` as the evidence cutoff. Not

the schedule tick, not the calendar.

1. Sweep bounded evidence per references/bounded-evidence-sweeps.md. Query a

conditional source only when its trigger window has opened; record an intentional non-query as an exclusion, not as degradation.

1. Classify each evidenced change: new commitment, state transition, blocker

change, delivery, acknowledgement, release, supersession, evidence-boundary expansion, or no change.

1. Patch minimal frontmatter, and advance last_verified_at only after the

sweep completes.

1. Read changed records back. Verify ID, state, evidence, next action, tags,

coarse status, and body/frontmatter agreement.

1. Recompute counts and dependency chains from the records.
2. Generate the projection from the records, then read the written artifact

back.

Distinctions the classification depends on

Evidence-boundary expansion is not a lifecycle transition. When a new issue, ticket or defect belongs to the same failure family, intended outcome, accountable party and acceptance boundary as an existing commitment, enrich that record's source_ref, next_action and body — do not create a new commitment and do not call it a state change. Split it out only when it introduces a distinct deliverable or acceptance boundary.

Message timestamps are the boundary, not session start times. A session that began before the cutoff may contain a later message proving delivery.

Exclude the register's own machinery. Scheduled jobs and dashboard refreshes that restate register content are not evidence. Repetition by a projection is not a signal. Inspect the underlying messages when a hit comes from a scheduled session.

A newly scheduled meeting is execution context, not a commitment — surface it as the next opportunity to resolve existing actions while Changes since… still reads No evidenced state changes. Exception: when the obligation was specifically to arrange the meeting, a verified invitation fulfils it. That proves scheduling only — not acceptance, attendance, or any downstream commitment.

Repair every human-readable surface, not just the body. After a rescope, due-date move, unblock or transition, audit description, title, next_action, blocked_on, acceptance text and opening prose in the same pass. A later corrective appendix does not make an earlier contradictory summary harmless — dashboards and search previews render the stale field first. Include terminal records in this audit: a fulfilled commitment may still open with "blocked" or an executable next action. That is hygiene, not a transition.

A timeout after requesting a state change is ambiguous, not failed. Read the record and its audit trail before retrying; if the transition already landed, continue from it rather than duplicating the mutation.

No-change runs

A scheduled run may begin minutes after a prior verified pass. When it does: