@adamchanadam/agent-handoff-kit 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +77 -246
- package/README.md +77 -252
- package/bin/agent-handoff-kit.mjs +247 -47
- package/bin/commands.mjs +56 -8
- package/bin/installed-file-contract.mjs +79 -63
- package/bin/migration-baselines/official-origin-catalog.json +472 -1
- package/bin/official-origin-catalog.mjs +294 -257
- package/bin/progress/assets.mjs +6 -0
- package/bin/progress/dashboard.mjs +1 -1
- package/bin/progress/index.html +4 -1
- package/bin/progress/launch.mjs +40 -0
- package/bin/progress/open.mjs +4 -3
- package/bin/progress/project-version.mjs +121 -0
- package/bin/progress/renderer.js +1 -0
- package/bin/progress/server.mjs +5 -3
- package/bin/progress/styles.css +1 -1
- package/bin/upgrade-inventory.mjs +153 -273
- package/docs/commands.md +61 -59
- package/docs/progress.md +45 -39
- package/package.json +1 -1
- package/packs/agent-governance.md +3 -3
- package/packs/closeout.md +4 -4
- package/packs/integrations.md +20 -20
- package/packs/knowledge.md +3 -3
- package/packs/onboarding.md +16 -12
- package/packs/safety.md +2 -2
- package/runtime-core/AGENTS.core.md +15 -1
- package/runtime-core/DOC_SYNC_REGISTRY.md +1 -1
- package/runtime-core/SESSION_HANDOFF.md +1 -1
- package/runtime-core/SESSION_LOG.md +1 -1
- package/runtime-core/USER_RULES_ENTRY.md +5 -3
package/docs/progress.md
CHANGED
|
@@ -1,67 +1,73 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Agent Handoff Kit 進度頁
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[English](#dashboard)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
在專案的 AI 對話輸入 `/handoff-kit-progress`;Codex 用 `$handoff-kit-progress`,或從 `/skills` 選取。AI 會開啟或重用這個專案的頁面。先看頁面上的專案名稱,避免認錯專案。
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **歷程**:近 7 日、近 30 日、自選日期、關鍵字及工作線篩選。日期標示年份,按封存索引逐批查閱歷史;日期不隱藏目前未完事項。
|
|
9
|
-
- **文件導覽**:核心關係圖顯示八種 Kit 文件角色;清單另列已登記的專案文件,並非專案所有檔案。點選節點突出相關文件與方向,查看用途、原文及來源,也可切換清單。沒有明確記錄的關係不靠 AI 猜補。
|
|
7
|
+
## 可以看到甚麼
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
- **總覽**:目前工作、成果、未完成、等待和待驗收事項。「正在查看」只是你選中的工作,不會改動紀錄。工作排列不是完成順序,完成子項也不代表整項完成。
|
|
10
|
+
- **歷程**:用近 7 日、近 30 日、自選日期、關鍵字和工作篩選,找回已保存的改變。日期篩選不會隱藏目前未完事項。長期紀錄分批讀取,還有內容時可繼續載入;日期排序只包括已載入結果。
|
|
11
|
+
- **文件地圖**:看重要文件的用途、關係及原文。這裏只列已登記文件,不是整個資料夾的所有檔案;沒有記錄的關係不會自行猜補。
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## 何時更新,會用多少 token
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
AI 正常保存工作紀錄後,頁面自行更新,不用刷新,也不用重新設計。AI 只維護有變的進度和必要紀錄,不必記下每一步操作或再寫一份報告。
|
|
16
16
|
|
|
17
|
-
AI
|
|
17
|
+
叫 AI 開頁面和保存紀錄會使用一些 token;之後瀏覽、篩選、動畫和畫面更新不呼叫 AI。沿用安裝時已有的 Node.js 和瀏覽器,不需另外安裝資料庫、Python 或購買金鑰。進度頁程式會隨正常安裝/升級一併準備好;開頁不需下載工具或連接 npm。
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
頁面可切換繁體中文和英文。若紀錄本身沒有翻譯,就保留原文。動畫只提示選取或資料變更,不表示 AI 正在思考或工作已驗收。
|
|
20
20
|
|
|
21
|
-
##
|
|
21
|
+
## 看到缺漏或舊資料時
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
| 情況 | 意思與做法 |
|
|
24
|
+
|---|---|
|
|
25
|
+
| 未記錄/尚未分類 | 原有紀錄沒有這項資料。AI 不會猜進度百分比或完成狀態;可查看原文,或請 AI 在正常保存時補清楚。 |
|
|
26
|
+
| 紀錄只顯示一部分 | 首頁先顯示摘要,其餘可看完整工作或原文。歷史資料太多、缺檔或格式有問題時,頁面會提示未讀齊;縮窄日期或請 AI 查明原因。 |
|
|
27
|
+
| 斷線/更新失敗 | 畫面保留上次資料並提示,會自動重試。可按「立即重連」;仍失敗就再用進度頁指令。 |
|
|
28
|
+
| 升級中 | 暫停讀取,等升級完成後再看,避免把更新到一半的內容當作最新。 |
|
|
29
|
+
| 版本未核實/版本不同 | 頁面從專案讀取這套工具的版本;讀不到不會猜。「資料依據」另列開啟頁面的工具版本。有疑問用 `handoff-kit-check`;查最新正式版用 `handoff-kit-update`。 |
|
|
24
30
|
|
|
25
|
-
|
|
26
|
-
npx --yes @adamchanadam/agent-handoff-kit@latest progress --background --root <project-root>
|
|
27
|
-
```
|
|
31
|
+
「交接保存」是交接文件的保存時間,不是所有專案檔案最後修改的時間。未保存的聊天內容不會出現。頁面只整理已保存的內容,不能證明 AI 已讀齊交接或成果已經驗收。
|
|
28
32
|
|
|
29
|
-
|
|
33
|
+
## 關掉後怎樣重開
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
頁面開着時會持續連線。全部頁面關閉後,本機服務保留八小時;閒置時不反覆讀檔。超過時間、電腦重啟或服務停止後,再用同一個進度頁指令即可。舊網址不能自己啟動已停止的程式。
|
|
32
36
|
|
|
33
|
-
|
|
37
|
+
這是你電腦上的檢視頁,不會公開上網。查看、篩選和點選文件不會改檔;它只讀取專案內已登記、允許顯示的文件,原文以文字顯示。請勿把密碼等秘密寫進專案紀錄。
|
|
34
38
|
|
|
35
|
-
|
|
36
|
-
|---|---|---|
|
|
37
|
-
| 名稱/專案目標 | `dev/PROJECT_INDEX.md` → `Project` | 512 KiB |
|
|
38
|
-
| 工作/交接 | `dev/SESSION_HANDOFF.md` → `Work Items` 及原有段落 | 1 MiB;128 項工作 |
|
|
39
|
-
| 最近變更 | `dev/SESSION_LOG.md` | 頭 64 KiB、十則完整條目;首頁三則 |
|
|
40
|
-
| 歷程 | 主日誌及 `dev/SESSION_LOG_archive/INDEX.md` 登記批次 | 每次 256 KiB 日誌、4 檔、20 結果;索引 512 KiB |
|
|
41
|
-
| 文件 | Kit 角色、Index Directory Map / Document Relations、工作 Source | 160 文件;文字預覽 1 MiB |
|
|
39
|
+
## Dashboard
|
|
42
40
|
|
|
43
|
-
|
|
41
|
+
In your project’s AI conversation, enter `/handoff-kit-progress`. In Codex, use `$handoff-kit-progress` or select it through `/skills`. The AI opens or reuses that project’s page. Check the displayed project name so you know which project you are viewing.
|
|
44
42
|
|
|
45
|
-
|
|
43
|
+
### What you can see
|
|
46
44
|
|
|
47
|
-
|
|
45
|
+
- **Overview**: current work, results, unfinished items, things waiting and work awaiting checks. “Viewing” identifies your selection without changing records. The order of work items is not a completion sequence, and completing a child does not complete its parent.
|
|
46
|
+
- **History**: find saved changes using the last 7 days, last 30 days, custom dates, keywords and work filters. Date filters do not hide current outstanding items. Long histories load in batches; load more when available. Date sorting covers only loaded results.
|
|
47
|
+
- **Documents**: see important files, their purpose, connections and source text. Only registered files appear, not every file in the folder. Unrecorded connections are not invented.
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
### Updates and token use
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
The page updates when the AI saves normal work records, without a refresh or redesign. The AI maintains changed progress and necessary records, rather than logging every action or writing a second report.
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
Asking the AI to open the page and saving records use some tokens. After that, browsing, filters, animation and page updates make no AI calls. It uses the tool’s existing Node.js and your browser; no database, Python or purchased key is needed. Normal installation or upgrade supplies the progress program; opening it requires no tool download or npm connection.
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
The interface switches between Traditional Chinese and English. Records without a translation keep their original language. Animation indicates a selection or changed data, not AI thinking or accepted work.
|
|
56
56
|
|
|
57
|
-
|
|
57
|
+
### Missing or older information
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
| What you see | What it means and what to do |
|
|
60
|
+
|---|---|
|
|
61
|
+
| Unrecorded / unclassified | The records lack that information. No progress percentages or completion states are guessed. Read the source or ask the AI to clarify it during a normal save. |
|
|
62
|
+
| Only part of the history | Home shows summaries with links to full work or sources. Large histories, missing files or formatting problems produce an incomplete-coverage notice. Narrow the dates or ask the AI to investigate. |
|
|
63
|
+
| Disconnected / update failed | The page keeps the last data with a warning and retries. Select “Reconnect now”, or use the Progress shortcut again if it still fails. |
|
|
64
|
+
| Upgrade in progress | Reading pauses until the upgrade finishes, so partly updated files are not treated as current. |
|
|
65
|
+
| Version unverified / versions differ | The page reads the version recorded in this project and does not guess if it is unavailable. Sources also lists the tool version that opened the page. Use `handoff-kit-check` for concerns or `handoff-kit-update` to check the latest release. |
|
|
60
66
|
|
|
61
|
-
|
|
67
|
+
“Handoff saved” is the handoff file’s save time, not the last change to every project file. Unsaved chat content does not appear. The page organizes saved records; it does not prove that the AI has read the full handoff or that the work has passed its checks.
|
|
62
68
|
|
|
63
|
-
|
|
69
|
+
### Reopening the page
|
|
64
70
|
|
|
65
|
-
|
|
71
|
+
The service stays connected while a page is open. After all pages close, it remains available for eight hours without repeatedly reading files while idle. After that, a computer restart or a stopped service, use the same Progress shortcut again. An old browser address cannot start a stopped program by itself.
|
|
66
72
|
|
|
67
|
-
|
|
73
|
+
This is a view on your computer, not a public website. Browsing, filtering and selecting files do not edit them. Only registered files within the project that are allowed for display are read, and their contents are shown as text. Do not put passwords or other secrets into project records.
|
package/package.json
CHANGED
|
@@ -20,9 +20,9 @@ Use for governance rules, prompts, agent instructions, handoff systems, startup/
|
|
|
20
20
|
4. Do not let development-only workspace rules enter public runtime.
|
|
21
21
|
5. Check complexity budget before adding default-core behavior.
|
|
22
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 `
|
|
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 installed `AGENTS.md` Persistence Gate decision; do not duplicate the gate thresholds in this pack.
|
|
24
24
|
8. Before any pre-closeout handoff / log write for governance work, apply the core Persistence Gate explicitly. A concern that future agents may read stale handoff is not enough when the changed rule, spec, runbook, or document is itself the target authority; leave handoff lag expected unless checkpoint conditions are met. When the gate does select a checkpoint, write only the smallest current-state field or concise log entry and leave historical evidence sections byte-stable where practical.
|
|
25
|
-
9. For long-running projects, maintain `dev/PROJECT_DECISIONS.md`
|
|
25
|
+
9. For long-running projects, maintain `dev/PROJECT_DECISIONS.md` under `dev/rules/closeout.md` `## 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.
|
|
26
26
|
10. 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.
|
|
27
27
|
11. 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.
|
|
28
28
|
12. 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.
|
|
@@ -37,7 +37,7 @@ This is the single write-location contract for installed projects, not for autho
|
|
|
37
37
|
2. Treat the `AGENTS.md` managed-core region and complete official `dev/rules/*` pack bodies as protected. Daily project edits must not insert, translate, reformat, reorder or remove their contents or delimiters. Verify the installed version's official content before identifying the boundary; a heading, marker or version row alone is not ownership proof. Formal upgrade or an explicitly scoped repair owns official changes. If local rules are already interleaved, preserve them and report the required bounded reconciliation; do not guess which lines to delete or bless the mixed body as official.
|
|
38
38
|
3. Reuse the matching pack's existing project supplement when it owns the rule. Otherwise place a short local rule after the entire verified official body under `## Project Rules`; preserve the official trailing newline. This heading labels the writable appendix, not the end of official ownership. For substantial or shared procedures, reuse a registered project reference; create a new reference only if no suitable owner exists. If `dev/USER_RULES.md` formally owns the rule, use its accepted update procedure rather than editing witnessed bytes or creating a competing copy. Always-needed project entry rules may live outside the managed core only after checking their existing owner.
|
|
39
39
|
4. Preserve project-state schemas separately: edit handoff fields, actual log entries, index data or registry rows in their existing writable sections; do not insert policy into template instructions or alter machine markers. Preserve official routing rows in `dev/RULE_PACKS.md`; add a project row only when a project reference needs a task trigger, naming both the relevant pack and reference. A same-pack appendix uses that pack's existing route. Do not add a route or load a pack merely for bare startup.
|
|
40
|
-
5. Before and after an edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>`
|
|
40
|
+
5. Before and after an ordinary project-rule edit touching core or pack files, compare the complete protected region against the verified input; every protected byte must remain unchanged. For a formal upgrade or explicitly scoped repair, verify the approved official diff against the verified input and perform its required readback instead; preserve interleaved or unknown user content and do not guess which bytes to remove. Use the installed-version CLI's read-only `upgrade --dry-run --root <project root>` where that lifecycle applies; record the CLI version and any existing conflict separately. A pre-existing conflict requires reconciliation before claiming the write boundary is verified. A new conflict or a change outside the approved scope prevents completion; restore only your own scoped change from its verified input without discarding concurrent or pre-existing user work. For ordinary project-state edits, use schema/marker and local readback checks instead of an upgrade preview.
|
|
41
41
|
6. Read back the rule from its normal consumer path: task signal -> router -> relevant pack including the project supplement and required reference -> requested action. Verify its exact requirement, scope and precedence, and that unrelated packs stay unloaded. An indexed file that no applicable route reads is not connected. Evidence must show both correct application and preserved upgrade compatibility; a successful preview alone does not prove an AI followed the rule.
|
|
42
42
|
|
|
43
43
|
## Governance Bridge Workflow
|
package/packs/closeout.md
CHANGED
|
@@ -27,7 +27,7 @@ Do not copy the full opening message into `dev/SESSION_LOG.md` or any third curr
|
|
|
27
27
|
|
|
28
28
|
Full closeout is differential and write-minimal. Update only fields whose current truth changed. For unchanged state, preserve bytes where practical and record checked/no-op only when it helps the next agent. 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.
|
|
29
29
|
|
|
30
|
-
Handoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style.
|
|
30
|
+
Handoff cold zones are historical / evidence sections, old validation records, completed-work narratives, and unchanged durable anchors. Stable anchors and decision-changing current facts stay in the packet. Do not rewrite, reword, reorder, or refresh cold zones for ceremony or style. When older detailed narrative no longer changes the next action, preserve it byte-for-byte in existing trace/archive storage and verify that copy before removing it from the current packet. Do not rewrite or archive unchanged material at every closeout, impose an arbitrary size cap, or weaken the required full reception of the current packet.
|
|
31
31
|
|
|
32
32
|
1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then update only changed closeout-reconciled fields or sections; leave already-current sections unchanged instead of rewriting them for ceremony.
|
|
33
33
|
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.
|
|
@@ -42,7 +42,7 @@ Handoff cold zones are historical / evidence sections, old validation records, c
|
|
|
42
42
|
10. Mark first-use guidance `consumed` after the first successfully completed task or first full closeout. Upgrade must never reset `consumed` or `not_applicable` to `eligible`.
|
|
43
43
|
11. Verify `START_NEXT_SESSION_PROMPT.txt` against the sole fenced handoff opening-message block first. Regenerate it only when normalized content differs, then run the project's fixed prompt-mirror checker or perform an equivalent anchored read-back that verifies marker, heading, fence, full-copy uniqueness, and normalized content equality.
|
|
44
44
|
12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
|
|
45
|
-
13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source
|
|
45
|
+
13. Run `agent-handoff-kit closeout-status --root <project root>` after the handoff and prompt read-back. It performs the one required fresh doctor read-back plus a read-only workspace-health comparison against the handoff snapshot, and its output is the only final card source. A nonzero result means the closeout is blocked; do not replace it with a success summary.
|
|
46
46
|
|
|
47
47
|
## Packet-Only Reconstruction Check
|
|
48
48
|
|
|
@@ -70,7 +70,7 @@ If no trigger applies, record one no-op reason. Handoff carries continuity; log
|
|
|
70
70
|
|
|
71
71
|
The handoff opening-message block is authoritative. It must name the absolute root, route the agent through `AGENTS.md` and the handoff, state the current objective and boundary, and avoid instructing the next agent to redo completed work. It must not require SESSION_LOG as an ordinary startup read.
|
|
72
72
|
|
|
73
|
-
Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs.
|
|
73
|
+
Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. When it returns a card, copy the full card verbatim in a fenced `text` block before any explanation for both `status: complete` and `status: blocked`; never reduce it to selected status or blocker lines, print the literal placeholder `v<version>`, hand-compose a substitute success/blocked card, or use `handoff saved` unless the command reports `status: complete`. Only when no CLI card exists because the CLI could not be launched or returned no card may the final response show a fenced `closeout unavailable` card with no version and no `saved`/`complete` claim, followed by the actual missing condition. That presentation does not complete closeout and never replaces a returned complete or blocked CLI card.
|
|
74
74
|
|
|
75
75
|
```text
|
|
76
76
|
/\_/\ Agent Handoff Kit v<version>
|
|
@@ -84,7 +84,7 @@ status: complete
|
|
|
84
84
|
⚠️ Boundary: <important boundary or none>
|
|
85
85
|
```
|
|
86
86
|
|
|
87
|
-
For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root.
|
|
87
|
+
For `status: blocked`, the command instead says `handoff blocked`; retain that status, blocker reason, and human explanation: `這不是失敗;只是還有事未保存、未提交、未驗證或需要處理。先照 Blocker 行處理,不要把本輪當作已完成交接。` Then give the short local-root entry `Start Agent Handoff` / `開工` and the path-bearing fallback for an agent not yet pointed at the root. The narrow `closeout unavailable` presentation above is allowed only when there is no CLI card; do not use it to replace a returned blocked card or hand-compose a third stateful prompt.
|
|
88
88
|
|
|
89
89
|
## Stop Conditions
|
|
90
90
|
|
package/packs/integrations.md
CHANGED
|
@@ -48,7 +48,7 @@ Agents must not use model memory, old session experience, copied examples, Conne
|
|
|
48
48
|
| Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
|
|
49
49
|
| Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
|
|
50
50
|
|
|
51
|
-
If the required source cannot be inspected,
|
|
51
|
+
If the required source cannot be inspected, first classify the actual failure and check an already-authorized capable source/channel plus any normal platform approval. Mark only the affected use `blocked` or `unverified` when none can establish the needed contract; ask the user only for docs, schema, access, or a decision the AI cannot obtain, and use a manual packet only when it preserves the needed evidence. Do not continue by trial and error or bypass a real refusal. Connector-first means schema-first for the active runtime, not memory-first.
|
|
52
52
|
|
|
53
53
|
#### Runtime-Controlled Tool Operation Variants
|
|
54
54
|
|
|
@@ -110,7 +110,7 @@ MCP servers may be official, community, custom, or project-local. Custom MCPs of
|
|
|
110
110
|
Discipline:
|
|
111
111
|
|
|
112
112
|
- Use only the active runtime's exposed tool name, description, and input schema.
|
|
113
|
-
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `
|
|
113
|
+
- Treat non-vetted or custom MCP write operations with extra caution. Destructive writes require dry-run and user confirmation under `dev/rules/safety.md`.
|
|
114
114
|
- If the server fails because of process crash, config error, or unavailable runtime state, surface the failure, recommend checking MCP config and restarting the host tool, and do not blindly retry.
|
|
115
115
|
|
|
116
116
|
#### 3.3 Plugins
|
|
@@ -158,18 +158,18 @@ Record declared integrations in `PROJECT_INDEX` `## Installed Integrations`, usi
|
|
|
158
158
|
|
|
159
159
|
#### Phase 2 — Cross-session handoff
|
|
160
160
|
|
|
161
|
-
`SESSION_HANDOFF` durable anchors should point future agents to `PROJECT_INDEX` `## Installed Integrations`.
|
|
161
|
+
`SESSION_HANDOFF` durable anchors should point future agents to `PROJECT_INDEX` `## Installed Integrations`. Follow the core Intent And Startup contract for when to read that section; a durable anchor does not add it to every next-session opening read order.
|
|
162
162
|
|
|
163
163
|
#### Phase 3 — Before-use availability probe
|
|
164
164
|
|
|
165
165
|
Immediately before the current task uses a declared integration, run the smallest relevant availability probe when the runtime exposes the needed tool schema. Do not probe unrelated integrations at startup. `TBD`, examples, blank rows, and placeholder-only tables are not declarations.
|
|
166
166
|
|
|
167
|
-
- Probe success: update `Last Verified`
|
|
168
|
-
- Probe fail:
|
|
167
|
+
- Probe success: update `Last Verified` only through the normal Persistence Gate, then proceed.
|
|
168
|
+
- Probe fail: record the actual unavailable/failed result where the Persistence Gate applies, then use this pack's fallback flow only for the affected surface.
|
|
169
169
|
|
|
170
170
|
#### Phase 4 — Task execution
|
|
171
171
|
|
|
172
|
-
Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available,
|
|
172
|
+
Apply the knowledge pack's Connector-first discipline: check declaration, use the verified direct tool when available, then follow this pack's classified fallback. A manual packet or user question is a last resort only when an authorized capable channel cannot supply the needed evidence.
|
|
173
173
|
|
|
174
174
|
#### Phase 5 — Mid-session drift handling
|
|
175
175
|
|
|
@@ -177,18 +177,18 @@ If an integration fails mid-task because of expired auth, rate limit, network ti
|
|
|
177
177
|
|
|
178
178
|
- Surface the failure and impact.
|
|
179
179
|
- Do not auto-fix credentials or auth.
|
|
180
|
-
- Update `PROJECT_INDEX` `Last Verified` /
|
|
180
|
+
- Update `PROJECT_INDEX` `Last Verified` only after a real successful probe and the normal Persistence Gate; record an actual failed probe as failure/drift without relabeling it available.
|
|
181
181
|
- Record the drift in `SESSION_LOG` and unresolved risk in `SESSION_HANDOFF` when it affects future work.
|
|
182
182
|
|
|
183
183
|
#### Phase 6 — Cross-tool consistency
|
|
184
184
|
|
|
185
|
-
Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use fallback flow
|
|
185
|
+
Integration declarations are project-level; they do not guarantee every AI runtime has the same tools installed. A new runtime must verify availability, warn on capability differences, and use this pack's fallback flow for the affected surface; do not require the user to install or switch tools before checking an already-authorized capable channel.
|
|
186
186
|
|
|
187
187
|
## Rules
|
|
188
188
|
|
|
189
189
|
1. **Credential separation**: never ask for, log, or persist credential values. Redact credential-like values and warn about rotation when appropriate.
|
|
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
|
-
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,
|
|
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, inspect the active runtime for an authorized capable tool/schema before asking the user about access or source information.
|
|
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
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.
|
|
@@ -208,7 +208,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
208
208
|
- Before external-tool first use, write, destructive operation, raw API / SDK / CLI / URI / plugin API call, or retry after tool error, confirm the current usage source.
|
|
209
209
|
- Surface and record mid-session integration drift.
|
|
210
210
|
- After external-tool use, perform ownership-based resource closeout. For long-running, multi-tool, MCP, browser automation, repeated-error, or slowdown scenarios, report grouped residual processes or services when observable.
|
|
211
|
-
- Before closeout, update `Last Verified` for integrations
|
|
211
|
+
- Before closeout, update `Last Verified` only for integrations with a real successful probe and when the normal Persistence Gate selects the write; retain actual failed-probe drift separately.
|
|
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
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`.
|
|
@@ -216,7 +216,7 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
216
216
|
|
|
217
217
|
## Closeout
|
|
218
218
|
|
|
219
|
-
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells
|
|
219
|
+
1. Update `PROJECT_INDEX` `## Installed Integrations` `Last Verified` cells only after real successful probes and when the normal Persistence Gate selects the write; record actual failed drift without claiming availability.
|
|
220
220
|
2. If drift happened, record the drift narrative, impact, and suggested next handling in `SESSION_LOG`.
|
|
221
221
|
3. Add unresolved integration failures to `SESSION_HANDOFF` `## Risks / Blockers`.
|
|
222
222
|
4. If unresolved drift affects startup, mention the next-session verification need in the opening message.
|
|
@@ -227,9 +227,9 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
227
227
|
|
|
228
228
|
| Anti-pattern | Why it is wrong | Correct approach |
|
|
229
229
|
|---|---|---|
|
|
230
|
-
| Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations
|
|
230
|
+
| Assuming no Connector or MCP exists whenever the user mentions Notion, Google Drive, or another external source | Mature connector ecosystems make paste-only fallback an unreliable default. | Read `PROJECT_INDEX` Installed Integrations, then inspect the active runtime for an authorized capable tool/schema; ask only for missing user-held access or source information. |
|
|
231
231
|
| Guessing tool names, endpoints, CLI flags, URI parameters, or plugin APIs from memory | Stale examples cause unknown tool, invalid args, 400 / 404, permission, or auth loops. | Verify active runtime schema, official docs, official types/samples, or versioned local runbooks. |
|
|
232
|
-
| Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference;
|
|
232
|
+
| Treating browser validation as ordinary coding and guessing Chrome, Playwright, or DevTools commands | Browser and tool-control surfaces differ across runtimes, profiles, plugins, and installed packages. | Verify the active runtime schema, official docs, or a registered tool operation reference; use the classified fallback only for the affected surface when unavailable. |
|
|
233
233
|
| Treating a Connector marketing page or old example as executable schema | Marketing pages do not prove the active runtime's current tool name or input schema. | Use active runtime tool list/schema as the invocation source. |
|
|
234
234
|
| Retrying unknown tool / invalid args by changing names or parameters repeatedly | Trial-and-error hides the real schema or docs gap. | Stop same-pattern retries and return to the External Tool Usage Verification Gate. |
|
|
235
235
|
| Writing credential values into `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG` | Project files and git history are persistent; leaked credentials remain exposed. | Record credential references only, never values. |
|
|
@@ -245,10 +245,10 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
245
245
|
|
|
246
246
|
## Cross-reference
|
|
247
247
|
|
|
248
|
-
- `
|
|
249
|
-
- `
|
|
250
|
-
- `
|
|
251
|
-
- `
|
|
252
|
-
- `
|
|
253
|
-
- `
|
|
254
|
-
- `
|
|
248
|
+
- `dev/rules/knowledge.md` Rule 5: Connector-first source access discipline.
|
|
249
|
+
- `dev/rules/safety.md` Rule 10: external API / SDK / CLI / tool verification boundary.
|
|
250
|
+
- `dev/rules/safety.md` Rule 12: credential leak prevention.
|
|
251
|
+
- `dev/rules/safety.md` Rule 14: process termination and cache cleanup boundary for external-tool resources.
|
|
252
|
+
- `dev/rules/onboarding.md` Scenario F: first-contact declaration entry point.
|
|
253
|
+
- installed `AGENTS.md`: task-triggered availability probe discipline.
|
|
254
|
+
- `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## External Sources` `via` column: declaration registry.
|
package/packs/knowledge.md
CHANGED
|
@@ -17,9 +17,9 @@ 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 `
|
|
21
|
-
(c) If a declared Integration is unavailable in the current session
|
|
22
|
-
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool:
|
|
20
|
+
(b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in installed `AGENTS.md`): 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
|
+
(c) If a declared Integration is unavailable in the current session, follow `dev/rules/integrations.md` fallback: classify the actual failure, check a task-authorized capable channel and normal platform approval, and use a manual packet only when it preserves the needed evidence. Record drift honestly; update `Last Verified` only after a real successful probe and the normal Persistence Gate.
|
|
22
|
+
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: first inspect the active runtime for an authorized capable tool/schema. Ask the user only for access, source information, or a decision that the AI cannot obtain; do not silently assume paste fallback. Backward-compat: existing v0.2.x projects with no Installed Integrations section follow the same bounded capability check before any necessary user question.
|
|
23
23
|
6. When writing to an external mirror or index, read back the written record before claiming sync success.
|
|
24
24
|
7. Preserve local file paths as plain text, code, or structured rich text fields when the external tool parses Markdown links or escape characters.
|
|
25
25
|
|
package/packs/onboarding.md
CHANGED
|
@@ -33,17 +33,11 @@ Load this pack when the user message contains an onboarding signal such as:
|
|
|
33
33
|
- The user asks a generic capability question instead of giving a concrete task.
|
|
34
34
|
- The user appears unfamiliar with the workflow, for example asking what the AI should do rather than giving an objective.
|
|
35
35
|
|
|
36
|
-
## Discipline
|
|
37
|
-
|
|
38
|
-
### 1. Do not assume prior reading
|
|
39
|
-
|
|
40
|
-
The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
|
|
36
|
+
## Discipline
|
|
41
37
|
|
|
42
|
-
### 1.
|
|
38
|
+
### 1. Onboarding brand card
|
|
43
39
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
Start broad help / capability answers with this display-only onboarding card in a fenced `text` block:
|
|
40
|
+
Every onboarding reply, including a blocked/safe-stop reply, starts with a fenced cat brand card. Use the normal guidance card when help can continue:
|
|
47
41
|
|
|
48
42
|
```text
|
|
49
43
|
/\_/\ Agent Handoff Kit
|
|
@@ -51,7 +45,17 @@ Start broad help / capability answers with this display-only onboarding card in
|
|
|
51
45
|
> ^ <
|
|
52
46
|
```
|
|
53
47
|
|
|
54
|
-
The card is
|
|
48
|
+
When a required condition blocks onboarding, keep the same card and replace only its middle line with ` ( x.x ) onboarding paused`, then state the exact blocker and next safe action. The normal guidance card is the display-only onboarding card. The card is presentation only: it must not claim `continuity ready`, `handoff saved`, a version, loaded state, doctor health, or that `SESSION_HANDOFF.md` has been read.
|
|
49
|
+
|
|
50
|
+
### 1.1 Do not assume prior reading
|
|
51
|
+
|
|
52
|
+
The user may start directly from an AI conversation. Explain only the minimum needed for the current step. Do not teach internal file structure, pack names, release identifiers, maintenance rules, or implementation details unless the user asks.
|
|
53
|
+
|
|
54
|
+
### 1.2 Public capability answer
|
|
55
|
+
|
|
56
|
+
When the user asks "教我用", "能力", "能做甚麼", "what can agent handoff kit do", or an equivalent broad help question, answer in normal user language first. The main answer is what the user can say to an AI, not a CLI command list.
|
|
57
|
+
|
|
58
|
+
For broad help / capability answers, use the normal `quick guide` card above. Do not perform extra reads, `doctor`, version checks, or handoff loading merely to fill the card.
|
|
55
59
|
|
|
56
60
|
Cover these public command categories:
|
|
57
61
|
|
|
@@ -184,7 +188,7 @@ Step E.5: after confirmation, load the appropriate regular pack combination.
|
|
|
184
188
|
|
|
185
189
|
Use this scenario when the user already has external tools installed or asks how to use them safely across sessions. This scenario does not teach installation. It records declarations, boundaries, verification, and safe use.
|
|
186
190
|
|
|
187
|
-
Step F.1:
|
|
191
|
+
Step F.1: inspect runtime-exposed external tools by category first: Connectors, MCPs, Plugins, Skills, browser automation, crawlers, notebooks, or local helper services. Ask the user only for names, access, or source details the runtime cannot reveal, then classify them.
|
|
188
192
|
|
|
189
193
|
Step F.2: explain credential separation: Kit files record tool names, project usage, access scope, and credential reference location only. They must never store API keys, OAuth tokens, secrets, or credential values.
|
|
190
194
|
|
|
@@ -192,7 +196,7 @@ Step F.3: map source-of-truth architecture: source of truth, index, persistent m
|
|
|
192
196
|
|
|
193
197
|
Step F.4: when authorized, write the declaration into `PROJECT_INDEX` `## Installed Integrations` and cross-reference relevant External Sources `via` values.
|
|
194
198
|
|
|
195
|
-
Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks.
|
|
199
|
+
Step F.5: verify current availability using runtime-exposed tool schemas, official docs, or versioned local runbooks. For an unavailable tool, follow `dev/rules/integrations.md` classified fallback for the affected surface; mark blocked / unverified only when no authorized capable route can establish the needed contract.
|
|
196
200
|
|
|
197
201
|
## Cross-reference to guide.html
|
|
198
202
|
|
package/packs/safety.md
CHANGED
|
@@ -15,7 +15,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
15
15
|
1. Before deleting, overwriting, moving, renaming, cleaning, resetting, publishing, or running destructive tool operations, list the exact target paths, expected scope, impact, and required confirmation.
|
|
16
16
|
2. Preserve user-provided source files by default. Create renamed outputs instead of in-place overwrites unless overwrite is explicitly requested.
|
|
17
17
|
3. Never operate on a filesystem root, drive root, home directory root, repository parent root, system directory, or ambiguous path.
|
|
18
|
-
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations.
|
|
18
|
+
4. Do not bypass permissions, file locks, sandbox limits, failed safety checks, or denied operations. First classify the actual failure and use normal platform approval or another already-authorized safe method only when its scope is verified; a true unresolved denial remains an affected-operation blocker. Ask for manual action only when the user alone can supply the missing condition.
|
|
19
19
|
5. Never run `rm -rf`, `sudo rm -rf`, `Remove-Item -Recurse -Force`, `git clean -fdx`, `git reset --hard`, or an obfuscated / wrapped equivalent. User request does not make these named commands permissible. Use a narrower reversible operation or provide a manual action list.
|
|
20
20
|
6. On Windows, do not use `cmd /c rmdir`, `cmd /c rd`, or any `cmd.exe /c` variant combined with `rmdir` or `rd`. Prefer native PowerShell cmdlets when PowerShell is active, and do not compose filesystem modification commands across shells.
|
|
21
21
|
7. On macOS / Linux, never use destructive wildcards, recursive `chmod 777`, recursive `chown`, disk formatting, mount-point cleanup, or home/system-directory cleanup. Other destructive operations require explicit authorization plus resolved target verification and must use the narrowest safe tool.
|
|
@@ -30,7 +30,7 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
30
30
|
(a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
|
|
31
31
|
(b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
|
|
32
32
|
(c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
|
|
33
|
-
(d) Auth failure (token expired / revoked
|
|
33
|
+
(d) Auth failure (token expired / revoked) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance). A rate limit is a capacity constraint, not proof of an auth failure: respect its limit and use only an authorized safe path without demanding re-login unless an actual auth failure is verified.
|
|
34
34
|
13. Shell / script parser failure discipline: after a shell, quoting, here-string, wrapper, temporary script, or parser failure, stop same-pattern retries and classify the failing layer before trying again: active shell, wrapper shell, runtime parser, package manager, or target CLI. Do not embed large JavaScript, JSON, Markdown, regex, patch, or path-heavy content inside shell strings when a direct tool, patch file, or real script file is safer. For temporary scripts, first make a minimal reproducible script, run a syntax-only check such as `node --check`, `python -m py_compile`, or an equivalent parser check where available, then execute. After any write script, read back the affected files or affected ranges before claiming success. If the same parser failure repeats, stop and return to root-cause classification instead of changing quoting again.
|
|
35
35
|
14. Process termination and cache cleanup boundary: agents may automatically close or clean up resources that are clearly task-owned or agent-managed, including task-created browser contexts, MCP child processes, helper servers, notebook kernels, temp directories, or bounded caches. Agents must not terminate shared, ambiguous, user-owned, system-level, or other-agent-owned processes; delete broad caches; disable tools; uninstall packages; mutate browser profiles, desktop app sessions, shared tool servers, notebook kernels, global package / browser / plugin caches, or change configuration without explicit user confirmation listing exact process IDs or paths, tool names, evidence, expected impact, and restart / rollback path. Generic process names such as `node`, `python`, or `chrome` are never enough ownership evidence by themselves. If a process, browser context, desktop app session, notebook kernel, MCP service, or helper server may belong to another AI agent running on the same machine, treat it as shared unless current-task ownership is proven.
|
|
36
36
|
15. Short-lived localhost validation services: when local HTML / app validation needs a safer fallback after `file://` is blocked, a task-owned loopback static server is allowed only within a bounded project or temp path, bound to localhost / loopback, and used for the current validation task. Record the served root, URL, and evidence collected. Stop the server before completion and verify it is no longer reachable when the runtime allows. Do not leave helper servers running as a convenience, expose them beyond loopback, reuse another agent's server without confirmation, or mutate browser profiles / extension state to make the validation pass.
|
|
@@ -4,6 +4,18 @@ This is the small always-read contract. Detailed task and closeout procedures li
|
|
|
4
4
|
|
|
5
5
|
## 1. Intent And Startup
|
|
6
6
|
|
|
7
|
+
### Upgrade lock guard
|
|
8
|
+
|
|
9
|
+
Before any handoff, user-rule router, pack, or other project-state read, use the verified project root to probe `dev/governance_migrations/.upgrade.lock`. A present lock, or inability to establish its absence, stops ordinary work and all further project-state reads and searches. Do not search for recovery instructions or edit or delete the lock. Before that explanation, render this fenced brand card:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
/\_/\ Agent Handoff Kit
|
|
13
|
+
( x.x ) continuity unavailable
|
|
14
|
+
> ^ <
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It must not claim loaded, healthy, saved, or version-verified state. Explain that continuity is unavailable and give the supported recovery command `agent-handoff-kit upgrade --yes --root <verified-project-root>`. Bare startup never runs this command automatically. If the existence probe is unreadable, report continuity unavailable without claiming a lock is present and do not auto-recover. When the visible user request explicitly authorizes update, upgrade or recovery, only the official CLI performs transaction recovery; resume ordinary state loading only after that CLI succeeds and a new probe establishes lock absence.
|
|
18
|
+
|
|
7
19
|
Classify the user's visible intent before loading project state. For explicit continuity, closeout, or a task whose next action depends on persisted project state, read `dev/SESSION_HANDOFF.md` first; it is the current-state authority. A direct ordinary or stateless task does not read the handoff merely because the project root is known. If the message is genuinely unresolved and the handoff can resolve it, read the handoff before asking the user.
|
|
8
20
|
|
|
9
21
|
Do not read `dev/SESSION_LOG.md` during ordinary startup; it is trace-back evidence only. Do not read `START_NEXT_SESSION_PROMPT.txt` in addition to the handoff when already operating in the project root; that file is a portable generated mirror for an agent that has not yet been pointed at the root.
|
|
@@ -73,6 +85,8 @@ In every user-facing reply, lead with ordinary language: state the result and it
|
|
|
73
85
|
|
|
74
86
|
- Simple answers, pure conversation or creation with no durable state, and low-risk tasks with an obvious target may proceed directly with proportionate reading and checking.
|
|
75
87
|
- Non-trivial work reads relevant sources before changing them.
|
|
88
|
+
- For failures spanning steps or recurring, trace relevant inputs, processing, saved state and actual consumers until evidence explains the cause and direct impact. Then stop expanding the investigation and repair the affected locations with that cause within the authorized scope; do not turn a simple local fix into a whole-system audit.
|
|
89
|
+
- When repeated attempts produce no improved result, unblocked dependency or new evidence, reassess the cause and method before retrying; preserve useful results. Necessary waits and experiments that yield new evidence are not stagnation. Existing safety and retry limits still apply.
|
|
76
90
|
- High-risk work states scope, impact, acceptance, and required confirmation before writes.
|
|
77
91
|
- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.
|
|
78
92
|
- Task-first governance locality: when the user supplied a concrete, actionable, authorized task plan and no safety / source-truth / permission blocker prevents it, follow the plan's main acceptance path before governance side work. Governance may become the main path only when the task itself is governance, the user explicitly asks for governance bridge or long-term governance, the content semantically requires cross-session force, or deferring it would create a safety, continuity, source-of-truth, or discoverability blocker. Otherwise, keep governance to the smallest classification, indexing, sync, or Persistence Gate decision that does not change the main deliverable path; do not start governance bridge, long-term-governance routing, repo-wide scans, handoff writes, or closeout solely because the task mentions Markdown, README, docs, specs, plans, checklists, or generated outputs.
|
|
@@ -116,7 +130,7 @@ Do not delete, reset, overwrite user-owned content, bulk-move, publish, change p
|
|
|
116
130
|
|
|
117
131
|
Named prohibited destructive commands in `dev/rules/safety.md` remain prohibited even when requested. Never use a weaker pack or local instruction to bypass core safety.
|
|
118
132
|
|
|
119
|
-
Verify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs.
|
|
133
|
+
Verify the selected root and real target boundaries before writes. Do not follow a link, junction, mount, or computed path outside the confirmed root. Do not expose credential values in output, reports, backups, tests, or logs. A real permission or lock refusal stops the affected operation; it is not permission to elevate, switch provider or mode, or use a riskier command. Normal platform approval and another already-authorized safe method remain available only after their actual scope and safety are verified.
|
|
120
134
|
|
|
121
135
|
Do not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.
|
|
122
136
|
|
|
@@ -8,7 +8,7 @@ Use: `confirmed`, `unverified`, `pending`, `blocked`, `not_applicable`.
|
|
|
8
8
|
|
|
9
9
|
| Change type | Also check/update | Verification |
|
|
10
10
|
|---|---|---|
|
|
11
|
-
| New file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed |
|
|
11
|
+
| New durable or discoverable project file or directory | `dev/PROJECT_INDEX.md` Directory Map | path listed; temporary or one-time evidence follows the next row's classification instead |
|
|
12
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
13
|
| Stack or command change | `dev/PROJECT_INDEX.md` Stack / Entry Points | command verified or marked unverified |
|
|
14
14
|
| Public behavior change | README, public docs, changelog | docs mention current behavior |
|
|
@@ -19,7 +19,7 @@ Stable facts that should survive across sessions. Update only when they change,
|
|
|
19
19
|
|
|
20
20
|
This is the current-state area. At every full closeout, update only sections whose current truth changed; leave already-current sections byte-stable where practical and record checked/no-op only when useful. Do not append a new state snapshot under an old one.
|
|
21
21
|
|
|
22
|
-
Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Apply the core Persistence Gate's bounded opening-consistency rule when the changed current facts are repeated in the opening.
|
|
22
|
+
Pre-closeout checkpoint edits, when explicitly authorized or required by the core Persistence Gate, update only the named hot current-state field(s) or one concise log entry. Apply the core Persistence Gate's bounded opening-consistency rule when the changed current facts are repeated in the opening. Cold-zone retention and trace/archive handling are owned by `dev/rules/closeout.md`; keep stable anchors plus the current outcome, remaining obligations, decision-changing corrections/rejected reasons, evidence limits and pointers in this packet. Full reception of the current packet remains mandatory.
|
|
23
23
|
|
|
24
24
|
<!-- ack:section:current-baseline -->
|
|
25
25
|
## Current Baseline
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- ack:section:session-log-preamble -->
|
|
4
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
|
|
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 applies `dev/rules/closeout.md` `## Maintenance Trigger Check`; that owner defines the current thresholds and archive discipline.
|
|
6
6
|
|
|
7
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
8
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
<!-- ack:user-rules-acceptance:sha256=2807fc8bcb006a8ed65d5b7dfe0cd53a499342a2eac41195f0efdad44174b2bc -->
|
|
3
3
|
Before loading task packs, read `dev/USER_RULES.md`. Its registered entries
|
|
4
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.
|
|
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.
|
|
8
|
+
|
|
9
|
+
The core `Upgrade lock guard` applies first when it stops ordinary work.
|