@adamchanadam/agent-handoff-kit 0.3.64 → 0.3.66
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +17 -11
- package/README.md +11 -5
- package/bin/agent-handoff-kit.mjs +228 -35
- package/bin/migration-baselines/official-origin-catalog.json +386 -1
- package/bin/user-rules-router.mjs +4 -5
- package/package.json +1 -1
- package/packs/agent-governance.md +13 -2
- package/packs/closeout.md +10 -2
- package/runtime-core/AGENTS.core.md +5 -3
- package/runtime-core/SESSION_HANDOFF.md +15 -7
|
@@ -133,11 +133,10 @@ function ensureStateRegion(routerText) {
|
|
|
133
133
|
export function renderUserRulesAcceptanceDigest(agentsText, digest) {
|
|
134
134
|
if (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)) throw new Error("user-rules acceptance digest is invalid");
|
|
135
135
|
const source = String(agentsText);
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
return lines.join(newline);
|
|
136
|
+
parseFormalUserRulesEntry(source);
|
|
137
|
+
// Validation above proves there is one active digest. Replace only that
|
|
138
|
+
// token; splitting/rejoining the file would rewrite mixed-newline user data.
|
|
139
|
+
return source.replace(acceptanceAnchorPattern, `<!-- ack:user-rules-acceptance:sha256=${digest} -->`);
|
|
141
140
|
}
|
|
142
141
|
|
|
143
142
|
/**
|
package/package.json
CHANGED
|
@@ -14,8 +14,8 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
14
14
|
|
|
15
15
|
## Rules
|
|
16
16
|
|
|
17
|
-
1. Locate the existing source of truth before adding a rule.
|
|
18
|
-
2. Prefer merge, replace, or registry rows over append-only rule growth.
|
|
17
|
+
1. Locate the existing source of truth before adding a rule. Read the matching categories in `dev/RULE_PACKS.md`, their applicable packs, project supplements and required references first; then apply `Governance Write Boundary` below. A matching topic does not make official prose writable.
|
|
18
|
+
2. Prefer merge, replace, or registry rows over append-only rule growth, within the verified project-owned location. Change an existing project rule in place rather than duplicating it in another file or appending an override.
|
|
19
19
|
3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
|
|
20
20
|
4. Do not let development-only workspace rules enter public runtime.
|
|
21
21
|
5. Check complexity budget before adding default-core behavior.
|
|
@@ -29,6 +29,17 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
29
29
|
13. New Markdown or generated documents are not automatically harmless. After creating or materially changing them, classify each artifact before completion: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary. Durable artifacts must be discoverable from `dev/PROJECT_INDEX.md` or intentionally tied to a registered sync / source-of-truth row. Temporary or one-time evidence must be labeled as such in the task record or closeout so future agents do not treat it as hidden current state.
|
|
30
30
|
14. Do not create a new document to hold a rule, requirement, checklist, or process if an existing authoritative document can carry it. Merge into the existing home or make the new document explicitly subordinate. If two files now carry the same durable instruction, resolve the duplicate by choosing one authoritative home and pointing the other to it.
|
|
31
31
|
|
|
32
|
+
## Governance Write Boundary
|
|
33
|
+
|
|
34
|
+
This is the single write-location contract for installed projects, not for authorized Kit source development. It guides agent edits; it cannot intercept arbitrary editor writes.
|
|
35
|
+
|
|
36
|
+
1. Classify the change before writing. Use the existing task category and normative owner; read the full relevant rule and its project supplements. A current task instruction is not automatically a durable rule. Do not create a new goal, acceptance threshold or balancing policy merely to reconcile your preferences with the user's request. Follow instruction priority; surface a material unresolved conflict instead of silently inventing an override.
|
|
37
|
+
2. Treat the `AGENTS.md` managed-core region and complete official `dev/rules/*` pack bodies as protected. Daily project edits must not insert, translate, reformat, reorder or remove their contents or delimiters. Verify the installed version's official content before identifying the boundary; a heading, marker or version row alone is not ownership proof. Formal upgrade or an explicitly scoped repair owns official changes. If local rules are already interleaved, preserve them and report the required bounded reconciliation; do not guess which lines to delete or bless the mixed body as official.
|
|
38
|
+
3. Reuse the matching pack's existing project supplement when it owns the rule. Otherwise place a short local rule after the entire verified official body under `## Project Rules`; preserve the official trailing newline. This heading labels the writable appendix, not the end of official ownership. For substantial or shared procedures, reuse a registered project reference; create a new reference only if no suitable owner exists. If `dev/USER_RULES.md` formally owns the rule, use its accepted update procedure rather than editing witnessed bytes or creating a competing copy. Always-needed project entry rules may live outside the managed core only after checking their existing owner.
|
|
39
|
+
4. Preserve project-state schemas separately: edit handoff fields, actual log entries, index data or registry rows in their existing writable sections; do not insert policy into template instructions or alter machine markers. Preserve official routing rows in `dev/RULE_PACKS.md`; add a project row only when a project reference needs a task trigger, naming both the relevant pack and reference. A same-pack appendix uses that pack's existing route. Do not add a route or load a pack merely for bare startup.
|
|
40
|
+
5. Before and after an edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>` before and after those edits as the compatibility check; record the CLI version and any existing conflict separately. A pre-existing conflict requires reconciliation before claiming the write boundary is verified. A new conflict or changed official region prevents completion; restore only your own scoped change from its verified input without discarding concurrent or pre-existing user work. For ordinary project-state edits, use schema/marker and local readback checks instead of an upgrade preview.
|
|
41
|
+
6. Read back the rule from its normal consumer path: task signal -> router -> relevant pack including the project supplement and required reference -> requested action. Verify its exact requirement, scope and precedence, and that unrelated packs stay unloaded. An indexed file that no applicable route reads is not connected. Evidence must show both correct application and preserved upgrade compatibility; a successful preview alone does not prove an AI followed the rule.
|
|
42
|
+
|
|
32
43
|
## Governance Bridge Workflow
|
|
33
44
|
|
|
34
45
|
Use this workflow when the user asks for governance bridge, connect this document to governance, asks to scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
|
package/packs/closeout.md
CHANGED
|
@@ -32,7 +32,7 @@ Handoff cold zones are historical / evidence sections, old validation records, c
|
|
|
32
32
|
2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
|
|
33
33
|
The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. The semantic lifecycle gate is `agent-handoff-kit closeout-status`; when it blocks, use its first `Resolved [...]` / `Carry-forward [...]` pair to repair the handoff, not a separate project workaround, repeated doctor runs, or a broader governance rewrite. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.
|
|
34
34
|
3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
|
|
35
|
-
4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.
|
|
35
|
+
4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. Apply the packet-only reconstruction check below before answering handoff sufficiency. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.
|
|
36
36
|
5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.
|
|
37
37
|
6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
|
|
38
38
|
7. Run `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, then record only the last-verified root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization. Do not treat `dev/PROJECT_INDEX.md` or old handoff prose as the live worktree truth.
|
|
@@ -43,7 +43,15 @@ Handoff cold zones are historical / evidence sections, old validation records, c
|
|
|
43
43
|
12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
|
|
44
44
|
13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source: copy its status faithfully. A nonzero result means the closeout is blocked; do not replace it with a success summary.
|
|
45
45
|
|
|
46
|
-
##
|
|
46
|
+
## Packet-Only Reconstruction Check
|
|
47
|
+
|
|
48
|
+
Before closing out, reconstruct the next task using only the handoff, without chat memory, old logs or opening linked sources. Identify the parent outcome and consumer, the current step's relation to it, the exact resume point, remaining step/parent acceptance, and required sources with revision/freshness, reading scope/depth and unread gaps. Cite the owning handoff sections in `Reconstruction evidence`; do not create a second task summary. Then compare that reconstruction against the user's actual request and the relevant sources read this session. Missing, contradictory or assumed critical facts must be repaired in their existing handoff sections or explicitly recorded as blockers with the next clarification/read needed. Do not answer yes on labels or a successful CLI card alone: the CLI checks the recorded answer and evidence presence, not the truth of this reconstruction.
|
|
49
|
+
|
|
50
|
+
Keep one `Answer:` line (`yes`, `no` or `unknown`, with optional explanation) and one `Reconstruction evidence:` line inside the marked sufficiency section. An affirmative answer requires concrete section references; keep `next-ai-can-continue` consistent. For an older handoff, add missing facts to its existing sections at this authorized closeout; upgrade must preserve user state and must not invent reconstruction evidence. Missing or negative answers, placeholder evidence and duplicate fields block `closeout-status` without changing project files.
|
|
51
|
+
|
|
52
|
+
Use only the depth needed to resume safely. A standalone task needs no invented parent tree; state that it is the whole task. Finishing a child does not complete its parent or authorize another step. Keep the next consequential action bounded by its input, output and acceptance; do not enumerate every future microstep. Keep decision-relevant terms and identifiers faithful; when a translation could change their meaning, retain the original term alongside it. Reading coverage is previous-session evidence, never permission for the next agent to skip required fresh source reads. Honest blocked-work handoff can be sufficient when the missing fact, impact and safe next action are explicit.
|
|
53
|
+
|
|
54
|
+
## Maintenance Trigger Check
|
|
47
55
|
|
|
48
56
|
Every full closeout runs this short check; full maintenance runs only when triggered.
|
|
49
57
|
|
|
@@ -6,7 +6,9 @@ This is the small always-read contract. Detailed task and closeout procedures li
|
|
|
6
6
|
|
|
7
7
|
Classify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.
|
|
8
8
|
|
|
9
|
-
Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.
|
|
9
|
+
Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.
|
|
10
|
+
|
|
11
|
+
When resuming, use the handoff's Task Understanding, Active Objective and Next Task Required Reading to recover the parent outcome, current step, resume point, remaining acceptance and source coverage. Surface missing critical context in the startup warning and recommend the specific clarification/read; do not infer parent completion from a finished child or treat previous-session reading as your own. Bare startup remains status-only, with no extra source reads or writes.
|
|
10
12
|
|
|
11
13
|
Route intent in this order:
|
|
12
14
|
|
|
@@ -113,7 +115,7 @@ The always-enforced closeout invariants are:
|
|
|
113
115
|
|
|
114
116
|
## 5. Pack Loading
|
|
115
117
|
|
|
116
|
-
Use `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.
|
|
118
|
+
Use `dev/RULE_PACKS.md` to load the minimum task-specific set. Read the applicable packs, including their project supplements and required references, before deciding how to act; an index, title or remembered summary is not the rule itself. Apply them within the user's actual objective and instruction priority: do not invent a replacement goal, acceptance standard or competing rule system. Missing or conflicting requirements must be resolved from their owners, not filled by an invented policy. Packs may add stricter requirements but cannot weaken core safety or continuity.
|
|
117
119
|
|
|
118
120
|
Load `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.
|
|
119
121
|
|
|
@@ -121,4 +123,4 @@ After the task, apply the Persistence Gate. Do not assume the next session remem
|
|
|
121
123
|
|
|
122
124
|
## Core Complexity Rule
|
|
123
125
|
|
|
124
|
-
Before changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.
|
|
126
|
+
Before changing `AGENTS.md` or adding a durable governance rule, use `dev/RULE_PACKS.md` to load `dev/rules/agent-governance.md` and locate the existing normative owner. Follow its `Governance Write Boundary` before choosing a writable location: installed official core and pack bodies are not project-editable rule homes. Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. Scenario-specific or project-specific detail belongs in an existing pack's project supplement or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner. Do not copy the agent-governance classification table or workflow into the core.
|
|
@@ -38,7 +38,9 @@ Pre-closeout checkpoint edits, when explicitly authorized or required by the cor
|
|
|
38
38
|
- User intent: TBD
|
|
39
39
|
<!-- ack:field:task-essence -->
|
|
40
40
|
- Task essence: TBD
|
|
41
|
-
- User value: TBD
|
|
41
|
+
- User value: TBD
|
|
42
|
+
- Parent outcome / consumer: TBD
|
|
43
|
+
- Task position: TBD — parent -> current step and how this step advances it; use standalone when this is the whole task, unknown when not established.
|
|
42
44
|
<!-- ack:field:success-criteria -->
|
|
43
45
|
- Success criteria: TBD
|
|
44
46
|
- Key background already read: TBD
|
|
@@ -46,9 +48,11 @@ Pre-closeout checkpoint edits, when explicitly authorized or required by the cor
|
|
|
46
48
|
- Non-goals / boundaries: TBD
|
|
47
49
|
|
|
48
50
|
<!-- ack:section:active-objective -->
|
|
49
|
-
## Active Objective
|
|
50
|
-
|
|
51
|
-
TBD
|
|
51
|
+
## Active Objective
|
|
52
|
+
|
|
53
|
+
- Current step: TBD
|
|
54
|
+
- Resume point: TBD — next bounded action, target and last verified result; distinguish finished preparation from unfinished work.
|
|
55
|
+
- Remaining acceptance: TBD — what still proves the current step and the parent outcome; if complete, cite evidence rather than infer from child completion.
|
|
52
56
|
|
|
53
57
|
<!-- ack:section:completed-this-session -->
|
|
54
58
|
## Completed This Session
|
|
@@ -67,7 +71,9 @@ Recommended next step: TBD — reason: TBD
|
|
|
67
71
|
<!-- ack:section:next-task-required-reading -->
|
|
68
72
|
## Next Task Required Reading
|
|
69
73
|
|
|
70
|
-
Before acting on the next task, read or mark blocked:
|
|
74
|
+
Before acting on the next task, read or mark blocked:
|
|
75
|
+
|
|
76
|
+
In Source, identify the authoritative file/link, revision or unverified freshness, and relevant sections/range. In Why required, name the decision or acceptance it supports. In Status, record the previous session's actual depth (located / skimmed / relevant range read / verified), remaining unread scope, and what the next agent must read before acting. An old read claim is not a fresh read. For no required sources, state none with a reason; do not invent coverage.
|
|
71
77
|
|
|
72
78
|
| Source | Why required | Status |
|
|
73
79
|
|---|---|---|
|
|
@@ -141,8 +147,10 @@ Closeout-card rule: `closeout-status` reads only these existing handoff fields p
|
|
|
141
147
|
|
|
142
148
|
Can the next AI continue from `AGENTS.md`, this handoff, and only the project index / rule packs required by the next task, without searching old log history?
|
|
143
149
|
|
|
144
|
-
Answer: TBD
|
|
145
|
-
|
|
150
|
+
Answer: TBD
|
|
151
|
+
Reconstruction evidence: TBD — apply the packet-only reconstruction check in `dev/rules/closeout.md`; cite the sections supporting the outcome, task position, resume point, remaining acceptance and source coverage. Record gaps explicitly; a bare yes is insufficient.
|
|
152
|
+
Keep the `Answer:` and `Reconstruction evidence:` labels. Use `yes`, `no` or `unknown` for Answer, followed by an explanation if needed. Narrative and section headings may use the project's language.
|
|
153
|
+
If no, update this handoff before closeout. Unknown critical context blocks dependent work and is not permission to guess. A saved packet may honestly describe blocked work.
|
|
146
154
|
|
|
147
155
|
Continuity rule: this file carries current state and next action. `dev/SESSION_LOG.md` carries recent evidence only. Archive old detail only when needed; do not create an archive directory by default.
|
|
148
156
|
|