thoth-agents 0.4.2 → 0.5.0

package/plugin/skills/thoth-constitution/SKILL.md

@@ -1,53 +1,34 @@
 ---
 name: thoth-constitution
-description: Create or explicitly amend the project constitution, choose its governance SemVer bump, propagate its impact, and validate lifecycle metadata. Use only for constitution lifecycle work; routine SDD planning reads the constitution without activating this skill.
+description: Create or explicitly amend the active .thoth constitution with SemVer and sync-impact lifecycle validation.
 license: MIT
-compatibility: Requires Node.js >=22.19 for bundled validation scripts.
+compatibility: Requires Node.js >=22.19 for bundled validation.
 metadata:
   author: thoth-agents
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Thoth Constitution
 
-The canonical project constitution is `openspec/memory/constitution.md`.
-Resolve `<skill-dir>` as the directory containing this `SKILL.md`. Every bundled
-validator or template path below is anchored to that installed skill root rather
-than the project or current working directory.
-
-## Routine SDD
-
-- Read every active principle before planning.
-- Record concrete pre-design and post-design Constitution Check evidence in
-  `plan.md`.
-- Do not amend the constitution, bump its version, or run lifecycle validation
-  for an ordinary feature change.
-
-## Explicit amendment
-
-Activate this lifecycle only on explicit user direction or when the user accepts
-a confirmed durable governance change.
-
-1. Read the current constitution and every affected template, instruction, and
-   durable workflow document.
-2. Classify the governance version bump:
-   - **MAJOR** removes or redefines a principle or compatibility boundary.
-   - **MINOR** adds a principle/section or materially expands guidance.
-   - **PATCH** clarifies wording without semantic change.
-3. Preserve the original ratification date, set `Last amended` to today, and
-   update `Version` using complete `MAJOR.MINOR.PATCH` SemVer.
-4. Prepend or refresh the HTML-comment `Sync Impact Report`: old → new version,
-   modified principles, added/removed sections, affected templates with status,
-   and follow-up TODOs.
-5. Propagate the accepted rule to every affected template, instruction, and
-   documentation surface in the same change.
-6. Remove unexplained placeholders and deferred TODOs, then run:
-
-```bash
-node "<skill-dir>/scripts/validate.mjs" \
-  --constitution openspec/memory/constitution.md --json
+Canonical active governance is `.thoth/constitution.md`; substantial change
+records and durable specifications live under `.thoth/`. Historical changes are
+preserved and are not an active workflow dependency. Routine SDD reads relevant
+principles but does not amend constitution metadata.
+
+Only explicit user direction or an accepted material governance change activates
+amendment. Preserve original ratification, set last-amended to the amendment
+date, choose MAJOR for redefinition/removal, MINOR for addition/material
+expansion, PATCH for clarification, and refresh the Sync Impact Report (old/new
+version, modified principles, added/removed sections, affected templates,
+follow-up). This requirement for explicit activation is not replaced by a
+defaulted choice. Any orchestrator choice presented during amendment follows the
+shared per-question recommendation policy; a safe deferral keeps unresolved
+human-owned intent open, and missing facts or secrets are never invented.
+Propagate changes to affected instruction and template surfaces, then run:
+
+```text
+node "<skill-dir>/scripts/validate.mjs" --constitution .thoth/constitution.md --json
 ```
 
-Initialization copies `<skill-dir>/templates/constitution.md` only when the
-project has no constitution, resolves its date placeholders, and never
-overwrites a project-owned constitution.
+Initialization copies the bundled template only when the constitution is absent,
+replaces date placeholders, and never overwrites project-owned governance.

package/plugin/skills/thoth-constitution/templates/constitution.md

@@ -15,57 +15,67 @@ Sync Impact Report
 
 ## Principles
 
-### I. User-value first
+### I. Native authority and human choice
 
-Every change MUST map to an observable user or operator outcome. Speculative
-infrastructure without a current requirement is prohibited.
+The active harness owns dispatch, status, wait, cancellation, and terminal
+results. Workflow guidance MUST NOT build a scheduler, state mirror, or process
+tools. Every change completes proportional explore, specify, and clarify
+reasoning before the orchestrator classifies by meaningful coordination and
+contract impact, uncertainty, and risk. File count alone does not increase scope:
+a clear, low-risk localized mechanical change may touch several files and remain
+small. Material product, architecture, security, and destructive decisions
+remain human-owned; unresolved material intent blocks classification and
+implementation. Whenever an orchestrator presents a choice with a meaningful
+recommended action, it states that recommendation. For each choice separately,
+repeat the same question after the first and second confirmed answerless native
+returns without taking dependent action; after the third, select the
+recommendation. Explicit answers and `Stop` win. Pending, unavailable, failed,
+interrupted, or host-prohibited attempts do not count; report higher-priority
+host limits accurately. Never fabricate facts or secrets. A safe deferral may be
+the recommendation for unresolved human-owned intent and leaves it unresolved.
 
-### II. Simplicity and bounded scope
+### II. Minimal recoverable SDD
 
-Delivery MUST use the smallest coherent design that satisfies accepted
-requirements. Non-goals MUST be named, and scope cannot expand silently.
-Before the SDD route question, Root MUST summarize relevant context, scope,
-clarity, risk, and its evidence-based recommendation. Any explicit answer wins.
-When the native question returns answerless, Root MUST make at most three total
-attempts; after the third answerless result, the recommended route counts as
-selected.
+Small, clear, low-risk work uses test-first implementation and focused
+verification without a persistent record. Substantial work uses one compact
+`.thoth/changes/<id>/<id>.md` record for grounded exploration, intent, acceptance,
+clarifications, decisions, plan, tasks, authorization, and verification. A
+patch-sized change can still require planning when coordination impact,
+uncertainty, or risk warrants it. Increased scope or risk reopens understanding
+and classification. Avoid mandatory sidecar reports, evidence directories,
+worker packets, or generated process tools. Historical changes remain untouched.
+Provider memory is independent of project records.
 
-### III. Testable contracts
+### III. Bounded ownership and verification
 
-Behavioral requirements MUST have observable acceptance evidence. Behavior
-changes MUST use test-first execution at an agreed public seam when practical.
+Delegation depth is one and each mutable surface has one writer. Root accepts
+terminal dependency results before releasing consumers. At substantial `ready`,
+root always offers Oracle plan review (Recommended) or proceeding without review,
+even if implementation was authorized; an unanswered offer never means skip.
+After `[OKAY]`, root separately offers the Implement (Recommended) / Stop choice,
+honors prior explicit authorization, and lets explicit Stop supersede it. Record
+selection provenance as `EXPLICIT_REVIEW`, `EXPLICIT_SKIP`, or
+`DEFAULT_REVIEW_AFTER_3`; only `EXPLICIT_SKIP` permits `SKIPPED`, and `OKAY`
+requires explicit review or the third-return recommendation. A plan review is not
+implementation authorization or final verification. Every change is verified;
+substantial or materially risky work needs a fresh independent Oracle judgment,
+and no implementation writer approves their own work. Archive only after
+complete acceptance evidence and verification still match the actual record and
+sources.
 
-### IV. Independent assurance
+### IV. Durable governance
 
-Every route MUST include verification proportional to the changed behavior and
-risk. The implementation writer cannot approve its own work. Trivial
-deterministic Direct work MAY be verified by Root when the decision is bounded
-and independent of the implementation writer. Materially risky Direct work and
-every Accelerated or Full final verify MUST use a fresh independent read-only
-reviewer. Pre-implementation plan review is optional and is selected explicitly
-or by the bounded recommended fallback; when offered, any explicit answer wins.
-After the third answerless result,
-`Review plan with Oracle (Recommended)` counts as selected. Actionable review
-rejections MUST be repaired and revalidated before a fresh reviewer round until
-approval or a material human-owned blocker. After approval, Root MUST give an
-approved plan summary before asking `Implement (Recommended)` or `Stop`; any
-explicit answer wins, while the third answerless result selects implementation.
-Plan review never substitutes for final verification.
-
-### V. Traceable delivery
-
-Specifications, plans, tasks, implementation evidence, verification verdicts,
-and archive reports MUST remain traceable without relying on chat history.
+Declare ADDED, MODIFIED, REMOVED, or RENAMED requirement deltas by capability and
+exact title against `.thoth/specs/`. Apply only reviewed deltas at transactional
+archive; preserve unaffected canonical requirements and historical changes.
+Recovery inspects retained transactions before retry and never blindly replays
+external effects.
 
 ## Governance
 
-- Planning MUST record evidence-backed Constitution Check results before and
-  after design; routine feature work reads the principles but does not amend or
-  revalidate constitution lifecycle metadata.
-- Exceptions MUST identify the principle, reason, risk, owner, and removal
-  condition.
-- Amendments require explicit user direction, an updated Sync Impact Report,
-  and propagation to affected templates, instructions, and documentation.
-- MAJOR versions remove or redefine governance compatibility.
-- MINOR versions add a principle or materially expand guidance.
-- PATCH versions clarify wording without changing its meaning.
+- Amendments require explicit user direction, a refreshed Sync Impact Report,
+  and propagation to affected templates and instructions.
+- Routine work reads relevant active principles; it does not amend lifecycle metadata.
+- MAJOR versions remove or redefine a principle or compatibility boundary.
+- MINOR versions add principles or materially expand guidance.
+- PATCH versions clarify wording without changing semantic behavior.

package/plugin/skills/thoth-init/SKILL.md

@@ -1,43 +1,33 @@
 ---
 name: thoth-init
-description: Initialize or synchronize the minimum project OpenSpec governance structure required by thoth-agents SDD flows.
+description: Initialize canonical offline .thoth governance without modifying existing project records.
 license: MIT
-compatibility: Requires Node.js >=22.19 and write access to the target project.
+compatibility: Requires Node.js >=22.19 and write access to target project.
 metadata:
   author: thoth-agents
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Thoth Init
 
-Initialize or synchronize the current project's OpenSpec governance from this
-installed skill bundle. Resolve `<skill-dir>` as the directory containing this
-`SKILL.md`, then run the bundled script by absolute path:
+Run the installed script by absolute skill-root path:
 
 ```text
 node "<skill-dir>/scripts/init.mjs" --project <project-root> --json
 ```
 
-The project root must already exist. The initializer preflights the complete
-target structure before changing it, then ensures these minimum paths exist:
-
-- `openspec/changes/archive/`
-- `openspec/specs/`
-- `openspec/memory/`
-- `openspec/.thoth-agents.json`
-
-The missing constitution is copied from the installed sibling
-`thoth-constitution` skill. An existing constitution remains byte-for-byte
-intact, while the thoth-managed manifest may be normalized to the current
-contract. Any legacy `openspec/templates/` tree is outside the managed graph and
-remains untouched. Inspect the JSON `created`, `managed`, and `preserved` arrays
-when reporting the result.
-
-The initializer never creates, copies, validates, reads, or synchronizes SDD
-workflow templates. Those assets remain in the installed `thoth-sdd` skill and
-are consumed directly from that bundle by the workflow phase contracts.
-
-This operation is offline, idempotent, and harness-neutral. Every write stays
-inside `openspec/`. It never installs or synchronizes skills, agents, plugins,
-harness configuration, external dependencies, or global instruction files;
-those are responsibilities of `npx thoth-agents install`.
+For a new project, initialize `.thoth/changes/archive/`, `.thoth/specs/`, and
+`.thoth/constitution.md`. A missing constitution comes from the sibling
+thoth-constitution template with date placeholders filled. Preserve an existing
+constitution and all existing `.thoth` change/spec history byte-for-byte; never
+auto-migrate or overwrite project governance. Refuse symlinked ancestors,
+unknown path collisions, or an active legacy OpenSpec tree rather than creating a
+duplicate active store. Migration is an explicit project change, not an init side
+effect.
+
+The operation is offline and idempotent. It creates no manifests, change records,
+workflow templates, OpenSpec tree, process tools, or mirrored state. Return JSON
+`created` and `preserved` paths. No installer or network access is involved.
+This skill presents no interactive choices and does not infer missing target
+facts. Any orchestrator choice around initialization follows the shared SDD
+recommendation and per-question retry policy.

package/plugin/skills/thoth-init/scripts/init.mjs

@@ -1,24 +1,21 @@
 #!/usr/bin/env node
-
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, parse, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const SKILL_ROOT = dirname(dirname(SCRIPT_PATH));
 const BUNDLE_ROOT = dirname(SKILL_ROOT);
-const OPEN_SPEC_DIRECTORIES = [
-  'openspec',
+const THOTH_DIRECTORIES = [
+  '.thoth',
+  join('.thoth', 'changes'),
+  join('.thoth', 'changes', 'archive'),
+  join('.thoth', 'specs'),
+];
+const LEGACY_ACTIVE_PATHS = [
   join('openspec', 'changes'),
-  join('openspec', 'changes', 'archive'),
   join('openspec', 'specs'),
-  join('openspec', 'memory'),
+  join('openspec', 'memory', 'constitution.md'),
 ];
 
 function parseArgs(argv) {
@@ -33,25 +30,65 @@ function parseArgs(argv) {
   return options;
 }
 
+function lstatMaybe(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return undefined;
+    throw error;
+  }
+}
+
+function assertNoSymlinkAncestors(path, label) {
+  const absolute = resolve(path);
+  const { root } = parse(absolute);
+  let cursor = root;
+  for (const part of absolute.slice(root.length).split(sep).filter(Boolean)) {
+    cursor = join(cursor, part);
+    if (lstatMaybe(cursor)?.isSymbolicLink()) {
+      throw new Error(`${label} has a symlinked ancestor: ${cursor}`);
+    }
+  }
+}
+
 function assertDirectory(path, label) {
-  if (!existsSync(path)) return;
-  const stat = lstatSync(path);
-  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+  assertNoSymlinkAncestors(path, label);
+  const stat = lstatMaybe(path);
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) {
     throw new Error(`${label} must be a directory: ${path}`);
   }
 }
 
 function assertRegularFile(path, label) {
-  if (!existsSync(path)) return;
-  const stat = lstatSync(path);
-  if (stat.isSymbolicLink() || !stat.isFile()) {
+  assertNoSymlinkAncestors(path, label);
+  const stat = lstatMaybe(path);
+  if (stat && (!stat.isFile() || stat.isSymbolicLink())) {
     throw new Error(`${label} must be a regular file: ${path}`);
   }
 }
 
+function assertNoLegacyActiveStore(project) {
+  const openspec = join(project, 'openspec');
+  assertDirectory(openspec, 'Legacy OpenSpec path');
+  for (const relativePath of LEGACY_ACTIVE_PATHS) {
+    const target = join(project, relativePath);
+    assertNoSymlinkAncestors(target, 'Legacy OpenSpec path');
+    if (lstatMaybe(target)) {
+      throw new Error(
+        `Active legacy OpenSpec content requires explicit migration before init: ${target}`,
+      );
+    }
+  }
+}
+
 function preflight(project) {
-  assertDirectory(project, 'Project root');
-  if (!existsSync(project)) {
+  assertNoSymlinkAncestors(project, 'Project root');
+  const projectStat = lstatMaybe(project);
+  if (
+    !projectStat ||
+    !projectStat.isDirectory() ||
+    projectStat.isSymbolicLink()
+  ) {
     throw new Error(
       `--project must reference an existing project directory: ${project}`,
     );
@@ -64,64 +101,40 @@ function preflight(project) {
     'constitution.md',
   );
   assertRegularFile(constitutionSource, 'Bundled constitution template');
-  if (!existsSync(constitutionSource)) {
+  if (!lstatMaybe(constitutionSource)) {
     throw new Error(
       `Bundled constitution template is missing: ${constitutionSource}`,
     );
   }
 
-  for (const directory of OPEN_SPEC_DIRECTORIES) {
-    assertDirectory(join(project, directory), 'OpenSpec path');
+  for (const directory of THOTH_DIRECTORIES) {
+    assertDirectory(join(project, directory), 'Thoth path');
   }
 
-  const constitutionTarget = join(
-    project,
-    'openspec',
-    'memory',
-    'constitution.md',
-  );
-  const manifestTarget = join(project, 'openspec', '.thoth-agents.json');
-  assertRegularFile(constitutionTarget, 'OpenSpec constitution path');
-  assertRegularFile(manifestTarget, 'OpenSpec manifest path');
-
-  return {
-    constitutionSource,
-    constitutionTarget,
-    manifestTarget,
-  };
+  const constitutionTarget = join(project, '.thoth', 'constitution.md');
+  assertRegularFile(constitutionTarget, 'Thoth constitution path');
+  assertNoLegacyActiveStore(project);
+
+  return { constitutionSource, constitutionTarget };
 }
 
 function createDirectory(target, report) {
-  if (existsSync(target)) return;
+  if (lstatMaybe(target)) return;
   mkdirSync(target);
   report.created.push(target);
 }
 
 function writePreservingExisting(target, content, report) {
-  if (existsSync(target)) {
+  if (lstatMaybe(target)) {
     report.preserved.push(target);
     return;
   }
-  writeFileSync(target, content);
+  writeFileSync(target, content, { flag: 'wx' });
   report.created.push(target);
 }
 
-function synchronizeManagedFile(target, content, report) {
-  if (!existsSync(target)) {
-    writeFileSync(target, content);
-    report.created.push(target);
-    return;
-  }
-  if (readFileSync(target, 'utf8') === content) {
-    report.preserved.push(target);
-    return;
-  }
-  writeFileSync(target, content);
-  report.managed.push(target);
-}
-
-function synchronizeOpenSpec(project, assets, report) {
-  for (const directory of OPEN_SPEC_DIRECTORIES) {
+function initializeThoth(project, assets, report) {
+  for (const directory of THOTH_DIRECTORIES) {
     createDirectory(join(project, directory), report);
   }
 
@@ -134,11 +147,6 @@ function synchronizeOpenSpec(project, assets, report) {
     ),
     report,
   );
-  synchronizeManagedFile(
-    assets.manifestTarget,
-    `${JSON.stringify({ version: 1, initializedBy: 'thoth-agents' }, null, 2)}\n`,
-    report,
-  );
 }
 
 try {
@@ -149,15 +157,14 @@ try {
     status: 'ready',
     project,
     created: [],
-    managed: [],
     preserved: [],
   };
 
-  synchronizeOpenSpec(project, assets, report);
+  initializeThoth(project, assets, report);
 
   const output = options.json
     ? JSON.stringify(report)
-    : `thoth-agents synchronized OpenSpec governance in ${project}`;
+    : `thoth-agents initialized .thoth governance in ${project}`;
   process.stdout.write(`${output}\n`);
 } catch (error) {
   process.stderr.write(