Core Analysis¶

Core Capability: The project implements auditing and traceability along three axes:

1. Append-only JSONL run ledger: Key events are appended to JSONL forming a time-series event stream.
2. Human-readable plan files: task_plan.md / progress.md provide context and phase definitions for manual review.
3. Attestation & SHA cache: Plan injection is validated by signatures/hashes, rejecting unattested inputs to prevent tampering at the source.

Technical details & how to use for compliance¶

• Event modeling: Standardize event types (phase-start, phase-complete, action-result, external-confirmation) with fields such as timestamp, actor, phase, status, sha/signature, and metadata for parsing and indexing.
• Immutability: Use append-only writes and keep external backups/versioned copies of ledger files to prevent deletions or tampering.
• Summaries & mapping: Run ledger-summary / phase-status to aggregate events into phase completion views and map each JSONL record back to task_plan.md ### Phase headings.
• Attestation flow: Verify SHA/signatures at plan injection or pull templates from a trusted source; enable reject-unattested to ensure only validated plans are accepted.

Operational recommendations (for compliance)¶

1. Enable attestation by default and manage signatures/hashes via CI/CD onboarding so each plan has verifiable provenance.
2. Standardize event schema and ingest the JSONL stream into ELK/Datadog/TS store for indexed audit queries.
3. Retain ledgers long-term per retention policy and keep read-only backups for forensics.
4. Document mappings that tie ledger events to task_plan.md phases and to compliance checkpoints.

Important Notice: Attestation increases security but may cause injection failures during initial integration—configure and test in a controlled environment first.

Summary: The combination of JSONL ledger, Markdown plans, and attestation creates a readable, machine-parseable, and verifiable audit trail suitable for traceability and compliance in coding-agent scenarios.

Core Analysis¶

Core Issue: The gated completion gate is a safety layer executed at the agent Stop-hook to ensure that an agent does not terminate before all defined plan milestones are actually complete. It is designed for long-running, multi-stage, or human-in-the-loop tasks.

How it works (technical overview)¶

• Trigger point: The gate runs in the agent Stop-hook via check-complete.sh/.ps1.
• Decision inputs: The script examines task_plan.md ### Phase headings, progress.md, and the JSONL ledger (via ledger-summary / phase-status) to determine whether required phases have completed or if a block cap is reached.
• Blocking behavior: If completion criteria are unmet, Stop is blocked (the agent remains running or waits for human intervention) until conditions are met or a timeout/manual override occurs.

When to use gated¶

1. Operations requiring strong guarantees or non-reversible actions: production releases, DB migrations, or staged deployments where skipping a step is unacceptable.
2. Human approval/confirmation points: tasks that require manual verification before advancing.
3. Multi-agent orchestration needing milestone alignment: when multiple agents must reach agreed checkpoints and those checkpoints must be auditable.

When to use autonomous¶

• Short, reversible automation: tasks such as formatting, one-off scripts, or operations that don’t affect external systems and can be safely retried.

Practical tips¶

1. Define clear ### Phase headings and completion criteria before enabling gated; validate check-complete with tests.
2. Configure sensible block caps and timeouts and provide a documented manual override path.
3. Use ledger-summary and monitoring/alerts to detect long-running blocks.

Important Notice: Gated provides stronger guarantees but increases operational overhead. If completion criteria are hard to quantify or external dependencies often delay progress, consider using autonomous first or improving observability on gated.

Summary: Use gated for critical, non-reversible flows and autonomous for lightweight automation. The choice depends on failure impact and observability.

Core Analysis¶

Project Positioning: planning-with-files intentionally persists plans and progress as Markdown and JSONL files to move agent state out of volatile model context. This design prioritizes portability and auditability over the operational complexity of running a centralized service or database.

Technical Features and Advantages¶

• Portability & low ops: No database or extra services are required, making it easy to run in local, IDE, or minimal container environments.
• Auditability: Human-friendly Markdown and an immutable JSONL event stream make manual and automated auditing straightforward.
• Runtime-agnostic consistency: SKILL.md hooks enable consistent behavior across many agent runtimes with reusable scripts and templates.

Key Trade-offs (Limitations)¶

1. Concurrency & races: Concurrent writes by multiple agents to the same directory can cause conflicts; the project does not provide distributed locking or merge logic.
2. Cross-host synchronization: There is no built-in multi-host sync; external sync (e.g., git, NFS, centralized storage) is required for multi-host collaboration.
3. Strong consistency & high throughput: For transactional or high-concurrency workloads, file-based models are less robust than databases or queue systems.

Practical Recommendations¶

1. Use the native file-based approach for single-host or IDE/plugin scenarios to get fast integration and auditability.
2. For multi-agent/multi-host setups, add an external synchronization layer (git sync, centralized storage, or a lock service) to avoid races.
3. If real-time coordination or high throughput is required, use planning-with-files as a durable/audit layer and add a centralized queue/transaction layer for coordination.

Important Notice: File-based persistence is not inherently unreliable—it’s a trade-off that emphasizes understandable persistence. For cross-host deployments, explicitly design synchronization and locking.

Summary: The file-centric approach trades off centralized consistency for portability, low operations, and auditability—well-suited to coding-agent use cases but requiring supplemental synchronization for distributed scenarios.

Core Analysis¶

Core Issue: planning-with-files does not include built-in distributed locks or merge logic. Concurrent writes by multiple agents to the same plan directory can produce races and overwrites; therefore, you must address concurrency at the deployment and application level.

Concrete engineering practices¶

1. Git as a serialization layer:
   - Put the plan directory under a git repo; agents pull before writes and commit & push afterwards. Use branch/PR workflows or file-lock files to serialize edits.
   - Pros: audit history, easy integration; Cons: added latency and conflict resolution.

2. Centralized storage + lock service:
   - Use a centralized file store (S3 + DynamoDB lock, NFS + etcd locks) to provide global locks and atomic writes.
   - Suitable for multi-host production deployments.

3. Application-level optimistic concurrency:
   - Include version or hash on each write; compare current version before commit and reject/merge on conflicts.
   - For JSONL, prefer atomic append operations to avoid read-modify-write overwrites.

4. Enhanced ledger validation & rollback:
   - After writes, immediately generate signatures/SHA and store them in the attestation cache; in conflicts, use ledger-based rollback/replay to restore a consistent state.

5. Platform compatibility tests:
   - Validate realpath, short names (8.3), and file encodings on Windows to avoid silent injection failures (as fixed in v3.2.0).

Practical recommendations¶

1. Use git-sync for lightweight scenarios and a lock service for high-concurrency/multi-host setups.
2. Treat the ledger as the ultimate source of truth: record all merge/rollback actions in JSONL for auditability.
3. Integrate attestation/signing into write workflows so outputs remain verifiable after conflict resolution.

Important Notice: Don’t rely solely on filesystem permissions to prevent concurrency—this approach does not scale. Make concurrency control an explicit architectural concern.

Summary: Combining infra-level synchronization (git/lock service), app-level version checks and atomic appends, plus ledger+attestation-backed conflict records and rollback, provides a robust solution to concurrency and data-loss risks in multi-agent deployments.

Core Analysis¶

Core Issue: Most failures or integration pain points with planning-with-files stem from installation/configuration and platform differences rather than core runtime flaws. Key issues are SKILL.md frontmatter YAML errors, Windows path/encoding quirks, misconfigured gated mode, concurrent writes by multiple agents, and immature attestation workflows that reject plan injection.

Technical Analysis¶

• YAML/frontmatter: The v3.1.3 fix highlights that invalid SKILL.md YAML can block skill loading; frontmatter must be syntactically correct and validated at install time.
• Platform differences: v3.2.0 shows session-catchup.py silently failed on Windows, so explicit handling of Windows paths (short names/8.3) and file encodings is required.
• Gated configuration risk: Missing ### Phase headings or improper block caps can cause Stop-hook misjudgment (e.g., “0/0 phases”) or indefinite waiting.
• Concurrent writes: The file-based model is prone to conflicts when multiple agents write the same directory; use external locks or sync strategies.
• Attestation: The default ‘reject unattested’ policy necessitates a prepared SHA cache/signing workflow to avoid rejected injections.

Practical Recommendations (reduce production risk)¶

1. Template & validate: Use provided templates (e.g., task_plan_autonomous.md) and add SKILL.md frontmatter/YAML checks to CI.
2. Install rehearsal: Perform a full install and session-catchup recovery on target platforms including Windows to validate path/encoding handling.
3. Gated dry runs: Enable gated in staging first, and verify ledger-summary and phase-status reflect expected milestones.
4. Concurrency strategy: For multi-agent setups, introduce external sync (git sync, centralized storage, or a file-lock service) to prevent direct concurrent writes.
5. Roll out attestation gradually: Configure SHA cache and signing in a controlled environment before enabling ‘reject-unattested’ in production.

Important Notice: Don’t enable gated and reject-unattested simultaneously on day one—validate subsystems stepwise.

Summary: Using templates, CI checks, platform-specific testing, and staged enablement of gate/attestation reduces learning curve friction and production integration risk.