thoth-agents 0.3.5 → 0.3.7

package/plugin/skills/thoth-sdd/references/phases/tasks.md

@@ -3,15 +3,22 @@
 **Owner**: root<br>
 **Output**: `openspec/changes/<feature>/tasks.md`
 
+Start from `<skill-dir>/templates/tasks.md`, where `<skill-dir>` is the directory
+containing the installed `thoth-sdd/SKILL.md`.
+
 Every executable line uses exactly:
 
 ```text
 - [ ] T### [P?] [US#?] description with FR-###/SC-### coverage in `exact/path` | Verify: observable outcome
 ```
 
-IDs are unique and sequential. `[US#]` links story work; omit it only for shared
-setup or closeout. Cover every FR and **buildable** SC. Outcome SCs remain
-verification targets but do not justify artificial implementation tasks.
+IDs start at `T001` and remain unique and sequential across the entire file;
+never reset numbering per story or section. `[P]`, when present, precedes
+`[US#]`; omit `[US#]` only for shared setup or closeout. Before `| Verify:`, use
+exactly one backtick span containing one literal repository-relative path and no
+placeholder, glob, absolute path, URI, home path, or repository escape. Cover
+every FR and **buildable** SC. Outcome SCs remain verification targets but do
+not justify artificial implementation tasks.
 
 Order test-first work before its implementation, group tasks by independently
 deliverable story, identify the MVP, and state dependencies. `[P]` is permitted

package/plugin/skills/thoth-sdd/references/phases/verify.md

@@ -17,6 +17,7 @@ task.
 Return `pass` or `fail`, compliance matrix, commands/results, stable findings,
 critical issues, warnings, and remediation anchors. For Direct, return the
 verdict in-session. For Accelerated and Full, root persists oracle's exact result
-using `templates/verify-report.md`. Fail routes to converge (straight back to
-implement for Direct); PASS permits closeout and archive for artifact-backed
-routes.
+using `<skill-dir>/templates/verify-report.md`, where `<skill-dir>` is the
+directory containing the installed `thoth-sdd/SKILL.md`. Fail routes to converge
+(straight back to implement for Direct); PASS permits closeout and archive for
+artifact-backed routes.

package/plugin/skills/thoth-sdd/templates/plan.md

@@ -6,11 +6,17 @@
 
 ## Constitution Check (pre-design)
 
-Repeat every active Constitution principle by its exact heading. Each entry must
-use one status and concrete evidence; placeholders are invalid in a completed
-plan.
+Read `openspec/memory/constitution.md` and extract every active numbered
+principle heading. Build one ordered name set and reuse it unchanged in both
+Constitution Checks: do not add, remove, abbreviate, or rename a heading between
+the pre-design and post-design lists.
 
-- **[Exact principle heading]**: PASS | JUSTIFIED EXCEPTION | FAIL — [concrete evidence]
+Each entry must use the canonical form
+`- **<exact principle heading>**: <PASS | JUSTIFIED EXCEPTION | FAIL> — <concrete evidence>`.
+Placeholders are invalid, and any `FAIL` blocks task generation. Replace the
+anchor below; do not append entries beside an example list.
+
+<!-- PRE-DESIGN-CONSTITUTION-ENTRIES -->
 
 ## Design
 
@@ -33,6 +39,8 @@ plan.
 
 ## Constitution Check (post-design)
 
-Repeat the same active principles used by the pre-design check.
+Reuse the exact ordered principle names from the pre-design check and provide
+fresh evidence about the completed design. Replace the anchor below; the two
+checks must differ only in status/evidence, never in principle coverage.
 
-- **[Exact principle heading]**: PASS | JUSTIFIED EXCEPTION | FAIL — [concrete design evidence]
+<!-- POST-DESIGN-CONSTITUTION-ENTRIES -->

package/plugin/skills/thoth-sdd/templates/tasks.md

@@ -1,5 +1,20 @@
 # Tasks: [Feature name]
 
+## Authoring contract
+
+Replace every HTML anchor below with real content; do not append new tasks next
+to retained examples. Across the entire file, task identifiers start at `T001`
+and increase by exactly one without resetting for a new story or section.
+
+The canonical task form is:
+``- [ ] T001 [P] [US1] Description with FR-###/SC-### coverage in `path/to/file` | Verify: observable outcome``
+
+`[P]` is optional and must precede the optional `[US#]` tag. Before
+`| Verify:`, each task must contain exactly one backtick span, reserved for one
+literal repository-relative path. Do not use placeholders, globs, absolute or
+home-relative paths, repository escapes, URIs, or extra backticks. Every task
+must end with a concrete `Verify` outcome.
+
 ## MVP scope
 
 [Name the first independently testable story and its completion evidence.]
@@ -10,20 +25,18 @@
 
 ## Story US1
 
-- [ ] T001 [US1] Add the failing behavior test for FR-001 and buildable SC-001 in `[exact/test/path]` | Verify: the focused test fails for the missing behavior
-- [ ] T002 [US1] Implement FR-001 and buildable SC-001 in `[exact/source/path]` | Verify: the focused test passes
-- [ ] T003 [P] [US1] Update independent documentation for FR-001 in `[exact/doc/path]` | Verify: the documented contract matches the tested behavior
+<!-- STORY-US1-TASKS -->
 
 Outcome SCs remain verification targets; do not manufacture implementation tasks
 for them.
 
 ## Parallel execution
 
-[Keep exactly one form below. Use `[P]` only when mutable paths cannot overlap.]
+[Replace the anchor with exactly one form: concrete task pairings covering every
+`[P]` task, or `- None: <evidence-backed reason>`. Never keep both forms.]
 
-- T003 may run with T001 because `[exact/doc/path]` and `[exact/test/path]` do not overlap.
-- None: [reason no tasks can safely overlap]
+<!-- PARALLEL-EXECUTION-EVIDENCE -->
 
 ## Final verification
 
-- [ ] T004 [US1] Map FR-001 and buildable SC-001 evidence in `[verify-report path]` | Verify: oracle records a passing verdict with executed evidence
+<!-- FINAL-VERIFICATION-TASKS -->

package/skills/README.md

@@ -2,8 +2,8 @@
 
 This directory is the canonical, versioned source for skills owned by
 thoth-agents. `pnpm run integration:sync` copies those skills into the Codex and
-Claude Code plugins; OpenCode exposes `/thoth-init`, which materializes them
-project-locally.
+Claude Code plugins; `npx thoth-agents install --agent=opencode` materializes
+the same packaged skill trees globally under `~/.config/opencode/skills/`.
 
 Owned workflow skills are `thoth-init`, `thoth-sdd`, `thoth-constitution`,
 `thoth-archive`, and `plan-reviewer`. The last one implements the optional,
@@ -11,4 +11,6 @@ user-selected, read-only Oracle review before implementation. Mandatory external
 skills (`simplify`, `tdd`,
 `progressive-context-router`, and `architectural-grilling`) are not copied here:
 the thoth-agents installer invokes `npx skills add` against their canonical
-repositories so they retain a single source of truth.
+repositories so they retain a single source of truth. `thoth-init` only
+initializes or synchronizes minimum project `openspec/` governance and never
+installs skills.

package/skills/plan-reviewer/SKILL.md

@@ -26,10 +26,14 @@ Oracle review; mandatory final Oracle verify still applies.
 
 ## Ownership and inputs
 
+Resolve `<skill-dir>` as the directory containing this `SKILL.md`. Every bundled
+asset path in this contract is anchored to that installed skill root rather than
+the project or current working directory.
+
 Root coordinates the phase and dispatches Oracle. Oracle remains read-only: it
 must not edit source, SDD artifacts, or coordination state. Root persists the
 returned review at `openspec/changes/<change>/plan-review.md` using
-`templates/plan-review.md`.
+`<skill-dir>/templates/plan-review.md`.
 
 Review these canonical inputs:
 

package/skills/thoth-archive/SKILL.md

@@ -6,16 +6,20 @@ description: Close a passing artifact-backed thoth-agents change by transactiona
 # Thoth Archive
 
 Archive is the required terminal transition for Accelerated and Full routes.
+Resolve `<skill-dir>` as the directory containing this `SKILL.md`, and resolve
+`<skills-root>` as its parent directory. Bundled paths below are anchored to
+those installed roots rather than the project or current working directory.
 
 1. Confirm every task is `[x]`, `verify-report.md` records independent oracle
    `PASS`, its compliance matrix covers every FR and buildable SC, every outcome
    SC has observed PASS evidence or an explicit residual RISK, and no unresolved
    CRITICAL issue remains.
-2. Prepare `archive-report.md` from the bundled template with status `READY`,
+2. Prepare `archive-report.md` from
+   `<skills-root>/thoth-sdd/templates/archive-report.md` with status `READY`,
    verification lineage, completed scope, deviations, residual warnings, and
    the pending canonical-sync line.
-3. Run the thoth-sdd validator through `closeout`.
-4. Run `scripts/archive.mjs --change <path> --date YYYY-MM-DD --json`.
+3. Run `node "<skills-root>/thoth-sdd/scripts/validate.mjs"` through `closeout`.
+4. Run `node "<skill-dir>/scripts/archive.mjs" --change <path> --date YYYY-MM-DD --json`.
 5. Return the dated archive path, updated capability specifications, and audit
    summary.
 

package/skills/thoth-constitution/SKILL.md

@@ -6,6 +6,9 @@ description: Create or explicitly amend the project constitution, choose its gov
 # 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
 
@@ -36,10 +39,10 @@ a confirmed durable governance change.
 6. Remove unexplained placeholders and deferred TODOs, then run:
 
 ```bash
-node skills/thoth-constitution/scripts/validate.mjs \
+node "<skill-dir>/scripts/validate.mjs" \
   --constitution openspec/memory/constitution.md --json
 ```
 
-Initialization copies `templates/constitution.md` only when the project has no
-constitution, resolves its date placeholders, and never overwrites a
-project-owned constitution.
+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.

package/skills/thoth-init/SKILL.md

@@ -1,30 +1,38 @@
 ---
 name: thoth-init
-description: Initialize project SDD governance and OpenCode local skills from the installed bundle; Codex global agents and instructions remain CLI-owned.
+description: Initialize or synchronize the minimum project OpenSpec governance structure required by thoth-agents SDD flows.
 ---
 
 # Thoth Init
 
-Initialize the current project from this installed skill bundle. Resolve
-`<skill-dir>` as the directory containing this `SKILL.md`, then run the bundled
-script by absolute path:
+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:
 
 ```text
-node "<skill-dir>/scripts/init.mjs" --project <project-root> --harness <opencode|codex|claude> --json
+node "<skill-dir>/scripts/init.mjs" --project <project-root> --json
 ```
 
-- OpenCode materializes the five thoth-owned workflow skills under
-  `.agents/skills/`.
-- Codex init creates project governance only. Codex plugin manifests cannot
-  install custom agents or global instructions; first run the mandatory
-  thoth-agents CLI setup that manages `~/.codex/agents/`,
-  `~/.codex/AGENTS.md`, and `~/.codex/config.toml`.
-- Claude uses auto-discovered plugin agents and owned skills; init creates only
-  project governance assets.
-
-For every harness, installation must already have used the thoth-agents CLI to
-install mandatory external skills from their canonical repositories. This init
-skill never invokes the CLI or downloads a skill.
-
-The operation is offline and idempotent. It never overwrites the project
-constitution, templates, or unrelated instruction content.
+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`.

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

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
 
 import {
-  cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
-  readdirSync,
   readFileSync,
-  statSync,
   writeFileSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -15,12 +13,12 @@ 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 OWNED_SKILL_NAMES = [
-  'thoth-init',
-  'thoth-sdd',
-  'thoth-constitution',
-  'thoth-archive',
-  'plan-reviewer',
+const OPEN_SPEC_DIRECTORIES = [
+  'openspec',
+  join('openspec', 'changes'),
+  join('openspec', 'changes', 'archive'),
+  join('openspec', 'specs'),
+  join('openspec', 'memory'),
 ];
 
 function parseArgs(argv) {
@@ -29,110 +27,137 @@ function parseArgs(argv) {
     const argument = argv[index];
     if (argument === '--json') options.json = true;
     else if (argument === '--project') options.project = argv[++index];
-    else if (argument === '--harness') options.harness = argv[++index];
     else throw new Error(`Unknown argument: ${argument}`);
   }
   if (!options.project) throw new Error('--project is required');
-  if (!['opencode', 'codex', 'claude'].includes(options.harness)) {
-    throw new Error('--harness must be opencode, codex, or claude');
-  }
   return options;
 }
 
-function copyMissing(source, target, report) {
-  if (!existsSync(source)) return;
-  const sourceStat = statSync(source);
-  if (sourceStat.isDirectory()) {
-    mkdirSync(target, { recursive: true });
-    for (const entry of readdirSync(source)) {
-      copyMissing(join(source, entry), join(target, entry), report);
-    }
-    return;
+function assertDirectory(path, label) {
+  if (!existsSync(path)) return;
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`${label} must be a directory: ${path}`);
   }
-  if (existsSync(target)) {
-    report.skipped.push(target);
-    return;
-  }
-  mkdirSync(dirname(target), { recursive: true });
-  cpSync(source, target, { errorOnExist: true });
-  report.created.push(target);
 }
 
-function writeMissing(target, content, report) {
-  if (existsSync(target)) {
-    report.skipped.push(target);
-    return;
+function assertRegularFile(path, label) {
+  if (!existsSync(path)) return;
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`${label} must be a regular file: ${path}`);
   }
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, content);
-  report.created.push(target);
 }
 
-function installConstitution(project, report) {
-  const target = join(project, 'openspec', 'memory', 'constitution.md');
-  const template = join(
+function preflight(project) {
+  assertDirectory(project, 'Project root');
+  if (!existsSync(project)) {
+    throw new Error(
+      `--project must reference an existing project directory: ${project}`,
+    );
+  }
+
+  const constitutionSource = join(
     BUNDLE_ROOT,
     'thoth-constitution',
     'templates',
     'constitution.md',
   );
-  if (!existsSync(template)) return;
-  const today = new Date().toISOString().slice(0, 10);
-  writeMissing(
-    target,
-    readFileSync(template, 'utf8').replaceAll('YYYY-MM-DD', today),
-    report,
+  assertRegularFile(constitutionSource, 'Bundled constitution template');
+  if (!existsSync(constitutionSource)) {
+    throw new Error(
+      `Bundled constitution template is missing: ${constitutionSource}`,
+    );
+  }
+
+  for (const directory of OPEN_SPEC_DIRECTORIES) {
+    assertDirectory(join(project, directory), 'OpenSpec 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,
+  };
 }
 
-function installGovernance(project, report) {
-  installConstitution(project, report);
-  const templatesRoot = join(BUNDLE_ROOT, 'thoth-sdd', 'templates');
-  if (existsSync(templatesRoot)) {
-    for (const entry of readdirSync(templatesRoot)) {
-      copyMissing(
-        join(templatesRoot, entry),
-        join(project, 'openspec', 'templates', entry),
-        report,
-      );
-    }
+function createDirectory(target, report) {
+  if (existsSync(target)) return;
+  mkdirSync(target);
+  report.created.push(target);
+}
+
+function writePreservingExisting(target, content, report) {
+  if (existsSync(target)) {
+    report.preserved.push(target);
+    return;
   }
-  writeMissing(
-    join(project, 'openspec', '.thoth-agents.json'),
-    `${JSON.stringify({ version: 1, initializedBy: 'thoth-agents' }, null, 2)}\n`,
-    report,
-  );
+  writeFileSync(target, content);
+  report.created.push(target);
 }
 
-function installOpenCode(project, report) {
-  for (const skillName of OWNED_SKILL_NAMES) {
-    copyMissing(
-      join(BUNDLE_ROOT, skillName),
-      join(project, '.agents', 'skills', skillName),
-      report,
-    );
+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) {
+    createDirectory(join(project, directory), report);
   }
+
+  const today = new Date().toISOString().slice(0, 10);
+  writePreservingExisting(
+    assets.constitutionTarget,
+    readFileSync(assets.constitutionSource, 'utf8').replaceAll(
+      'YYYY-MM-DD',
+      today,
+    ),
+    report,
+  );
+  synchronizeManagedFile(
+    assets.manifestTarget,
+    `${JSON.stringify({ version: 1, initializedBy: 'thoth-agents' }, null, 2)}\n`,
+    report,
+  );
 }
 
 try {
   const options = parseArgs(process.argv.slice(2));
   const project = resolve(options.project);
-  mkdirSync(project, { recursive: true });
+  const assets = preflight(project);
   const report = {
     status: 'ready',
-    harness: options.harness,
     project,
     created: [],
     managed: [],
-    skipped: [],
+    preserved: [],
   };
 
-  installGovernance(project, report);
-  if (options.harness === 'opencode') installOpenCode(project, report);
+  synchronizeOpenSpec(project, assets, report);
 
   const output = options.json
     ? JSON.stringify(report)
-    : `thoth-agents initialized ${project} for ${options.harness}`;
+    : `thoth-agents synchronized OpenSpec governance in ${project}`;
   process.stdout.write(`${output}\n`);
 } catch (error) {
   process.stderr.write(

package/skills/thoth-sdd/SKILL.md

@@ -37,6 +37,10 @@ Accelerated the minimum recommendation but does not force it.
 
 ## Progressive loading
 
+Resolve `<skill-dir>` as the directory containing this `SKILL.md`, and resolve
+`<skills-root>` as its parent directory. Every bundled path below is anchored to
+one of those installed roots, never to the project or current working directory.
+
 Use only installed local contracts during the pipeline. Never invoke the
 thoth-agents CLI, `npx skills add`, or a network fetch to advance an SDD phase.
 If a required contract or external skill is missing, stop and report an
@@ -46,24 +50,24 @@ Read only the current phase contract:
 
 | Phase | Contract |
 | --- | --- |
-| explore | `references/phases/explore.md` |
-| specify | `references/phases/specify.md` |
-| clarify | `references/phases/clarify.md` |
-| plan | `references/phases/plan.md` |
-| checklist | `references/phases/checklist.md` |
-| tasks | `references/phases/tasks.md` |
-| plan-review | bundled `plan-reviewer` skill |
-| implement | `references/phases/implement.md` |
-| verify | `references/phases/verify.md` |
-| converge | `references/phases/converge.md` |
-| archive | bundled `thoth-archive` skill |
+| explore | `<skill-dir>/references/phases/explore.md` |
+| specify | `<skill-dir>/references/phases/specify.md` |
+| clarify | `<skill-dir>/references/phases/clarify.md` |
+| plan | `<skill-dir>/references/phases/plan.md` |
+| checklist | `<skill-dir>/references/phases/checklist.md` |
+| tasks | `<skill-dir>/references/phases/tasks.md` |
+| plan-review | `<skills-root>/plan-reviewer/SKILL.md` |
+| implement | `<skill-dir>/references/phases/implement.md` |
+| verify | `<skill-dir>/references/phases/verify.md` |
+| converge | `<skill-dir>/references/phases/converge.md` |
+| archive | `<skills-root>/thoth-archive/SKILL.md` |
 
 ## Validation gates
 
-Run the validator from this skill directory:
+Run the validator from its installed absolute path:
 
 ```text
-node scripts/validate.mjs --change openspec/changes/<feature> --route <accelerated|full> --through <specify|plan|tasks|checklist|ready|closeout> --json
+node "<skill-dir>/scripts/validate.mjs" --change openspec/changes/<feature> --route <accelerated|full> --through <specify|plan|tasks|checklist|ready|closeout> --json
 ```
 
 - **Accelerated**: `specify`, then `ready` after the fast-forward planning pass,

package/skills/thoth-sdd/references/phases/checklist.md

@@ -5,6 +5,9 @@
 **Activation**: high contract/failure risk, compliance sensitivity, or
 ambiguity-prone scope
 
+When activated, start from `<skill-dir>/templates/checklist.md`, where
+`<skill-dir>` is the directory containing the installed `thoth-sdd/SKILL.md`.
+
 Record the concrete activation reason. Use sequential `CHK###` items to audit
 the requirements—not implementation—across the base taxonomy: Completeness,
 Clarity, Consistency, Measurability, and Coverage.

package/skills/thoth-sdd/references/phases/plan.md

@@ -3,10 +3,14 @@
 **Owner**: root<br>
 **Output**: `openspec/changes/<feature>/plan.md`
 
-Start from `templates/plan.md`. Read active constitution principles and record
-evidence-backed pre-design and post-design Constitution Checks. Routine SDD does
-not amend the constitution or run its lifecycle validator; activate
-`thoth-constitution` only when an explicit constitution amendment is in scope.
+Start from `<skill-dir>/templates/plan.md`, where `<skill-dir>` is the directory
+containing the installed `thoth-sdd/SKILL.md`. Read active constitution
+principles and record evidence-backed pre-design and post-design Constitution
+Checks. Extract the exact active numbered principle headings once, then reuse
+that same ordered name set in both checks; only status and evidence may differ.
+Routine SDD does not amend the constitution or run its lifecycle validator;
+activate `thoth-constitution` only when an explicit constitution amendment is
+in scope.
 
 Map each technical choice to FR/SC or a confirmed repository constraint. Name
 affected components, interfaces, exact paths, migrations, risks, rollback, and

package/skills/thoth-sdd/references/phases/specify.md

@@ -3,7 +3,9 @@
 **Owner**: root<br>
 **Output**: `openspec/changes/<feature>/spec.md`
 
-Start from `templates/spec.md` and remain implementation-neutral.
+Start from `<skill-dir>/templates/spec.md`, where `<skill-dir>` is the directory
+containing the installed `thoth-sdd/SKILL.md`, and remain
+implementation-neutral.
 
 - Record **Why**, **Impact**, and affected kebab-case capability slugs (or
   `None`).

package/skills/thoth-sdd/references/phases/tasks.md

@@ -3,15 +3,22 @@
 **Owner**: root<br>
 **Output**: `openspec/changes/<feature>/tasks.md`
 
+Start from `<skill-dir>/templates/tasks.md`, where `<skill-dir>` is the directory
+containing the installed `thoth-sdd/SKILL.md`.
+
 Every executable line uses exactly:
 
 ```text
 - [ ] T### [P?] [US#?] description with FR-###/SC-### coverage in `exact/path` | Verify: observable outcome
 ```
 
-IDs are unique and sequential. `[US#]` links story work; omit it only for shared
-setup or closeout. Cover every FR and **buildable** SC. Outcome SCs remain
-verification targets but do not justify artificial implementation tasks.
+IDs start at `T001` and remain unique and sequential across the entire file;
+never reset numbering per story or section. `[P]`, when present, precedes
+`[US#]`; omit `[US#]` only for shared setup or closeout. Before `| Verify:`, use
+exactly one backtick span containing one literal repository-relative path and no
+placeholder, glob, absolute path, URI, home path, or repository escape. Cover
+every FR and **buildable** SC. Outcome SCs remain verification targets but do
+not justify artificial implementation tasks.
 
 Order test-first work before its implementation, group tasks by independently
 deliverable story, identify the MVP, and state dependencies. `[P]` is permitted

package/skills/thoth-sdd/references/phases/verify.md

@@ -17,6 +17,7 @@ task.
 Return `pass` or `fail`, compliance matrix, commands/results, stable findings,
 critical issues, warnings, and remediation anchors. For Direct, return the
 verdict in-session. For Accelerated and Full, root persists oracle's exact result
-using `templates/verify-report.md`. Fail routes to converge (straight back to
-implement for Direct); PASS permits closeout and archive for artifact-backed
-routes.
+using `<skill-dir>/templates/verify-report.md`, where `<skill-dir>` is the
+directory containing the installed `thoth-sdd/SKILL.md`. Fail routes to converge
+(straight back to implement for Direct); PASS permits closeout and archive for
+artifact-backed routes.