@adamchanadam/agent-handoff-kit 0.3.49 → 0.3.50
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 +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +311 -30
- package/bin/migration-baselines/official-origin-catalog.json +181 -1
- package/package.json +1 -1
- package/packs/closeout.md +5 -3
- package/packs/integrations.md +7 -4
- package/packs/knowledge.md +1 -1
- package/runtime-core/AGENTS.core.md +2 -2
package/README.en.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[繁體中文](README.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
|
|
4
4
|
|
|
5
|
-
Source package version: `v0.3.
|
|
5
|
+
Source package version: `v0.3.50`. npm `@latest` and GitHub Release are verified by post-publish readback.
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit overview animation" width="720">
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
English: [README.en.md](README.en.md) · [Getting started](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.en.html) · [Practical guide](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.en.html) · [AI install page](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.en.html)
|
|
4
4
|
|
|
5
|
-
原始碼套件版本:`v0.3.
|
|
5
|
+
原始碼套件版本:`v0.3.50`。npm `@latest` 與 GitHub Release 以發佈後讀回為準。
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
|
|
@@ -656,6 +656,7 @@ async function runFinalizeCloseout(root, version) {
|
|
|
656
656
|
const doctorStatus = await runDoctor(root, version, {
|
|
657
657
|
silentCard: true,
|
|
658
658
|
context: "post-closeout-finalize-health",
|
|
659
|
+
skipVersionRegistryLookup: true,
|
|
659
660
|
expectedCurrentStateWitness: transaction.journal.currentStateWitness
|
|
660
661
|
});
|
|
661
662
|
if (doctorStatus !== "passed") throw new Error("post-closeout finalize doctor failed; finalize journal retained for inspection");
|
|
@@ -762,8 +763,16 @@ async function runInstall(command, root, options, version) {
|
|
|
762
763
|
// The only no-op authority here is the already committed whole current-state
|
|
763
764
|
// witness, freshly revalidated against every accepted byte, reader, route,
|
|
764
765
|
// priority, and effect by both loaders below.
|
|
766
|
+
let sourceConservationRebind = false;
|
|
765
767
|
if (command === "upgrade") {
|
|
766
|
-
|
|
768
|
+
let acceptedCurrentState = null;
|
|
769
|
+
try {
|
|
770
|
+
acceptedCurrentState = await loadCommittedCurrentStateWitness(root);
|
|
771
|
+
} catch (error) {
|
|
772
|
+
if (!String(error?.message ?? error).includes("doctor refuses an unbound success state")) throw error;
|
|
773
|
+
await assertUnboundCurrentStateMayAttemptUpgradeRebind(root, error);
|
|
774
|
+
sourceConservationRebind = true;
|
|
775
|
+
}
|
|
767
776
|
if (acceptedCurrentState?.transaction?.command === "upgrade"
|
|
768
777
|
&& acceptedCurrentState.transaction.attemptedVersion === version) {
|
|
769
778
|
const noOpHealth = await assessUpgradeNoopHealth(root, version);
|
|
@@ -890,8 +899,8 @@ async function runInstall(command, root, options, version) {
|
|
|
890
899
|
}
|
|
891
900
|
}
|
|
892
901
|
|
|
893
|
-
await executeInstallTransaction(command, root, mode, plan, version, candidateOutputs);
|
|
894
|
-
}
|
|
902
|
+
await executeInstallTransaction(command, root, mode, plan, version, candidateOutputs, { sourceConservationRebind });
|
|
903
|
+
}
|
|
895
904
|
|
|
896
905
|
async function readInstalledTemplateVersion(root) {
|
|
897
906
|
try {
|
|
@@ -903,7 +912,7 @@ async function readInstalledTemplateVersion(root) {
|
|
|
903
912
|
}
|
|
904
913
|
}
|
|
905
914
|
|
|
906
|
-
async function executeInstallTransaction(command, root, mode, plan, version, candidateOutputs = null) {
|
|
915
|
+
async function executeInstallTransaction(command, root, mode, plan, version, candidateOutputs = null, options = {}) {
|
|
907
916
|
const outputs = candidateOutputs ?? await buildTransactionOutputs(command, root, plan, version);
|
|
908
917
|
if (outputs.length === 0) {
|
|
909
918
|
const health = await assessUpgradeNoopHealth(root, version);
|
|
@@ -934,7 +943,16 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
934
943
|
const archiveMigrations = command === "upgrade"
|
|
935
944
|
? await prepareArchiveCasingMigrations(root)
|
|
936
945
|
: [];
|
|
937
|
-
const
|
|
946
|
+
const sourceConservationAuthority = command === "upgrade"
|
|
947
|
+
? await hasCommittedSourceConservationAuthority(root)
|
|
948
|
+
: false;
|
|
949
|
+
if (options.sourceConservationRebind === true) {
|
|
950
|
+
for (const output of outputs) delete output.runtimeAcceptance;
|
|
951
|
+
}
|
|
952
|
+
const runtimeAcceptance = command === "upgrade" && options.sourceConservationRebind !== true ? resolveRuntimeAcceptance(outputs) : null;
|
|
953
|
+
const sourceConservation = command === "upgrade" && (
|
|
954
|
+
runtimeAcceptance || sourceConservationAuthority
|
|
955
|
+
)
|
|
938
956
|
? await createSourceConservation(root, outputs, archiveMigrations)
|
|
939
957
|
: null;
|
|
940
958
|
// A repair may restore the exact bytes of a prior committed state. Keep the
|
|
@@ -942,7 +960,7 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
942
960
|
// doctor can select the freshly read-back transaction without falling back
|
|
943
961
|
// to mtime or a separate current-state registry.
|
|
944
962
|
const supersedesCurrentStateDigests = command === "upgrade"
|
|
945
|
-
? await findRestoredCurrentStateDigests(root, outputs, archiveMigrations)
|
|
963
|
+
? await findRestoredCurrentStateDigests(root, outputs, archiveMigrations, { sourceConservation, archiveMigrations })
|
|
946
964
|
: [];
|
|
947
965
|
const transaction = await prepareTransaction(root, command, version, outputs, mode, plan, sourceConservation, supersedesCurrentStateDigests, archiveMigrations);
|
|
948
966
|
try {
|
|
@@ -995,6 +1013,7 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
995
1013
|
const doctorStatus = await runDoctor(root, version, {
|
|
996
1014
|
silentCard: true,
|
|
997
1015
|
context: "post-transaction-project-health",
|
|
1016
|
+
skipVersionRegistryLookup: true,
|
|
998
1017
|
allowActiveTransaction: true,
|
|
999
1018
|
expectedCurrentStateWitness: transaction.journal.currentStateWitness,
|
|
1000
1019
|
captureFormalUserRules: (state) => { formalRuntimeState = state; },
|
|
@@ -2186,6 +2205,7 @@ async function recoverInterruptedTransaction(root) {
|
|
|
2186
2205
|
const doctorStatus = await runDoctor(root, journal.committedVersion, {
|
|
2187
2206
|
silentCard: true,
|
|
2188
2207
|
context: "recovered-committed-transaction-health",
|
|
2208
|
+
skipVersionRegistryLookup: true,
|
|
2189
2209
|
allowActiveTransaction: true,
|
|
2190
2210
|
expectedCurrentStateWitness: journal.currentStateWitness,
|
|
2191
2211
|
captureFormalUserRules: (state) => { formalRuntimeState = state; },
|
|
@@ -3748,8 +3768,7 @@ async function loadCommittedCurrentStateWitness(root) {
|
|
|
3748
3768
|
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
3749
3769
|
let names;
|
|
3750
3770
|
try { names = await readdir(migrationsRoot); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
|
|
3751
|
-
const
|
|
3752
|
-
const staleSourceConservation = [];
|
|
3771
|
+
const records = [];
|
|
3753
3772
|
for (const name of names) {
|
|
3754
3773
|
if (name === ".upgrade.lock") continue;
|
|
3755
3774
|
const journalPath = path.join(migrationsRoot, name, "transaction.json");
|
|
@@ -3759,30 +3778,129 @@ async function loadCommittedCurrentStateWitness(root) {
|
|
|
3759
3778
|
const journal = JSON.parse(await readFile(journalPath, "utf8"));
|
|
3760
3779
|
if (journal.state !== "committed" || !journal.currentStateWitness) continue;
|
|
3761
3780
|
await validateRecoveryJournal(root, journal, journalPath);
|
|
3762
|
-
|
|
3763
|
-
|
|
3781
|
+
const witness = validateCurrentStateWitness(journal);
|
|
3782
|
+
records.push({ journal, journalPath, witness, matches: await journalMatchesCurrentState(root, journal) });
|
|
3764
3783
|
} catch (error) {
|
|
3765
3784
|
if (error?.code !== "ENOENT") throw error;
|
|
3766
3785
|
}
|
|
3767
3786
|
}
|
|
3768
|
-
|
|
3787
|
+
const superseded = effectiveCurrentStateSupersededDigests(records);
|
|
3788
|
+
const staleSourceConservation = records.filter((record) => (
|
|
3789
|
+
!record.matches
|
|
3790
|
+
&& record.witness.sourceConservation
|
|
3791
|
+
&& !superseded.has(record.witness.currentStateDigest)
|
|
3792
|
+
));
|
|
3793
|
+
if (staleSourceConservation.length > 0) {
|
|
3769
3794
|
throw new Error("committed Gate 5 current-state source witness no longer matches project bytes; doctor refuses an unbound success state");
|
|
3770
3795
|
}
|
|
3796
|
+
const candidates = records.filter((record) => record.matches);
|
|
3771
3797
|
if (candidates.length === 0) return null;
|
|
3772
3798
|
// A later repair can deliberately restore the exact bytes of an earlier
|
|
3773
3799
|
// state. Its sealed supersession link is the only permitted tie-breaker:
|
|
3774
3800
|
// filesystem timestamps remain untrusted and an unlinked tie stays fatal.
|
|
3775
|
-
const
|
|
3776
|
-
journal.currentStateWitness.transaction.supersedesCurrentStateDigests ?? []
|
|
3777
|
-
)));
|
|
3778
|
-
const currentCandidates = candidates.filter(({ journal }) => !superseded.has(journal.currentStateWitness.currentStateDigest));
|
|
3801
|
+
const currentCandidates = candidates.filter(({ witness }) => !superseded.has(witness.currentStateDigest));
|
|
3779
3802
|
if (currentCandidates.length !== 1) {
|
|
3780
3803
|
throw new Error("multiple committed journals match the current filesystem state; doctor refuses ambiguous current-state authority");
|
|
3781
3804
|
}
|
|
3782
3805
|
return validateCurrentStateWitness(currentCandidates[0].journal);
|
|
3783
3806
|
}
|
|
3784
3807
|
|
|
3785
|
-
|
|
3808
|
+
function effectiveCurrentStateSupersededDigests(records) {
|
|
3809
|
+
const byDigest = new Map(records.map((record) => [record.witness.currentStateDigest, record]));
|
|
3810
|
+
const superseded = new Set();
|
|
3811
|
+
for (const record of records) {
|
|
3812
|
+
for (const digest of record.witness.transaction.supersedesCurrentStateDigests ?? []) {
|
|
3813
|
+
const prior = byDigest.get(digest);
|
|
3814
|
+
if (!prior) continue;
|
|
3815
|
+
if (canSupersedeCurrentStateWitness(record.witness, prior.witness)) superseded.add(digest);
|
|
3816
|
+
}
|
|
3817
|
+
}
|
|
3818
|
+
return superseded;
|
|
3819
|
+
}
|
|
3820
|
+
|
|
3821
|
+
async function hasCommittedSourceConservationAuthority(root) {
|
|
3822
|
+
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
3823
|
+
let names;
|
|
3824
|
+
try { names = await readdir(migrationsRoot); } catch (error) { if (error?.code === "ENOENT") return false; throw error; }
|
|
3825
|
+
const records = [];
|
|
3826
|
+
for (const name of names) {
|
|
3827
|
+
if (name === ".upgrade.lock") continue;
|
|
3828
|
+
const journalPath = path.join(migrationsRoot, name, "transaction.json");
|
|
3829
|
+
try {
|
|
3830
|
+
const stats = await lstat(journalPath);
|
|
3831
|
+
if (!stats.isFile() || stats.isSymbolicLink()) continue;
|
|
3832
|
+
const journal = JSON.parse(await readFile(journalPath, "utf8"));
|
|
3833
|
+
if (journal.state !== "committed" || !journal.currentStateWitness) continue;
|
|
3834
|
+
await validateRecoveryJournal(root, journal, journalPath);
|
|
3835
|
+
records.push({ journal, journalPath, witness: validateCurrentStateWitness(journal), matches: await journalMatchesCurrentState(root, journal) });
|
|
3836
|
+
} catch (error) {
|
|
3837
|
+
if (error?.code !== "ENOENT") throw error;
|
|
3838
|
+
}
|
|
3839
|
+
}
|
|
3840
|
+
const superseded = effectiveCurrentStateSupersededDigests(records);
|
|
3841
|
+
let hasSourceConservation = false;
|
|
3842
|
+
for (const record of records) {
|
|
3843
|
+
if (!record.witness.sourceConservation || superseded.has(record.witness.currentStateDigest)) continue;
|
|
3844
|
+
hasSourceConservation = true;
|
|
3845
|
+
if (record.matches) continue;
|
|
3846
|
+
const { illegalNonCloseout } = await classifyCurrentStateRebindMismatches(root, record.journal);
|
|
3847
|
+
if (illegalNonCloseout.length > 0) {
|
|
3848
|
+
throw new Error(`conflict: non-closeout drift blocks upgrade source-conservation rebind: ${illegalNonCloseout.map((item) => item.path).join(", ")}`);
|
|
3849
|
+
}
|
|
3850
|
+
}
|
|
3851
|
+
if (hasSourceConservation) return true;
|
|
3852
|
+
return false;
|
|
3853
|
+
}
|
|
3854
|
+
|
|
3855
|
+
async function assertUnboundCurrentStateMayAttemptUpgradeRebind(root, cause) {
|
|
3856
|
+
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
3857
|
+
let names;
|
|
3858
|
+
try { names = await readdir(migrationsRoot); } catch (error) { if (error?.code === "ENOENT") throw cause; throw error; }
|
|
3859
|
+
const records = [];
|
|
3860
|
+
for (const name of names) {
|
|
3861
|
+
if (name === ".upgrade.lock") continue;
|
|
3862
|
+
const journalPath = path.join(migrationsRoot, name, "transaction.json");
|
|
3863
|
+
try {
|
|
3864
|
+
const stats = await lstat(journalPath);
|
|
3865
|
+
if (!stats.isFile() || stats.isSymbolicLink()) continue;
|
|
3866
|
+
const journal = JSON.parse(await readFile(journalPath, "utf8"));
|
|
3867
|
+
if (journal.state !== "committed" || !journal.currentStateWitness) continue;
|
|
3868
|
+
await validateRecoveryJournal(root, journal, journalPath);
|
|
3869
|
+
records.push({ journal, journalPath, witness: validateCurrentStateWitness(journal), matches: await journalMatchesCurrentState(root, journal) });
|
|
3870
|
+
} catch (error) {
|
|
3871
|
+
if (error?.code !== "ENOENT") throw error;
|
|
3872
|
+
}
|
|
3873
|
+
}
|
|
3874
|
+
const superseded = effectiveCurrentStateSupersededDigests(records);
|
|
3875
|
+
for (const record of records) {
|
|
3876
|
+
if (record.matches || !record.witness.sourceConservation || superseded.has(record.witness.currentStateDigest)) continue;
|
|
3877
|
+
const { mismatches, illegalNonCloseout } = await classifyCurrentStateRebindMismatches(root, record.journal);
|
|
3878
|
+
if (illegalNonCloseout.length > 0) throw cause;
|
|
3879
|
+
const managedCore = mismatches.filter((mismatch) => installedFileContract(mismatch.path)?.strategy === "managed-core");
|
|
3880
|
+
if (managedCore.length > 0) throw cause;
|
|
3881
|
+
}
|
|
3882
|
+
}
|
|
3883
|
+
|
|
3884
|
+
async function classifyCurrentStateRebindMismatches(projectRoot, journal) {
|
|
3885
|
+
const mismatches = await currentStateMismatches(projectRoot, journal);
|
|
3886
|
+
const illegalNonCloseout = [];
|
|
3887
|
+
for (const mismatch of mismatches) {
|
|
3888
|
+
if (isCloseoutFinalizeTarget(mismatch.path)) continue;
|
|
3889
|
+
if (await mismatchMatchesCurrentInstalledSource(projectRoot, mismatch)) continue;
|
|
3890
|
+
illegalNonCloseout.push(mismatch);
|
|
3891
|
+
}
|
|
3892
|
+
return { mismatches, illegalNonCloseout };
|
|
3893
|
+
}
|
|
3894
|
+
|
|
3895
|
+
async function mismatchMatchesCurrentInstalledSource(projectRoot, mismatch) {
|
|
3896
|
+
const contract = installedFileContract(mismatch.path);
|
|
3897
|
+
if (!contract || contract.strategy === "managed-core") return false;
|
|
3898
|
+
const current = await readOptionalBuffer(path.join(projectRoot, mismatch.path));
|
|
3899
|
+
const source = await readOptionalBuffer(path.join(packageRoot, contract.sourceRel));
|
|
3900
|
+
return Boolean(current && source && current.length === source.length && sha256(current) === sha256(source));
|
|
3901
|
+
}
|
|
3902
|
+
|
|
3903
|
+
async function findRestoredCurrentStateDigests(root, outputs, archiveMigrations = [], replacement = {}) {
|
|
3786
3904
|
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
3787
3905
|
let names;
|
|
3788
3906
|
try { names = await readdir(migrationsRoot); } catch (error) { if (error?.code === "ENOENT") return []; throw error; }
|
|
@@ -3797,8 +3915,11 @@ async function findRestoredCurrentStateDigests(root, outputs, archiveMigrations
|
|
|
3797
3915
|
const journal = JSON.parse(await readFile(journalPath, "utf8"));
|
|
3798
3916
|
if (journal.state !== "committed" || !journal.currentStateWitness) continue;
|
|
3799
3917
|
await validateRecoveryJournal(root, journal, journalPath);
|
|
3918
|
+
const priorWitness = validateCurrentStateWitness(journal);
|
|
3800
3919
|
if (await journalMatchesCurrentState(root, journal)
|
|
3801
|
-
|| await journalIsRestoredByOutputs(root, journal, outputWitnesses, archiveMigrations)
|
|
3920
|
+
|| await journalIsRestoredByOutputs(root, journal, outputWitnesses, archiveMigrations)
|
|
3921
|
+
|| sourceConservationRebindsPrior(priorWitness, replacement.sourceConservation)) {
|
|
3922
|
+
if (!canSupersedeCurrentStateWitness(replacement, priorWitness)) continue;
|
|
3802
3923
|
restored.push(journal.currentStateWitness.currentStateDigest);
|
|
3803
3924
|
}
|
|
3804
3925
|
} catch (error) {
|
|
@@ -3808,6 +3929,62 @@ async function findRestoredCurrentStateDigests(root, outputs, archiveMigrations
|
|
|
3808
3929
|
return [...new Set(restored)].sort((left, right) => left.localeCompare(right));
|
|
3809
3930
|
}
|
|
3810
3931
|
|
|
3932
|
+
function currentStateWitnessCapability(value = {}) {
|
|
3933
|
+
return {
|
|
3934
|
+
sourceConservation: Boolean(value.sourceConservation),
|
|
3935
|
+
archiveMigrations: Array.isArray(value.archiveMigrations) && value.archiveMigrations.length > 0
|
|
3936
|
+
};
|
|
3937
|
+
}
|
|
3938
|
+
|
|
3939
|
+
function canSupersedeCurrentStateWitness(replacement, priorWitness) {
|
|
3940
|
+
const replacementCapability = currentStateWitnessCapability(replacement);
|
|
3941
|
+
if (priorWitness.sourceConservation && !replacementCapability.sourceConservation) return false;
|
|
3942
|
+
if (Array.isArray(priorWitness.archiveMigrations) && priorWitness.archiveMigrations.length > 0
|
|
3943
|
+
&& !replacementCapability.archiveMigrations
|
|
3944
|
+
&& !archiveMigrationHistoryIsRebound(priorWitness, replacement.sourceConservation)) {
|
|
3945
|
+
return false;
|
|
3946
|
+
}
|
|
3947
|
+
return true;
|
|
3948
|
+
}
|
|
3949
|
+
|
|
3950
|
+
function sourceConservationRebindsPrior(priorWitness, replacementSourceConservation) {
|
|
3951
|
+
if (!replacementSourceConservation) return false;
|
|
3952
|
+
const replacementByPath = new Map(replacementSourceConservation.entries.map((entry) => [entry.sourcePath, entry]));
|
|
3953
|
+
const coversTransactionEntries = priorWitness.entries.every((entry) => {
|
|
3954
|
+
const replacement = replacementByPath.get(entry.targetRel);
|
|
3955
|
+
return replacement
|
|
3956
|
+
&& replacement.accepted
|
|
3957
|
+
&& typeof replacement.accepted.sha256 === "string"
|
|
3958
|
+
&& Number.isInteger(replacement.accepted.bytes);
|
|
3959
|
+
});
|
|
3960
|
+
if (!coversTransactionEntries) return false;
|
|
3961
|
+
if (!priorWitness.sourceConservation) return true;
|
|
3962
|
+
return priorWitness.sourceConservation.entries.every((entry) => {
|
|
3963
|
+
const replacement = replacementByPath.get(entry.sourcePath);
|
|
3964
|
+
return replacement
|
|
3965
|
+
&& replacement.accepted
|
|
3966
|
+
&& typeof replacement.accepted.sha256 === "string"
|
|
3967
|
+
&& Number.isInteger(replacement.accepted.bytes);
|
|
3968
|
+
});
|
|
3969
|
+
}
|
|
3970
|
+
|
|
3971
|
+
function archiveMigrationHistoryIsRebound(priorWitness, replacementSourceConservation) {
|
|
3972
|
+
if (!replacementSourceConservation || !Array.isArray(priorWitness.archiveMigrations) || priorWitness.archiveMigrations.length === 0) return false;
|
|
3973
|
+
const replacementByPath = new Map(replacementSourceConservation.entries.map((entry) => [entry.sourcePath, entry]));
|
|
3974
|
+
for (const migration of priorWitness.archiveMigrations) {
|
|
3975
|
+
for (const file of migration.snapshot.files ?? []) {
|
|
3976
|
+
const conserved = replacementByPath.get(`${migration.canonicalRel}/${file.path}`);
|
|
3977
|
+
if (!conserved
|
|
3978
|
+
|| !conserved.accepted
|
|
3979
|
+
|| conserved.accepted.sha256 !== file.sha256
|
|
3980
|
+
|| conserved.accepted.bytes !== file.bytes) {
|
|
3981
|
+
return false;
|
|
3982
|
+
}
|
|
3983
|
+
}
|
|
3984
|
+
}
|
|
3985
|
+
return sourceConservationRebindsPrior(priorWitness, replacementSourceConservation);
|
|
3986
|
+
}
|
|
3987
|
+
|
|
3811
3988
|
async function journalIsRestoredByOutputs(root, journal, outputWitnesses, archiveMigrations = []) {
|
|
3812
3989
|
const witness = validateCurrentStateWitness(journal);
|
|
3813
3990
|
const archiveRebindings = new Map();
|
|
@@ -3919,23 +4096,123 @@ async function findCloseoutFinalizeBase(root) {
|
|
|
3919
4096
|
if (error?.code !== "ENOENT") throw error;
|
|
3920
4097
|
}
|
|
3921
4098
|
}
|
|
3922
|
-
const
|
|
3923
|
-
const illegal = [];
|
|
4099
|
+
const records = [];
|
|
3924
4100
|
for (const item of inspected) {
|
|
3925
|
-
|
|
4101
|
+
const witness = validateCurrentStateWitness(item.journal);
|
|
3926
4102
|
const mismatches = await currentStateMismatches(root, item.journal);
|
|
3927
|
-
|
|
3928
|
-
|
|
3929
|
-
|
|
4103
|
+
const closeoutOnly = mismatches.every((mismatch) => isCloseoutFinalizeTarget(mismatch.path));
|
|
4104
|
+
records.push({
|
|
4105
|
+
...item,
|
|
4106
|
+
witness,
|
|
4107
|
+
mismatches,
|
|
4108
|
+
closeoutOnly,
|
|
4109
|
+
isSuperseded: superseded.has(witness.currentStateDigest),
|
|
4110
|
+
additionalSupersedes: []
|
|
4111
|
+
});
|
|
3930
4112
|
}
|
|
4113
|
+
const current = records.filter((item) => !item.isSuperseded);
|
|
4114
|
+
const illegal = current.filter((item) => item.mismatches.length > 0 && !item.closeoutOnly);
|
|
3931
4115
|
if (illegal.length > 0) return illegal.sort((left, right) => right.mismatches.length - left.mismatches.length)[0];
|
|
3932
|
-
|
|
3933
|
-
|
|
3934
|
-
|
|
3935
|
-
|
|
4116
|
+
|
|
4117
|
+
const staleStrong = current.filter((item) => item.mismatches.length > 0 && item.closeoutOnly && item.witness.sourceConservation);
|
|
4118
|
+
const unsupportedStale = current.filter((item) => item.mismatches.length > 0 && item.closeoutOnly && !item.witness.sourceConservation);
|
|
4119
|
+
if (staleStrong.length > 0 && unsupportedStale.length > 0) {
|
|
4120
|
+
const digests = [...staleStrong, ...unsupportedStale].map(({ witness }) => witness.currentStateDigest).join(", ");
|
|
4121
|
+
throw new Error(`multiple closeout-finalize stale witness authorities exist: ${digests}`);
|
|
4122
|
+
}
|
|
4123
|
+
if (staleStrong.length > 1) {
|
|
4124
|
+
const digests = staleStrong.map(({ witness }) => witness.currentStateDigest).join(", ");
|
|
3936
4125
|
throw new Error(`multiple closeout-finalize candidate witnesses are stale: ${digests}`);
|
|
3937
4126
|
}
|
|
3938
|
-
|
|
4127
|
+
if (staleStrong.length === 1) {
|
|
4128
|
+
return withAdditionalCloseoutSupersedes(staleStrong[0], current);
|
|
4129
|
+
}
|
|
4130
|
+
|
|
4131
|
+
if (unsupportedStale.length > 0) {
|
|
4132
|
+
if (unsupportedStale.length > 1) {
|
|
4133
|
+
const digests = unsupportedStale.map(({ witness }) => witness.currentStateDigest).join(", ");
|
|
4134
|
+
throw new Error(`multiple closeout-finalize unsupported stale witnesses exist: ${digests}`);
|
|
4135
|
+
}
|
|
4136
|
+
const bridged = closeoutFinalizeBridgeCandidates(records, unsupportedStale);
|
|
4137
|
+
if (bridged.length === 1) return withAdditionalCloseoutSupersedes(bridged[0], current);
|
|
4138
|
+
if (bridged.length > 1) {
|
|
4139
|
+
const digests = bridged.map(({ witness }) => witness.currentStateDigest).join(", ");
|
|
4140
|
+
throw new Error(`multiple closeout-finalize source-conservation bridge witnesses are stale: ${digests}`);
|
|
4141
|
+
}
|
|
4142
|
+
const digests = unsupportedStale.map(({ witness }) => witness.currentStateDigest).join(", ");
|
|
4143
|
+
throw new Error(`post-upgrade current-state witness is stale but lacks source-conservation evidence for closeout finalize: ${digests}`);
|
|
4144
|
+
}
|
|
4145
|
+
|
|
4146
|
+
const matching = current.filter((item) => item.mismatches.length === 0);
|
|
4147
|
+
if (matching.length > 1) {
|
|
4148
|
+
const digests = matching.map(({ witness }) => witness.currentStateDigest).join(", ");
|
|
4149
|
+
throw new Error(`multiple committed journals match the current filesystem state; finalize-closeout refuses ambiguous current-state authority: ${digests}`);
|
|
4150
|
+
}
|
|
4151
|
+
return matching[0] ?? null;
|
|
4152
|
+
}
|
|
4153
|
+
|
|
4154
|
+
function closeoutFinalizeBridgeCandidates(records, unsupportedStale) {
|
|
4155
|
+
const byDigest = new Map(records.map((item) => [item.witness.currentStateDigest, item]));
|
|
4156
|
+
const candidates = new Map();
|
|
4157
|
+
for (const unsupported of unsupportedStale) {
|
|
4158
|
+
const traced = traceCloseoutFinalizeBridge(unsupported, byDigest);
|
|
4159
|
+
for (const candidate of traced) {
|
|
4160
|
+
const existing = candidates.get(candidate.strong.witness.currentStateDigest) ?? { ...candidate.strong, additionalSupersedes: [] };
|
|
4161
|
+
existing.additionalSupersedes.push(...candidate.weakChain);
|
|
4162
|
+
candidates.set(candidate.strong.witness.currentStateDigest, existing);
|
|
4163
|
+
}
|
|
4164
|
+
}
|
|
4165
|
+
return [...candidates.values()];
|
|
4166
|
+
}
|
|
4167
|
+
|
|
4168
|
+
function traceCloseoutFinalizeBridge(start, byDigest) {
|
|
4169
|
+
const candidates = new Map();
|
|
4170
|
+
const visit = (record, weakChain, pathStack) => {
|
|
4171
|
+
const digest = record.witness.currentStateDigest;
|
|
4172
|
+
if (pathStack.includes(digest)) {
|
|
4173
|
+
throw new Error(`cycle in closeout-finalize supersession chain: ${[...pathStack, digest].join(", ")}`);
|
|
4174
|
+
}
|
|
4175
|
+
if (record.mismatches.length > 0 && !record.closeoutOnly) {
|
|
4176
|
+
throw new Error(`non-closeout drift in closeout-finalize supersession chain: ${record.mismatches.map((item) => item.path).join(", ")}`);
|
|
4177
|
+
}
|
|
4178
|
+
if (record.witness.sourceConservation) {
|
|
4179
|
+
if (record.mismatches.length === 0) {
|
|
4180
|
+
throw new Error(`closeout-finalize source-conservation bridge is not stale: ${digest}`);
|
|
4181
|
+
}
|
|
4182
|
+
candidates.set(digest, { strong: record, weakChain });
|
|
4183
|
+
return;
|
|
4184
|
+
}
|
|
4185
|
+
const supersedes = record.witness.transaction.supersedesCurrentStateDigests ?? [];
|
|
4186
|
+
if (supersedes.length === 0) {
|
|
4187
|
+
throw new Error(`post-upgrade current-state witness is stale but has no source-conservation bridge: ${digest}`);
|
|
4188
|
+
}
|
|
4189
|
+
if (supersedes.length > 1) {
|
|
4190
|
+
throw new Error(`branching closeout-finalize supersession chain: ${digest} -> ${supersedes.join(", ")}`);
|
|
4191
|
+
}
|
|
4192
|
+
for (const supersededDigest of supersedes) {
|
|
4193
|
+
const next = byDigest.get(supersededDigest);
|
|
4194
|
+
if (!next) {
|
|
4195
|
+
throw new Error(`missing closeout-finalize supersession link: ${digest} -> ${supersededDigest}`);
|
|
4196
|
+
}
|
|
4197
|
+
visit(next, [...weakChain, digest], [...pathStack, digest]);
|
|
4198
|
+
}
|
|
4199
|
+
};
|
|
4200
|
+
visit(start, [], []);
|
|
4201
|
+
return [...candidates.values()];
|
|
4202
|
+
}
|
|
4203
|
+
|
|
4204
|
+
function withAdditionalCloseoutSupersedes(base, current) {
|
|
4205
|
+
const additional = current
|
|
4206
|
+
.filter((item) => item.witness.currentStateDigest !== base.witness.currentStateDigest)
|
|
4207
|
+
.filter((item) => !item.witness.sourceConservation)
|
|
4208
|
+
.filter((item) => item.mismatches.length === 0 || item.closeoutOnly)
|
|
4209
|
+
.map((item) => item.witness.currentStateDigest);
|
|
4210
|
+
return {
|
|
4211
|
+
...base,
|
|
4212
|
+
additionalSupersedes: [...new Set([...(base.additionalSupersedes ?? []), ...additional])]
|
|
4213
|
+
.filter((digest) => digest !== base.witness.currentStateDigest)
|
|
4214
|
+
.sort((left, right) => left.localeCompare(right))
|
|
4215
|
+
};
|
|
3939
4216
|
}
|
|
3940
4217
|
|
|
3941
4218
|
async function currentStateMismatches(root, journal) {
|
|
@@ -3965,6 +4242,10 @@ async function currentStateMismatches(root, journal) {
|
|
|
3965
4242
|
|
|
3966
4243
|
async function writeCloseoutFinalizeJournal(root, version, prior) {
|
|
3967
4244
|
const oldWitness = validateCurrentStateWitness(prior.journal);
|
|
4245
|
+
const supersedesCurrentStateDigests = [...new Set([
|
|
4246
|
+
oldWitness.currentStateDigest,
|
|
4247
|
+
...(prior.additionalSupersedes ?? [])
|
|
4248
|
+
])].sort((left, right) => left.localeCompare(right));
|
|
3968
4249
|
const id = `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID()}`;
|
|
3969
4250
|
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
3970
4251
|
const migrationDir = path.join(migrationsRoot, id);
|
|
@@ -4059,7 +4340,7 @@ async function writeCloseoutFinalizeJournal(root, version, prior) {
|
|
|
4059
4340
|
runtimeAcceptanceReadback: null,
|
|
4060
4341
|
sourceConservation,
|
|
4061
4342
|
archiveMigrations: oldWitness.archiveMigrations ?? [],
|
|
4062
|
-
supersedesCurrentStateDigests
|
|
4343
|
+
supersedesCurrentStateDigests,
|
|
4063
4344
|
currentStateWitness: null,
|
|
4064
4345
|
currentStateReadback: null
|
|
4065
4346
|
};
|
|
@@ -4071,7 +4352,7 @@ async function writeCloseoutFinalizeJournal(root, version, prior) {
|
|
|
4071
4352
|
"",
|
|
4072
4353
|
`- Command: finalize-closeout`,
|
|
4073
4354
|
`- Attempted version: ${version}`,
|
|
4074
|
-
`- Supersedes current-state digest: ${
|
|
4355
|
+
`- Supersedes current-state digest: ${supersedesCurrentStateDigests.join(", ")}`,
|
|
4075
4356
|
`- Current-state digest: ${journal.currentStateWitness.currentStateDigest}`,
|
|
4076
4357
|
`- Finalized paths: ${prior.mismatches.map((item) => item.path).join(", ") || "none"}`,
|
|
4077
4358
|
""
|
|
@@ -10626,6 +10626,181 @@
|
|
|
10626
10626
|
"canonicalSha256": "cd696ae93f90ccbf0e0ae24f522c9a1a9d6482b0dd7011225096ab771d2c7fae"
|
|
10627
10627
|
}
|
|
10628
10628
|
}
|
|
10629
|
+
},
|
|
10630
|
+
"0.3.49": {
|
|
10631
|
+
"source": {
|
|
10632
|
+
"npm": {
|
|
10633
|
+
"spec": "@adamchanadam/agent-handoff-kit@0.3.49",
|
|
10634
|
+
"shasum": "9e918c634a6c01ba1fbbfeb33c6965a5546a0a1d",
|
|
10635
|
+
"integrity": "sha512-agwBr5rWtJxvbENzSC23hMERJkm5gsFq8pLRW0VzXeBj9G7gn/e+pTxLQQ8/xw3P5flyX3qvZpO6Z6CYD4heAQ==",
|
|
10636
|
+
"entryCount": 35,
|
|
10637
|
+
"gitHead": null
|
|
10638
|
+
},
|
|
10639
|
+
"git": {
|
|
10640
|
+
"tag": "v0.3.49",
|
|
10641
|
+
"directObject": "d8ec8ba39c5c71d23cee1e0a3c489fa4c600e29d",
|
|
10642
|
+
"peeledCommit": null,
|
|
10643
|
+
"commit": "d8ec8ba39c5c71d23cee1e0a3c489fa4c600e29d"
|
|
10644
|
+
},
|
|
10645
|
+
"githubRelease": {
|
|
10646
|
+
"tag": "v0.3.49",
|
|
10647
|
+
"publishedAt": "2026-07-20T15:45:14Z"
|
|
10648
|
+
},
|
|
10649
|
+
"sourceDivergence": {
|
|
10650
|
+
"status": "npm-gitHead-unavailable",
|
|
10651
|
+
"npmGitHead": null,
|
|
10652
|
+
"remoteTagCommit": "d8ec8ba39c5c71d23cee1e0a3c489fa4c600e29d"
|
|
10653
|
+
}
|
|
10654
|
+
},
|
|
10655
|
+
"manifest": {
|
|
10656
|
+
"AGENTS.md": {
|
|
10657
|
+
"state": "present",
|
|
10658
|
+
"contentId": "f310944edb22dd7cda50510678825a5f1f60945867f95553185a6dcac79a5cd0",
|
|
10659
|
+
"rawSha256": "0ed131a1c5d09b32fab68d8c548e070bd3294a5e2ec010090d70ce3760718e7c",
|
|
10660
|
+
"normalizedSha256": "0ed131a1c5d09b32fab68d8c548e070bd3294a5e2ec010090d70ce3760718e7c",
|
|
10661
|
+
"canonicalSha256": "0ed131a1c5d09b32fab68d8c548e070bd3294a5e2ec010090d70ce3760718e7c"
|
|
10662
|
+
},
|
|
10663
|
+
"CLAUDE.md": {
|
|
10664
|
+
"state": "present",
|
|
10665
|
+
"contentId": "7a2cf08a1171762ebcb53f43036a2170655379416945258b9c85d4b189ecaecf",
|
|
10666
|
+
"rawSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
10667
|
+
"normalizedSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad",
|
|
10668
|
+
"canonicalSha256": "9e326c3c1ab08fbcd23b28cd398561c17d851a59997842e0f4f97ff3473ff0ad"
|
|
10669
|
+
},
|
|
10670
|
+
"GEMINI.md": {
|
|
10671
|
+
"state": "present",
|
|
10672
|
+
"contentId": "36da47034bb2ce6c760ddbbbbd49dccc1d17665dbb18bec56ffa3b26bac1c135",
|
|
10673
|
+
"rawSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
10674
|
+
"normalizedSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986",
|
|
10675
|
+
"canonicalSha256": "b6e8bfc51ba751fec2acd1719c4459b41524f013e0464a5573de7f66d436c986"
|
|
10676
|
+
},
|
|
10677
|
+
"START_NEXT_SESSION_PROMPT.txt": {
|
|
10678
|
+
"state": "present",
|
|
10679
|
+
"contentId": "210c34689425e5096dc47e8d83f753df3c533cc5ba00e38084c09483fc0b0775",
|
|
10680
|
+
"rawSha256": "5fa03a4344481d00ec58cc8291444a32d600f4a885ff4c0f7613f580b9f97a48",
|
|
10681
|
+
"normalizedSha256": "5fa03a4344481d00ec58cc8291444a32d600f4a885ff4c0f7613f580b9f97a48",
|
|
10682
|
+
"canonicalSha256": "6ca8b7c47204e781fb498cd05bb035da115fd03f19e7dca8f340e998922d32ee"
|
|
10683
|
+
},
|
|
10684
|
+
"dev/SESSION_HANDOFF.md": {
|
|
10685
|
+
"state": "present",
|
|
10686
|
+
"contentId": "3ad88dea4d8e078fad577db537cc446a7bdcc08b1ce062749d359aa296c267a4",
|
|
10687
|
+
"rawSha256": "9711e05be6551126b52cb3f12ae9052b4d308e5ca7b653d9c8ccf47000772e0d",
|
|
10688
|
+
"normalizedSha256": "9711e05be6551126b52cb3f12ae9052b4d308e5ca7b653d9c8ccf47000772e0d",
|
|
10689
|
+
"canonicalSha256": "b938678a44fc8f93bbd6203265f1e73a5e6e7668f7e315e0d289177f99c750b8"
|
|
10690
|
+
},
|
|
10691
|
+
"dev/SESSION_LOG.md": {
|
|
10692
|
+
"state": "present",
|
|
10693
|
+
"contentId": "7b6184ee4dabe89f504a894c3d4803f012d962c7af53c7f29801a8fb28d9d51c",
|
|
10694
|
+
"rawSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
|
|
10695
|
+
"normalizedSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47",
|
|
10696
|
+
"canonicalSha256": "fb6bfd7026a15f87a54cfa64fbd69f032538b0c3193372876a3722fb997a3a47"
|
|
10697
|
+
},
|
|
10698
|
+
"dev/PROJECT_INDEX.md": {
|
|
10699
|
+
"state": "present",
|
|
10700
|
+
"contentId": "cc6eb8c88f8b4f71b81ea010633450f3ee72e06a58b0513f2d35f048cc472f3a",
|
|
10701
|
+
"rawSha256": "416b715be7fcbf33d0e001c4eb23967836a158bb7cd04a78593cb762e77a4b40",
|
|
10702
|
+
"normalizedSha256": "416b715be7fcbf33d0e001c4eb23967836a158bb7cd04a78593cb762e77a4b40",
|
|
10703
|
+
"canonicalSha256": "1ff9d23d69aa723549047352302e8f6825cadc75494dd80c95721f2a1747f3bc"
|
|
10704
|
+
},
|
|
10705
|
+
"dev/DOC_SYNC_REGISTRY.md": {
|
|
10706
|
+
"state": "present",
|
|
10707
|
+
"contentId": "f6545b524dc440d3563041e04a05caff4229863f6cae2a39127f85a29a120249",
|
|
10708
|
+
"rawSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
10709
|
+
"normalizedSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6",
|
|
10710
|
+
"canonicalSha256": "56807afee836d3ce19cabb1d020ef37168880a405b5eb8c6d7347e25e94c36e6"
|
|
10711
|
+
},
|
|
10712
|
+
"dev/RULE_PACKS.md": {
|
|
10713
|
+
"state": "present",
|
|
10714
|
+
"contentId": "a92986fcb4f7630e533bacf114d096e8e655973de297ff972a1bf1de5610af4b",
|
|
10715
|
+
"rawSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
|
|
10716
|
+
"normalizedSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf",
|
|
10717
|
+
"canonicalSha256": "a3e433884fc6bf26448acfa79ba106acaaafe5b4bdb212cb8ce6dc4aaea2faaf"
|
|
10718
|
+
},
|
|
10719
|
+
"dev/PROJECT_DECISIONS.md": {
|
|
10720
|
+
"state": "present",
|
|
10721
|
+
"contentId": "3aae993bd5b85bf6b1d1d458f1bcf82c7d3105c843f053ffa13553bb5931b8c4",
|
|
10722
|
+
"rawSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
10723
|
+
"normalizedSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e",
|
|
10724
|
+
"canonicalSha256": "c2fbfb759a36145a92750226d0f7585d49ce0fa4bf1cfde474988ce510dc455e"
|
|
10725
|
+
},
|
|
10726
|
+
"dev/rules/safety.md": {
|
|
10727
|
+
"state": "present",
|
|
10728
|
+
"contentId": "dd6bcf74722d038f76d202e2044a6583a6e6ad107fbb010520e513eec799ff4a",
|
|
10729
|
+
"rawSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
10730
|
+
"normalizedSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0",
|
|
10731
|
+
"canonicalSha256": "685e501bb8a8cf721dd742312c9160a46a1066a4a875235eaaf579c1c8e72ab0"
|
|
10732
|
+
},
|
|
10733
|
+
"dev/rules/coding.md": {
|
|
10734
|
+
"state": "present",
|
|
10735
|
+
"contentId": "1c6deb9a5a281c13e97b0ac96079e9e1beccbd1ff106186e7a6ac78c0eeb75c2",
|
|
10736
|
+
"rawSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
10737
|
+
"normalizedSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4",
|
|
10738
|
+
"canonicalSha256": "79e96a709d7e9ccc629a0e35f88fde72522cccb71a0e7bd103b02ab7a5a1e7f4"
|
|
10739
|
+
},
|
|
10740
|
+
"dev/rules/writing.md": {
|
|
10741
|
+
"state": "present",
|
|
10742
|
+
"contentId": "ceee5412520ba860e6b40de46bb164e2ce3919d2197d5fadb926198eb7dddd3b",
|
|
10743
|
+
"rawSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
10744
|
+
"normalizedSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593",
|
|
10745
|
+
"canonicalSha256": "106376ae5c4eb703cab471efe2b285e1b0de5e35c2460977731fec2662c24593"
|
|
10746
|
+
},
|
|
10747
|
+
"dev/rules/research.md": {
|
|
10748
|
+
"state": "present",
|
|
10749
|
+
"contentId": "4414f9c82c6d04ad49d7446f4b0740055242f425ef5b00391d9c8c78c96c0f66",
|
|
10750
|
+
"rawSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
10751
|
+
"normalizedSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104",
|
|
10752
|
+
"canonicalSha256": "b282a48392250b570651f5e2e80c59d6c247617d08db35331d1e7538747a2104"
|
|
10753
|
+
},
|
|
10754
|
+
"dev/rules/agent-governance.md": {
|
|
10755
|
+
"state": "present",
|
|
10756
|
+
"contentId": "d3751dc9cb96774413fdd32895bc0c04fcf177346945dab52ffb3cc0ad3a6855",
|
|
10757
|
+
"rawSha256": "33baedd735ee7ec83583f37122a7bfea5c986536b4be6e3d14653f66acec0e77",
|
|
10758
|
+
"normalizedSha256": "33baedd735ee7ec83583f37122a7bfea5c986536b4be6e3d14653f66acec0e77",
|
|
10759
|
+
"canonicalSha256": "33baedd735ee7ec83583f37122a7bfea5c986536b4be6e3d14653f66acec0e77"
|
|
10760
|
+
},
|
|
10761
|
+
"dev/rules/release.md": {
|
|
10762
|
+
"state": "present",
|
|
10763
|
+
"contentId": "b0a0c9dea88016185f4093f9be4ce3c0e29904222e21dd1fa1735fcc1bb7e744",
|
|
10764
|
+
"rawSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
10765
|
+
"normalizedSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7",
|
|
10766
|
+
"canonicalSha256": "cb01295a69be627564307bb8475f1a6e6438fae79d910ef3e318e7fcb8ced8a7"
|
|
10767
|
+
},
|
|
10768
|
+
"dev/rules/knowledge.md": {
|
|
10769
|
+
"state": "present",
|
|
10770
|
+
"contentId": "a5944e8e165bd48e211868f5fb1c4d97754151c35d4bd547cecc4242a4292cd3",
|
|
10771
|
+
"rawSha256": "590bfa8fb176f344f5a030334cbe3292b9c9a30e89f00d1aa0aa1fb86eed6c7c",
|
|
10772
|
+
"normalizedSha256": "590bfa8fb176f344f5a030334cbe3292b9c9a30e89f00d1aa0aa1fb86eed6c7c",
|
|
10773
|
+
"canonicalSha256": "590bfa8fb176f344f5a030334cbe3292b9c9a30e89f00d1aa0aa1fb86eed6c7c"
|
|
10774
|
+
},
|
|
10775
|
+
"dev/rules/communication.md": {
|
|
10776
|
+
"state": "present",
|
|
10777
|
+
"contentId": "34fd0034cbc75dad43f789b86a414763f01916dda4d59876db9c4d8d92ae6a87",
|
|
10778
|
+
"rawSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
10779
|
+
"normalizedSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591",
|
|
10780
|
+
"canonicalSha256": "8622edcc31d76d12699ee3bb6c95ff74ad5f0e962fa063d4ad0146cfa083d591"
|
|
10781
|
+
},
|
|
10782
|
+
"dev/rules/closeout.md": {
|
|
10783
|
+
"state": "present",
|
|
10784
|
+
"contentId": "77c7cd99b3f1cc7fa6416f1caba476361bc332eb6bc8d22c35a84892b1399c6c",
|
|
10785
|
+
"rawSha256": "fc6263a00bbdcfc97772a4528d9f4a33d53c63b6cf99a56941100aea1fd3cb01",
|
|
10786
|
+
"normalizedSha256": "fc6263a00bbdcfc97772a4528d9f4a33d53c63b6cf99a56941100aea1fd3cb01",
|
|
10787
|
+
"canonicalSha256": "fc6263a00bbdcfc97772a4528d9f4a33d53c63b6cf99a56941100aea1fd3cb01"
|
|
10788
|
+
},
|
|
10789
|
+
"dev/rules/onboarding.md": {
|
|
10790
|
+
"state": "present",
|
|
10791
|
+
"contentId": "e67b34ca3eb5e3aac6e36aa3a3929daae0c881e803badb6d22d5837fc37588ab",
|
|
10792
|
+
"rawSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
|
|
10793
|
+
"normalizedSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3",
|
|
10794
|
+
"canonicalSha256": "ae0ab942b86e216e29e8996f17947442d7568910b84899b6df2b836b1fcdbed3"
|
|
10795
|
+
},
|
|
10796
|
+
"dev/rules/integrations.md": {
|
|
10797
|
+
"state": "present",
|
|
10798
|
+
"contentId": "6286f7d7b45803071ffddcd1ca864cf87213f0f21c3b195d10261a8c4187dfd1",
|
|
10799
|
+
"rawSha256": "cd696ae93f90ccbf0e0ae24f522c9a1a9d6482b0dd7011225096ab771d2c7fae",
|
|
10800
|
+
"normalizedSha256": "cd696ae93f90ccbf0e0ae24f522c9a1a9d6482b0dd7011225096ab771d2c7fae",
|
|
10801
|
+
"canonicalSha256": "cd696ae93f90ccbf0e0ae24f522c9a1a9d6482b0dd7011225096ab771d2c7fae"
|
|
10802
|
+
}
|
|
10803
|
+
}
|
|
10629
10804
|
}
|
|
10630
10805
|
},
|
|
10631
10806
|
"contents": {
|
|
@@ -11343,7 +11518,12 @@
|
|
|
11343
11518
|
"targetRel": "AGENTS.md",
|
|
11344
11519
|
"canonicalSha256": "aa71a1e4f94f0d6e7eefc17dc554be322f9ad87dd487f48c0d342c89311df1dd",
|
|
11345
11520
|
"text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\nThis is the small always-read contract. Detailed task and closeout procedures live in routed packs.\n\n## 1. Intent And Startup\n\nClassify 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.\n\nDo 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.\n\nRoute intent in this order:\n\n1. Clear closeout intent routes directly to `dev/rules/closeout.md`.\n2. Clear continuity intent such as \"開工\", \"Start Agent Handoff\", \"開始接力\", or \"continue handoff\" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, writes, network access, or opt-out wording such as \"unless you object I will start\". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as \"開工,繼續做到下一個 blocker\" or \"開工,繼續完成目前目標\" may continue under the normal task and safety rules.\n3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.\n4. Explicit guidance requests such as \"I'm new\", \"teach me\", \"help me start\", \"新手\", \"教我用\", or \"點開始\" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\n\nTreat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.\n\nRead `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.\n\nIf the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.\n\nBefore a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.\n\nProbe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.\n\nShow the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.\n\nUse a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( o.o ) continuity ready\n > ^ <\n\n🔎 交接狀態:<loaded / new install / resumed>\n📌 目前目標:<current objective>\n⚠️ 注意事項:<important boundary or none>\n🚀 推薦下一步:<one action + reason>\n```\n\nUse the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.\n\n## 2. Proportionate Work Loop\n\nApply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.\n\nIn every user-facing reply, lead with ordinary language: state the result and its practical effect, then the next action when one helps. Put exact commands, errors, hashes, and detailed evidence after that; brevity must not hide uncertainty or safety risk.\n\n- 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.\n- Non-trivial work reads relevant sources before changing them.\n- High-risk work states scope, impact, acceptance, and required confirmation before writes.\n- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.\n- Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.\n\n## 2.1 Persistence Gate\n\nChoose exactly one tier after a task:\n\n1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.\n2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.\n3. Full closeout: explicit end-of-session / handoff intent, a tool or day boundary, or completed external / release / governance work that the next agent must continue. Load `dev/rules/closeout.md`.\n\nRoute current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.\n\nExternal effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.\n\n## 2.2 Upgrade Completion\n\nThe CLI owns upgrade truth. An upgrade is complete only when:\n\n1. The root is not newer than the CLI and every target passes read-only classification.\n2. Conflict produces zero governance-target and version writes.\n3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.\n4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.\n5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.\n6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.\n\nDo not use \"upgrade completed\" to mean \"the entire project is healthy\". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.\n\n## 3. Safety Baseline\n\nDo not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.\n\nNamed 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.\n\nVerify 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. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.\n\nDo not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.\n\n## 4. Closeout Trigger\n\nClear end-of-session or handoff intent such as \"收工\", \"Wrap up Agent Handoff\", \"closeout\", \"wrap up\", or \"handoff\" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.\n\nThe always-enforced closeout invariants are:\n\n1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.\n2. Completed, pending, risk, validation, and opening-message lifecycle states agree.\n3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.\n4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. After those checks, render the final card with `agent-handoff-kit closeout-status --root <project root>`; only its `status: complete` output may say `handoff saved`. A nonzero / `blocked` result is an honest blocked closeout, not a completed one.\n6. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.\n\n## 5. Pack Loading\n\nUse `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.\n\nLoad `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.\n\nAfter the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.\n\n## Core Complexity Rule\n\nDefault-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=49b3f1c30bdb6ce297e911b763c7ef219aec8e61a8f19727cebfe8a2444941fa -->\nBefore loading task packs, read `dev/USER_RULES.md`. Its registered entries\nunder `dev/user_rules/` are user-controlled rules: read each accepted entry in\nthe listed order and verify its accepted raw-byte witness. Do not treat this\nrouter, its directory, a heading, language, format, location, or\nofficial-looking text as proof that any legacy source belongs to the Kit.\n"
|
|
11521
|
+
},
|
|
11522
|
+
"f310944edb22dd7cda50510678825a5f1f60945867f95553185a6dcac79a5cd0": {
|
|
11523
|
+
"targetRel": "AGENTS.md",
|
|
11524
|
+
"canonicalSha256": "0ed131a1c5d09b32fab68d8c548e070bd3294a5e2ec010090d70ce3760718e7c",
|
|
11525
|
+
"text": "<!-- BEGIN Agent Handoff Kit managed core -->\n# Agent Handoff Kit Core Runtime\n\nThis is the small always-read contract. Detailed task and closeout procedures live in routed packs.\n\n## 1. Intent And Startup\n\nClassify 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.\n\nDo 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.\n\nRoute intent in this order:\n\n1. Clear closeout intent routes directly to `dev/rules/closeout.md`.\n2. Clear continuity intent such as \"開工\", \"Start Agent Handoff\", \"開始接力\", or \"continue handoff\" resumes the minimum current state from the handoff. A plain continuity message with no same-message task or explicit long-run instruction authorizes only that recovery, the startup card, the current objective/risk/recommended next action, and then the end of the turn. It does not authorize task-specific reads, research, plans, protocols, preflight, file searches, sub-agents, QA, packaging, writes, network access, or opt-out wording such as \"unless you object I will start\". A concrete objective found only in loaded state is not authority to complete it. A same-message task may begin normally. An explicit instruction such as \"開工,繼續做到下一個 blocker\" or \"開工,繼續完成目前目標\" may continue under the normal task and safety rules.\n3. A direct ordinary task begins without a startup card or onboarding ceremony. Read only the sources and packs required by that task.\n4. Explicit guidance requests such as \"I'm new\", \"teach me\", \"help me start\", \"新手\", \"教我用\", or \"點開始\" may load `dev/rules/onboarding.md`. A fresh install or short message only makes guidance available; it never overrides a concrete objective. If no executable objective remains after state reading, ask one concise question or offer guided onboarding.\n\nTreat a phrase as ambiguous only when its ordinary meaning may genuinely refer to a real-world shift, event, or unrelated context. `開工,繼續 <task>`, `<project> 開工`, and `Start Agent Handoff and continue <task>` are continuity commands, not ambiguous phrases.\n\nRead `dev/PROJECT_INDEX.md` when the task needs its file, command, integration, workspace, or source map. Read `dev/RULE_PACKS.md` when a task pack must be selected. Read `dev/DOC_SYNC_REGISTRY.md` before durable cross-file or external synchronization and during closeout. Pack loading is normally silent; explain it only when it changes risk, requires a user decision, or materially affects the next action.\n\nIf the user supplies the portable startup prompt, use it to locate the root, then trust the handoff over the mirror. If the root is unclear or mismatched, stop and ask for the intended root before reading or editing project state. Missing required governance files are a repair condition, not permission to invent a parallel structure.\n\nBefore a non-trivial task, identify and read the required local and external truth sources or mark them blocked. Reachable is not the same as ingested. Search hits, truncated output, summaries, and status claims do not replace the relevant source content.\n\nProbe an integration only immediately before a task uses it, when the handoff explicitly identifies it as a dependency for the current objective, or when the user requests an integration health check. `TBD`, examples, blank rows, and undeclared placeholders are not installed integrations. Record `Last Verified` only after a real probe and through the normal persistence gate. Never write integration status merely because a session started.\n\nShow the startup card only for explicit continuity startup. For a plain continuity message, show the card after the minimum state recovery and end the turn; its recommended next action is advice, not permission to act. An explicit same-message task or long-run continuation may combine the card with its first useful action. Direct ordinary tasks do not show the card. If onboarding is explicitly requested, combine any card and guidance in one response.\n\nUse a verified version already present in loaded state. If obtaining it would require reading an otherwise unnecessary file, print `version unverified`; do not create a second version source merely to fill the card.\n\n```text\n /\\_/\\ Agent Handoff Kit v<version>\n ( o.o ) continuity ready\n > ^ <\n\n🔎 交接狀態:<loaded / new install / resumed>\n📌 目前目標:<current objective>\n⚠️ 注意事項:<important boundary or none>\n🚀 推薦下一步:<one action + reason>\n```\n\nUse the full product name, plain user language, and one recommended next action. Never print the literal placeholder `v<version>`.\n\n## 2. Proportionate Work Loop\n\nApply PLAN → READ → CHANGE → QC internally and in proportion to task state and risk. Do not make the user watch governance ceremony that does not help the task.\n\nIn every user-facing reply, lead with ordinary language: state the result and its practical effect, then the next action when one helps. Put exact commands, errors, hashes, and detailed evidence after that; brevity must not hide uncertainty or safety risk.\n\n- 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.\n- Non-trivial work reads relevant sources before changing them.\n- High-risk work states scope, impact, acceptance, and required confirmation before writes.\n- External skill flows, subagents, task plans, demo workspaces, and another tool's finish step do not replace the active root's persistence decision.\n- Materially changed Markdown governance artifacts must be indexed, synchronized, consolidated into their authoritative home, or explicitly classified as temporary / one-time evidence. Other durable formats follow the same human governance rule, but the bundled doctor does not claim to scan them.\n\n## 2.1 Persistence Gate\n\nChoose exactly one tier after a task:\n\n1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.\n2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.\n3. Full closeout: explicit end-of-session / handoff intent, a tool or day boundary, or completed external / release / governance work that the next agent must continue. Load `dev/rules/closeout.md`.\n\nRoute current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.\n\nExternal effects are never implied permission for commit, push, publish, release, deployment, cleanup, or another workspace write. Record verified external impact through the relevant integrations, release, safety, and closeout contracts without exposing private content or secrets.\n\n## 2.2 Upgrade Completion\n\nThe CLI owns upgrade truth. An upgrade is complete only when:\n\n1. The root is not newer than the CLI and every target passes read-only classification.\n2. Conflict produces zero governance-target and version writes.\n3. Staged outputs pass the offline migration acceptance gate: root boundary, structure, cross-file invariants, preservation hashes, and version transition.\n4. The recoverable transaction commits without an unresolved journal; only a failure caused by this transaction triggers rollback.\n5. Whole-project `doctor` reports project health separately. Pre-existing or unrelated health failures do not convert a correct migration into a destructive rollback; new migration-caused blockers do.\n6. The migration report records attempted version, committed version, transaction state, actions, redacted reasons, and backup locations without credential values.\n\nDo not use \"upgrade completed\" to mean \"the entire project is healthy\". Report `migration committed` and `project health` separately. Conflict, incomplete recovery, failed migration acceptance, and future-version roots are not completed upgrades.\n\n## 3. Safety Baseline\n\nDo not delete, reset, overwrite user-owned content, bulk-move, publish, change permissions, or perform another irreversible or external action without the required explicit authorization.\n\nNamed 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.\n\nVerify 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. Permission or lock failure is a stop condition, not permission to elevate or switch to a riskier command.\n\nDo not modify unrelated files or erase unexpected user changes. Do not claim completion without read-back evidence and proportionate checks.\n\n## 4. Closeout Trigger\n\nClear end-of-session or handoff intent such as \"收工\", \"Wrap up Agent Handoff\", \"closeout\", \"wrap up\", or \"handoff\" triggers full closeout, not a chat-only summary. Load `dev/rules/closeout.md` and follow its complete contract. `收工,記得 <handoff requirement>` and equivalent closeout-plus-instruction phrases are clear closeout intent. Ask one concise confirmation only when the phrase genuinely refers to an unrelated real-world closing or shift.\n\nThe always-enforced closeout invariants are:\n\n1. Current state lives in `dev/SESSION_HANDOFF.md`; trace evidence lives in `dev/SESSION_LOG.md`.\n2. Completed, pending, risk, validation, and opening-message lifecycle states agree.\n3. `START_NEXT_SESSION_PROMPT.txt` is regenerated from the sole authoritative handoff block and no third full copy is retained.\n4. Closeout is not complete until required files are written, read back, and the available closeout checks pass.\n5. After those checks, render the final card with `agent-handoff-kit closeout-status --root <project root>`; only its `status: complete` output may say `handoff saved`. A nonzero / `blocked` result is an honest blocked closeout, not a completed one.\n6. Git commit, push, release, publish, deployment, deletion, and permission changes remain separately authorized actions.\n\n## 5. Pack Loading\n\nUse `dev/RULE_PACKS.md` to load the minimum task-specific set. Packs may add stricter requirements but cannot weaken core safety or continuity.\n\nLoad `dev/rules/integrations.md` when the current task actually uses an external tool, not merely because a registry or placeholder table exists. Load `dev/rules/closeout.md` only for full closeout. If two packs conflict, use the safer and more verifiable path and record the unresolved conflict at closeout.\n\nAfter the task, apply the Persistence Gate. Do not assume the next session remembers pack context, and do not use handoff or log as the only home for reusable procedures.\n\n## Core Complexity Rule\n\nDefault-core rules must apply to most sessions, protect safety or continuity, and be shorter than the routed detail they replace. New scenario detail belongs in an existing pack or registered reference; a new pack is justified only when it creates a smaller, independently loadable responsibility with one normative owner.\n<!-- END Agent Handoff Kit managed core -->\n\n<!-- ack:user-rules-router:dev/USER_RULES.md -->\n<!-- ack:user-rules-acceptance:sha256=a7eaf01cdbf4656416cc4f85b23a0ef5eff88e286e7d1dd605ada48244e637a1 -->\nBefore loading task packs, read `dev/USER_RULES.md`. Its registered entries\nunder `dev/user_rules/` are user-controlled rules: read each accepted entry in\nthe listed order and verify its accepted raw-byte witness. Do not treat this\nrouter, its directory, a heading, language, format, location, or\nofficial-looking text as proof that any legacy source belongs to the Kit.\n"
|
|
11346
11526
|
}
|
|
11347
11527
|
},
|
|
11348
|
-
"catalogDigestSha256": "
|
|
11528
|
+
"catalogDigestSha256": "1df61a3edecfa571d455a9b740a0022e8a4a1cf066224e504d17d07ca4faa2d2"
|
|
11349
11529
|
}
|
package/package.json
CHANGED
package/packs/closeout.md
CHANGED
|
@@ -22,9 +22,11 @@ Use Kit markers as machine boundaries: `ack:section:*`, `ack:field:*`, `ack:log-
|
|
|
22
22
|
|
|
23
23
|
Do not copy the full opening message into `dev/SESSION_LOG.md` or any third current governance file. The log records that the mirror was regenerated and verified, plus an evidence reference when useful.
|
|
24
24
|
|
|
25
|
-
## Full Closeout
|
|
26
|
-
|
|
27
|
-
|
|
25
|
+
## Full Closeout
|
|
26
|
+
|
|
27
|
+
Full closeout is differential. Reuse a completed task check only when its recorded root, task input, tool identity, commit / artifact identity, and required file hashes still match the current state. Do not rerun task QA that is already bound to unchanged identity. Do rerun checks affected by closeout writes, gates that are incomplete or indeterminate, closeout-specific checks, and the final `closeout-status` read-back. If a closeout attempt is interrupted, stopped, aborted, times out, or hits a spawn / transport error, resume at the first incomplete or indeterminate gate; do not restart from the beginning unless the root, input, tool identity, commit, artifact, or relevant hash changed.
|
|
28
|
+
|
|
29
|
+
1. Reconcile `dev/SESSION_HANDOFF.md`; never append a new current-state snapshot beneath an old one. Verify durable anchors, then rewrite or explicitly confirm every closeout-reconciled section.
|
|
28
30
|
2. Reconcile lifecycle state across `Completed This Session`, `Validation / QC`, `Next Priorities`, `Risks / Blockers`, and `Next Session Opening Message`. Completed or verified work cannot remain unresolved unless explicitly reclassified as monitor-only, follow-up scope, blocked, or reopened with its missing evidence or trigger.
|
|
29
31
|
The bundled doctor is a mechanical floor for obvious overlap and unresolved fields; it cannot prove that renamed or paraphrased work is semantically consistent. Read all five sections as a whole before marking the lifecycle field resolved. For governance, release, or another project-defined high-risk completion, use the project's independent semantic review gate in addition to doctor.
|
|
30
32
|
3. Make `Next Priorities` name one recommended next action and a short reason unless blocked or a real user decision is required.
|
package/packs/integrations.md
CHANGED
|
@@ -190,14 +190,15 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
190
190
|
2. **External Tool Usage Verification Gate**: verify current runtime schema, official docs, official types/samples, or registered tool operation references before invoking or retrying external tools.
|
|
191
191
|
3. **Declaration before use**: read `dev/PROJECT_INDEX.md` `## Installed Integrations` and `## Tool Operation References` before external-tool or runtime-controlled tool-operation work. If absent, ask about integration status rather than assuming none exists.
|
|
192
192
|
4. **Connector-first default**: when a declared integration is functional, prefer the verified direct tool call. Manual paste is fallback, not default.
|
|
193
|
-
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
193
|
+
5. **Write operations require read-back verification**: read back every external write before claiming success.
|
|
194
194
|
6. **No auto-fix credential / auth issues**: surface auth failures to the user and point to the runtime settings or tool owner.
|
|
195
195
|
7. **Cross-tool capability awareness**: verify availability immediately before use, when the current objective declares the integration as a dependency, or when the user requests a health check.
|
|
196
196
|
8. **Do not cross source-of-truth layers**: follow the role and write direction declared in `PROJECT_INDEX`.
|
|
197
197
|
9. **Drift event mandatory recording**: record integration drift in `PROJECT_INDEX`, `SESSION_LOG`, and `SESSION_HANDOFF` when it affects future work.
|
|
198
198
|
10. **Plugin / Skill subordination**: plugin and skill instructions coexist with rule packs; safety, governance, and closeout rules take precedence on conflict.
|
|
199
199
|
11. **External tool resource lifecycle**: after external-tool use, classify resources by ownership. Task-owned / agent-managed resources may be closed or cleaned automatically; shared, user-owned, system-level, other-agent-owned, or unknown resources require evidence reporting and user confirmation before remediation.
|
|
200
|
-
12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
|
|
200
|
+
12. **Local HTML / app validation fallback**: if `file://` browser access is blocked, do not bypass the policy and do not stop on that single surface failure. Use a registered operation reference or a short-lived loopback localhost service for actual browser / DevTools / Playwright validation, then close the task-owned service and record the evidence.
|
|
201
|
+
13. **Terminal-state contract**: a tool operation succeeds only when the runtime returns an explicit successful terminal state and any required read-back passes. Stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial stdout before termination makes the affected operation indeterminate or failed, not successful. It does not make unrelated already-verified task evidence permanently invalid. For read-only operations, verify the state and rerun only the affected operation when still needed. For any operation that may have written externally or to disk, read back the actual target state before retrying, recovery, or success claims.
|
|
201
202
|
|
|
202
203
|
## Checks
|
|
203
204
|
|
|
@@ -210,7 +211,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
210
211
|
- Before closeout, update `Last Verified` for integrations touched this session.
|
|
211
212
|
- Self-check credential leakage before writing `PROJECT_INDEX`, `SESSION_HANDOFF`, or `SESSION_LOG`.
|
|
212
213
|
- Verify that `PROJECT_INDEX` External Sources `via` references match declared Installed Integrations entries.
|
|
213
|
-
- 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`.
|
|
214
|
+
- For local HTML / app validation, verify that a rejected `file://` attempt is followed by a registered operation reference or short-lived localhost fallback before declaring `blocked`.
|
|
215
|
+
- Treat stopped, aborted, timeout, spawn / transport error, signal, and missing final result as operation-level indeterminate / failed states. Never count partial stdout, a wrapper exit code, or an outer command's success as terminal success without the expected final state and read-back.
|
|
214
216
|
|
|
215
217
|
## Closeout
|
|
216
218
|
|
|
@@ -235,7 +237,8 @@ Integration declarations are project-level; they do not guarantee every AI runti
|
|
|
235
237
|
| Auto-fixing auth or re-auth flows | Auth belongs to the user and the runtime/tool boundary. | Surface the failure and point to the runtime or tool settings. |
|
|
236
238
|
| Claiming an external write succeeded without read-back | External writes may fail silently or partially. | Read back and compare before claiming success. |
|
|
237
239
|
| Crossing source-of-truth layers | It can corrupt truth, mirrors, or working drafts. | Follow the declared layer role and write direction in `PROJECT_INDEX`. |
|
|
238
|
-
| Skipping
|
|
240
|
+
| Skipping current availability verification because an old handoff said the tool worked | Tokens expire, runtimes change, and tools can be removed. | Probe availability in the current runtime before using the integration. |
|
|
241
|
+
| Treating stopped, aborted, timeout, spawn / transport error, signal, missing final result, or partial PASS output as success | Tool output can be partial, wrappers can hide inner failure, and external writes may be unknown. | Mark the affected operation indeterminate or failed; read back any possible write target before retrying or claiming success. |
|
|
239
242
|
| Leaving task-owned MCP / browser / helper processes running after the task | Turns one-off tool use into a long-lived resource leak and can slow the host. | Use graceful close or task-owned process cleanup automatically; switch to user confirmation only when ownership is unclear. |
|
|
240
243
|
| Broadly killing by process name such as `node.exe`, `python`, or `chrome` | A generic process name does not prove ownership and may terminate user work, another project, or another AI agent's active tools. | Classify by tool family, process ID, start time, parent chain, and task-created path; treat unknown ownership as shared. |
|
|
241
244
|
| Automatically cleaning global caches, marketplace caches, OS temp roots, or browser profiles | May remove shared state, login state, or data other tools still need. | Automatically clean only task-owned / agent-managed bounded paths; report evidence and wait for confirmation otherwise. |
|
package/packs/knowledge.md
CHANGED
|
@@ -17,7 +17,7 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
|
|
|
17
17
|
4. Do not perform destructive external writes without explicit confirmation.
|
|
18
18
|
5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
|
|
19
19
|
(a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
|
|
20
|
-
(b) If a declared Integration is functional in the current session (verified
|
|
20
|
+
(b) If a declared Integration is functional in the current session (verified under the task-triggered availability probe in `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
|
|
21
21
|
(c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
|
|
22
22
|
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
|
|
23
23
|
6. When writing to an external mirror or index, read back the written record before claiming sync success.
|
|
@@ -59,8 +59,8 @@ In every user-facing reply, lead with ordinary language: state the result and it
|
|
|
59
59
|
Choose exactly one tier after a task:
|
|
60
60
|
|
|
61
61
|
1. No persistence: no durable fact was produced. One-off answers, transient output, active unapproved drafts, and routine rerunnable checks normally use this tier.
|
|
62
|
-
2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
|
|
63
|
-
3. Full closeout: explicit end-of-session / handoff intent, a
|
|
62
|
+
2. Lightweight checkpoint: a durable fact affects future action while the session continues or may be interrupted. This is the default for ongoing sessions. Write only its smallest correct home; do not regenerate the startup mirror or perform full closeout.
|
|
63
|
+
3. Full closeout: explicit end-of-session / handoff intent, a real day / tool-session boundary, or a state where the current agent cannot continue and the next agent must take over. Ordinary external-tool use, a completed release / governance subtask, or a durable note during an ongoing session is not by itself a full closeout trigger. Load `dev/rules/closeout.md` only when this tier is selected.
|
|
64
64
|
|
|
65
65
|
Route current objective, next action, active risk, blocker, and startup-needed facts to `dev/SESSION_HANDOFF.md`; chronological evidence to `dev/SESSION_LOG.md`; maps to `dev/PROJECT_INDEX.md`; sync obligations to `dev/DOC_SYNC_REGISTRY.md`; long-term rationale to `dev/PROJECT_DECISIONS.md`; and reusable procedures to the relevant pack, registered reference, or QA check. Do not store the same task contract or reusable rule in several homes.
|
|
66
66
|
|