@adamchanadam/agent-handoff-kit 0.3.67 → 0.4.0

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.
@@ -0,0 +1,31 @@
1
+ @charset "UTF-8";
2
+ .brand-label{display:flex;flex-direction:column;align-items:flex-start;line-height:1.25;gap:3px}.kit-version{font-size:11px;font-weight:500;line-height:1.25;letter-spacing:.15px;color:var(--muted)}.kit-version[data-state=different],.kit-version[data-state=unverified]{color:#805400}
3
+ :root{color-scheme:light;--paper:#faf8f3;--ink:#121720;--muted:#67707c;--line:#e5e3df;--blue:#1454ff;--red:#ee303e;--yellow:#ffcf13;--green:#00997b;--radius:18px;--control-face:linear-gradient(150deg,#fffefa,#f0ede6);--control-border:#dedbd3;--control-shadow:inset 0 1px 1px #fff,inset 0 -1px 2px #897d6414,0 4px 10px #4b453714;--control-pressed:inset 0 2px 5px #53493424,0 1px 2px #fff;--action-face:linear-gradient(155deg,#3862ba,#244a98 56%,#183a7f);--action-shadow:inset 0 1px 1px #ffffff60,inset 0 -2px 3px #10255340,0 6px 14px #254c8f28;font:16px/1.65 "Segoe UI","Microsoft JhengHei","PingFang TC",sans-serif}
4
+ *{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);min-width:320px}h1,h2,h3,p{margin:0}h1,h2,h3{line-height:1.3}button,input,select{font:inherit;color:inherit}button,a,input,select{outline-offset:5px}button:focus-visible,a:focus-visible,input:focus-visible,select:focus-visible{outline:3px solid var(--blue)}button{border:0;background:none;cursor:pointer}button:disabled{opacity:.5;cursor:default}a{color:inherit;text-decoration:none}button,a{touch-action:manipulation}[hidden]{display:none!important}svg{width:23px;height:23px;fill:none;stroke:currentColor;stroke-width:1.7;flex-shrink:0}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.skip{position:fixed;top:-80px;left:20px;z-index:50;background:var(--yellow);padding:10px 20px}.skip:focus{top:12px}
5
+ .brandbar{min-height:90px;padding:14px max(4vw,24px);display:flex;align-items:center;justify-content:space-between;gap:24px;border-bottom:1px solid var(--line);background:#fffaf4a6}.brand{display:flex;align-items:center;gap:14px;font-size:21px;font-weight:750;white-space:nowrap;letter-spacing:-.5px}.brand img{width:47px;height:47px;object-fit:contain}nav{display:flex;gap:34px;align-self:stretch;align-items:center}nav a{font-size:15px;font-weight:650;padding:18px 2px;position:relative}nav a[aria-current=page]:after{content:"";height:4px;border-radius:5px;background:var(--action-face);box-shadow:inset 0 1px 1px #ffffff55,0 2px 4px #26488920;position:absolute;bottom:4px;left:0;right:0}.tools{display:flex;align-items:center;gap:24px}#sync{font-size:13px;color:var(--muted);white-space:nowrap}#sync:before{content:"";display:inline-block;width:9px;height:9px;background:#a78326;border-radius:50%;margin-right:9px}body[data-live=true] #sync:before{background:#119961}#language{border:1px solid var(--control-border);border-radius:14px;background:var(--control-face);box-shadow:var(--control-shadow);padding:10px 14px;font-size:14px;min-height:44px}main{max-width:1500px;margin:auto;padding:0 40px}button,.node-circle,.panel{transition:background-color .18s,box-shadow .18s,transform .18s,border-color .18s}.project{padding:36px 20px 16px;position:relative}.eyebrow{font-size:12px;letter-spacing:1.2px;color:var(--muted);margin-bottom:10px}h1{font-size:clamp(30px,3.4vw,48px);font-weight:750;letter-spacing:-1.3px}#goal{font-size:19px;color:#535c68;line-height:1.65;max-width:970px;margin:12px 0 12px;overflow-wrap:anywhere}.quiet{font-size:13px;color:var(--muted);padding:8px 0;display:inline-flex;align-items:center;gap:9px;min-height:40px}.quiet svg{width:18px;height:18px}.text-link{color:#2758b0;font-size:13px;font-weight:550;display:inline-flex;align-items:center;gap:7px;padding:9px 0;min-height:40px}.text-link:hover,.quiet:hover{color:var(--blue);text-decoration:underline}.text-link svg{width:17px;height:17px}.journey{padding:4px 36px 22px;text-align:center}.work-route{display:flex;justify-content:space-around;align-items:flex-start;gap:20px;position:relative}.route-node{min-width:0;flex:1;max-width:360px;position:relative;padding:0 15px 12px;z-index:1}.route-node:before{content:none;height:2px;position:absolute;left:calc(50% + 45px);right:calc(-50% + 5px);top:48px;background:var(--ink);z-index:-1}.route-node:last-child:before{display:none}/* Shared matte material: local light, shade and contact shadow for every object icon. */
6
+ .node-circle,.mini-node{--object-light:#f7745b;--object-mid:#d63b31;--object-dark:#98231f;--object-glow:#b833242c;--object-shadow:inset 2px 2px 3px #ffffff57,inset -5px -7px 12px #0012232e,0 10px 18px var(--object-glow);background:radial-gradient(ellipse at 27% 18%,#ffffff26,transparent 58%),linear-gradient(145deg,var(--object-light),var(--object-mid) 55%,var(--object-dark));border:1px solid #ffffff50;box-shadow:var(--object-shadow)}
7
+ .node-circle{width:94px;height:94px;border-radius:50%;display:flex;align-items:center;justify-content:center;margin:0 auto 20px;color:#fffaf1}.route-node:nth-child(3n+2) .node-circle{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e}.route-node:nth-child(3n) .node-circle{--object-light:#40aa8f;--object-mid:#087c66;--object-dark:#004b41;--object-glow:#006c5529}.route-node[aria-pressed=true] .node-circle{border-color:#ffffffc4;outline:1px solid #bdcceb;outline-offset:7px;box-shadow:var(--object-shadow),0 0 0 7px #edf1fb,0 12px 24px #254a8b21;transform:scale(1.08)}.route-node:hover .node-circle{transform:translateY(-3px)}.node-circle svg{width:37px;height:37px;stroke-width:1.8;filter:drop-shadow(0 2px 1px #15332c35)}.route-node strong{display:block;font-size:20px;font-weight:700;margin-bottom:7px;overflow-wrap:anywhere}.route-node .description{display:block;font-size:14px;line-height:1.7;color:var(--muted);max-width:270px;margin:auto;overflow-wrap:anywhere}.route-node .relation{display:block;font-size:12px;color:var(--muted);margin-top:6px}.focus-panel{display:inline-block;text-align:center;max-width:740px;min-width:min(440px,100%);padding:20px 28px 17px;border:1px solid #dbe1ec;background:linear-gradient(155deg,#fffefa,#f0f3f9);border-radius:16px;margin-top:14px;box-shadow:inset 0 1px 1px #fff,0 8px 24px #273b560a}.focus-panel h2{font-size:18px;line-height:1.6}.focus-panel .focus-summary{font-size:14px;color:var(--muted);max-width:610px;margin:7px auto 8px;overflow-wrap:anywhere}.focus-actions{display:flex;gap:10px;align-items:center;justify-content:center;margin-top:10px}.primary{background:var(--action-face);box-shadow:var(--action-shadow);text-shadow:0 1px 1px #102f6650;color:#fff;padding:10px 24px;border-radius:10px;font-size:14px;font-weight:650;min-height:43px;display:inline-flex;align-items:center;justify-content:center;gap:12px;border:1px solid #244a8e}.primary:hover{box-shadow:var(--action-shadow),0 9px 20px #254c8f20;filter:brightness(1.06);transform:translateY(-2px)}.secondary{background:var(--control-face);box-shadow:var(--control-shadow);border:1px solid var(--control-border);border-radius:10px;padding:10px 16px;min-height:43px;font-size:14px}.secondary:hover{border-color:#a7b7ce;box-shadow:var(--control-shadow),0 6px 14px #3c486514;transform:translateY(-1px)}.pill{--pill-bg:#eef1f5;display:inline-flex;align-items:center;gap:7px;border-radius:20px;background:linear-gradient(155deg,#ffffff8f,#ffffff00),var(--pill-bg);border:1px solid #ffffff8c;box-shadow:inset 0 1px 0 #ffffffb8,0 2px 4px #463e3010;color:#455264;font-size:12px;padding:3px 11px;margin:6px 3px;white-space:nowrap}.pill:before{content:"";width:7px;height:7px;border-radius:50%;background:currentColor;box-shadow:inset 0 1px 1px #ffffff77,0 1px 2px #19202a24}.pill.active{--pill-bg:#e5edff;color:#1954e3}.pill.waiting,.pill.review{--pill-bg:#fff3c3;color:#7b5700}.pill.done{--pill-bg:#dcf3e9;color:#006c52}.pill.paused,.pill.dropped{--pill-bg:#ececec;color:#555}.overview-grid{display:grid;grid-template-columns:.95fr 1.12fr;gap:20px}.panel{background:#ffffffd9;border:1px solid #edecea;border-radius:var(--radius);padding:22px 27px;min-width:0;box-shadow:0 5px 20px #2e2d2303}.section-heading{display:flex;align-items:center;justify-content:space-between;gap:20px;margin-bottom:12px}.section-heading h2{display:flex;gap:12px;align-items:center;font-size:17px}.section-heading h2>svg{width:29px;height:29px;padding:5px;box-sizing:border-box;border-radius:9px;background:var(--control-face);border:1px solid #ffffffb8;box-shadow:var(--control-shadow)}.section-heading .text-link{flex-shrink:0}.recent-list{position:relative}.recent-row{display:grid;grid-template-columns:16px 75px 1fr;gap:14px;text-align:left;width:100%;padding:11px 0;min-width:0;position:relative}.recent-row:before{content:"";width:11px;height:11px;background:#111;border-radius:50%;margin-top:7px;box-shadow:0 0 0 4px white;z-index:1}.recent-row:first-child:before{background:var(--blue)}.recent-row:not(:last-child):after{content:"";position:absolute;left:5px;top:28px;bottom:-6px;width:1px;background:#b5b9be}.recent-row time{font-size:13px;color:var(--muted);padding-top:3px}.recent-row strong{display:block;font-size:14px;line-height:1.6}.recent-row small{display:block;color:var(--muted);font-size:12px;line-height:1.6;margin-top:4px}.recent-row:hover strong{color:var(--blue)}.pending-columns{display:grid;grid-template-columns:1.25fr .8fr;gap:20px}.work-row{display:flex;align-items:flex-start;gap:10px;width:100%;text-align:left;padding:11px 0;border-bottom:1px solid var(--line)}.work-row:last-child{border:0}.work-row .pill{margin:0;flex-shrink:0}.work-row strong{font-size:14px;line-height:1.6;display:block}.work-row small{display:block;font-size:12px;color:var(--muted);line-height:1.6;margin-top:4px}.results{border-left:1px solid var(--line);padding-left:20px}.results h3{font-size:14px;margin:4px 0 12px}.result-row{display:flex;gap:10px;text-align:left;width:100%;padding:9px 0;align-items:flex-start}.result-row svg{color:var(--blue);width:22px;height:22px}.result-row strong{font-size:13px;display:block}.result-row small{font-size:11px;color:var(--muted);display:block;overflow-wrap:anywhere}.document-strip{display:flex;align-items:center;gap:24px;margin-top:20px;padding:20px 26px}.strip-intro{flex:0 0 215px}.strip-intro h2{font-size:16px;margin-bottom:5px}.strip-intro p{font-size:12px;color:var(--muted)}#document-strip{display:flex;justify-content:space-around;gap:24px;flex:1}.strip-node{display:flex;align-items:center;gap:12px;text-align:left;position:relative}.mini-node{width:50px;height:50px;color:#fffaf1;border-radius:50%;display:flex;align-items:center;justify-content:center;flex-shrink:0}.mini-node svg{filter:drop-shadow(0 1px 1px #15332c35)}.strip-node:nth-child(2) .mini-node{--object-light:#ffe077;--object-mid:#edb723;--object-dark:#be8612;--object-glow:#af7a0929;color:#151515}.strip-node:nth-child(3) .mini-node{--object-light:#40aa8f;--object-mid:#087c66;--object-dark:#004b41;--object-glow:#006c5529}.strip-node:nth-child(4) .mini-node{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e}.strip-node strong{font-size:13px;display:block}.strip-node small{font-size:10px;color:var(--muted);display:block;max-width:135px;overflow-wrap:anywhere}.warning{padding:15px 20px;background:#fff3d6;border:1px solid #eed394;border-radius:12px;margin:20px 0;font-size:14px}.empty{font-size:14px;color:var(--muted);padding:16px 0;line-height:1.8}.view-header{padding:38px 20px 24px;display:flex;align-items:center;justify-content:space-between;gap:20px}.view-header p:not(.eyebrow){color:var(--muted);margin-top:10px}.filterbar{display:flex;flex-wrap:wrap;gap:12px;align-items:center;margin:0 20px 8px}.filterbar label{display:flex;align-items:center;gap:8px;font-size:13px}.filterbar input{box-shadow:inset 0 2px 4px #6057400d,0 1px 0 #fff;border:1px solid var(--control-border);border-radius:10px;padding:9px 12px;background:#fff;min-height:44px;font-size:14px}.search-label input{width:160px}.segmented{display:inline-flex;border:1px solid var(--control-border);border-radius:12px;padding:4px;background:#eae7df;box-shadow:inset 0 1px 3px #51473114,0 1px 0 #fff;gap:3px}.segmented button{border-radius:9px;padding:8px 14px;font-size:13px;min-height:36px}.segmented button[aria-pressed=true]{background:var(--action-face);box-shadow:var(--action-shadow);color:#fff}.segmented button:not([aria-pressed=true]):hover{background:var(--control-face);box-shadow:var(--control-shadow)}.scope-note{color:var(--muted);font-size:12px;margin:10px 20px 16px;line-height:1.8}.timeline{max-width:1040px;padding:18px 20px 25px}.day{display:grid;grid-template-columns:125px 1fr;gap:28px}.day>h2{font-size:18px;padding-top:18px}.day-events{border-left:2px solid #c2c7ce;padding:0 0 23px 30px}.event{display:block;width:100%;text-align:left;padding:18px 22px;background:white;border:1px solid var(--line);border-radius:13px;position:relative;margin-bottom:14px}.event:before{content:"";position:absolute;left:-38px;top:24px;width:12px;height:12px;border:2px solid var(--paper);border-radius:50%;background:var(--blue);box-shadow:0 0 0 1px var(--blue)}.event:hover{border-color:#9cb8ff;transform:translateX(3px)}.event strong{font-size:17px;line-height:1.55}.event p{font-size:14px;color:var(--muted);margin:7px 0}.event .event-meta{font-size:11px;color:var(--muted)}#history-more{margin:0 20px 25px}.document-map{position:relative;min-height:520px;display:grid;grid-template-columns:repeat(4,1fr);gap:40px 34px;padding:48px 40px;background:#ffffff7a;border:1px solid var(--line);border-radius:20px}.doc-node{position:relative;z-index:1;display:flex;align-items:center;flex-direction:column;text-align:center;gap:10px;padding:15px 10px;border:1px solid transparent;border-radius:14px}.doc-node:hover,.doc-node.related{background:#f0f4ff;border-color:#dce5ff}.doc-node .node-circle{width:73px;height:73px;margin:0 0 5px;border-width:1px}.doc-node[data-role=handoff] .node-circle{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e;color:white}.doc-node[data-role=log] .node-circle{--object-light:#ffe077;--object-mid:#edb723;--object-dark:#be8612;--object-glow:#af7a0929;color:#111}.doc-node[data-role=decisions] .node-circle{--object-light:#40aa8f;--object-mid:#087c66;--object-dark:#004b41;--object-glow:#006c5529}.doc-node strong{font-size:16px}.doc-node small{font-size:11px;color:var(--muted);overflow-wrap:anywhere;max-width:200px}.doc-node .relations{font-size:11px;color:#526c96}.doc-node.missing{opacity:.6}.document-list{background:white;border:1px solid var(--line);border-radius:16px;overflow:hidden}.document-list button{width:100%;display:grid;grid-template-columns:210px 1fr 110px;padding:18px 24px;border-bottom:1px solid var(--line);text-align:left;gap:16px}.document-list small{color:var(--muted);overflow-wrap:anywhere}footer{padding:25px 0 20px;display:flex;align-items:center;justify-content:space-between;gap:20px;color:var(--muted);font-size:12px}dialog{position:fixed;inset:0 0 0 auto;margin:0;width:min(560px,95vw);max-width:none;height:100dvh;max-height:none;border:0;border-left:1px solid var(--line);background:#fffefa;color:var(--ink);padding:32px;box-shadow:-15px 0 70px #141f3415;overflow:auto;overscroll-behavior:contain}dialog::backdrop{background:#18223126;backdrop-filter:blur(2px)}dialog>header{display:flex;justify-content:space-between;align-items:flex-start;gap:18px;border-bottom:1px solid var(--line);padding-bottom:22px;margin-bottom:22px}dialog h2{font-size:26px;line-height:1.5;overflow-wrap:anywhere}dialog h3{font-size:15px;margin:22px 0 9px}.icon-button{width:40px;height:40px;min-width:40px;display:flex;align-items:center;justify-content:center;border-radius:50%;background:var(--control-face);border:1px solid var(--control-border);box-shadow:var(--control-shadow)}.icon-button:hover{transform:translateY(-1px)}.icon-button:active,.segmented button:active{box-shadow:var(--control-pressed);transform:translateY(1px)}dialog p,dialog pre{overflow-wrap:anywhere;white-space:pre-wrap;font:14px/1.85 "Segoe UI","Microsoft JhengHei",sans-serif}dialog pre{background:#f8f7f2;padding:16px;border:1px solid var(--line);border-radius:10px}dialog .citation{font-size:12px;color:var(--muted);margin:20px 0;overflow-wrap:anywhere}.drawer-actions{display:flex;gap:10px;flex-wrap:wrap;margin:20px 0}.source-row{padding:14px 0;border-bottom:1px solid var(--line)}.source-row small{display:block;color:var(--muted);font-size:12px}.updated-note{font-size:12px;color:#175994;margin:12px 0}.work-list .work-row{padding:16px 0}.work-list .work-row strong{font-size:16px}.view{animation:arrive .22s ease-out}@keyframes arrive{from{opacity:.4;transform:translateY(4px)}to{opacity:1;transform:none}}
8
+ @media(min-width:1500px){.project{padding-top:45px}.journey{padding-top:12px;padding-bottom:28px}}
9
+ @media(max-width:1100px){.brandbar{gap:18px;padding:14px 25px}.brand{font-size:17px}nav{gap:22px}.tools{gap:12px}.overview-grid{grid-template-columns:1fr 1fr}.pending-columns{grid-template-columns:1fr}.results{border-left:0;border-top:1px solid var(--line);padding:15px 0 0;display:flex;gap:18px;flex-wrap:wrap}.results h3{width:100%;margin:0}.result-row{width:auto}.document-strip{flex-wrap:wrap}.strip-intro{flex-basis:100%}#document-strip{gap:18px}.strip-node small{max-width:100px}.document-map{grid-template-columns:repeat(3,1fr)}.route-node strong{font-size:18px}}
10
+ @media(max-width:760px){main{padding:0 20px}.brandbar{flex-wrap:wrap;gap:8px 14px;padding:12px 20px}.brand{font-size:16px}.brand img{width:38px;height:38px}.tools{margin-left:auto}#sync{font-size:11px}#language{font-size:12px;padding:7px;min-height:38px}nav{order:3;width:100%;justify-content:center;gap:40px}nav a{padding:12px 2px;font-size:14px}.project{padding:26px 2px 16px}h1{font-size:32px;letter-spacing:-.6px}#goal{font-size:16px}.journey{padding:8px 0 22px}.work-route{gap:8px;overflow-x:auto;justify-content:flex-start;padding:10px 6px;scroll-snap-type:x proximity}.route-node{min-width:150px;padding:0 7px;scroll-snap-align:center}.route-node .description{font-size:12px}.route-node strong{font-size:15px}.node-circle{width:70px;height:70px;border-width:1px;margin-bottom:15px}.node-circle svg{width:30px;height:30px}.route-node:before{top:35px;left:calc(50% + 35px);right:calc(-50% + 1px)}.focus-panel{padding:17px 18px;width:100%;min-width:0}.focus-panel h2{font-size:16px}.overview-grid{grid-template-columns:1fr;gap:15px}.panel{padding:20px}.pending-columns{grid-template-columns:1.2fr 1fr;gap:16px}.results{display:block;border-left:1px solid var(--line);border-top:0;padding:0 0 0 15px}.results h3{margin-bottom:8px}.document-strip{gap:14px}#document-strip{display:grid;grid-template-columns:1fr 1fr;width:100%;gap:17px}.strip-node small{max-width:120px}.document-strip>.text-link{margin-left:auto}.recent-row{grid-template-columns:12px 58px 1fr;gap:12px}.recent-row time{font-size:11px}.view-header{padding:28px 0 20px;flex-wrap:wrap}.view-header .segmented{margin-left:auto}.filterbar{margin:0;gap:10px}.filterbar label{flex:1}.filterbar input{min-width:0;width:100%;font-size:13px}.filterbar .search-label{flex-basis:65%}.segmented button{font-size:12px;padding:8px 11px}.scope-note{margin:12px 0}.timeline{padding:12px 0}.day{grid-template-columns:1fr;gap:10px}.day>h2{padding-top:4px;font-size:16px}.day-events{margin-left:8px;padding-left:22px}.event:before{left:-30px}.event{padding:15px}.event strong{font-size:15px}.event p{font-size:13px}#history-more{margin-left:0}.document-map{grid-template-columns:repeat(2,1fr);gap:15px;padding:20px 10px}.doc-node{padding:10px 6px}.doc-node strong{font-size:14px}.doc-node small{font-size:10px}.document-list button{grid-template-columns:1fr;padding:15px;gap:5px}footer{font-size:11px;align-items:flex-start}footer .quiet{font-size:11px;flex-shrink:0}dialog{padding:24px;width:min(540px,100vw)}dialog h2{font-size:23px}}
11
+ @media(max-width:420px){.tools{gap:8px}#sync{display:none}.brand{font-size:15px}.pending-columns{grid-template-columns:1fr}.results{border-left:0;border-top:1px solid var(--line);padding:15px 0 0}.result-row{padding:6px 0}}
12
+ @media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}}
13
+ /* Brand geometry supports navigation; motion is driven by state and user input. */
14
+ .brandbar{min-height:82px}.project{padding:28px 20px 12px}.project:after{content:"";position:absolute;right:26px;top:25px;width:95px;height:95px;background:var(--yellow);border-radius:50%;box-shadow:88px -35px 0 10px var(--red);opacity:.92;pointer-events:none}.project:before{content:"";position:absolute;right:72px;top:33px;width:145px;height:100px;border:1.5px solid #222;border-left-style:dashed;border-bottom-style:dashed;border-radius:0 32px 32px 22px;pointer-events:none}#goal{font-size:20px;margin:10px 0 6px;padding-right:170px}.journey{padding:0 40px 18px}.journey-label{font-size:11px;font-weight:500;color:var(--muted);text-align:left;margin:0 0 6px;letter-spacing:1px}.route-node{padding-bottom:5px}.node-circle{width:86px;height:86px;margin-bottom:12px}.route-node:before{top:43px}.route-node:after{content:none;position:absolute;width:11px;height:11px;background:var(--ink);border:3px solid var(--paper);border-radius:50%;right:-17px;top:38px}.route-node:last-child:after{display:none}.route-node .description{font-size:14px;max-width:290px}.route-node .relation{margin-top:3px;font-size:11px}.focus-panel{margin-top:12px;padding:14px 24px;position:relative;min-width:400px}.focus-panel:before{content:"";position:absolute;top:-7px;left:calc(50% - 6px);width:12px;height:12px;border-left:1px solid #dbe1ec;border-top:1px solid #dbe1ec;background:#fffefa;transform:rotate(45deg)}.focus-panel .pill{margin:5px 3px}.focus-actions{margin-top:4px}.focus-panel .primary{min-height:40px;padding:8px 24px}.panel{padding:18px 24px}.recent-row{padding:9px 0}.work-row{padding:8px 0}.result-row small{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}.document-strip{margin-top:16px;padding:18px 24px}.section-heading{margin-bottom:8px}.strip-intro{flex-basis:190px}.map-lines{position:absolute;inset:0;width:100%;height:100%;stroke-width:1.6;color:#9ba3af;overflow:visible;pointer-events:none}.map-lines>path{fill:none;stroke:currentColor;opacity:.35;transition:opacity .2s}.map-lines>path.lit{stroke:var(--blue);color:var(--blue);opacity:1;stroke-dasharray:7 5;animation:trace .7s ease-out}.document-map{min-height:450px;gap:46px 38px;padding:35px 40px}.doc-node{transition:opacity .2s,transform .2s,background-color .2s}.doc-node.subdued{opacity:.5}.doc-node .node-circle{box-shadow:var(--object-shadow),0 0 0 7px var(--paper)}.doc-node[aria-pressed=true]{background:linear-gradient(150deg,#fffefa,#eaf0fa);border-color:#c6d7ec;box-shadow:var(--control-shadow);transform:translateY(-3px)}.doc-node.related:not([aria-pressed=true]){background:transparent}.doc-node:hover{opacity:1;transform:translateY(-3px)}.doc-node.missing{opacity:.5}.map-detail{margin-top:18px;display:flex;align-items:center;justify-content:space-between;gap:24px}.map-detail h2{font-size:18px}.map-detail p{font-size:14px;color:var(--muted);margin-top:5px}.map-relations{display:flex;flex-direction:column;font-size:13px}.map-relations .text-link{padding:2px;min-height:30px}.filterbar select{border:1px solid var(--control-border);background:var(--control-face);box-shadow:var(--control-shadow);border-radius:10px;min-height:44px;padding:8px 12px;font-size:13px;max-width:200px}.timeline{position:relative;min-height:100px}.timeline[aria-busy=true]:before{content:"";height:3px;background:var(--blue);width:25%;position:absolute;top:0;left:20px;animation:read .9s ease-in-out infinite alternate;border-radius:4px}.route-node:hover .node-circle{box-shadow:var(--object-shadow),0 12px 24px #293a5214;transform:translateY(-4px)}.strip-node:hover .mini-node{transform:translateY(-3px);box-shadow:var(--object-shadow),0 8px 16px #293a5214}.mini-node{transition:transform .2s,box-shadow .2s}.event:hover{box-shadow:0 6px 18px #234c8410}.primary:active,.secondary:active{transform:translateY(1px) scale(.985);box-shadow:var(--control-pressed)}@keyframes trace{from{stroke-dashoffset:40;opacity:.2}to{stroke-dashoffset:0;opacity:1}}@keyframes read{from{transform:translateX(0)}to{transform:translateX(220%)}}
15
+ @media(max-width:1100px){.project:after,.project:before{opacity:.4;transform:scale(.75);transform-origin:top right}#goal{padding-right:170px}.map-detail{flex-wrap:wrap}.map-detail>div:first-child{flex:1 1 100%}.document-map{grid-template-columns:repeat(4,1fr);padding:30px 20px;gap:40px 10px}}
16
+ @media(max-width:760px){.brandbar{min-height:0}.project{padding:26px 2px 16px}.project:before,.project:after{display:none}#goal{padding-right:0;font-size:16px}.journey{padding:0 0 18px}.journey-label{margin-bottom:0}.node-circle{width:70px;height:70px}.route-node:before{top:35px}.route-node:after{top:30px;right:-14px}.focus-panel{min-width:0;padding:14px}.panel{padding:20px}.pending-columns{grid-template-columns:1fr}.results{border-left:0;border-top:1px solid var(--line);padding:15px 0 0}.document-map{grid-template-columns:repeat(2,1fr);gap:30px 12px;padding:22px 10px}.map-detail{gap:12px}.map-relations{width:100%}.doc-node strong{font-size:14px}.doc-node small{max-width:135px}.filterbar select{max-width:none;width:100%}.project h1{font-size:30px}.filterbar .segmented{flex-basis:100%}.timeline[aria-busy=true]:before{left:0}}
17
+ @media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important;transition:none!important;scroll-behavior:auto!important}.timeline[aria-busy=true]:before{width:100%;opacity:.35}}
18
+
19
+ .route-node .description{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;min-height:48px}.route-node .relation{position:static;width:auto;height:auto;overflow:visible;clip:auto}.doc-node.subdued{opacity:1}.doc-node.subdued .node-circle{filter:saturate(.55);opacity:.8}.doc-node[data-role=index] .node-circle{--object-light:#6c91e2;--object-mid:#2957b5;--object-dark:#173877;--object-glow:#244b942e}.work-route{padding-top:2px}.focus-panel{margin-top:8px}.project{overflow:hidden}
20
+ .recent-row strong,.recent-row small{display:-webkit-box;-webkit-line-clamp:1;-webkit-box-orient:vertical;overflow:hidden}@media(max-width:760px){.recent-row strong{-webkit-line-clamp:2}}
21
+ .project:before,.project:after{display:none;content:none}
22
+ .project{display:grid;grid-template-columns:minmax(0,1fr) minmax(280px,38%);grid-template-rows:1fr auto;gap:10px 32px;align-items:center;padding:20px 20px 24px;overflow:visible}
23
+ .project-copy{grid-column:1;grid-row:1;min-width:0;align-self:end}.project-meta{grid-column:1;grid-row:2;min-width:0;align-self:start}
24
+ .project-art{grid-column:2;grid-row:1 / span 2;width:100%;height:auto;max-height:280px;object-fit:contain;display:block;pointer-events:none}
25
+ @media(max-width:760px){.project{grid-template-columns:minmax(0,1fr) 115px;grid-template-rows:auto auto;gap:12px;padding:24px 2px 18px}.project-copy{align-self:center}.project-art{grid-row:1;width:115px}.project-meta{grid-column:1 / -1;grid-row:2}.project h1{font-size:28px}.project .eyebrow{font-size:10px;letter-spacing:.7px}}
26
+
27
+ .journey-label{font-size:13px;margin:0 0 4px;text-align:center}.journey{padding-top:0}.focus-panel{margin-top:4px}
28
+
29
+ .recorded-current{display:block;text-align:left;max-width:min(970px,100%);line-height:1.5;overflow-wrap:anywhere;padding-top:0}.legacy-label{font-size:13px;margin-top:12px}#work-scope{margin:0 0 14px}.route-node .relation{font-weight:600}
30
+
31
+ #pending-list>.text-link{display:block;margin-top:10px}
@@ -0,0 +1,59 @@
1
+ # 快捷入口 / Kit shortcuts
2
+
3
+ 啟用後,在專案的 AI 對話輸入短口令即可。Claude Code、Gemini CLI、Antigravity CLI 用 `/handoff-kit-help`;Codex 用 `$handoff-kit-help`,或輸入 `/skills` 選擇 `handoff-kit-help`。Codex 並不提供相同的直接 `/handoff-kit-*` 自訂命令。
4
+
5
+ | 用途 | Claude / Gemini / Antigravity | Codex |
6
+ |---|---|---|
7
+ | 開工、接收交接 | `/handoff-kit-start` | `$handoff-kit-start` |
8
+ | 收工、保存及檢查交接 | `/handoff-kit-close` | `$handoff-kit-close` |
9
+ | 開啟自動更新的進度頁 | `/handoff-kit-progress` | `$handoff-kit-progress` |
10
+ | 檢查文件是否接上治理 | `/handoff-kit-align` | `$handoff-kit-align` |
11
+ | 新手引導 | `/handoff-kit-onboard` | `$handoff-kit-onboard` |
12
+ | 保存日後要遵守的工作規則 | `/handoff-kit-remember` | `$handoff-kit-remember` |
13
+ | 檢查 Kit 安裝狀態 | `/handoff-kit-check` | `$handoff-kit-check` |
14
+ | 顯示這份功能選單 | `/handoff-kit-help` | `$handoff-kit-help` |
15
+
16
+ 可在口令後補充目標,例如 `/handoff-kit-align docs/plan.md`、`/handoff-kit-remember 回覆請用繁體中文`,或 `/handoff-kit-start 繼續完成目前目標`。單獨開工只接收狀態;未指定文件的對齊先列候選,不自行整理整個專案。收工會執行原有完整流程,但不新增提交或發佈權限。原有「開工」「收工」等自然語句仍可使用。
17
+
18
+ ## 每個專案啟用一次
19
+
20
+ 對 AI 說:「在這個專案啟用 Kit 常用快捷入口。」正常 AI 安裝教學亦包含這一步。AI 應先完成 Kit 安裝/升級及其驗收,再執行:
21
+
22
+ ```text
23
+ npx --yes @adamchanadam/agent-handoff-kit@latest commands --root . --dry-run
24
+ npx --yes @adamchanadam/agent-handoff-kit@latest commands --root . --yes
25
+ ```
26
+
27
+ 預設建立全部平台入口;`--agent claude|gemini|codex|antigravity` 可只建立指定平台。Codex 與 Antigravity 共用一份 `.agents/skills`。程序只建立缺少的入口;相同內容保持不動;任何同名差異會在寫入前停止,不覆寫用戶設定。中斷時保留已完成入口,重新預覽再補齊。此程序不代替 Kit 健康檢查,亦不修改全機設定或官方規則正文。
28
+
29
+ 快捷入口只可安裝在專案內。預覽及啟用都會拒絕使用者主目錄、磁碟根目錄,以及已知的 AI 全域設定位置(包括環境變數指定的位置);即使目錄已有 Kit 檔案也不例外。若任何入口的輸出位置會落入全域範圍,整批停止,不建立檔案或目錄。主目錄下的一般專案及 Codex 管理的 `worktrees` 內專案仍可使用;全域設定資料夾本身不能當作專案。
30
+
31
+ 如入口未出現,重新開啟該專案的 AI 對話;Gemini CLI 亦可用 `/commands reload`。舊版 CLI 若顯示不認識 `commands`,代表執行的套件未包含此功能。未發佈開發版必須使用已選定的本機套件,不能把 npm 舊版當成新功能驗收。
32
+
33
+ 入口由 `bin/commands.mjs` 統一產生。Claude 使用 `.claude/skills/handoff-kit-*/SKILL.md`,Gemini 使用 `.gemini/commands/handoff-kit-*.toml`,Codex/Antigravity 使用 `.agents/skills/handoff-kit-*/SKILL.md`。規則仍由專案 `AGENTS.md`、`dev/RULE_PACKS.md` 及其指向的文件負責。這些入口不會因被 AI 自動發現便授權執行。
34
+
35
+ ## 進度頁與使用成本
36
+
37
+ `handoff-kit-progress` 自動開啟頁面,同一專案重複使用會重用相符服務。全部頁面斷線後保留 8 小時,閒置時暫停讀檔;其後服務才自動停止,下次再用口令會重新啟動。不同專案各自識別;頁面正在顯示哪個專案,以頁面專案名稱為準。詳見[進度頁說明](progress.md)。
38
+
39
+ 口令本身由 AI 處理,會使用少量對話內容;進度頁之後由本機程式讀取既有紀錄並自動更新,不需 AI 再寫報告、重做 HTML 或逐步呼叫更新。使用既有 Node.js 18+ 與瀏覽器,不需額外安裝 Python 或服務平台。`npx` 取得工具可能需要網絡;頁面服務本身只在本機運行。
40
+
41
+ ## English
42
+
43
+ Use `/handoff-kit-*` in Claude Code, Gemini CLI and Antigravity CLI. In Codex, use `$handoff-kit-*` or select the skill through `/skills`; direct custom `/handoff-kit-*` commands are not equivalent Codex syntax.
44
+
45
+ The eight entries are **handoff-kit-start** (resume), **handoff-kit-close** (save and verify the full handoff), **handoff-kit-progress** (open the live overview), **handoff-kit-align** (check document governance links), **handoff-kit-onboard** (guided introduction), **handoff-kit-remember** (save an explicitly requested future working rule), **handoff-kit-check** (check the Kit installation), and **handoff-kit-help** (menu).
46
+
47
+ Add context after an entry, such as `/handoff-kit-align docs/plan.md` or `/handoff-kit-start continue the current objective`. Bare start only recovers state. Alignment without a target lists candidates before any edits. Closeout follows the existing complete workflow without granting Git or publishing permission. Natural-language requests still work.
48
+
49
+ Ask the AI to “Enable Kit shortcuts in this project.” After installing/upgrading Kit and verifying that operation, run the two commands above: preview, then enable with `--yes`. This setup step is included in the AI installation guide. The default enables all platforms; `--agent claude|gemini|codex|antigravity` selects one. Codex and Antigravity share `.agents/skills`. Missing files are created, identical files kept, and any different same-name file stops the preflight with zero writes. After interruption, completed files remain and a new preview shows what is left. This setup does not replace health checks, change global settings or rewrite official rules.
50
+
51
+ Shortcuts are project-local only. Preview and enable both refuse user home directories, filesystem roots and known shared AI configuration locations, including environment-configured locations, even if Kit files exist there. If any generated entry would land in global scope, the whole operation stops without creating files or directories. Ordinary projects beneath home and projects inside Codex-managed `worktrees` remain supported; the global configuration folder itself cannot serve as a project.
52
+
53
+ Reopen the project's AI session if entries do not appear; Gemini also supports `/commands reload`. An unrecognized `commands` option means the running package lacks this feature. Use the selected local package for unreleased development; testing npm's older release cannot verify new features.
54
+
55
+ `bin/commands.mjs` owns the shared content and generates Claude `.claude/skills/handoff-kit-*/SKILL.md`, Gemini `.gemini/commands/handoff-kit-*.toml`, and Codex/Antigravity `.agents/skills/handoff-kit-*/SKILL.md`. Project `AGENTS.md`, `dev/RULE_PACKS.md` and their routed owners still define procedures. Automatic skill discovery does not authorize action.
56
+
57
+ `handoff-kit-progress` opens the view and reuses a matching service for the same project. The service stays available for eight hours after all pages disconnect, without idle file polling; invoke the entry again to reuse it or restart it after expiry. Projects have separate identities; check the displayed project name. See [the progress guide](progress.md). An AI invocation uses some conversation tokens; subsequent page updates read existing records locally, without more AI reports, redesigned HTML or per-step update calls. It uses the existing Node.js 18+ environment and a browser; no Python or hosting platform is required. `npx` tool acquisition may need network access, while the view itself runs locally.
58
+
59
+ Platform references: [Claude skills](https://code.claude.com/docs/en/skills), [Gemini custom commands](https://geminicli.com/docs/cli/custom-commands/), [Antigravity CLI skills](https://antigravity.google/docs/skills?app=cli), [Codex skills](https://learn.chatgpt.com/docs/build-skills).
@@ -0,0 +1,67 @@
1
+ # 專案總覽 / Project dashboard
2
+
3
+ 對 AI 說「開啟專案進度頁」,或啟用[快捷入口](commands.md)後使用 `/handoff-kit-progress`。Codex 使用 `$handoff-kit-progress` 或從 `/skills` 選取。這是每個已安裝 Kit 的專案共用的固定頁面,無須重新設計 HTML。
4
+
5
+ ## 三個入口
6
+
7
+ - **總覽**:專案名稱、交接記錄的目前工作、各項工作狀態、待完成/等待/待驗收事項、成果及最近變更。「正在查看」只表示你選中的工作,不改變交接狀態。工作排列不表示先後順序,子項完成也不表示整項完成。
8
+ - **歷程**:近 7 日、近 30 日、自選日期、關鍵字及工作線篩選。日期標示年份,按封存索引逐批查閱歷史;日期不隱藏目前未完事項。
9
+ - **文件導覽**:核心關係圖顯示八種 Kit 文件角色;清單另列已登記的專案文件,並非專案所有檔案。點選節點突出相關文件與方向,查看用途、原文及來源,也可切換清單。沒有明確記錄的關係不靠 AI 猜補。
10
+
11
+ 保存紀錄後自動更新,不需要刷新。點選主線、日期及文件時有短動畫;新資料短暫標示改變處,支援減少動畫設定。動畫不代表 AI 正在思考、已驗收或已完整接收交接。
12
+
13
+ 品牌旁的版本讀取專案 `PROJECT_INDEX.md` 的 `Stack`,沿用 Kit 共用讀取方法;「資料依據」另列啟動頁面工具的套件版本。兩者不同會提示,缺失或格式無效則顯示「版本未核實」,不以工具版本代替專案版本。讀取不查網絡、不呼叫 AI,也不升級專案。
14
+
15
+ ## 少量維護,不另寫報告
16
+
17
+ AI 在正常、已授權的保存時,維護 Index 的專案名稱/目標與 Handoff 的精簡工作表;只改有變的事項,不記錄每一步終端操作。兩份模板定義欄位格式,詳細證據保留在原有位置。尚無工作表項目的專案,直接顯示已有「下一步」及「風險與阻礙」,標明尚未分類,不猜測其狀態。首頁只顯示有界摘要;其餘項目數量與查看完整工作/交接原文的入口一併列出。缺失資訊保持未記錄,不捏造階段、百分比或完成數字。「交接保存」專指交接檔案保存時間,不代表整個專案最後有變更的時間。
18
+
19
+ 介面支援繁中/英文。來源可選 `Name zh-Hant`、`Goal zh-Hant`、`Title zh-Hant`、`Summary zh-Hant`,缺少則保留原文;日誌也可在正常保存時加入簡短中文標題/摘要,不必回寫歷史翻譯。讀取、篩選、動畫及同步由程式處理,**不呼叫 AI、不要求第二份進度 JSON 或重複報告**。
20
+
21
+ ## 啟動及環境
22
+
23
+ 沿用 Kit 的 Node.js 與瀏覽器,不需要資料庫、Python、建置工具或 API key。
24
+
25
+ ```text
26
+ npx --yes @adamchanadam/agent-handoff-kit@latest progress --background --root <project-root>
27
+ ```
28
+
29
+ `npx` 可能下載 CLI 至快取;未發佈版本使用選定的本機套件。`progress` 自身不查網絡版本、不安裝/升級、不寫回專案。`--background` 啟動或重用同專案、版本與頁面內容的背景服務,開啟瀏覽器後返回。`--no-open` 只給網址;`--port <0-65535>` 指定埠。不停止不相符的服務。
30
+
31
+ 只綁定 `127.0.0.1`,拒絕跨網站請求及寫入。有頁面連線時持續運作;全部頁面斷線後保留 8 小時,未曾開啟亦保留 8 小時。無連線時停止輪詢紀錄,再次開啟立即讀取最新內容並延長保留時間。超時、電腦重啟或服務結束後,使用既有快捷入口便會重新啟動;舊網址不能自行啟動已停止的本機程式。前景模式可按 Ctrl+C 立即停止。
32
+
33
+ ## 來源及邊界
34
+
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 |
42
+
43
+ 自訂文件關係在 Index 的 `## Document Relations` 使用 `From | To | Relation`:已登記的相對路徑及 `references`、`routes`、`mirrors`、`checks`。只表達關係,不授權同步。只讀專案內登記文件,拒絕越界、隱藏設定、機密名稱及遷移內部檔;原文以純文字顯示,不執行 HTML 等內容。已知憑證模式會遮蔽,不代替來源的機密管理。
44
+
45
+ 首頁與歷程共用同一日誌欄位讀取方式,支援逐行欄位、項目符號、粗體欄位名及縮排續行;中文標題與摘要在兩處一致使用。識別欄位不會被當成摘要。歷程只涵蓋索引登記批次。缺索引、格式錯誤、缺檔、未封口/過大條目、同 Event ID 內容衝突及超限都明示覆蓋不足。日誌可選 `Event ID` 用於搬移去重、`Work` 對應工作 ID;無 Event ID 則用原標題與內容辨識;原有 ID 是 agent/session 識別,可重複。單則上限 64 KiB;每查詢最多記住 10,000 事件,超過請收窄日期。最多 32 個分頁查詢,十五分鐘到期;來源改變即拒絕舊分頁。日期排序只涵蓋已載入結果。
46
+
47
+ 有頁面連線時每半秒檢查狀態,無變動不重讀內容。斷線時保留已顯示資料,以 1、2、4、8、16、30 秒間隔重試,其後每 30 秒一次;回到頁面會提早重連,也可按「立即重連」。服務重啟後會更新歷程及詳情,保留日期、工作選擇及介面語言。失敗提示附可複製的重開口令。首頁不掃歷史;最近查過的 128 份封存檔會監看。文件地圖只檢查登記檔案的存在及時間。讀前/後核對身份與穩定性;無效來源保留上次有效畫面並告警,升級鎖存在即暫停。歷程自動更新每輪最多五個有界請求,更多可繼續查閱。
48
+
49
+ 一般 Markdown 不是交易格式:結構完整的中間狀態不能永遠與最終意圖區分。來源完成聲稱不等於獨立驗收;總覽不代替 AI 全文接收交接包。
50
+
51
+ ## English
52
+
53
+ The brand badge reads the project's Kit version from `PROJECT_INDEX.md` Stack through the shared Kit reader. Sources also shows the running dashboard package version. Different versions are indicated; missing or invalid project metadata displays “Version unverified”, never the tool version as a substitute. This reads locally without model calls, network version checks or project upgrades.
54
+
55
+ Open the dashboard through your AI or the [command entry](commands.md). The fixed, reusable view has Overview, History and Documents. Overview shows project identity, current work recorded in handoff, declared work and states, outstanding work and references. “Viewing” only identifies the reader's selection; it does not change recorded work. History includes years in date headings and filters saved events by date, keyword and work ID, reading indexed archives in batches. The core map shows eight Kit document roles; the list also includes registered project files, not every project file. It highlights declared relationships and opens source text. Workstream order is not a sequence; child completion never completes its parent.
56
+
57
+ At normal authorized saves, maintain only changed meaningful rows in Handoff `Work Items` and stable identity in Index `Project`; their templates own the fields. No extra report, per-terminal-step record or progress JSON is required. Without work rows, existing Next Priorities and Risks / Blockers appear directly as unclassified source text, with no inferred status. Home shows bounded excerpts and a remaining count with access to all work or the handoff source. “Handoff saved” is that file's save time, not the last change across the project. Optional `Name zh-Hant`, `Goal zh-Hant`, `Title zh-Hant` and `Summary zh-Hant` provide Chinese counterparts; otherwise source language is preserved. Logs may carry the Chinese title/summary too, without rewriting history. Missing fields stay unrecorded. Viewing, filtering, motion and live updates make no model calls or source writes.
58
+
59
+ Run the command above. Background mode reuses a matching project/version/build service; `--no-open` returns its URL, `--port` selects a port. `npx` may fetch the package; progress itself does not check network versions, install or upgrade. It needs existing Node.js and a browser, not a database, Python, build tools or API keys. It binds only to 127.0.0.1, rejects foreign origins and writes, and remains available for eight hours without connected pages, including before the first connection. File polling stops with no clients and resumes with a fresh read on return. Reopening renews the idle window. After expiry, process exit or a computer restart, use the existing command entry to start it again; a cold browser URL cannot launch a stopped local process. Ctrl+C stops foreground mode; unrelated services are not terminated.
60
+
61
+ Home and History share one event reader for plain fields, list fields, bold labels and indented continuations, including Chinese titles and summaries. Identity metadata is never used as the summary.
62
+
63
+ Limits: Handoff 1 MiB/128 work items; Index 512 KiB; 160 registered documents with 1 MiB text previews; home log prefix 64 KiB/ten complete entries, displaying three. Each history request reads at most 256 KiB from four log files and returns twenty events. Archive selection uses the 512 KiB master index. Each entry is limited to 64 KiB; queries track at most 10,000 identities, then require a narrower date range. Up to 32 cursors expire after fifteen minutes and reject source changes. Global date sorting covers loaded results only. Missing/malformed manifests, missing files, incomplete/oversized entries, Event ID conflicts and capacity limits disclose incomplete coverage. Optional log `Event ID` supports move deduplication; `Work` links a work item; otherwise original title/body identify entries; existing `ID` denotes an agent/session and may repeat.
64
+
65
+ Only registered project-relative documents are available. Hidden/secret-related paths, migration internals and real paths outside the project are rejected. Text is escaped; HTML and other executable content are never run. Known credential patterns are redacted as a secondary defense. Optional Index `Document Relations` use `From | To | Relation`, registered relative paths and `references`, `routes`, `mirrors` or `checks`; links grant no write permission.
66
+
67
+ While pages are connected, metadata is checked every half second; unchanged content is not reread. Disconnection retains the last displayed data and retries after 1, 2, 4, 8, 16 and 30 seconds, then every 30 seconds. Returning to the page or Reconnect now retries sooner. Recovery refreshes history and details, including after server restarts, while preserving filters, selection and UI language. The failure notice includes a copyable reopen prompt. Home does not scan archives; the 128 most recently queried archives are watched. Registered document existence/time is checked. Reads verify identity and stability; invalid input retains the last valid state with warnings, and upgrade locks pause reads. History auto-update makes up to five bounded requests per round; further reading is explicit. Brief transitions and change highlights respect reduced motion, never imply agent reasoning or acceptance. Structurally complete intermediate Markdown can be indistinguishable from intended final state. The dashboard proves neither independent acceptance nor full AI handoff reception.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adamchanadam/agent-handoff-kit",
3
- "version": "0.3.67",
3
+ "version": "0.4.0",
4
4
  "description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -11,6 +11,8 @@
11
11
  "runtime-core/",
12
12
  "packs/",
13
13
  "README.md",
14
+ "docs/progress.md",
15
+ "docs/commands.md",
14
16
  "LICENSE"
15
17
  ],
16
18
  "engines": {
package/packs/closeout.md CHANGED
@@ -1,29 +1,30 @@
1
- # Closeout Pack
2
-
3
- ## Scope
4
-
5
- This pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.
6
-
7
- ## Required Reads
8
-
9
- Read the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.
10
-
11
- ## Write Contract
12
-
13
- Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.
14
-
15
- - Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.
16
- - Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.
17
- - File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.
18
- - Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.
19
- - Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.
20
- - Reusable procedures belong in the relevant pack, registered reference, or QA check.
21
- - `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.
22
-
1
+ # Closeout Pack
2
+
3
+ ## Scope
4
+
5
+ This pack is the single detailed contract for full Agent Handoff Kit closeout. Load it only for clear end-of-session or handoff intent. It does not authorize Git, release, publish, deployment, deletion, permission, or cleanup actions.
6
+
7
+ ## Required Reads
8
+
9
+ Read the current `dev/SESSION_HANDOFF.md`, `dev/SESSION_LOG.md`, `dev/PROJECT_INDEX.md`, and `dev/DOC_SYNC_REGISTRY.md`. Read `dev/PROJECT_DECISIONS.md`, integration rules, or another pack only when its closeout trigger or the session's actual work requires it.
10
+
11
+ ## Write Contract
12
+
13
+ Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-entry:start/end`, and managed-core BEGIN/END. Human headings may be localized; markers may not be removed or translated.
14
+
15
+ - Current state, objective, recommended next action, active risk, blocker, required reading, workspace identity, and sync status belong in `dev/SESSION_HANDOFF.md`.
16
+ - When saving meaningful work changes, maintain the handoff's concise `Work Items` table using its declared fields, and keep project-wide name/goal in `PROJECT_INDEX` `Project`. Add the table/section to older projects only at an authorized state save when useful. Reconcile changed statuses against the evidence; do not duplicate full reports, rewrite old history, or create per-terminal-step records for the dashboard. Read-only dashboard viewing never triggers these writes.
17
+ - Chronological work and evidence disposition belong in `dev/SESSION_LOG.md`.
18
+ - File / command / source / capability maps belong in `dev/PROJECT_INDEX.md`.
19
+ - Recurring sync obligations belong in `dev/DOC_SYNC_REGISTRY.md`.
20
+ - Long-term evolution, architectural rationale, and accumulated learning belong in `dev/PROJECT_DECISIONS.md` when triggered.
21
+ - Reusable procedures belong in the relevant pack, registered reference, or QA check.
22
+ - `START_NEXT_SESSION_PROMPT.txt` is generated only from the handoff opening-message block.
23
+
23
24
  Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records whether the mirror was verified no-op or regenerated and verified, plus an evidence reference when useful.
24
-
25
- ## Full Closeout
26
-
25
+
26
+ ## Full Closeout
27
+
27
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.
28
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. Change them only when the closeout directly proves their current meaning is false or the section itself is the named target of the reconciliation; otherwise preserve cold-zone bytes where practical and update only hot current-state fields.
@@ -31,56 +32,60 @@ Handoff cold zones are historical / evidence sections, old validation records, c
31
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.
32
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.
33
34
  The bundled doctor is a mechanical floor for required lifecycle markers and readable sections only. `agent-handoff-kit closeout-status` checks explicit lifecycle declarations and same-scope textual contradictions; it does not prove natural-language semantic consistency. When it blocks, inspect its first `Resolved [...]` / `Carry-forward [...]` pair against the actual evidence: completion of one action does not complete another acceptance scope, and a preserved limitation is not a completion claim. Repair a real contradiction in its owning handoff section. If truthful, distinct scopes are misclassified, preserve the facts, report the checker defect and stop wording retries; do not add a reclassification prefix, invent a trigger, erase a limitation or broaden governance just to pass. A blocked result remains blocked until verified repair. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to `closeout-status`.
34
- 3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
35
+ 3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
35
36
  4. Complete the persistence-routing, handoff-sufficiency, `Closeout outcome`, and `Project-required persistence` fields. Apply the packet-only reconstruction check below before answering handoff sufficiency. The next agent must be able to continue from `AGENTS.md`, the handoff, the project index when needed, and routed packs without searching old log history. `complete` is allowed only when all required writes/read-backs and any project-required persistence succeeded; use `not_required` only when that persistence is genuinely not required. If a required commit, push, release record, or equivalent persistence is blocked or not authorized, set both fields to `blocked` with the exact boundary.
36
- 5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.
37
- 6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
37
+ 5. Add one concise log entry for work actually performed. Record evidence disposition and the prompt-mirror verification result; omit the full opening message by design.
38
+ 6. Update the project index and sync registry only when their owned maps or obligations changed. Record each applicable sync target as `confirmed`, `unverified`, `pending`, `blocked`, or `not_applicable`.
38
39
  7. Run `agent-handoff-kit workspace-health --root <project root>` or equivalent read-only Git probes, then record only the last-verified root, Git root, branch, commit, worktrees / parallel workspaces, uncommitted changes, and unresolved drift. Do not clean or change them without separate authorization. Do not treat `dev/PROJECT_INDEX.md` or old handoff prose as the live worktree truth.
39
- 8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.
40
- 9. Run the short maintenance trigger check below and record its result in the log.
41
- 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`.
40
+ 8. If the session used external tools or helper processes, apply the integrations and safety ownership rules. Close only task-owned resources. Retain shared, user-owned, other-agent-owned, system, or ambiguous resources unless separately authorized; state visibility limits.
41
+ 9. Run the short maintenance trigger check below and record its result in the log.
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`.
42
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.
43
- 12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
44
+ 12. Run available project-specific closeout checks. Do not run a separate bundled `doctor`: the `closeout-status` command below performs the one required fresh doctor read-back. Do not treat an external update-check failure as local closeout failure. Fix state or mirror failures before claiming handoff ready.
44
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: copy its status faithfully. A nonzero result means the closeout is blocked; do not replace it with a success summary.
45
-
46
+
46
47
  ## Packet-Only Reconstruction Check
47
48
 
48
- Before closing out, reconstruct the next task using only the handoff, without chat memory, old logs or opening linked sources. Identify the parent outcome and consumer, the current step's relation to it, the exact resume point, remaining step/parent acceptance, and required sources with revision/freshness, reading scope/depth and unread gaps. Cite the owning handoff sections in `Reconstruction evidence`; do not create a second task summary. Then compare that reconstruction against the user's actual request and the relevant sources read this session. Missing, contradictory or assumed critical facts must be repaired in their existing handoff sections or explicitly recorded as blockers with the next clarification/read needed. Do not answer yes on labels or a successful CLI card alone: the CLI checks the recorded answer and evidence presence, not the truth of this reconstruction.
49
+ Before closing out, reconstruct the next task using only the handoff, without chat memory, old logs or opening linked sources. Identify the parent outcome and consumer, the current step's relation to it, the exact resume point, remaining step/parent acceptance, and required sources with revision/freshness, reading scope/depth and unread gaps. Also recover decision-changing user corrections, reasons for accepted/rejected approaches, reusable artifacts with their evidence limits, every remaining consequential obligation and its downstream use, and permission/stop boundaries. Cite the owning handoff sections in `Reconstruction evidence`; do not create a second task summary. Then compare that reconstruction against the user's actual request and the relevant sources read this session. Missing, contradictory or assumed critical facts must be repaired in their existing handoff sections or explicitly recorded as blockers with the next clarification/read needed. Do not answer yes on labels or a successful CLI card alone: the CLI checks the recorded answer and evidence presence, not the truth of this reconstruction.
50
+
51
+ Check whether a reader could repeat a rejected attempt, redo accepted work, omit an obligation, act on obsolete instructions, or choose a plausible but wrong next action while still agreeing with the packet's headline. If so, preserve the missing decision-changing fact in its existing owning section, not merely in a linked historical log. Keep the packet sufficient and proportionate; do not paste the whole chat or silently discard important facts to fit an output limit. Transport truncation is handled by the core reception checkpoint, not by weakening the task.
52
+
53
+ Closeout verifies this session's saved packet. It cannot certify that a future reader received or understood it. Do not describe `closeout-status: complete` as successful future-session reception; the next agent must pass the core Handoff reception and recovery checkpoint independently.
49
54
 
50
55
  Keep one `Answer:` line (`yes`, `no` or `unknown`, with optional explanation) and one `Reconstruction evidence:` line inside the marked sufficiency section. An affirmative answer requires concrete section references; keep `next-ai-can-continue` consistent. For an older handoff, add missing facts to its existing sections at this authorized closeout; upgrade must preserve user state and must not invent reconstruction evidence. Missing or negative answers, placeholder evidence and duplicate fields block `closeout-status` without changing project files.
51
56
 
52
57
  Use only the depth needed to resume safely. A standalone task needs no invented parent tree; state that it is the whole task. Finishing a child does not complete its parent or authorize another step. Keep the next consequential action bounded by its input, output and acceptance; do not enumerate every future microstep. Keep decision-relevant terms and identifiers faithful; when a translation could change their meaning, retain the original term alongside it. Reading coverage is previous-session evidence, never permission for the next agent to skip required fresh source reads. Honest blocked-work handoff can be sufficient when the missing fact, impact and safe next action are explicit.
53
58
 
54
59
  ## Maintenance Trigger Check
55
-
56
- Every full closeout runs this short check; full maintenance runs only when triggered.
57
-
58
- - SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.
59
- - PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.
60
- - Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.
61
-
62
- If no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.
63
-
64
- ## Opening Message And Card
65
-
66
- 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.
67
-
68
- Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. It renders the verified version when available and otherwise `version unverified`; never print the literal placeholder `v<version>`, hand-compose a substitute card, or use `handoff saved` unless the command reports `status: complete`.
69
-
70
- ```text
71
- /\_/\ Agent Handoff Kit v<version>
72
- ( -.- ) handoff saved
73
- > ^ <
74
-
75
- status: complete
76
- ✅ Done: <completed summary>
77
- 🔎 QC: <validation summary>
78
- 📌 Handoff: opening message ready
79
- ⚠️ Boundary: <important boundary or none>
80
- ```
81
-
82
- 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. Do not hand-compose a third stateful prompt in the final response.
83
-
84
- ## Stop Conditions
85
-
86
- Do not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, `closeout-status` is nonzero, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.
60
+
61
+ Every full closeout runs this short check; full maintenance runs only when triggered.
62
+
63
+ - SESSION_LOG: trigger when the main log reaches at least 11 entries, exceeds 1500 lines, or the 10-closeout backstop is due. Keep recent safety-buffer entries; collapse only content already absorbed by an authoritative home. Archive older raw entries to `dev/SESSION_LOG_archive/archive_<batch>_<low_date>_to_<high_date>.md` and maintain `INDEX.md`. Port unique narrative before collapsing it.
64
+ - PROJECT_DECISIONS: trigger when a decisions-like handoff section has at least 30 entries; retain the newest 8–22 in the hot tier and move older decisions into the decisions archive. Also write substantive task evolution, a multi-option architectural choice with rationale, or a cross-session learning when observed.
65
+ - Backstop: every 10 closeouts, run the full long-term maintenance pass even when no semantic trigger is obvious. If the count cannot be determined confidently at the boundary, treat the backstop as due.
66
+
67
+ If no trigger applies, record one no-op reason. Handoff carries continuity; log and project decisions carry trace and long-term narrative.
68
+
69
+ ## Opening Message And Card
70
+
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
+
73
+ Use `agent-handoff-kit closeout-status --root <project root>` after the required read-backs. It renders the verified version when available and otherwise `version unverified`; never print the literal placeholder `v<version>`, hand-compose a substitute card, or use `handoff saved` unless the command reports `status: complete`.
74
+
75
+ ```text
76
+ /\_/\ Agent Handoff Kit v<version>
77
+ ( -.- ) handoff saved
78
+ > ^ <
79
+
80
+ status: complete
81
+ ✅ Done: <completed summary>
82
+ 🔎 QC: <validation summary>
83
+ 📌 Handoff: opening message ready
84
+ ⚠️ Boundary: <important boundary or none>
85
+ ```
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. Do not hand-compose a third stateful prompt in the final response.
88
+
89
+ ## Stop Conditions
90
+
91
+ Do not claim closeout complete when any required write or read-back failed, lifecycle state conflicts remain, the mirror is stale or duplicated, the root is uncertain, mandatory sync is unclassified, `closeout-status` is nonzero, or required Git persistence was explicitly part of the project's closeout contract but did not succeed. State the exact blocker and leave the project in an honest resumable state.