@adamchanadam/agent-handoff-kit 0.3.52 → 0.3.53

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.52",
3
+ "version": "0.3.53",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,103 +1,103 @@
1
- # Agent Governance Pack
2
-
3
- ## Scope
4
-
5
- Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
6
-
7
- ## Load When
8
-
9
- - User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
10
- - A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
11
- - User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
12
- - User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
13
- - The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
14
-
15
- ## Rules
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.
19
- 3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
20
- 4. Do not let development-only workspace rules enter public runtime.
21
- 5. Check complexity budget before adding default-core behavior.
22
- 6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
23
- 7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
24
- 8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
25
- 9. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
26
- 10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
27
- 11. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
28
- 12. 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.
29
- 13. 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.
30
-
31
- ## Governance Bridge Workflow
32
-
33
- 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 的重要文件".
34
-
35
- 1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
36
- 2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
37
- 3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and "read when" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.
38
- 4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.
39
- 5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.
40
- 6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
41
- 7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.
42
- 8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.
43
-
44
- For repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.
45
-
46
- Output format:
47
-
48
- - Status: bridged / partially bridged / unbridged / blocked.
49
- - Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.
50
- - Already bridged: list the governance links that are present.
51
- - Gaps: list missing links and why they matter for the next agent.
52
- - Not applicable: list skipped layers with a reason.
53
- - Suggested patches: list exact files and sections to update.
54
- - Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
55
- - Acceptance: give one concrete check that proves the bridge is complete.
56
-
57
- ## Generated Artifact Governance Workflow
58
-
59
- Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
60
-
61
- 1. List the artifacts created or materially changed in this task.
62
- 2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
63
- 3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
64
- 4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.
65
- 5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.
66
- 6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.
67
- 7. Before claiming completion, run the available project governance check or `agent-handoff-kit doctor`; if it reports orphan artifact candidates, register, consolidate, or explicitly classify them.
68
-
69
- ## Long-term Governance Routing
70
-
71
- Use this workflow when the user asks to write something into long-term governance, turn an experience into a mechanism, make a rule apply across sessions, or when the content itself clearly has durable force.
72
-
73
- 1. Classify the knowledge before writing:
74
- - Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.
75
- - Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
76
- - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
77
- - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
78
- - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
79
- - Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
80
- - Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
81
- - API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
82
- 2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
83
- 3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
84
- 4. Add or update a QA check when the same failure class could recur and can be tested.
85
- 5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
86
-
87
- ## Checks
88
-
89
- - Verify affected files are indexed or intentionally installed templates.
90
- - Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
91
- - Confirm old overlapping wording was retired or marked legacy.
92
- - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
93
- - Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
94
- - Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
95
- - Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
96
- - Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
97
- - For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
98
- - Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
99
- - For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
100
-
101
- ## Closeout
102
-
103
- Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
1
+ # Agent Governance Pack
2
+
3
+ ## Scope
4
+
5
+ Use for governance rules, prompts, agent instructions, handoff systems, startup/closeout behavior, skills, and rule packs.
6
+
7
+ ## Load When
8
+
9
+ - User asks to change AI behavior, project governance, prompts, handoff, startup, closeout, or tool-use rules.
10
+ - A change affects `AGENTS.md`, `dev/*`, rule packs, installer templates, or durable workflow docs.
11
+ - User asks to bridge governance, connect a document to governance, scan for unbridged governance documents, or uses equivalent Chinese phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", or "掃描未接入 Agent Handoff Kit 的重要文件".
12
+ - User asks to make something long-term, cross-session, reusable, future sessions should remember an API / MCP / tool-use pattern, or uses equivalent Chinese phrases such as "寫入長期治理", "轉成長期機制", or "之後都要遵守".
13
+ - The task creates or materially changes Markdown documents, generated outputs, specifications, runbooks, checklists, guides, source-of-truth files, or research artifacts that future agents may need to discover.
14
+
15
+ ## Rules
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.
19
+ 3. Keep public runtime rules generic; project-specific incidents belong in logs, runbooks, or project index.
20
+ 4. Do not let development-only workspace rules enter public runtime.
21
+ 5. Check complexity budget before adding default-core behavior.
22
+ 6. Before creating durable workflow, runbook, or instruction files, first classify the knowledge type and verify whether an existing home can carry it without a new file: current state belongs in `dev/SESSION_HANDOFF.md`; trace evidence belongs in `dev/SESSION_LOG.md`; file / command / reference maps belong in `dev/PROJECT_INDEX.md`; sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`; reusable operating procedures belong in the relevant rule pack or registered reference. New runbooks are last resort only.
23
+ 7. When a task uses external skills, subagents, demo workspaces, or another tool's closeout, treat those flows as subordinate to the active root's Agent Handoff Kit governance. The active root still needs the `runtime-core/AGENTS.core.md` persistence gate decision; do not duplicate the gate thresholds in this pack.
24
+ 8. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` per R-028 closeout discipline (see `runtime-core/AGENTS.core.md` closeout maintenance trigger check): capture major decisions when they happen, run the short trigger check at every closeout, and do full long-term maintenance only when a hard trigger, semantic trigger, or 10-closeout backstop applies. Short single-task projects keep this as a no-op default; users are not expected to edit this file manually.
25
+ 9. Governance bridge is a triggered review, not a default startup scan. Use it when an important file, source-of-truth document, runbook, production guide, workflow, checklist, stock list, or similar durable document may need to be connected to project governance.
26
+ 10. Content-based trigger: long-term governance routing is content-based, not trigger-only. Even if the user does not use explicit governance-routing phrases, treat a statement as durable governance when it says future sessions must follow it, when it corrects a recurring AI mistake, or when it defines a reusable API / MCP / tool-use pattern. Do not persist long-term governance knowledge only in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or `START_NEXT_SESSION_PROMPT.txt`; those surfaces may be compressed, archived, or regenerated.
27
+ 11. Mid-task changes to product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope are task contract changes. Before writing them, check whether the same contract already lives in a spec, backlog, issue list, README, runbook, project index entry, or handoff section. Merge into the existing authoritative home, then leave only a pointer or current-state summary elsewhere.
28
+ 12. 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.
29
+ 13. 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.
30
+
31
+ ## Governance Bridge Workflow
32
+
33
+ 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 的重要文件".
34
+
35
+ 1. Identify the target. If the user named a file, inspect that file and its surrounding directory. If no file is named, run a bounded repo scan for likely durable documents such as source-of-truth files, runbooks, workflows, guides, checklists, stock lists, production guides, and rules.
36
+ 2. Check the target file itself: it should state its role, scope, update trigger, owner or responsible workflow when known, and what must not be inferred from it.
37
+ 3. Check `dev/PROJECT_INDEX.md`: the file should be discoverable with its role and "read when" condition. Source-of-truth or reference files should appear in Fact Base, External Sources, Directory Map, Entry Points, or another existing indexed home that fits the project.
38
+ 4. Check `dev/DOC_SYNC_REGISTRY.md`: future same-type changes should have a matching change type or an explicit reason no durable sync rule is needed.
39
+ 5. Check related workflows, guides, runbooks, or rule packs: if a process creates or updates the file, that process should say when to update the file or its index row.
40
+ 6. Check `dev/SESSION_HANDOFF.md`: only current state, recommended next action with reason, unresolved risk, blocker, or a startup-needed fact should be in handoff. Do not copy whole documents or old evidence into handoff.
41
+ 7. Check `dev/SESSION_LOG.md`: this session's bridge review, validation, and evidence can be logged when it affects future action, but log entries must not become current state.
42
+ 8. Search for duplicate source-of-truth risk. If another file has the same durable role, recommend merge, reference, or retire options; do not delete, rename, or move files without explicit approval.
43
+
44
+ For repo-wide scans, report candidates as candidates. Do not fail ordinary docs merely because they are not indexed; only durable files that future agents need to discover, update, or distinguish from drafts should be bridged.
45
+
46
+ Output format:
47
+
48
+ - Status: bridged / partially bridged / unbridged / blocked.
49
+ - Use bridged only when every applicable governance link is present. If only `dev/PROJECT_INDEX.md` or `dev/SESSION_LOG.md` was updated, report partially bridged.
50
+ - Already bridged: list the governance links that are present.
51
+ - Gaps: list missing links and why they matter for the next agent.
52
+ - Not applicable: list skipped layers with a reason.
53
+ - Suggested patches: list exact files and sections to update.
54
+ - Manual decisions: list duplicates, naming choices, deletion, renaming, external sync, or ownership questions requiring user confirmation.
55
+ - Acceptance: give one concrete check that proves the bridge is complete.
56
+
57
+ ## Generated Artifact Governance Workflow
58
+
59
+ Use this workflow whenever the current task creates or materially changes Markdown documents or other durable artifacts, even if the user did not explicitly ask for governance bridge.
60
+
61
+ 1. List the artifacts created or materially changed in this task.
62
+ 2. Classify each artifact: source of truth, reference, runbook, workflow, checklist, public document, generated output, one-time evidence, draft, or temporary.
63
+ 3. For source-of-truth, reference, runbook, workflow, checklist, public document, and reusable generated output, update `dev/PROJECT_INDEX.md` so the file is discoverable with a role and read condition.
64
+ 4. For artifacts that require future mirror, external index, publication, or repeated sync, update `dev/DOC_SYNC_REGISTRY.md` or record why no durable sync rule applies.
65
+ 5. For one-time evidence, draft, or temporary files, record that classification in `dev/SESSION_LOG.md` or the task summary, and do not promote it to current handoff unless it affects the next action.
66
+ 6. Search for duplicate source-of-truth risk before keeping a new document. If another file already owns the same rule, requirement, checklist, or process, merge into that file or make the new document explicitly subordinate.
67
+ 7. Before claiming completion, explicitly confirm the artifacts created or materially changed in this task have been classified, indexed, synchronized, consolidated, or marked temporary through the steps above. You may also run the available project governance check and `agent-handoff-kit doctor` for scoped Kit / typed registered-surface checks, but doctor does not discover unregistered ordinary workspace files and cannot replace explicit changed-artifact review.
68
+
69
+ ## Long-term Governance Routing
70
+
71
+ Use this workflow when the user asks to write something into long-term governance, turn an experience into a mechanism, make a rule apply across sessions, or when the content itself clearly has durable force.
72
+
73
+ 1. Classify the knowledge before writing:
74
+ - Current task contract changes, including product goals, requirements, development checklists, acceptance rules, exclusions, priorities, or scope -> the existing authoritative spec / backlog / issue / runbook when one exists; otherwise `dev/SESSION_HANDOFF.md` current-state sections.
75
+ - Current task state, recommended next action with reason, unresolved risk, or startup-needed fact -> `dev/SESSION_HANDOFF.md`.
76
+ - Chronological evidence or validation trace -> `dev/SESSION_LOG.md`.
77
+ - File maps, command maps, API reference locations, tool capability maps, and external source coordinates -> `dev/PROJECT_INDEX.md`.
78
+ - Sync obligations or external mirror duties -> `dev/DOC_SYNC_REGISTRY.md`.
79
+ - Durable decisions, architecture trade-offs, research-derived rationale, and long-term lessons -> `dev/PROJECT_DECISIONS.md`.
80
+ - Reusable procedures, recurring mistake prevention, API / MCP / tool-use rules -> the relevant rule pack, registered reference, or QA check.
81
+ - API / MCP / tool-use patterns -> project index / registered reference / integrations pack, depending on scope.
82
+ 2. If the knowledge is reusable but no existing home fits, propose the smallest new registered reference or rule-pack patch. New runbooks remain last resort.
83
+ 3. If the knowledge was first captured in `SESSION_LOG` or handoff for short-term continuity, promote it to the correct durable home before claiming it is long-term.
84
+ 4. Add or update a QA check when the same failure class could recur and can be tested.
85
+ 5. Keep governance bridge wording reserved for document orphan prevention. Do not relabel non-file governance as "file connected to Agent Handoff Kit".
86
+
87
+ ## Checks
88
+
89
+ - Verify affected files are indexed or intentionally installed templates.
90
+ - Check `dev/DOC_SYNC_REGISTRY.md` for governance, closeout/startup, and README sync rows.
91
+ - Confirm old overlapping wording was retired or marked legacy.
92
+ - Confirm any new durable file is reachable from `dev/PROJECT_INDEX.md` and does not rely only on a one-session handoff note.
93
+ - Confirm every Markdown document or generated artifact created in this task is indexed, synced, consolidated, or explicitly classified as draft / temporary / one-time evidence.
94
+ - Confirm no new file has become a parallel source for an existing rule, requirement, checklist, or process.
95
+ - Confirm reusable operating procedure knowledge is not stored only in `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, or a decision narrative when it belongs in a pack or registered reference.
96
+ - Confirm long-term governance knowledge is promoted out of `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, and `START_NEXT_SESSION_PROMPT.txt` when it should survive log archive or prompt regeneration.
97
+ - For governance bridge work, confirm the target file, project index, sync registry, related workflow, handoff/log role split, and duplicate-source risk were all checked or explicitly marked not applicable.
98
+ - Before claiming completion, apply the active root's core persistence gate and record the result only when that gate selects a checkpoint or full closeout; do not assume child or demo workspaces cover the parent/root workspace.
99
+ - For long-running projects, confirm `dev/PROJECT_DECISIONS.md` retains its four H2 sections in order (Evolution Timeline / Decisions Archive / Architecture Choices / Insights & Learnings) and that the closeout maintenance trigger check was recorded, with full maintenance applied where its trigger conditions were met.
100
+
101
+ ## Closeout
102
+
103
+ Record the changed rule home, reason, complexity impact, retired wording, and follow-up checks.
package/packs/closeout.md CHANGED
@@ -22,11 +22,11 @@ Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-
22
22
 
23
23
  Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records that the mirror was regenerated and verified, plus an evidence reference when useful.
24
24
 
25
- ## Full Closeout
26
-
27
- Full closeout is differential. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
28
-
29
- 1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.
25
+ ## Full Closeout
26
+
27
+ Full closeout is differential. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
28
+
29
+ 1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.
30
30
  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.
31
31
  The bundled doctor is a mechanical floor for obvious overlap and unresolved fields; it cannot prove that renamed or paraphrased work is semantically consistent. 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 doctor.
32
32
  3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
package/packs/coding.md CHANGED
@@ -1,28 +1,28 @@
1
- # Coding Pack
2
-
3
- ## Scope
4
-
5
- Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
-
7
- ## Load When
8
-
9
- - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
- - The task depends on framework, runtime, dependency, or API behavior.
11
-
12
- ## Rules
13
-
14
- 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
- 2. Inspect relevant source, tests, configs, and docs before changing code.
16
- 3. Prefer project-local patterns and helpers over new abstractions.
17
- 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
- 5. Preserve unrelated user changes.
19
-
20
- ## Checks
21
-
22
- - Run the narrowest relevant test, build, lint, or typecheck available.
23
- - If a check cannot run, record why and what remains unverified.
24
- - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
-
26
- ## Closeout
27
-
28
- Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
1
+ # Coding Pack
2
+
3
+ ## Scope
4
+
5
+ Use for code changes, tests, builds, package managers, SDKs, CLIs, APIs, or developer tooling.
6
+
7
+ ## Load When
8
+
9
+ - User asks to write, edit, debug, refactor, test, build, package, or integrate code.
10
+ - The task depends on framework, runtime, dependency, or API behavior.
11
+
12
+ ## Rules
13
+
14
+ 1. Read `dev/PROJECT_INDEX.md` for stack, commands, entry points, and directory roles before editing.
15
+ 2. Inspect relevant source, tests, configs, and docs before changing code.
16
+ 3. Prefer project-local patterns and helpers over new abstractions.
17
+ 4. Do not guess current SDK, CLI, package, API, or deployment behavior when docs or project files can verify it.
18
+ 5. Preserve unrelated user changes.
19
+
20
+ ## Checks
21
+
22
+ - Run the narrowest relevant test, build, lint, or typecheck available.
23
+ - If a check cannot run, record why and what remains unverified.
24
+ - Check `dev/DOC_SYNC_REGISTRY.md` if behavior, commands, public docs, or runbooks changed.
25
+
26
+ ## Closeout
27
+
28
+ Record files changed, commands run, results, remaining risks, and any project index or doc sync updates.
@@ -190,15 +190,15 @@ Integration declarations are project-level; they do not guarantee every AI runti
190
190
  2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
191
191
  3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, ask about integration status rather than assuming none exists.
192
192
  4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
193
- 5. **Write operations require read-back verification**: read back every external write before claiming success.
193
+ 5. **Write operations require read-back verification**: read back every external write before claiming success.
194
194
  6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
195
195
  7. **Cross-tool capability awareness**: verify availability immediately before use, when the current objective declares the integration as a dependency, or when the user requests a health check.
196
196
  8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
197
197
  9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
198
198
  10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
199
199
  11. **External tool resource lifecycle**: after external-tool use, classify resources by ownership. Task-owned / agent-managed resources may be closed or cleaned automatically; shared, user-owned, system-level, other-agent-owned, or unknown resources require evidence reporting and user confirmation before remediation.
200
- 12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
201
- 13. **Terminal-state contract**: a tool operation succeeds only when the runtime returns an explicit successful terminal state and any required read-back passes. Stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial stdout before termination makes the affected operation indeterminate or failed, not successful. It does not make unrelated already-verified task evidence permanently invalid. For read-only operations, verify the state and rerun only the affected operation when still needed. For any operation that may have written externally or to disk, read back the actual target state before retrying, recovery, or success claims.
200
+ 12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
201
+ 13. **Terminal-state contract**: a tool operation succeeds only when the runtime returns an explicit successful terminal state and any required read-back passes. Stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial stdout before termination makes the affected operation indeterminate or failed, not successful. It does not make unrelated already-verified task evidence permanently invalid. For read-only operations, verify the state and rerun only the affected operation when still needed. For any operation that may have written externally or to disk, read back the actual target state before retrying, recovery, or success claims.
202
202
 
203
203
  ## Checks
204
204
 
@@ -211,8 +211,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
211
211
  - Before closeout, update `Last Verified` for integrations touched this session.
212
212
  - Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
213
213
  - Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
214
- - For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
215
- - Treat stopped, aborted, timeout, spawn / transport error, signal, and missing final result as operation-level indeterminate / failed states. Never count partial stdout, a wrapper exit code, or an outer command's success as terminal success without the expected final state and read-back.
214
+ - For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
215
+ - Treat stopped, aborted, timeout, spawn / transport error, signal, and missing final result as operation-level indeterminate / failed states. Never count partial stdout, a wrapper exit code, or an outer command's success as terminal success without the expected final state and read-back.
216
216
 
217
217
  ## Closeout
218
218
 
@@ -237,8 +237,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
237
237
  | Auto-fixing auth or re-auth flows | Auth belongs to the user and the runtime/tool boundary. | Surface the failure and point to the runtime or tool settings. |
238
238
  | Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
239
239
  | Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
240
- | Skipping current availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
241
- | Treating stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial PASS output as success | Tool output can be partial, wrappers can hide inner failure, and external writes may be unknown. | Mark the affected operation indeterminate or failed; read back any possible write target before retrying or claiming success. |
240
+ | Skipping current availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
241
+ | Treating stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial PASS output as success | Tool output can be partial, wrappers can hide inner failure, and external writes may be unknown. | Mark the affected operation indeterminate or failed; read back any possible write target before retrying or claiming success. |
242
242
  | Leaving task-owned MCP / browser / helper processes running after the task | Turns one-off tool use into a long-lived resource leak and can slow the host. | Use graceful close or task-owned process cleanup automatically; switch to user confirmation only when ownership is unclear. |
243
243
  | Broadly killing by process name such as `node.exe`, `python`, or `chrome` | A generic process name does not prove ownership and may terminate user work, another project, or another AI agent's active tools. | Classify by tool family, process ID, start time, parent chain, and task-created path; treat unknown ownership as shared. |
244
244
  | Automatically cleaning global caches, marketplace caches, OS temp roots, or browser profiles | May remove shared state, login state, or data other tools still need. | Automatically clean only task-owned / agent-managed bounded paths; report evidence and wait for confirmation otherwise. |
@@ -17,7 +17,7 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
17
17
  4. Do not perform destructive external writes without explicit confirmation.
18
18
  5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
19
19
  (a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
20
- (b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
20
+ (b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
21
21
  (c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
22
22
  (d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
23
23
  6. When writing to an external mirror or index, read back the written record before claiming sync success.
package/packs/research.md CHANGED
@@ -1,30 +1,30 @@
1
- # Research Pack
2
-
3
- ## Scope
4
-
5
- Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
6
-
7
- ## Load When
8
-
9
- - User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
10
- - The topic may have changed recently or needs precise attribution.
11
-
12
- ## Rules
13
-
14
- 1. Prefer primary sources, official docs, papers, standards, or direct data when available.
15
- 2. Separate verified facts, source summaries, and inference.
16
- 3. Record dates for time-sensitive facts.
17
- 4. Do not overstate confidence when sources conflict or coverage is thin.
18
- 5. Keep source quotes short and cite where evidence came from.
19
-
20
- ## Checks
21
-
22
- - Confirm source relevance, date, and authority.
23
- - Cross-check important claims with more than one source when practical.
24
- - Record open questions or unverified claims.
25
-
26
- ## Closeout
27
-
28
- Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
-
30
- If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
1
+ # Research Pack
2
+
3
+ ## Scope
4
+
5
+ Use for source gathering, evidence comparison, fact synthesis, recommendations, and uncertainty handling.
6
+
7
+ ## Load When
8
+
9
+ - User asks for current facts, comparisons, recommendations, source-backed conclusions, or external evidence.
10
+ - The topic may have changed recently or needs precise attribution.
11
+
12
+ ## Rules
13
+
14
+ 1. Prefer primary sources, official docs, papers, standards, or direct data when available.
15
+ 2. Separate verified facts, source summaries, and inference.
16
+ 3. Record dates for time-sensitive facts.
17
+ 4. Do not overstate confidence when sources conflict or coverage is thin.
18
+ 5. Keep source quotes short and cite where evidence came from.
19
+
20
+ ## Checks
21
+
22
+ - Confirm source relevance, date, and authority.
23
+ - Cross-check important claims with more than one source when practical.
24
+ - Record open questions or unverified claims.
25
+
26
+ ## Closeout
27
+
28
+ Record sources used, conclusions, uncertainty, and any facts that should be persisted into project files.
29
+
30
+ If research changes a long-term decision, public claim, strategy, governance rule, or material selection, persist a research-derived decision entry using the `dev/PROJECT_DECISIONS.md` evidence-chain format. One-time fact checks do not need this extra structure.
@@ -11,15 +11,15 @@ Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evide
11
11
  Route intent in this order:
12
12
 
13
13
  1. Clear closeout intent routes directly to `dev/rules/closeout.md`.
14
- 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as "unless you object I will start". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as "開工,繼續做到下一個 blocker" or "開工,繼續完成目前目標" may continue under the normal task and safety rules.
14
+ 2. Clear continuity intent such as "開工", "Start Agent Handoff", "開始接力", or "continue handoff" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, one optional display-only title update when safely supported, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, project-file writes, network access, other external actions, or opt-out wording such as "unless you object I will start". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as "開工,繼續做到下一個 blocker" or "開工,繼續完成目前目標" may continue under the normal task and safety rules.
15
15
  3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.
16
16
  4. Explicit guidance requests such as "I'm new", "teach me", "help me start", "新手", "教我用", or "點開始" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.
17
17
 
18
- Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
19
-
20
- During explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-title readback and title control. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe title control/readback is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.
21
-
22
- Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
18
+ Treat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.
19
+
20
+ During explicit continuity startup, the only optional presentation effect beyond state recovery and card/status is a user-visible task/conversation title update, when the active runtime safely supports current-title readback and title control. Replace only a generic or stale title, or update once when the main objective clearly changes; keep an informative title and do not rename for tests, reviews, or small substeps. Use `<project name>|<primary action>` from facts already loaded for startup: a concrete same-message task first, otherwise the loaded current objective plus recommended next action. Do not read `dev/PROJECT_INDEX.md`, files, network, or other state solely to name the title. The title must not contain progress, completion, status, task/session IDs, absolute paths, secrets, or unverified facts. If safe title control/readback is unavailable, skip silently. The title is display-only; it is not project state, permission, progress, completion evidence, a health result, or a source of truth, and it does not authorize project/file writes, network activity, external task work, or continuation beyond the startup boundary.
21
+
22
+ Read `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.
23
23
 
24
24
  If the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.
25
25
 
@@ -29,7 +29,7 @@ Probe an integration only immediately before a task uses it, when the handoff ex
29
29
 
30
30
  Show the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.
31
31
 
32
- Use a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.
32
+ For explicit bare continuity startup, after the handoff is read, the startup card may read only the bounded version evidence from `dev/PROJECT_INDEX.md`: the unique stable-semver `| Agent Handoff Kit template version | X.Y.Z | ... |` row inside the unique real `## Stack` section. Do not route on, summarize, or load any other Project Index content for startup, title, permissions, packs, health, or task work. Missing, unreadable, malformed, duplicate, prerelease, or out-of-Stack-only version evidence prints `version unverified`; the turn remains status-only with zero writes. A direct ordinary or stateless task does not read the handoff or Project Index merely to fill a card or version.
33
33
 
34
34
  ```text
35
35
  /\_/\ Agent Handoff Kit v<version>
@@ -61,8 +61,8 @@ In every user-facing reply, lead with ordinary language: state the result and it
61
61
  Choose exactly one tier after a task:
62
62
 
63
63
  1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
64
- 2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
65
- 3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.
64
+ 2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
65
+ 3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.
66
66
 
67
67
  Route current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.
68
68
 
@@ -112,6 +112,6 @@ Load `dev/rules/integrations.md` when the current task actually uses an external
112
112
 
113
113
  After the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.
114
114
 
115
- ## Core Complexity Rule
116
-
117
- Default-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario 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.
115
+ ## Core Complexity Rule
116
+
117
+ 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.
@@ -1,13 +1,13 @@
1
- # Claude Code Entry Bridge
2
-
3
- @AGENTS.md
4
-
5
- This file is a bridge only. Claude Code reads `CLAUDE.md` automatically, so this bridge imports `AGENTS.md`, which remains the single authoritative startup file for Agent Handoff Kit.
6
-
7
- Do not expand, summarize, replace, or "improve" this file during onboarding, setup, `/init`, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
-
9
- If the user says `I just installed agent-handoff-kit`, `help me get started`, or similar first-use wording, do not run Claude Code `/init` and do not load an `init` skill. Agent Handoff Kit is already installed. Read `AGENTS.md`, load the onboarding rule when appropriate, and guide the user through the first task.
10
-
11
- Only edit this file when the user explicitly asks to edit `CLAUDE.md` itself, or when `agent-handoff-kit upgrade` reports a bridge conflict and asks for manual repair.
12
-
13
- After loading this bridge, follow `AGENTS.md` and the startup read order defined there.
1
+ # Claude Code Entry Bridge
2
+
3
+ @AGENTS.md
4
+
5
+ This file is a bridge only. Claude Code reads `CLAUDE.md` automatically, so this bridge imports `AGENTS.md`, which remains the single authoritative startup file for Agent Handoff Kit.
6
+
7
+ Do not expand, summarize, replace, or "improve" this file during onboarding, setup, `/init`, or project documentation work. Do not add command lists, architecture summaries, project state, or handoff notes here.
8
+
9
+ If the user says `I just installed agent-handoff-kit`, `help me get started`, or similar first-use wording, do not run Claude Code `/init` and do not load an `init` skill. Agent Handoff Kit is already installed. Read `AGENTS.md`, load the onboarding rule when appropriate, and guide the user through the first task.
10
+
11
+ Only edit this file when the user explicitly asks to edit `CLAUDE.md` itself, or when `agent-handoff-kit upgrade` reports a bridge conflict and asks for manual repair.
12
+
13
+ After loading this bridge, follow `AGENTS.md` and the startup read order defined there.
@@ -1,24 +1,24 @@
1
- # Doc Sync Registry
2
-
3
- Purpose: map change types to documents and checks. Keep this as rows, not long prose.
4
-
5
- ## Status Vocabulary
6
-
7
- Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
8
-
9
- | Change type | Also check/update | Verification |
10
- |---|---|---|
11
- | New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
12
- | Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
13
- | Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
14
- | Public behavior change | README, public docs, changelog | docs mention current behavior |
15
- | API or SDK behavior change | API docs, examples, tests | tests or documented reason |
16
- | Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
17
- | Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
18
- | Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
19
- | Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
20
- | Release | release notes, README version, changelog | release pack checklist |
21
-
22
- ## Registry Rule
23
-
24
- If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.
1
+ # Doc Sync Registry
2
+
3
+ Purpose: map change types to documents and checks. Keep this as rows, not long prose.
4
+
5
+ ## Status Vocabulary
6
+
7
+ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
8
+
9
+ | Change type | Also check/update | Verification |
10
+ |---|---|---|
11
+ | New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
12
+ | Generated Markdown or durable artifact | `dev/PROJECT_INDEX.md` Directory Map / Fact Base / Entry Points, and this registry when future updates need sync | artifact classified as indexed / synced / temporary / one-time evidence; duplicate source-of-truth risk checked |
13
+ | Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
14
+ | Public behavior change | README, public docs, changelog | docs mention current behavior |
15
+ | API or SDK behavior change | API docs, examples, tests | tests or documented reason |
16
+ | Runbook change | runbook path in `PROJECT_INDEX.md` | procedure still executable |
17
+ | Governance rule change | relevant pack/core, registry, README if public-facing | complexity budget checked |
18
+ | Closeout/startup contract change | `AGENTS.md`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, README quick usage | opening message schema + workspace identity present |
19
+ | Workspace identity change | `dev/SESSION_HANDOFF.md`, `dev/PROJECT_INDEX.md` | root/branch/commit/status recorded or marked unverified |
20
+ | Release | release notes, README version, changelog | release pack checklist |
21
+
22
+ ## Registry Rule
23
+
24
+ If a change has no matching row, add a row before closeout or record why no durable sync rule is needed. At closeout, record sync status for every row touched by the session.