dsh-inkstone-agent 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `dsh-inkstone-agent` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-10
+
+### Added
+
+- **Deterministic Authority Kernel (L2)** (`src/kernel/`):
+  - Persistent `Grant` registry with an append-only JSONL event log (`authority.jsonl`) and per-record SHA-256 hash chaining for tamper detection.
+  - Multi-workspace isolation, restart recovery, and audit records (`DecisionRecord`).
+  - Effective write authority computed as strict intersection: `Host Sandbox Root ∩ Effective Grant ∩ Task writeScopes`.
+- **Team Task Interception & Anti-Escalation**:
+  - `team_task_create` with write scopes by a teammate is denied (`INKSTONE_SCOPE_DELEGATION_REQUIRED`).
+  - Task owner editing its own task scopes may only narrow (`INKSTONE_SCOPE_ESCALATION` otherwise); only Lead edits issue grants.
+  - Sensitive files (`.env*`, `*.pem`, `*.key`, `.npmrc`, `id_rsa`, configs with secrets) cannot be delegated through tasks (`INKSTONE_SENSITIVE_SCOPE`).
+- **Transactional Snapshots & Atomic Rollback**:
+  - Byte-exact before/after snapshots for every write tool call (text stored as-is, binary stored as Base64).
+  - 1 MiB truncation safety guard (`ROLLBACK_TRUNCATED`): files exceeding limit record SHA-256 only and prevent erroneous blanking upon rollback.
+  - Pre-rollback after-state conflict verification against current disk content (`ROLLBACK_CONFLICT`).
+  - Human-only `--force` option to override disk conflicts (`/rollback <target> --force`).
+  - Automated secret and credential redaction (`[REDACTED]`) in `tools/post-execute`.
+- **AST Architecture Perception & Contract Handback (L1)** (`src/mandate/`):
+  - `SymbolGraph` and `ImpactAnalyzer` traversing 1–2 hop upstream/downstream call closures (`resolved` and `probable` edges).
+  - Automated detection of broken upstream callers when exported function/interface signatures change.
+  - `mandate_handback` tool: transforms out-of-scope write attempts into structured change requests routed to file owners via `ctx.agentTeams.sendMessage` (messages convey zero authority).
+- **Zero-Trust Tribunal Gate & Attention Firewall (L3)** (`src/tribunal/`, `src/evidence/`):
+  - Interception of `team_task_update(action: 'complete')`.
+  - Multi-provider objective evidence gathering: human verification policy (`.inkstone.policy.json`), snapshot integrity, Git conflict markers (`<<<<<<<`), strict JSON/JSONC parsing, protected file checks, and AST caller consistency.
+  - Hash-bound human approval via `/inkstone-approve [reason]`; subsequent writes invalidate earlier approvals.
+  - `DeadlockWatchdog`: computes failure fingerprints and halts automated retries after `maxTribunalRejections` (default 2), escalating to a 3-choice human attention dialog.
+  - 10-minute timeout for human attention prompts; unanswered or skipped dialogs trigger defensive task termination.
+- **On-Demand Challenge Tasks (M4, Experimental)** (`src/challenge/`):
+  - Lead-opened challenges bound to specific ChangeSet content hashes.
+  - Finding lifecycle (`open` → `reproduced` → `fixed` → `close`), submitted strictly with counterexamples and reproduction steps; findings block completion.
+- **C4 Cross-Session Self-Evolving Immune Memory (L4)** (`src/immune/`):
+  - High-signal experience distillation from tribunal recoveries and human `/rollback` interventions.
+  - Mathematical dynamic scoring with validations boost, time decay, misleading penalties, and Jaccard clustering ($\ge 0.6$).
+  - Automatic injection of historical risk cues into prompt context during `agent/pre-step`.
+- **Interactive Commands & Tools**:
+  - Human slash commands: `/changes`, `/rollback`, `/mandate`, `/inkstone-approve`, `/immune`.
+  - Model autonomous tools: `mandate_analyze`, `mandate_handback`, `tribunal_verify`, `inkstone_rollback`, `inkstone_worktree`, `inkstone_integrate`, `inkstone_challenge`.
+- **Documentation & Workflows**:
+  - Comprehensive, standalone bilingual in-depth workflow tutorials: `docs/TUTORIAL.zh.md` and `docs/TUTORIAL.md`.
+  - Copy-paste ready `.inkstone.policy.json` templates for TypeScript, Python, and Rust/Go projects with executable allow-list specifications.
+  - Added `"docs/*.md"` to `package.json` package files list.
+
+### Changed
+
+- **Host-Only Architecture**: Fully converted into a host-only DSH plugin with zero client bundle footprint; UI elements rely on DSH native rendering.
+- **Simplified Settings Schema**: Consolidated settings into three top-level master switches (`confinementEnabled`, `tribunalEnabled`, `immuneMemoryEnabled`) with secure defaults.
+- **Model Review Off Critical Path**: `tribunalModelReviewEnabled` defaults to `false` and acts as advisory evidence only; missing or unparsable LLM reviews fail-closed into `Unknown`.
+- **CI & Build Modernization**:
+  - Aligned `.github/workflows/ci.yml` to automatically resolve `packageManager` from `package.json` (`pnpm@11.28.5`) via `pnpm/action-setup@v4`.
+  - Added `--ignore-scripts` to CI dependency installation to satisfy pnpm 11 build approval rules.
+- **Removed Obsolete Baseline Checks**: Replaced redundant read-time SHA-256 CAS baseline checks in favor of DSH native `FS_STALE_VERSION`.
+- **Clean Lifecycle Integration**: Public entry points export strictly necessary Cordis contracts; host services (`tools`, `commands`, `agentTeams`, `llm`, `userQuestions`) resolve dynamically at runtime with graceful degradation.
+
+### Fixed
+
+- **Sub-Agent Approval Route**: Addressed DSH sub-agent approval policy pinned to `never`; teammate out-of-scope and sensitive writes are denied directly and forwarded to Lead rather than triggering deadlocked prompts.
+- **Safe Rollback**: Prevented rollbacks from clobbering newer external file modifications using pre-apply disk state verification (`ROLLBACK_CONFLICT`).
+- **Binary-Safe Snapshots**: Preserved non-UTF-8 and binary assets via Base64 encoding rather than corrupted UTF-8 string conversions.
+- **Fail-Closed Authority Kernel**: If the authority kernel or hash-chained log is corrupt, mutations are refused rather than falling back to self-declared scopes.
+- **Markdown Header False Positive**: Fixed Git conflict parser to distinguish Markdown heading underlines (`=======`) from actual conflict blocks.
+- **Deadlock Escalation Timeout**: Added defensive 10-minute timeout to human attention prompts to eliminate indefinite token burn.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fengzhiyushui and dsh-inkstone-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,310 @@
-# Temporary Holding Version
+# dsh-inkstone-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.md) | [简体中文](README.zh.md)
+
+> [!WARNING]
+> **Critical Warnings & Notices**:
+> - **Mandatory Policy File**: Missing `.inkstone.policy.json` **blocks task completion** due to lack of objective evidence.
+> - **Review-Ready Only**: Passing the gate only signals readiness for human review; **never auto-merges or deploys**.
+> - **In-Memory Snapshots & Memory**: File snapshots and C4 immune memories live in process RAM and **reset upon host restart (not persisted)**; raw shell writes (e.g. `>`) bypass hooks.
+
+---
+
+## Table of Contents
+
+- [1. Overview](#1-overview)
+- [2. Quick Installation & Host Integration](#2-quick-installation--host-integration)
+- [3. Quick Start Guide](#3-quick-start-guide)
+- [4. Project Verification Policy (.inkstone.policy.json) Configuration Guide](#4-project-verification-policy-inkstonepolicyjson-configuration-guide)
+  - [4.1 Purpose & Anti-Injection Rules](#41-purpose--anti-injection-rules)
+  - [4.2 Configuration Schema](#42-configuration-schema)
+  - [4.3 Security Allow-List Rules](#43-security-allow-list-rules)
+  - [4.4 Ready-to-Use Templates](#44-ready-to-use-templates)
+- [5. Configuration Parameters](#5-configuration-parameters)
+  - [5.1 Master Switches](#51-master-switches)
+  - [5.2 Complete Parameters Table](#52-complete-parameters-table)
+- [6. Slash Commands & Model Tools Reference](#6-slash-commands--model-tools-reference)
+  - [6.1 Human Slash Commands](#61-human-slash-commands)
+  - [6.2 Model Tools](#62-model-tools)
+- [7. Detailed Tutorials & Workflows (Separate Docs)](#7-detailed-tutorials--workflows-separate-docs)
+- [8. State Persistence & Threat Boundaries](#8-state-persistence--threat-boundaries)
+- [9. Development & Testing](#9-development--testing)
+- [10. Future Roadmap](#10-future-roadmap)
+
+---
+
+## 1. Overview
+
+`dsh-inkstone-agent` is an autonomous engineering host plugin for **DeepSeek Harness (DSH)**. Rather than simply stacking agent quantities, it focuses on deterministic governance: **which files may be touched**, **whether modifications can be rolled back**, and **when a task is genuinely complete**.
+
+### Four Core Pillars
+
+1. **L1 Mandate Engine & AST Semantic Impact**: Traces call graphs and verifies caller integrity when exported signatures change;
+2. **L2 Hard Confinement & Transactional Snapshots**: Hard write boundaries (Sandbox $\cap$ Grant $\cap$ Task Scope), byte-exact before/after snapshots, atomic rollback, and secret redaction;
+3. **L3 Zero-Trust Tribunal & Attention Firewall**: Intercepts task completion, enforces objective policy commands, and breaks deadlocks via human 3-choice attention dialogs;
+4. **L4 C4 Self-Evolving Immune Memory**: Distills high-signal lessons from recoveries and rollbacks to inject historical risk cues before new tasks begin.
+
+---
+
+## 2. Quick Installation & Host Integration
+
+### 2.1 Installation
+
+```bash
+# Method 1: npm registry (recommended)
+pnpm add dsh-inkstone-agent
+
+# Method 2: Direct GitHub installation (pre-built lib/ included in repo)
+pnpm add github:fengzhiyushui/dsh-inkstone-agent
+```
+
+### 2.2 Host Registration (cordis.patch.yml)
+
+Declare the plugin in your DSH `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: dsh-inkstone-agent
+      name: dsh-inkstone-agent
+      config:
+        confinementEnabled: true   # Write boundaries, snapshots & atomic rollback
+        tribunalEnabled: true      # Evidence-based completion gate
+        immuneMemoryEnabled: true  # C4 immune memory distillation & injection
+```
+
+Host services (`tools`, `commands`, `agentTeams`, etc.) are discovered dynamically at runtime with graceful degradation.
+
+---
+
+## 3. Quick Start Guide
+
+1. **Install and register the plugin** in `cordis.patch.yml`;
+2. **Add a minimal policy file** `.inkstone.policy.json` to the workspace root (see Section 4);
+3. **Autonomous coding with atomic safety nets**:
+   - Edits automatically create transactional snapshots;
+   - Use `/changes` to view recent transactions;
+   - Use `/rollback latest` to undo the last edit instantly;
+   - Teammate out-of-scope edits are blocked and redirected to `mandate_handback`.
+
+---
+
+## 4. Project Verification Policy (.inkstone.policy.json) Configuration Guide
+
+### 4.1 Purpose & Anti-Injection Rules
+
+When `tribunalEnabled: true`, **`.inkstone.policy.json` must be present at the workspace root**:
+- **Why Human-Authored**: Agents are physically blocked from modifying this file to prevent prompt injection or weakening verification rules;
+- **Missing File Impact**: Without this file, the tribunal gate cannot establish a trusted verification baseline, resulting in `INKSTONE_EVIDENCE_UNKNOWN` which **blocks task completion**.
+
+### 4.2 Configuration Schema
+
+Located at `<workspaceRoot>/.inkstone.policy.json`:
+
+```json
+{
+  "version": 1,
+  "forbidProtectedChanges": false,
+  "commands": [
+    {
+      "id": "typecheck",
+      "run": "pnpm run typecheck",
+      "required": true,
+      "timeoutMs": 600000
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Default | Description |
+| :--- | :---: | :---: | :---: | :--- |
+| `version` | `number` | **Yes** | `1` | Schema version, must be `1`. |
+| `forbidProtectedChanges` | `boolean` | No | `false` | If protected files (tests, CI, lockfiles) are modified:<br/>• `false`: Pauses for human `/inkstone-approve`;<br/>• `true`: Fails immediately without human override option. |
+| `commands` | `array` | **Yes** | - | Array of verification commands (max 12 commands, max 512 chars each). |
+| `commands[].id` | `string` | **Yes** | - | Unique command identifier (e.g. `typecheck`, `test`, `build`). |
+| `commands[].run` | `string` | **Yes** | - | Command line string (parsed as argument list directly, no shell). |
+| `commands[].required` | `boolean` | No | `true` | When `true`, command must exit with code `0`. |
+| `commands[].timeoutMs` | `number` | No | `600000` | Timeout in milliseconds (default 10 min, max 30 min / `1800000`). |
+
+### 4.3 Security Allow-List Rules
+
+Commands run directly as argv without passing through a shell:
+1. **Allowed Executables**:
+   `pnpm`, `npm`, `yarn`, `bun`, `node`, `npx`, `tsc`, `vitest`, `jest`, `playwright`, `pytest`, `python`, `python3`, `cargo`, `go`, `make`, `mvn`, `gradle`, `dotnet`.
+2. **Forbidden Patterns** (tripping any causes validation failure and blocks completion):
+   - ❌ Executable name with path separators (e.g. `./bin/test`);
+   - ❌ Shell syntax (`;`, `&`, `|`, `>`, `<`, `$`, backticks, parentheses, braces);
+   - ❌ Inline evaluation flags (`node -e`, `python -c`, etc.).
+
+### 4.4 Ready-to-Use Templates
+
+#### Template 1: Minimal Empty Policy (Syntax, Conflict & AST Checks Only)
+```json
+{
+  "version": 1,
+  "forbidProtectedChanges": false,
+  "commands": []
+}
+```
+
+#### Template 2: TypeScript / Node.js Standard Policy
+```json
+{
+  "version": 1,
+  "forbidProtectedChanges": false,
+  "commands": [
+    { "id": "typecheck", "run": "pnpm run typecheck", "required": true, "timeoutMs": 600000 },
+    { "id": "test", "run": "pnpm test", "required": true, "timeoutMs": 900000 },
+    { "id": "build", "run": "pnpm run build", "required": true, "timeoutMs": 900000 }
+  ]
+}
+```
+
+#### Template 3: Python Standard Policy
+```json
+{
+  "version": 1,
+  "forbidProtectedChanges": false,
+  "commands": [
+    { "id": "lint", "run": "pytest --flake8", "required": true },
+    { "id": "test", "run": "pytest tests/", "required": true, "timeoutMs": 600000 }
+  ]
+}
+```
+
+#### Template 4: Rust / Go Standard Policy
+```json
+{
+  "version": 1,
+  "forbidProtectedChanges": false,
+  "commands": [
+    { "id": "check", "run": "cargo check", "required": true },
+    { "id": "test", "run": "cargo test", "required": true, "timeoutMs": 900000 }
+  ]
+}
+```
+
+---
+
+## 5. Configuration Parameters
+
+### 5.1 Master Switches
+
+```yaml
+confinementEnabled: true   # Write boundaries, snapshots & rollback
+tribunalEnabled: true      # Objective completion gate (requires policy file)
+immuneMemoryEnabled: true  # C4 immune memory distillation & injection
+```
+
+### 5.2 Complete Parameters Table
+
+All parameters carry secure built-in defaults defined in [`src/config.ts`](src/config.ts):
+
+| Parameter | Default | Type | Description |
+| :--- | :---: | :---: | :--- |
+| `confinementEnabled` | `true` | `boolean` | Master switch for write confinement & rollback. |
+| `tribunalEnabled` | `true` | `boolean` | Master switch for completion gate and evidence. |
+| `immuneMemoryEnabled` | `true` | `boolean` | Master switch for C4 immune memory. |
+| `requireWriteScopeInTeam` | `true` | `boolean` | Requires teammates to hold task scopes before writing. |
+| `sensitiveFilePolicy` | `'ask'` | `'ask' \| 'deny'` | Policy for sensitive files (.env, keys). |
+| `outOfScopePolicy` | `'handback'` | `'handback' \| 'deny'` | Strategy for out-of-scope edits (`handback` creates request). |
+| `maxSnapshotBytes` | `1048576` (1 MiB) | `number` | File snapshot limit before hash-only truncation guard. |
+| `maxChangeRecords` | `50` | `number` | In-memory change records history ceiling per workspace. |
+| `redactSecrets` | `true` | `boolean` | Auto-redaction of secrets in tool execution outputs. |
+| `tribunalModelReviewEnabled`| `false` | `boolean` | Secondary read-only LLM reviewer pass (default `false`). |
+| `maxTribunalRejections` | `2` | `number` | Rejection threshold before deadlock attention escalation. |
+| `astImpactCheckEnabled` | `true` | `boolean` | AST broken-caller check on modified export signatures. |
+| `maxImmuneExperiences` | `200` | `number` | Experience memory capacity per workspace. |
+
+---
+
+## 6. Slash Commands & Model Tools Reference
+
+### 6.1 Human Slash Commands
+
+> 💡 **Tip**: Intended for human developers in the DSH chat UI. Not callable by agents.
+
+| Command | Syntax | Description |
+| :--- | :--- | :--- |
+| `/changes` | `/changes [limit]` | List recent transactional changes and change IDs. |
+| `/rollback` | `/rollback [latest \| <changeId> \| <taskId> \| <agent>] [--force]` | Roll back changes. `--force` allows overwriting newer edits. |
+| `/mandate` | `/mandate [add <paths...> \| clear \| view]` | Inspect or temporarily expand write grants. |
+| `/inkstone-approve`| `/inkstone-approve [reason]` | Approve high-risk protected file changes on current hash. |
+| `/immune` | `/immune [list \| clear]` | View or clear C4 immune memories. |
+
+### 6.2 Model Tools
+
+| Tool | Parameters | Description |
+| :--- | :--- | :--- |
+| `mandate_analyze` | `target_file`, `symbol_name?`, `hops?` | Analyze 1–2 hop upstream/downstream AST callers. |
+| `mandate_handback` | `target_file`, `requested_change`, `reason`, `target_agent?` | Request owner agent to modify an out-of-scope file. |
+| `tribunal_verify` | `task_id?` | Pre-flight completion evidence check. |
+| `inkstone_rollback` | `target` | Autonomous rollback without `--force`. |
+| `inkstone_worktree` | `action: 'create' \| 'status'` | Git worktree isolation with explicit degradation. |
+| `inkstone_integrate`| `source_root`, `task_id?`, `target_root?` | Serial integration of net diffs (Lead-only). |
+| `inkstone_challenge`| `action: 'open' \| 'report_finding' \| 'resolve_finding' \| 'close' \| 'list'` | Challenge task lifecycle and findings. |
+
+---
+
+## 7. Detailed Tutorials & Workflows (Separate Docs)
+
+For comprehensive, step-by-step practical guides, refer to our dedicated tutorial documents:
+
+- 📖 [**详细使用教程与工作流实战（中文版）**](docs/TUTORIAL.zh.md)
+- 📖 [**In-Depth Usage Tutorial & Workflow Guide (English)**](docs/TUTORIAL.md)
+
+**Topics Covered**:
+1. Multi-Agent Team Coordination, Write Confinement & Handback
+2. Transactional Snapshots, Truncation Guards & Rollback Conflicts
+3. Zero-Trust Tribunal Objective Evidence Chain & 3-State Verdicts
+4. Deadlock Watchdog Fingerprinting & 10-Minute Timeout Attention Cards
+5. On-Demand Challenge Tasks (ChallengeTask) & Finding Lifecycle
+6. C4 Immune Memory Dynamic Scoring, Aging & Pre-Step Injection
+
+---
+
+## 8. State Persistence & Threat Boundaries
+
+### 8.1 Persistence Matrix
+
+| State Type | Location | Survives Restart? |
+| :--- | :--- | :---: |
+| **Grants & Decisions Log** | `<stateDir>/state/authority.jsonl` | **Yes** |
+| **Challenges & Findings** | `<stateDir>/state/authority.jsonl` | **Yes** |
+| **Worktree Registry** | `<stateDir>/state/worktrees.json` | **Yes** |
+| **Policy Command Logs** | `<stateDir>/logs/` | **Yes** |
+| **File Snapshots** | Host In-Memory (RAM) | **No** |
+| **C4 Immune Memory** | Host In-Memory (RAM) | **No** |
+
+### 8.2 Hash-Chained Audit Trail
+`authority.jsonl` uses append-only logging where each record carries the SHA-256 hash of the previous line. External tampering trips hash validation and triggers **fail-closed shutdown**, denying further task updates and writes until repaired.
+
+---
+
+## 9. Development & Testing
+
+```bash
+# 1. Install dependencies (aligned with pnpm@11.28.5)
+pnpm install
+
+# 2. Type checking
+pnpm run typecheck
+
+# 3. Automated tests (6 suites, 12 test cases)
+pnpm test
+
+# 4. Production build (generates lib/index.js & lib/types/)
+pnpm run build
+```
+
+---
+
+## 10. Future Roadmap
+
+- **Automatic Policy Initialization**: Future releases will explore automatically detecting project tech stacks and initializing baseline `.inkstone.policy.json` upon plugin enablement to reduce manual setup overhead;
+- **Memory Plugin Integration**: Current C4 immune memory operates in-memory; we plan to integrate with a memory plugin in the future to achieve persistent, cross-session memory evolution and sharing.
+
+---
+
+## License
+
+[MIT License](LICENSE) © 2026 fengzhiyushui