devflow-kit 3.0.0 → 3.1.0

package/src/assets/scripts/hooks/lib/mkdir-lock.cjs

@@ -1,7 +1,9 @@
 // src/assets/scripts/hooks/lib/mkdir-lock.cjs
 //
-// Shared mkdir-based locking helpers used by json-helper.cjs, render-decisions.cjs,
-// and any other CJS hook that needs exclusive access to a shared resource.
+// Shared mkdir-based locking helpers used by learning-store.cjs — whose
+// withDecisionsLock every learning op that writes and the render CLI take, and
+// whose queue claim also takes the queue's own lock — and any other CJS hook that
+// needs exclusive access to a shared resource.
 //
 // DESIGN: mkdir is atomic on POSIX — the kernel guarantees that only one caller
 // succeeds on a given path. On EEXIST we check staleness (mtime > staleMs) and
@@ -44,12 +46,12 @@ function _idleSleep50() {
 /**
  * Acquire a mkdir-based lock. Returns true on success, false on timeout.
  *
- * Stale-break window (applies ADR-017): a lock directory older than `staleMs`
+ * Stale-break window: a lock directory older than `staleMs`
  * (default 60 s) is forcibly removed and the caller retries. This protects against
  * crashed holders but creates a narrow TOCTOU window: if a holder is actively
  * working and takes longer than 60 s, its lock can be stolen — leading to concurrent
- * ledger writes. Current callers (assign-anchor, retire-anchor, refresh-anchor, render CLI) perform
- * only synchronous file I/O + JSON parse and complete well under 60 s in practice,
+ * ledger writes. Current callers (the learning ops through withDecisionsLock, and the
+ * render CLI) perform only synchronous file I/O + JSON parse and complete well under 60 s in practice,
  * so this window is not reachable under normal operation. For long-running callers
  * call refreshLock(lockDir) periodically to reset the mtime and push the deadline
  * out by another staleMs interval.

package/src/assets/scripts/hooks/lib/project-paths.cjs

@@ -57,11 +57,16 @@ function getLearningPendingTurnsPath(projectRoot) {
   return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.jsonl');
 }
 
-/** .devflow/learning/.pending-turns.processing — atomic claim held by the Learning agent while processing */
+/** .devflow/learning/.pending-turns.processing — the claimed batch a Learning run holds while it processes it */
 function getLearningPendingTurnsProcessingPath(projectRoot) {
   return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.processing');
 }
 
+/** .devflow/learning/.pending-turns.owner — the token of the run that holds the claim (learning-store.cjs) */
+function getLearningClaimOwnerPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', '.pending-turns.owner');
+}
+
 // ---------------------------------------------------------------------------
 // Learning content files
 // ---------------------------------------------------------------------------
@@ -96,31 +101,21 @@ function getDecisionsArchivePath(projectRoot) {
   return path.join(projectRoot, '.devflow', 'learning', 'decisions-log.archive.jsonl');
 }
 
+/** .devflow/learning/decisions-history.jsonl — prior content versions of rewritten entries (learning-store.cjs) */
+function getDecisionsHistoryPath(projectRoot) {
+  return path.join(projectRoot, '.devflow', 'learning', 'decisions-history.jsonl');
+}
+
 /** .devflow/learning/.decisions.lock — mkdir-based lock directory */
 function getDecisionsLockDir(projectRoot) {
   return path.join(projectRoot, '.devflow', 'learning', '.decisions.lock');
 }
 
-/** .devflow/learning/.decisions-usage.json */
-function getDecisionsUsagePath(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.decisions-usage.json');
-}
-
-/** .devflow/learning/.decisions-usage.lock/ — mkdir-based lock directory for usage file */
-function getDecisionsUsageLockDir(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.decisions-usage.lock');
-}
-
 /** .devflow/learning/index.md — pre-rendered compact index written by render-decisions.cjs */
 function getDecisionsIndexPath(projectRoot) {
   return path.join(projectRoot, '.devflow', 'learning', 'index.md');
 }
 
-/** .devflow/learning/.observations.lock — mkdir-based lock directory for observation log writes */
-function getObservationsLockDir(projectRoot) {
-  return path.join(projectRoot, '.devflow', 'learning', '.observations.lock');
-}
-
 // ---------------------------------------------------------------------------
 // Memory / working-memory files
 // ---------------------------------------------------------------------------
@@ -185,6 +180,7 @@ module.exports = {
   // Learning queue files
   getLearningPendingTurnsPath,
   getLearningPendingTurnsProcessingPath,
+  getLearningClaimOwnerPath,
   // Learning content files
   getDecisionsFilePath,
   getPitfallsFilePath,
@@ -192,10 +188,8 @@ module.exports = {
   getDecisionsLedgerPath,
   getDecisionsLogPath,
   getDecisionsArchivePath,
+  getDecisionsHistoryPath,
   getDecisionsLockDir,
-  getObservationsLockDir,
-  getDecisionsUsagePath,
-  getDecisionsUsageLockDir,
   getDecisionsIndexPath,
   // Memory files
   getWorkingMemoryPath,