hermes-task-framework 1.2.0__tar.gz → 1.3.0__tar.gz

{hermes_task_framework-1.2.0 → hermes_task_framework-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-task-framework
-Version: 1.2.0
+Version: 1.3.0
 Summary: Structured task management skills for Hermes Agent — task creation, decomposition, stage gates
 Project-URL: Source, https://github.com/nuffin/hermes-task-framework-pip
 Requires-Python: >=3.11

hermes_task_framework-1.3.0/hermes_task_framework/skills/compact-directory-memory/SKILL.md

@@ -0,0 +1,167 @@
+---
+author: Hauzer S. Lee
+category: software-development
+description: Manage paired MEMORY.md/CHANGELOG.md in flat or nested directory contexts.
+license: MIT
+metadata:
+  hermes:
+    scenes:
+    - hermes
+    - coding
+    tags:
+    - memory
+    - changelog
+    - directory-context
+    - hierarchical-memory
+    - task-framework
+    relations:
+    - type: complemented_by
+      target: task-context-storage
+      properties:
+        reason: task-context-storage defines which persistence layer owns each fact
+        strength: strong
+name: compact-directory-memory
+platforms:
+- linux
+- macos
+version: 3.0.0
+---
+
+# Compact Directory Memory
+
+The authoritative format and maintenance skill for paired `MEMORY.md` and `CHANGELOG.md` files inside projects, tasks, and other directory-managed entities.
+
+`task-framework` decides when task context must be loaded. This skill owns how directory context is structured, formatted, created, read, updated, and verified.
+
+## Context pair
+
+| File | Meaning | Update mode |
+|------|---------|-------------|
+| `MEMORY.md` | Stable expected-state facts, constraints, paths, interfaces, and conventions | Replace stale facts; keep compact |
+| `CHANGELOG.md` | Chronological operations, decisions, verification, failures, and next steps | Append; never rewrite history |
+
+Transient runtime status never belongs in `MEMORY.md`. Record observed execution results in `CHANGELOG.md`.
+
+## MEMORY.md format
+
+```text
+<one declarative fact paragraph>
+
+§
+
+<another declarative fact paragraph>
+
+§
+
+🔴 <critical invariant>
+```
+
+Rules:
+
+- One fact per paragraph, separated by `§` on its own line.
+- No headings, tables, tags, or frontmatter.
+- Use declarative facts, not instructions.
+- Use `🔴` only for enforced invariants.
+- Remove or replace stale facts instead of retaining historical versions.
+- Prefer expected configuration over transient observations.
+- Keep reusable procedures in skills, not MEMORY.md.
+
+## CHANGELOG.md format
+
+Use chronological entries with the newest entry appended at the bottom:
+
+```markdown
+## YYYY-MM-DD HH:MM:SS
+
+**Operation:** What happened.
+**Reason:** Why this approach was selected.
+**Artifacts:** Files, repositories, or outputs changed.
+**Verification:** Commands/checks and real results.
+**Blockers:** Unresolved problems, if any.
+**Next step:** Exact continuation point for another session.
+```
+
+Raw command output belongs in `output/logs/` or another log directory, not in CHANGELOG.md.
+
+## Flat layout
+
+```text
+<entity>/
+├── MEMORY.md
+└── CHANGELOG.md
+```
+
+Use for one project, one task, or one cohesive entity.
+
+## Hierarchical layout
+
+Use when multiple sessions modify distinct subsystems under one long-running task or project:
+
+```text
+<entity>/
+├── MEMORY.md                         # root index and cross-subsystem facts
+├── CHANGELOG.md                      # cross-subsystem chronological summaries
+└── memories/
+    └── <sub-system>/
+        ├── MEMORY.md                 # subsystem-owned stable facts
+        └── CHANGELOG.md              # subsystem operations and verification
+```
+
+Subsystem names are lowercase kebab-case. Every subsystem directory must contain both files.
+
+### Root versus subsystem ownership
+
+- Root `MEMORY.md`: entity identity, subsystem index, cross-subsystem invariants, shared interfaces.
+- Root `CHANGELOG.md`: concise cross-subsystem summary with references to affected subsystem logs.
+- Subsystem `MEMORY.md`: facts owned only by that subsystem.
+- Subsystem `CHANGELOG.md`: detailed work history for that subsystem.
+
+Root files are indexes and syntheses, not copies of subsystem files.
+
+## Read protocol
+
+Before changing a hierarchical entity:
+
+1. Read root `MEMORY.md` completely.
+2. Read recent relevant root `CHANGELOG.md` entries.
+3. Identify the target subsystem.
+4. Read its `MEMORY.md` completely.
+5. Read recent relevant entries from its `CHANGELOG.md`.
+
+## Write protocol
+
+After a verified change:
+
+1. Update subsystem `MEMORY.md` only if stable facts changed.
+2. Append subsystem `CHANGELOG.md` with operation, reason, artifacts, verification, blockers, and next step.
+3. Update root `MEMORY.md` only if the subsystem index or cross-subsystem facts changed.
+4. Append a concise root `CHANGELOG.md` summary naming affected subsystem logs.
+
+## Tooling
+
+Create or extend a hierarchical context:
+
+```bash
+python3 scripts/manage_directory_context.py init <entity-dir> <sub-system> [<sub-system> ...]
+```
+
+Verify required files and naming:
+
+```bash
+python3 scripts/manage_directory_context.py verify <entity-dir>
+```
+
+The script never overwrites existing context files.
+
+## Relationship to task-framework
+
+`task-framework` owns task creation, status, checklist, indexes, and lifecycle. For task context it must:
+
+1. Create root `MEMORY.md` and `CHANGELOG.md`.
+2. Load this skill when hierarchical directory context is requested or detected.
+3. Delegate nested creation, format rules, and validation to this skill.
+4. Preserve `MEMORY.md`, `CHANGELOG.md`, and `memories/` during reset and cleanup.
+
+## Relationship to changelog skill
+
+The continuous `CHANGELOG.md` in this skill preserves cross-session context. The separate `changelog` skill creates immutable `changelog/<timestamp>.<topic>.md` delivery records. They are complementary and must not replace each other.

hermes_task_framework-1.3.0/hermes_task_framework/skills/compact-directory-memory/scripts/manage_directory_context.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Create and verify flat or hierarchical directory context."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+SUBSYSTEM_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+ROOT_MEMORY = """Entity context is managed by compact-directory-memory.
+
+§
+
+Subsystem context index is stored under `memories/`.
+"""
+
+ROOT_CHANGELOG = """# CHANGELOG.md
+
+Append chronological cross-session context entries.
+"""
+
+SUBSYSTEM_MEMORY = """Subsystem: `{subsystem}`.
+
+§
+
+Repository/path: <fill when known>.
+
+§
+
+Responsibilities and boundaries: <fill when known>.
+"""
+
+SUBSYSTEM_CHANGELOG = """# {subsystem} — CHANGELOG.md
+
+Append chronological subsystem operations, decisions, verification, blockers, and next steps.
+"""
+
+
+def ensure_file(path: Path, content: str) -> bool:
+    if path.exists():
+        return False
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def validate_subsystem(name: str) -> None:
+    if not SUBSYSTEM_RE.fullmatch(name):
+        raise ValueError(f"invalid subsystem name: {name!r}; use lowercase kebab-case")
+
+
+def init(entity_dir: Path, subsystems: list[str]) -> int:
+    if not entity_dir.is_dir():
+        print(f"ERROR: entity directory not found: {entity_dir}", file=sys.stderr)
+        return 2
+    created: list[Path] = []
+    if ensure_file(entity_dir / "MEMORY.md", ROOT_MEMORY):
+        created.append(entity_dir / "MEMORY.md")
+    if ensure_file(entity_dir / "CHANGELOG.md", ROOT_CHANGELOG):
+        created.append(entity_dir / "CHANGELOG.md")
+    memories = entity_dir / "memories"
+    memories.mkdir(exist_ok=True)
+    for subsystem in subsystems:
+        validate_subsystem(subsystem)
+        directory = memories / subsystem
+        directory.mkdir(exist_ok=True)
+        memory_file = directory / "MEMORY.md"
+        changelog_file = directory / "CHANGELOG.md"
+        if ensure_file(memory_file, SUBSYSTEM_MEMORY.format(subsystem=subsystem)):
+            created.append(memory_file)
+        if ensure_file(changelog_file, SUBSYSTEM_CHANGELOG.format(subsystem=subsystem)):
+            created.append(changelog_file)
+    for path in created:
+        print(f"created {path.relative_to(entity_dir)}")
+    print(f"initialized directory context: subsystems={len(subsystems)}")
+    return verify(entity_dir)
+
+
+def verify(entity_dir: Path) -> int:
+    errors: list[str] = []
+    for required in ("MEMORY.md", "CHANGELOG.md"):
+        if not (entity_dir / required).is_file():
+            errors.append(f"missing root file: {required}")
+    memories = entity_dir / "memories"
+    if not memories.is_dir():
+        errors.append("missing directory: memories/")
+    else:
+        for directory in sorted(path for path in memories.iterdir() if path.is_dir()):
+            try:
+                validate_subsystem(directory.name)
+            except ValueError as exc:
+                errors.append(str(exc))
+            for required in ("MEMORY.md", "CHANGELOG.md"):
+                if not (directory / required).is_file():
+                    errors.append(f"missing subsystem file: memories/{directory.name}/{required}")
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    subsystem_count = sum(1 for path in memories.iterdir() if path.is_dir())
+    print(f"verified directory context: root files OK, subsystems={subsystem_count}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    init_parser = commands.add_parser("init")
+    init_parser.add_argument("entity_dir", type=Path)
+    init_parser.add_argument("subsystems", nargs="*")
+    verify_parser = commands.add_parser("verify")
+    verify_parser.add_argument("entity_dir", type=Path)
+    args = parser.parse_args()
+    entity_dir = args.entity_dir.expanduser().resolve()
+    try:
+        if args.command == "init":
+            return init(entity_dir, args.subsystems)
+        return verify(entity_dir)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hermes_task_framework-1.3.0/hermes_task_framework/skills/task-archaeology/SKILL.md

@@ -0,0 +1,41 @@
+---
+author: Hermes Agent
+category: software-development
+description: Reconstruct missing session context from canonical task artifacts and repository history.
+license: MIT
+metadata:
+  hermes:
+    scenes: [hermes, research]
+    tags: [task-framework, archaeology, session-recovery, task-recovery, forensics]
+    relations:
+    - type: depends_on
+      target: task-aware-project-work
+      properties: {reason: canonical task context must be read in order, strength: strong}
+    - type: complemented_by
+      target: task-artifact-integrity
+      properties: {reason: validates recovered artifact closure, strength: strong}
+name: task-archaeology
+platforms: [linux, macos]
+version: 2.0.0
+---
+
+# Task Archaeology
+
+Use when session history is missing or incomplete but the user provides a task name, hash, or directory.
+
+## Recovery order
+
+1. Resolve the task with `task_api.py describe <identifier>`; do not pass task directory names as session IDs.
+2. Read `TASK.md`, root `MEMORY.md`, and recent root `CHANGELOG.md`.
+3. When hierarchical, read each relevant subsystem MEMORY and recent CHANGELOG.
+4. Read `README.md` and `.hermes-task.json` for creation time, outputs, and relationships.
+5. Resolve dependencies, related tasks, superseded tasks, and named outputs.
+6. Inventory `input/`, `output/docs/`, `output/logs/`, and scripts.
+7. Cross-reference repository branches and commits by timestamps and artifact paths.
+8. State what is directly evidenced, inferred, missing, and still blocked.
+
+Task artifacts are evidence of task state, not a verbatim transcript. Never invent user statements from file outcomes.
+
+## Result
+
+Return the reconstructed goal, decisions, produced artifacts, verification, unresolved issues, and exact continuation point, with file paths for every claim.

hermes_task_framework-1.3.0/hermes_task_framework/skills/task-artifact-integrity/SKILL.md

@@ -0,0 +1,72 @@
+---
+author: Hermes Agent
+category: software-development
+description: Validate task context closure, artifacts, references, and safe relocation before continuation or deletion.
+license: MIT
+metadata:
+  hermes:
+    scenes: [hermes, coding, research]
+    tags: [task-framework, artifact-integrity, relocation, audit, task-recovery]
+    relations:
+    - type: depends_on
+      target: task-framework
+      properties: {reason: task-framework defines canonical task files and references, strength: strong}
+    - type: complemented_by
+      target: compact-directory-memory
+      properties: {reason: hierarchical context files are part of task closure, strength: strong}
+name: task-artifact-integrity
+platforms: [linux, macos]
+version: 2.0.0
+---
+
+# Task Artifact Integrity
+
+Use when relocating a task root, consolidating related tasks, diagnosing an apparently empty task, or validating that another session can continue safely.
+
+## Context closure
+
+A complete task closure includes:
+
+- `TASK.md`, `README.md`, `MEMORY.md`, `CHANGELOG.md`, `.hermes-task.json`;
+- `memories/<sub-system>/MEMORY.md` and `CHANGELOG.md` pairs when hierarchical;
+- `input/`, `output/`, and `scripts/` inventories;
+- named outputs, dependencies, related/superseded tasks, ticket/project extension fields;
+- absolute paths and cross-task references.
+
+## Inspection
+
+1. Resolve the task through `task_api.py describe`.
+2. Read root and target subsystem context.
+3. Inventory source inputs separately from generated output.
+4. Resolve every related task and named output.
+5. Report missing, empty, stale, or external references before mutation.
+
+## Safe relocation
+
+1. Confirm exact source and destination roots.
+2. Refuse overwrite when destination exists.
+3. Copy metadata-preserving content without `--delete`.
+4. Compare relative path, type, size, and SHA-256 manifests.
+5. Rewrite absolute references only after copy verification.
+6. Append relocation entries to affected CHANGELOG files.
+7. Regenerate both roots' indexes.
+8. Remove source only after equality and reference verification.
+
+Same-machine relocation needs no archive unless requested. Cross-machine transfer or explicit rollback may retain an archive.
+
+## Completion evidence
+
+Report task hashes, roots, input/output inventories, manifest equality, context-pair verification, rewritten references, index regeneration, and source/archive status.
+
+See `references/task-root-relocation.md` for the checklist.
+
+## Permanent tooling
+
+```bash
+python3 scripts/task_integrity.py audit <hash-or-dir>
+python3 scripts/task_integrity.py closure <hash-or-dir>
+python3 scripts/task_integrity.py manifest <hash-or-dir> --output <manifest.json>
+python3 scripts/task_integrity.py compare <source-dir> <destination-dir>
+```
+
+All commands emit JSON and return nonzero when integrity or equality fails.

hermes_task_framework-1.3.0/hermes_task_framework/skills/task-artifact-integrity/references/task-root-relocation.md

@@ -0,0 +1,31 @@
+# Task root relocation checklist
+
+## Invariant
+
+After relocation, canonical files, root and subsystem context, source inputs, generated evidence, named outputs, and related-task references remain resolvable without an undeclared old root.
+
+## Required checks
+
+| Check | Evidence | Failure response |
+|---|---|---|
+| Canonical files | TASK, README, MEMORY, CHANGELOG, metadata are nonempty | Restore/report before source deletion |
+| Hierarchical context | Every subsystem directory has both context files | Repair complete pair before relocation |
+| Source input | `input/` inventory | Locate source owners; never infer emptiness is acceptable |
+| Generated evidence | `output/` and review/log inventory | Preserve evidence or owning task |
+| Related closure | metadata and document references resolve | Move closure or rewrite verified references |
+| Named outputs | every registered output resolves | Repair metadata/path before completion |
+| Copy equality | relative path/type/size/SHA-256 manifests match | Retain source and fail relocation |
+| Indexes | destination and source indexes regenerated | Do not report completion |
+
+## Record
+
+```markdown
+## YYYY-MM-DD HH:MM:SS TZ
+
+**Operation:** Relocated task `<hash>` from `<old-root>` to `<new-root>`.
+**Context closure:** `<related hashes and subsystems>`.
+**Verification:** `<file count and manifest equality>`.
+**References:** `<updated paths or none>`.
+**Indexes:** `<old/new regeneration result>`.
+**Source status:** `<removed after verification / retained>`.
+```

hermes_task_framework-1.3.0/hermes_task_framework/skills/task-artifact-integrity/scripts/task_integrity.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Audit task closure and compare deterministic task manifests."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+
+TASK_SCRIPTS = Path(__file__).resolve().parents[2] / "task-framework" / "scripts"
+sys.path.insert(0, str(TASK_SCRIPTS))
+import task_api  # pyright: ignore[reportMissingImports]  # noqa: E402
+
+CANONICAL = ("TASK.md", "README.md", "MEMORY.md", "CHANGELOG.md", ".hermes-task.json")
+RELATION_KEYS = ("dependencies", "related", "supersedes", "requires", "required_by")
+
+
+def file_hash(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_manifest(root: Path) -> list[dict]:
+    entries: list[dict] = []
+    for path in sorted(root.rglob("*")):
+        relative = path.relative_to(root).as_posix()
+        if relative == ".git" or relative.startswith(".git/"):
+            continue
+        if path.is_symlink():
+            entries.append({"path": relative, "type": "symlink", "target": os.readlink(path)})
+        elif path.is_dir():
+            entries.append({"path": relative, "type": "directory"})
+        elif path.is_file():
+            entries.append(
+                {"path": relative, "type": "file", "size": path.stat().st_size, "sha256": file_hash(path)}
+            )
+    return entries
+
+
+def relation_hashes(metadata: dict) -> list[str]:
+    values: list[str] = []
+    for key in RELATION_KEYS:
+        raw = metadata.get(key, [])
+        if isinstance(raw, list):
+            values.extend(str(item) for item in raw if item)
+    return sorted(set(values))
+
+
+def audit(identifier: str) -> dict:
+    description = task_api.command_describe(identifier)
+    root = Path(description["path"])
+    metadata = description["metadata"]
+    errors: list[str] = []
+    warnings: list[str] = []
+    for name in CANONICAL:
+        path = root / name
+        if not path.is_file():
+            errors.append(f"missing canonical file: {name}")
+        elif path.stat().st_size == 0:
+            errors.append(f"empty canonical file: {name}")
+    memories = root / "memories"
+    hierarchical = metadata.get("memory_layout") == "hierarchical" or memories.is_dir()
+    subsystems: list[str] = []
+    if hierarchical:
+        if not memories.is_dir():
+            errors.append("hierarchical metadata set but memories/ is missing")
+        else:
+            for directory in sorted(path for path in memories.iterdir() if path.is_dir()):
+                subsystems.append(directory.name)
+                for name in ("MEMORY.md", "CHANGELOG.md"):
+                    if not (directory / name).is_file():
+                        errors.append(f"incomplete subsystem context: memories/{directory.name}/{name}")
+    outputs = metadata.get("outputs", {})
+    if isinstance(outputs, dict):
+        for name, raw_path in outputs.items():
+            candidate = root / str(raw_path)
+            if not candidate.exists():
+                errors.append(f"named output does not resolve: {name} -> {raw_path}")
+    unresolved: list[str] = []
+    for task_hash in relation_hashes(metadata):
+        try:
+            task_api.command_describe(task_hash)
+        except FileNotFoundError:
+            unresolved.append(task_hash)
+    if unresolved:
+        errors.append(f"unresolved related task hashes: {', '.join(unresolved)}")
+    for dirname in ("input", "output", "scripts"):
+        if not (root / dirname).is_dir():
+            warnings.append(f"missing standard directory: {dirname}/")
+    return {
+        "task": description,
+        "ok": not errors,
+        "errors": errors,
+        "warnings": warnings,
+        "subsystems": subsystems,
+        "relations": relation_hashes(metadata),
+        "manifest_entries": len(build_manifest(root)),
+    }
+
+
+def closure(identifier: str) -> dict:
+    root = task_api.command_describe(identifier)
+    queue = [root["hash"]]
+    seen: dict[str, dict] = {}
+    unresolved: list[str] = []
+    while queue:
+        current = queue.pop(0)
+        if current in seen:
+            continue
+        try:
+            item = task_api.command_describe(current)
+        except FileNotFoundError:
+            unresolved.append(current)
+            continue
+        seen[current] = item
+        queue.extend(task_hash for task_hash in relation_hashes(item["metadata"]) if task_hash not in seen)
+    return {"root": root["hash"], "tasks": list(seen.values()), "unresolved": sorted(set(unresolved))}
+
+
+def compare(source: Path, destination: Path) -> dict:
+    source_manifest = build_manifest(source.resolve())
+    destination_manifest = build_manifest(destination.resolve())
+    source_map = {entry["path"]: entry for entry in source_manifest}
+    destination_map = {entry["path"]: entry for entry in destination_manifest}
+    missing = sorted(set(source_map) - set(destination_map))
+    extra = sorted(set(destination_map) - set(source_map))
+    changed = sorted(
+        path for path in set(source_map) & set(destination_map) if source_map[path] != destination_map[path]
+    )
+    return {"equal": not missing and not extra and not changed, "missing": missing, "extra": extra, "changed": changed}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    audit_parser = commands.add_parser("audit")
+    audit_parser.add_argument("identifier")
+    closure_parser = commands.add_parser("closure")
+    closure_parser.add_argument("identifier")
+    manifest_parser = commands.add_parser("manifest")
+    manifest_parser.add_argument("identifier")
+    manifest_parser.add_argument("--output", type=Path)
+    compare_parser = commands.add_parser("compare")
+    compare_parser.add_argument("source", type=Path)
+    compare_parser.add_argument("destination", type=Path)
+    args = parser.parse_args()
+    try:
+        if args.command == "audit":
+            result = audit(args.identifier)
+            code = 0 if result["ok"] else 1
+        elif args.command == "closure":
+            result = closure(args.identifier)
+            code = 0 if not result["unresolved"] else 1
+        elif args.command == "manifest":
+            root = Path(task_api.command_describe(args.identifier)["path"])
+            result = build_manifest(root)
+            if args.output:
+                args.output.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+            code = 0
+        else:
+            result = compare(args.source, args.destination)
+            code = 0 if result["equal"] else 1
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return code
+    except (FileNotFoundError, json.JSONDecodeError, OSError) as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hermes_task_framework-1.3.0/hermes_task_framework/skills/task-aware-project-work/SKILL.md

@@ -0,0 +1,42 @@
+---
+author: Hermes Agent
+category: software-development
+description: Load canonical root and subsystem task context before continuing project work.
+license: MIT
+metadata:
+  hermes:
+    scenes: [hermes, coding]
+    tags: [task-framework, task-context, discovery, continuation, project-management]
+    relations:
+    - type: depends_on
+      target: task-context-storage
+      properties: {reason: defines context ownership, strength: strong}
+    - type: depends_on
+      target: compact-directory-memory
+      properties: {reason: defines hierarchical read protocol, strength: strong}
+name: task-aware-project-work
+platforms: [linux, macos]
+version: 2.0.0
+---
+
+# Task-Aware Project Work
+
+Use when continuing a task by name/hash, returning to project work tied to a task, or before creating project artifacts that may already exist.
+
+## Protocol
+
+1. Resolve the task with `task_api.py describe <identifier>`.
+2. Read `TASK.md`, root `MEMORY.md`, and recent root `CHANGELOG.md`.
+3. Detect `.hermes-task.json.memory_layout` or `memories/`.
+4. Identify the target subsystem and read its full MEMORY plus recent CHANGELOG.
+5. Resolve project/repository paths from task context and verify existing artifacts before creating anything.
+6. If a hierarchical subsystem is missing, load `compact-directory-memory` and create the complete pair before source changes.
+
+Legacy `TASK_MEMORY.md` is not canonical. Use it only as archaeological evidence when canonical files are absent.
+
+## Pitfalls
+
+- A ticket is not a task-framework task.
+- Never start implementation before loading task context.
+- Search actual repositories before concluding an artifact was deleted.
+- Do not duplicate a project or subsystem because another session used a different path.