@adamchanadam/agent-handoff-kit 0.3.41 → 0.3.42

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.
@@ -1,43 +1,43 @@
1
- # Project Decisions Log
2
-
3
- This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
-
5
- Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
-
7
- The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
-
9
- Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
-
11
- ```text
12
- - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
- ```
14
-
15
- The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
-
17
- This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
-
19
- ---
20
-
21
- ## Evolution Timeline
22
-
23
- Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
-
25
- (empty)
26
-
27
- ## Decisions Archive
28
-
29
- Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
-
31
- (empty)
32
-
33
- ## Architecture Choices
34
-
35
- Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
-
37
- (empty)
38
-
39
- ## Insights & Learnings
40
-
41
- Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
-
43
- (empty)
1
+ # Project Decisions Log
2
+
3
+ This file stores long-term project evolution, decisions, architecture trade-offs, and accumulated learning observations. It is a warm narrative layer. AI agents do not need to read this file at startup unless the current task asks for historical rationale or the closeout maintenance trigger says to update it.
4
+
5
+ Short single-task projects can leave this file nearly empty. Long-running projects use it when a closeout trigger, semantic trigger, or periodic backstop applies. When the user asks why earlier choices were made, this file is the first long-term narrative reference.
6
+
7
+ The user is not expected to maintain this file manually. The AI updates it during closeout when required, and may record major decisions when they happen.
8
+
9
+ Research-derived decisions use this compact evidence-chain format inside the relevant section, without creating a new section:
10
+
11
+ ```text
12
+ - YYYY-MM-DD [research-derived] Decision summary. Evidence chain: Source=source:<id>; Summary=<source finding>; Inference=<reasoning>; Decision impact=<what changed>; Uncertainty=<limits or none>.
13
+ ```
14
+
15
+ The `source:<id>` token must also appear in `dev/PROJECT_INDEX.md` under `Fact Base` or `External Sources`, so later sessions can trace the decision back to its source map.
16
+
17
+ This file does not store raw build / upload / QC evidence, current next actions, one-time task results, or reusable operating procedures. Keep those in `dev/SESSION_LOG.md`, `dev/SESSION_HANDOFF.md`, or the relevant rule pack / registered reference.
18
+
19
+ ---
20
+
21
+ ## Evolution Timeline
22
+
23
+ Long-term narrative of task or product evolution. Newest first. Append when the AI observes substantive task evolution.
24
+
25
+ (empty)
26
+
27
+ ## Decisions Archive
28
+
29
+ Older decision entries split from `SESSION_HANDOFF.md` when its confirmed-decisions style section grows past the maintenance threshold. Newest first.
30
+
31
+ (empty)
32
+
33
+ ## Architecture Choices
34
+
35
+ Major architecture choices and rationale. Append when planning involves a multi-option trade-off and the selected path has been confirmed.
36
+
37
+ (empty)
38
+
39
+ ## Insights & Learnings
40
+
41
+ Accumulated lessons, reflections, and cross-session patterns. Append when the AI observes a recurring pattern across sessions.
42
+
43
+ (empty)
@@ -6,7 +6,7 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
6
6
 
7
7
  | Field | Value | Last verified |
8
8
  |---|---|---|
9
- | Agent Handoff Kit template version | 0.3.41 | implementation candidate; not yet published |
9
+ | Agent Handoff Kit template version | 0.3.42 | current release |
10
10
  | Runtime | TBD | TBD |
11
11
  | Framework | TBD | TBD |
12
12
  | Package manager | TBD | TBD |
@@ -20,13 +20,13 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
20
20
  |---|---|---|
21
21
  | `AGENTS.md` | primary Agent Handoff Kit entry and startup contract | session startup |
22
22
  | `CLAUDE.md` | Claude Code bridge to the same startup path | Claude Code startup |
23
- | `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
24
- | `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |
23
+ | `GEMINI.md` | Google Antigravity CLI / Gemini CLI migration bridge to the same startup path | Antigravity / Gemini startup |
24
+ | `START_NEXT_SESSION_PROMPT.txt` | portable generated mirror of the handoff opening-message block; `dev/SESSION_HANDOFF.md` remains authoritative | fallback when the next agent is not yet operating in this root; not an additional local startup read |
25
25
  | `src/` | application source | coding task |
26
26
  | `tests/` | tests | coding/QC |
27
27
  | `docs/` | user or product docs | doc/public behavior change |
28
- | `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |
29
- | `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |
28
+ | `dev/` | governance state | read the handoff at startup; other files are task-routed or closeout-routed |
29
+ | `dev/rules/closeout.md` | full closeout contract | clear end-of-session or handoff intent only |
30
30
  | `TBD` | local source-of-truth files | before tasks that depend on project facts |
31
31
  | `TBD` | external-source indexes or mirrors | before research, writing, or knowledge-sync tasks |
32
32
 
@@ -36,10 +36,10 @@ Purpose: give a stateless AI a compact map of the project before it reads or edi
36
36
  |---|---|---|
37
37
  | App entry | TBD | TBD |
38
38
  | Main config | TBD | TBD |
39
- | Test suite | TBD | TBD |
40
- | Runbook | TBD | TBD |
41
- | Public docs | TBD | TBD |
42
- | Generated Markdown review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated Markdown outputs, specs, runbooks, checklists, or research notes, classify each file as indexed / synced / temporary / one-time evidence before completion; other durable formats require human review because doctor scans Markdown only |
39
+ | Test suite | TBD | TBD |
40
+ | Runbook | TBD | TBD |
41
+ | Public docs | TBD | TBD |
42
+ | Generated Markdown review | `dev/PROJECT_INDEX.md` + `dev/DOC_SYNC_REGISTRY.md` | After creating Markdown docs, generated Markdown outputs, specs, runbooks, checklists, or research notes, classify each file as indexed / synced / temporary / one-time evidence before completion; other durable formats require human review because doctor scans Markdown only |
43
43
 
44
44
  ## Fact Base
45
45
 
@@ -53,68 +53,68 @@ Reachable means the source can be found. It does not mean the source has been re
53
53
 
54
54
  | Source | Role | Required before | Access method | `via` | Write-back rule | Last verified |
55
55
  |---|---|---|---|---|---|---|
56
- | TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
56
+ | TBD | source of truth / mirror / index / attachment store | TBD | URL, connector, or manual packet | `Notion Connector` / `Google Drive Connector` / `manual paste` / etc — must match an entry under `## Installed Integrations` | read-back required / manual only / no write | TBD |
57
57
 
58
- > `via` column discipline: every External Sources row must reference an entry name under `## Installed Integrations`, such as `Notion Connector` or `Google Drive Connector`, so the access path is explicit. Sources without a declared integration use `manual paste`. Doctor and release QA enforce cross-section consistency.
58
+ > `via` column discipline: every External Sources row must reference an entry name under `## Installed Integrations`, such as `Notion Connector` or `Google Drive Connector`, so the access path is explicit. Sources without a declared integration use `manual paste`. Doctor and release QA enforce cross-section consistency.
59
59
 
60
60
  ## Installed Integrations
61
61
 
62
- > **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
63
-
64
- > Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.
65
-
66
- ### Connectors
67
-
68
- | Tool | Project Usage | Access Scope | Specific Instance | Credential Reference (no value) | Declared | Last Verified |
69
- |------|---------------|--------------|-------------------|---------------------|----------|---------------|
70
- | TBD | TBD, for example an index of source paths or persistent reference storage | read / read+write | TBD, for example database name + URL or folder path | TBD, for example `AI tool secure storage` / `OS credential store` | TBD | TBD |
71
-
72
- ### MCPs
73
-
74
- | Server | Source | Project Usage | Credential Reference (no value) | Declared | Last Verified |
75
- |--------|--------|---------------|---------------------|----------|---------------|
76
- | TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |
77
-
78
- ### Plugins
79
-
80
- | Name | Bundle Content (Skills + MCP + hooks) | When Triggered | Last Verified |
81
- |------|----------------------------------------|----------------|---------------|
82
- | TBD | TBD | TBD | TBD |
83
-
84
- ### Skills
85
-
86
- | Name | Source | When Triggered | Last Verified |
87
- |------|--------|----------------|---------------|
88
- | TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |
89
-
90
- ### Source-of-truth Architecture
91
-
92
- > When a project uses several integrations as a source-of-truth system, for example Notion index + local primary sources + Google Drive reference mirror, this table records each layer's role so agents do not cross write boundaries.
93
-
94
- | Layer | Surface (specific instance) | Role | Write Direction |
95
- |-------|--------------------------|------|-----------------|
96
- | Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |
97
- | Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |
98
- | Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |
99
- | Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |
100
-
101
- ## Tool Operation References
102
-
103
- Use this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.
104
-
105
- Do not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.
106
-
107
- | Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
108
- |---|---|---|---|---|---|
109
- | TBD | TBD | TBD | TBD | TBD | TBD |
110
- | Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |
111
-
112
- ## Local QC Commands
113
-
114
- | Check | Command | Run before | Last verified |
115
- |---|---|---|---|
116
- | Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
117
- | Project governance check | Check newly created Markdown against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. Review non-Markdown durable outputs manually. | closeout / durable file changes | unverified until project-specific command exists |
62
+ > **Credential Separation Principle**: this section records only project usage and public reference coordinates such as Notion database names, URLs, or folder paths. It must never record API keys, OAuth tokens, or credential values. Credentials belong in AI runtime secure storage, OS credential stores, tool configuration, or user-managed secret stores. If an environment variable is used, record only the variable name, never the value. Before writing this section, self-check that no credential value is being persisted. Doctor scans this section, `SESSION_HANDOFF`, and `SESSION_LOG` for common credential prefixes such as `sk-`, `ntn_`, `ya29.`, `xoxp-`, `ghp_`, `sl.`, `AKIA`, and `AIza`.
63
+
64
+ > Purpose: tasks that use external tools read this section to understand declared capabilities and project roles. Declarations persist across sessions. A new session does not probe this table merely because it exists. `TBD`, examples, blanks, and placeholder-only rows are not installed integrations. Every real entry includes `Declared` and `Last Verified` so capability assumptions can be checked immediately before use.
65
+
66
+ ### Connectors
67
+
68
+ | Tool | Project Usage | Access Scope | Specific Instance | Credential Reference (no value) | Declared | Last Verified |
69
+ |------|---------------|--------------|-------------------|---------------------|----------|---------------|
70
+ | TBD | TBD, for example an index of source paths or persistent reference storage | read / read+write | TBD, for example database name + URL or folder path | TBD, for example `AI tool secure storage` / `OS credential store` | TBD | TBD |
71
+
72
+ ### MCPs
73
+
74
+ | Server | Source | Project Usage | Credential Reference (no value) | Declared | Last Verified |
75
+ |--------|--------|---------------|---------------------|----------|---------------|
76
+ | TBD | TBD, for example GitHub repository URL | TBD | TBD, for example `tool config + env var name only` / `user-managed secret store` | TBD | TBD |
77
+
78
+ ### Plugins
79
+
80
+ | Name | Bundle Content (Skills + MCP + hooks) | When Triggered | Last Verified |
81
+ |------|----------------------------------------|----------------|---------------|
82
+ | TBD | TBD | TBD | TBD |
83
+
84
+ ### Skills
85
+
86
+ | Name | Source | When Triggered | Last Verified |
87
+ |------|--------|----------------|---------------|
88
+ | TBD | TBD, for example plugin bundle or user-level install | TBD | TBD |
89
+
90
+ ### Source-of-truth Architecture
91
+
92
+ > When a project uses several integrations as a source-of-truth system, for example Notion index + local primary sources + Google Drive reference mirror, this table records each layer's role so agents do not cross write boundaries.
93
+
94
+ | Layer | Surface (specific instance) | Role | Write Direction |
95
+ |-------|--------------------------|------|-----------------|
96
+ | Source of truth | TBD, for example local `~/project/reference/` | Original auditable reference content | User-controlled placement; agent does not write directly unless explicitly authorized |
97
+ | Index | TBD, for example Notion database `Project Index` | Metadata, summaries, and tags for each source file | Agent may read/write through a verified Connector |
98
+ | Persistent mirror | TBD, for example Drive folder `Project Reference/` | Backup or cross-device reference mirror | User-controlled sync by default; agent does not push automatically |
99
+ | Working draft | TBD, for example local `~/project/output/` | Agent task output | Agent may read and write local files under normal safety rules |
100
+
101
+ ## Tool Operation References
102
+
103
+ Use this section for project-local runbooks or verified procedures for runtime-controlled tools such as browser validation, screenshots, DevTools, Playwright, crawlers, notebooks, desktop app automation, MCP/plugin helpers, or raw CLI/SDK operations.
104
+
105
+ Do not store credential values or machine-private paths here. Local machine-only references may be listed only when the project explicitly depends on them, and the scope / limits must say they are not portable.
106
+
107
+ | Tool / operation | Reference path or URL | Required before | Source and version/date | Scope and known limits | Last verified |
108
+ |---|---|---|---|---|---|
109
+ | TBD | TBD | TBD | TBD | TBD | TBD |
110
+ | Local HTML / app browser validation | TBD, for example project runbook or official browser-tool docs | Before validating local HTML, static app, generated guide, screenshot, click flow, or visual QA | TBD, include source and date | Prefer short-lived loopback localhost service when `file://` is blocked; record click/text/screenshot evidence and cleanup result; do not mutate user browser profiles or extension state | TBD |
111
+
112
+ ## Local QC Commands
113
+
114
+ | Check | Command | Run before | Last verified |
115
+ |---|---|---|---|
116
+ | Agent Handoff Kit doctor | `npx --yes @adamchanadam/agent-handoff-kit@latest doctor --root .` | closeout / governance changes / generated Markdown artifact checks | package latest |
117
+ | Project governance check | Check newly created Markdown against `dev/PROJECT_INDEX.md` and `dev/DOC_SYNC_REGISTRY.md`; register, sync, consolidate, or explicitly classify as temporary / one-time evidence. Review non-Markdown durable outputs manually. | closeout / durable file changes | unverified until project-specific command exists |
118
118
 
119
119
  ## Workspace Identity
120
120
 
@@ -135,9 +135,9 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
135
135
  | API behavior | TBD | tests + docs sync |
136
136
  | UI behavior | TBD | build + visual/manual check |
137
137
  | Data model | TBD | migration/checks |
138
- | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
139
- | Generated Markdown | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable; review other formats manually |
140
- | Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |
138
+ | Governance behavior | `AGENTS.md`, `dev/*` | doc sync registry |
139
+ | Generated Markdown | `docs/`, `outputs/`, root Markdown files, project-specific reference folders | classify as indexed / synced / temporary / one-time evidence; update `dev/PROJECT_INDEX.md` or `dev/DOC_SYNC_REGISTRY.md` when durable; review other formats manually |
140
+ | Closeout/startup contract | `AGENTS.md`, `dev/rules/closeout.md`, `START_NEXT_SESSION_PROMPT.txt`, `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md` | hot-path reads stay minimal; lifecycle state agrees; log has no full prompt; prompt mirror regenerated from handoff at closeout |
141
141
 
142
142
  ## External Services
143
143
 
@@ -145,6 +145,6 @@ Record this at closeout so the next AI can detect wrong-root or workspace drift.
145
145
  |---|---|---|---|
146
146
  | TBD | TBD | TBD | TBD |
147
147
 
148
- ## Maintenance Rule
149
-
150
- Update this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.
148
+ ## Maintenance Rule
149
+
150
+ Update this file when stack, commands, directory roles, entry points, external services, runtime-controlled tool operation references, workspace identity, durable runbooks, or governance file map changes.
@@ -2,24 +2,24 @@
2
2
 
3
3
  Read only the packs needed for the current task.
4
4
 
5
- | Task signal | Pack | Purpose |
6
- |---|---|---|
7
- | Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
8
- | Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install or "I just installed" is eligibility context, not a forced route. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or no executable objective remains |
5
+ | Task signal | Pack | Purpose |
6
+ |---|---|---|
7
+ | Clear end-of-session or handoff intent: "收工" / "wrap up" / "closeout" / "handoff" / "Wrap up Agent Handoff", including closeout plus a handoff instruction | `dev/rules/closeout.md` | <!-- ack:route:closeout --> full closeout, lifecycle reconciliation, maintenance triggers, prompt regeneration, read-back, and honest stop conditions |
8
+ | Explicit onboarding requests: "I'm new" / "new user" / "teach me" / "help me start" / "how do I start" / "show me how" / "getting started" / "what can agent handoff kit do"; or genuinely unresolved intent after current state has been read. Also recognize equivalent Chinese phrases such as "新手", "教我用", "點開始", and "能力". A fresh install or "I just installed" is eligibility context, not a forced route. `Start Agent Handoff` / "開工" is continuity. | `dev/rules/onboarding.md` | <!-- ack:route:onboarding --> infer when sufficient and begin a concrete task directly; ask one concise question or offer guided scenarios only when the user requests guidance or no executable objective remains |
9
9
  | Destructive file operations, shell writes, Git state changes, package managers, installers, deploy, release, cloud tools, external APIs, credentials, locked files, permission errors | `dev/rules/safety.md` | safety checks for data loss, external systems, secrets, and high-risk operations |
10
10
  | Code, tests, build, package manager, SDK, CLI, API | `dev/rules/coding.md` | development workflow and verification |
11
11
  | Draft, edit, style, publication content | `dev/rules/writing.md` | writing workflow and tone control |
12
12
  | Sources, evidence, comparison, fact finding | `dev/rules/research.md` | source handling and uncertainty |
13
- | Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
14
- | Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
15
- | Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
16
- | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
17
- | External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
18
- | A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |
19
- | Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |
20
- | External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
21
- | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
13
+ | Governance, prompts, agents, handoff, startup/closeout, skills | `dev/rules/agent-governance.md` | governance changes and boundary control |
14
+ | Governance bridge / bridge governance / connect this document to governance / scan for unbridged governance documents. Also recognize equivalent Chinese user phrases such as "治理打通", "把文件接入 Agent Handoff Kit", "接入 Agent Handoff Kit", and "掃描未接入 Agent Handoff Kit 的重要文件". | `dev/rules/agent-governance.md` | <!-- ack:route:governance-bridge --> connect important files, source-of-truth documents, runbooks, workflows, checklists, and guides to the project index, sync registry, handoff/log roles, and related workflows without creating duplicate sources of truth |
15
+ | Long-term governance routing / future sessions should remember / always use this API or MCP pattern. Also recognize equivalent Chinese user phrases such as "寫入長期治理", "轉成長期機制", "之後都要遵守", and "跨 session 有效". | `dev/rules/agent-governance.md` | <!-- ack:route:long-term-governance --> classify durable non-file knowledge by role and store it in the right home: rule pack, registered reference, project index, sync registry, project decisions, or QA check; do not leave reusable governance only in session log or handoff |
16
+ | Release, publish, deploy, tag, hotfix, GA | `dev/rules/release.md` | release verification and evidence |
17
+ | External notes, knowledge base, Notion, Obsidian, Google Drive | `dev/rules/knowledge.md` | external knowledge source integration |
18
+ | A task that actually uses an external Connector / MCP / Plugin / Skill; a handoff that declares one as a current-task dependency; or an explicit integration health check | `dev/rules/integrations.md` | <!-- ack:route:integration-use --> capability verification immediately before use, credential separation, source-of-truth boundaries, fallback, and cross-session resilience; registry placeholders alone do not load or probe |
19
+ | Runtime-controlled tool operation / browser UI validation / visual QA / screenshot / local HTML validation / file:// blocked / `file://` blocked / localhost fallback / Chrome / Playwright / DevTools / desktop app automation / crawler or scraper / notebook or data runtime / raw CLI, SDK, tool server, MCP, plugin, or local helper operation | `dev/rules/integrations.md` + `dev/rules/safety.md` (add `dev/rules/coding.md` only when changing code, tests, or project scripts) | <!-- ack:route:runtime-tool --> verify the active runtime capability, current schema, official docs, or registered tool operation reference before invocation; for local HTML / app validation, a blocked `file://` surface must route to a registered operation reference or short-lived localhost fallback before declaring blocked; preserve ownership and cleanup boundaries |
20
+ | External tool resource pressure / stale MCP process / plugin service leak / browser automation left running / cache growth after external tools / slowdown after MCP, plugin, browser, crawler, notebook, or local helper services | `dev/rules/integrations.md` + `dev/rules/safety.md` | <!-- ack:route:resource-closeout --> ownership-based external-tool resource closeout; task-owned cleanup allowed; shared or ambiguous remediation requires exact evidence and confirmation |
21
+ | Reply format, language, output schema | `dev/rules/communication.md` | user-facing response rules |
22
22
 
23
23
  ## Routing Rule
24
24
 
25
- Load the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.
25
+ Load the minimum set. If uncertain, load the narrower pack first. Pack selection is normally silent; state it only when it changes risk or user action. If a task clearly involves safety risk plus another domain, load `dev/rules/safety.md` with the relevant domain pack. Packs can add stricter rules, but cannot weaken core safety or continuity.
@@ -12,7 +12,7 @@ Stable facts that should survive across sessions. Update only when they change,
12
12
  3. Governance model: TBD
13
13
  4. Source-of-truth ownership: TBD
14
14
  5. Release / publish boundary: TBD
15
- 6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
15
+ 6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` is the declaration source. Probe only immediately before actual use, when the current objective names an integration dependency, or when the user asks for a health check. Credential values never appear in `dev/*`; record references only.
16
16
 
17
17
  <!-- ack:section:closeout-reconciled-state -->
18
18
  ## Closeout-Reconciled State
@@ -25,9 +25,9 @@ This is the current-state area. At every full closeout, rewrite or explicitly co
25
25
  1. Project root: TBD
26
26
  2. Product/system state: TBD
27
27
  3. Governance state: TBD
28
- 4. Source-of-truth notes: TBD
29
- <!-- ack:field:first-use-guidance-state -->
30
- 5. First-use guidance state: eligible
28
+ 4. Source-of-truth notes: TBD
29
+ <!-- ack:field:first-use-guidance-state -->
30
+ 5. First-use guidance state: eligible
31
31
 
32
32
  <!-- ack:section:task-understanding-summary -->
33
33
  ## Task Understanding Summary
@@ -55,12 +55,12 @@ Record only work actually completed in the current session.
55
55
 
56
56
  1. TBD
57
57
 
58
- <!-- ack:section:next-priorities -->
59
- ## Next Priorities
60
-
61
- Recommended next step: TBD — reason: TBD
62
-
63
- 1. TBD
58
+ <!-- ack:section:next-priorities -->
59
+ ## Next Priorities
60
+
61
+ Recommended next step: TBD — reason: TBD
62
+
63
+ 1. TBD
64
64
 
65
65
  <!-- ack:section:next-task-required-reading -->
66
66
  ## Next Task Required Reading
@@ -111,27 +111,33 @@ At full closeout, complete this check after updating the state sections above.
111
111
  - Reconciled at: TBD
112
112
  <!-- ack:field:state-sections-rewritten-or-confirmed -->
113
113
  - State sections rewritten or confirmed current: TBD
114
- <!-- ack:field:stale-snapshots-left -->
115
- - Stale snapshots left in this handoff: TBD
116
- <!-- ack:field:lifecycle-conflicts-resolved -->
117
- - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
114
+ <!-- ack:field:stale-snapshots-left -->
115
+ - Stale snapshots left in this handoff: TBD
116
+ <!-- ack:field:lifecycle-conflicts-resolved -->
117
+ - Completed / pending / risk / opening-message lifecycle conflicts resolved or explicitly reclassified: TBD
118
118
  <!-- ack:field:persistence-routing-checked -->
119
119
  - Persistence routing checked: TBD
120
+ <!-- ack:field:closeout-outcome -->
121
+ - Closeout outcome: not_started — full closeout has not yet been assessed.
122
+ <!-- ack:field:project-required-persistence -->
123
+ - Project-required persistence: not_assessed — state whether this project's required Git or other persistence completed, is not required, or is blocked.
120
124
  <!-- ack:field:recommended-next-step-explicit -->
121
- - Recommended next step is explicit and reasoned: TBD
122
- <!-- ack:field:opening-message-matches-current-state -->
123
- - Opening message matches current state: TBD
124
- <!-- ack:field:next-ai-can-continue -->
125
- - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
126
-
127
- If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready.
128
-
125
+ - Recommended next step is explicit and reasoned: TBD
126
+ <!-- ack:field:opening-message-matches-current-state -->
127
+ - Opening message matches current state: TBD
128
+ <!-- ack:field:next-ai-can-continue -->
129
+ - Next AI can continue from `AGENTS.md`, this handoff, `dev/PROJECT_INDEX.md`, and needed rule packs without searching old log history: TBD
130
+
131
+ If any answer is no, blocked, or uncertain, fix this handoff before declaring handoff ready. `Closeout outcome: complete` is allowed only when required writes, read-backs and project-required persistence are complete. If project-required persistence is blocked, use `Closeout outcome: blocked` and state the blocker; it is not a completed closeout.
132
+
129
133
  Lifecycle consistency rule: compare `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message` as full content, including renamed or paraphrased work. A completed or verified item must not remain as an unresolved next priority, active risk, or startup instruction unless it is explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with the missing evidence or trigger condition stated. Doctor catches only mechanical contradictions and unresolved fields; its green result is not semantic proof. Recommended next-step rule: `Next Priorities` must name the single recommended next action and a short reason before listing additional options, unless the next action is blocked or genuinely requires a user decision. Persistence routing rule: one-time delivery instructions, historical validation evidence, old hashes, old version facts, and incident notes must stay in trace evidence unless they still affect the next action.
134
+
135
+ Closeout-card rule: `closeout-status` reads only these existing handoff fields plus fresh doctor / mirror results; it does not create another persistence authority. Its `complete` card is the only permitted source for the user-facing `handoff saved` wording. A nonzero / `blocked` result must be shown as blocked, never summarized as completed.
130
136
 
131
137
  <!-- ack:section:handoff-sufficiency-check -->
132
138
  ## Handoff Sufficiency Check
133
139
 
134
- 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?
140
+ 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?
135
141
 
136
142
  Answer: TBD
137
143
  If no, update this handoff before closeout.
@@ -141,14 +147,14 @@ Continuity rule: this file carries current state and next action. `dev/SESSION_L
141
147
  <!-- ack:section:next-session-opening-message -->
142
148
  ## Next Session Opening Message
143
149
 
144
- This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
145
-
146
- 📋 Next session: agent-managed startup content below
150
+ This fenced block is the authoritative agent-managed startup content. At closeout, regenerate `START_NEXT_SESSION_PROMPT.txt` from this block. If the two differ, trust this block and rewrite the convenience copy. User-facing closeout output should show `Start Agent Handoff` / `開工` as the primary next-session entry, plus the path-bearing fallback when the next AI is not yet pointed at this project root; do not hand-write a separate stateful prompt in the final response.
151
+
152
+ 📋 Next session: agent-managed startup content below
147
153
 
148
154
  ```text
149
- Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
150
-
151
- If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
152
-
153
- Resume the current objective. If my message or the handoff already gives an executable task, begin its first safe action in this response. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
154
- ```
155
+ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
156
+
157
+ If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
158
+
159
+ Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, 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, writes, network access, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
160
+ ```
@@ -1,35 +1,35 @@
1
- # Session Log
2
-
3
- <!-- ack:section:session-log-preamble -->
4
-
5
- > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
6
-
7
- Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
-
9
- This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
-
11
- Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
-
13
- Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
-
15
- <!-- ack:section:session-log-entry-template -->
16
-
17
- ## Entry Template
18
-
19
- ````markdown
20
- <!-- ack:log-entry:start -->
21
- ## <YYYY-MM-DD> — <short session title>
22
-
23
- - **ID:** <agent_or_session_id>
24
- - **Summary:** <one sentence>
25
- - **Changed:** <files changed, or none>
26
- - **Done:** <work completed this session>
27
- - **QC:** <checks run and results, or why not run>
28
- - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
29
- - **Sync:** <doc/external sync status>
30
- - **Pending:** <next work>
31
- - **Risks:** <known risks or none>
32
- - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
- - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
- <!-- ack:log-entry:end -->
35
- ````
1
+ # Session Log
2
+
3
+ <!-- ack:section:session-log-preamble -->
4
+
5
+ > **Handoff role**: This log is the trace-back / audit trail layer. Handoff capability rests on `dev/SESSION_HANDOFF.md`. The next AI session can continue by reading `AGENTS.md` + `dev/SESSION_HANDOFF.md` + `dev/PROJECT_INDEX.md` + needed rule packs; reading this log is not required for continuity. Each closeout must run the maintenance trigger check per `AGENTS.md` `## Closeout And Handoff` step 11 (R-010 SESSION_LOG handoff-role discipline): N=1–3 keep full, N=4–10 may short-index after absorbed-source check when triggered, N=11+ archive into `dev/SESSION_LOG_archive/`.
6
+
7
+ Add new session entries at the top. Record what actually happened in the session; do not copy old completed work forward as new work.
8
+
9
+ This log carries recent evidence, not current state. Put the current objective, next action, risks, and workspace identity in `dev/SESSION_HANDOFF.md`.
10
+
11
+ Keep recent entries concise. If older entries no longer affect the next action and the maintenance trigger check says cleanup is due, reduce them to short dated indexes that point to the durable source of truth. Archive long error output, validation detail, or research trails only when triggered; do not create an archive directory by default.
12
+
13
+ Before closeout, record whether older log detail was kept, summarized, or archived, and whether the maintenance trigger check was no-op, triggered, or backstop-driven. Do not remove validation evidence or unresolved risks. The full opening message never belongs in this log.
14
+
15
+ <!-- ack:section:session-log-entry-template -->
16
+
17
+ ## Entry Template
18
+
19
+ ````markdown
20
+ <!-- ack:log-entry:start -->
21
+ ## <YYYY-MM-DD> — <short session title>
22
+
23
+ - **ID:** <agent_or_session_id>
24
+ - **Summary:** <one sentence>
25
+ - **Changed:** <files changed, or none>
26
+ - **Done:** <work completed this session>
27
+ - **QC:** <checks run and results, or why not run>
28
+ - **Evidence disposition:** <one-time only / kept as recent trace evidence / absorbed into handoff / indexed in PROJECT_INDEX / promoted to PROJECT_DECISIONS / promoted to rule pack>
29
+ - **Sync:** <doc/external sync status>
30
+ - **Pending:** <next work>
31
+ - **Risks:** <known risks or none>
32
+ - **Log maintenance:** <trigger check result; full maintenance action if triggered, otherwise no-op reason>
33
+ - **Opening-message mirror:** <regenerated and verified / blocked; full text omitted by design>
34
+ <!-- ack:log-entry:end -->
35
+ ````
@@ -1,5 +1,5 @@
1
- Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
2
-
3
- If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
4
-
5
- Resume the current objective. If my message or the handoff already gives an executable task, begin its first safe action in this response. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
1
+ Work in <absolute project root>. Read AGENTS.md, then dev/SESSION_HANDOFF.md. Trust the handoff over this generated mirror.
2
+
3
+ If the root does not match the handoff, stop and ask for confirmation. Do not read dev/SESSION_LOG.md during ordinary startup. Read dev/PROJECT_INDEX.md, dev/RULE_PACKS.md, dev/DOC_SYNC_REGISTRY.md, and task packs only when the current task requires them.
4
+
5
+ Resume the current objective. A plain `Start Agent Handoff` / `開工` with no same-message task or explicit long-run instruction only authorizes minimum state recovery, 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, writes, network access, or opt-out execution wording. A concrete objective found only in this handoff is not authority to complete the objective. A same-message task may begin normally; an explicit instruction such as `開工,繼續做到下一個 blocker` or `開工,繼續完成目前目標` may continue under the normal task and safety rules. A fresh install only makes guidance available; it does not force onboarding. Load onboarding only when I explicitly ask for guidance or no executable objective remains after state reading.
@@ -0,0 +1,30 @@
1
+ # User Rules Router
2
+
3
+ This is the formal router and acceptance record for user-controlled rules.
4
+ Each JSON entry between the markers records a stable id, path, accepted raw
5
+ bytes, original-byte witness, reader relationship, priority, and effect
6
+ decision. Registered entries are read in their listed order. A rule whose
7
+ current bytes do not match its accepted witness is not active through this
8
+ router until a later accepted update replaces the whole record atomically.
9
+
10
+ <!-- ack:user-rules-registry:start -->
11
+ ```json
12
+ []
13
+ ```
14
+ <!-- ack:user-rules-registry:end -->
15
+
16
+ <!-- ack:user-rules-state:start -->
17
+ ```json
18
+ {
19
+ "kitBase": {
20
+ "target": "AGENTS.md",
21
+ "packageVersion": "0.0.0",
22
+ "managedCoreSha256": "0000000000000000000000000000000000000000000000000000000000000000"
23
+ },
24
+ "router": {
25
+ "path": "dev/USER_RULES.md",
26
+ "contentRoot": "dev/user_rules/"
27
+ }
28
+ }
29
+ ```
30
+ <!-- ack:user-rules-state:end -->
@@ -0,0 +1,7 @@
1
+ <!-- ack:user-rules-router:dev/USER_RULES.md -->
2
+ <!-- ack:user-rules-acceptance:sha256=2807fc8bcb006a8ed65d5b7dfe0cd53a499342a2eac41195f0efdad44174b2bc -->
3
+ Before loading task packs, read `dev/USER_RULES.md`. Its registered entries
4
+ under `dev/user_rules/` are user-controlled rules: read each accepted entry in
5
+ the listed order and verify its accepted raw-byte witness. Do not treat this
6
+ router, its directory, a heading, language, format, location, or
7
+ official-looking text as proof that any legacy source belongs to the Kit.