hadara 0.3.0-rc.0 → 0.3.0-rc.1

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <img alt="Release candidate" src="https://img.shields.io/badge/npm-0.3.0--rc.0-blue">
+  <img alt="Published npm release" src="https://img.shields.io/badge/npm-0.3.0--rc.0-blue">
   <img alt="Node.js" src="https://img.shields.io/badge/node-%3E%3D22-brightgreen">
   <img alt="License" src="https://img.shields.io/badge/license-MIT-lightgrey">
 </p>
@@ -20,7 +20,13 @@ This repository is both the HADARA source checkout and the HADARA protocol works
 
 ## Release Status
 
-Current release candidate:
+Current release candidate prepared for operator publish:
+
+```text
+hadara@0.3.0-rc.1
+```
+
+Current published npm release:
 
 ```text
 hadara@0.3.0-rc.0
@@ -28,7 +34,7 @@ hadara@0.3.0-rc.0
 
 The 0.3.0 line is the Phase 7 Surface Refactor. It organizes HADARA's existing task, evidence, proof, lifecycle, release, and document surfaces so agents can distinguish primary lifecycle commands, diagnostics, advanced surfaces, canonical documents, historical documents, and safe Markdown update boundaries.
 
-Phase 7.x labels are internal implementation phases, not npm release-candidate labels. Publishing `0.3.0-rc.0` or any later release still requires the approval-gated release path and explicit operator confirmation.
+Phase 7.x labels are internal implementation phases, not npm release-candidate labels. Publishing `0.3.0-rc.1` or any later release still requires the approval-gated release path and explicit operator confirmation.
 
 | Surface | Status |
 |---|---|
@@ -36,7 +42,8 @@ Phase 7.x labels are internal implementation phases, not npm release-candidate l
 | `hadara@0.2.0-rc.1` | Previous published npm RC. |
 | `hadara@0.2.0-rc.2` | Previous published npm RC. |
 | `hadara@0.2.0-rc.3` | Previous published npm RC. |
-| `hadara@0.3.0-rc.0` | Current release candidate. |
+| `hadara@0.3.0-rc.0` | Current published npm RC; package metadata lacks the intended discovery fields. |
+| `hadara@0.3.0-rc.1` | Current publish candidate; T-0301 prepares the operator-confirmed npm publish path. |
 | GitHub Release | Secondary target, approval-gated. |
 | Docker image | Deferred. |
 | PyPI/Python package | `hadara==0.2.0rc1` published preview bridge. |
@@ -48,7 +55,7 @@ No release command should publish, create a GitHub Release, build Docker images,
 
 Requires Node.js 22.
 
-Install this release candidate:
+Install the latest published RC before the T-0301 publish step:
 
 ```bash
 npm install -g hadara@0.3.0-rc.0
@@ -63,6 +70,14 @@ npx hadara@0.3.0-rc.0 help
 npx hadara@0.3.0-rc.0 doctor --json
 ```
 
+After the T-0301 npm publish helper verifies `hadara@0.3.0-rc.1` on the registry, install the new RC:
+
+```bash
+npm install -g hadara@0.3.0-rc.1
+hadara help
+hadara doctor --json
+```
+
 ## What HADARA Gives You
 
 | Capability | Purpose |

package/dist/cli/protocol.js

@@ -2,10 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleProtocolCommand = handleProtocolCommand;
 const protocol_consistency_1 = require("../services/protocol-consistency");
+const protocol_migration_1 = require("../services/protocol-migration");
 const protocol_remediation_1 = require("../services/protocol-remediation");
 const args_1 = require("./args");
 function handleProtocolCommand(input) {
     const sub = input.args[1];
+    if (sub === 'migrate')
+        return handleProtocolMigrateCommand(input);
     if (sub === 'remediate')
         return handleProtocolRemediateCommand(input);
     if (sub !== 'doctor')
@@ -62,6 +65,40 @@ function handleProtocolCommand(input) {
         process.exitCode = 6;
     return true;
 }
+function handleProtocolMigrateCommand(input) {
+    const target = (0, args_1.getStringOption)(input.args, '--target', '0.3.0') ?? '0.3.0';
+    if (target !== '0.3.0')
+        throw new args_1.CliArgsError('CLI_OPTION_INVALID_VALUE', `unsupported protocol migration target: ${target}`);
+    const profile = (0, args_1.getStringOption)(input.args, '--profile');
+    if (profile !== undefined && profile !== 'basic' && profile !== 'standard' && profile !== 'governed' && profile !== 'hadara-dev') {
+        throw new args_1.CliArgsError('CLI_OPTION_INVALID_VALUE', `unsupported HADARA profile: ${profile}`);
+    }
+    const report = (0, protocol_migration_1.createProtocolMigrationReport)({
+        projectRoot: input.projectRoot,
+        target,
+        mode: (0, args_1.getFlag)(input.args, '--execute') ? 'execute' : 'dry-run',
+        beforeHash: (0, args_1.getStringOption)(input.args, '--before-hash'),
+        taskId: (0, args_1.getStringOption)(input.args, '--task'),
+        profile
+    });
+    if (input.jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else if (report.ok) {
+        console.log(`[HADARA] Protocol migration ${report.mode}: ${target}`);
+        for (const action of report.actions) {
+            console.log(`- ${action.status}: ${action.summary}${action.path ? ` (${action.path})` : ''}`);
+        }
+    }
+    else {
+        console.log(`[HADARA] Protocol migration failed: ${target}`);
+        for (const issue of report.issues)
+            console.log(`- ${issue.code}: ${issue.message}${issue.path ? ` (${issue.path})` : ''}`);
+    }
+    if (!report.ok)
+        process.exitCode = 6;
+    return true;
+}
 function handleProtocolRemediateCommand(input) {
     const fix = (0, args_1.getStringOption)(input.args, '--fix');
     if (!fix)

package/dist/core/schema.js

@@ -37,6 +37,7 @@ const package_smoke_schema_json_1 = __importDefault(require("../schemas/package-
 const plan_context_schema_json_1 = __importDefault(require("../schemas/plan-context.schema.json"));
 const private_evidence_schema_json_1 = __importDefault(require("../schemas/private-evidence.schema.json"));
 const protocol_consistency_schema_json_1 = __importDefault(require("../schemas/protocol-consistency.schema.json"));
+const protocol_migration_schema_json_1 = __importDefault(require("../schemas/protocol-migration.schema.json"));
 const protocol_remediation_schema_json_1 = __importDefault(require("../schemas/protocol-remediation.schema.json"));
 const provider_call_schema_json_1 = __importDefault(require("../schemas/provider-call.schema.json"));
 const provider_config_schema_json_1 = __importDefault(require("../schemas/provider-config.schema.json"));
@@ -101,6 +102,7 @@ const registeredSchemas = {
     'hadara.plan_context.v1': plan_context_schema_json_1.default,
     'hadara.privateEvidence.v1': private_evidence_schema_json_1.default,
     'hadara.protocol.consistency.v1': protocol_consistency_schema_json_1.default,
+    'hadara.protocol.migration.v1': protocol_migration_schema_json_1.default,
     'hadara.protocol.remediation.v1': protocol_remediation_schema_json_1.default,
     'hadara.provider.call.v1': provider_call_schema_json_1.default,
     'hadara.provider.config.v1': provider_config_schema_json_1.default,

package/dist/schemas/protocol-migration.schema.json

@@ -0,0 +1,111 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "hadara.protocol.migration.v1",
+    "x-hadara-schema-id": "hadara.protocol.migration.v1",
+    "title": "HADARA Protocol Migration Report",
+    "type": "object",
+    "additionalProperties": true,
+    "required": ["schemaVersion", "command", "ok", "mode", "target", "scope", "projectRoot", "detection", "summary", "actions", "issues"],
+    "properties": {
+        "schemaVersion": { "const": "hadara.protocol.migration.v1" },
+        "command": { "const": "protocol.migrate" },
+        "ok": { "type": "boolean" },
+        "mode": { "type": "string", "enum": ["dry-run", "execute"] },
+        "target": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["protocolVersion"],
+            "properties": {
+                "protocolVersion": { "const": "0.3.0" }
+            }
+        },
+        "scope": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["kind", "taskId"],
+            "properties": {
+                "kind": { "type": "string", "enum": ["project", "task"] },
+                "taskId": {
+                    "anyOf": [
+                        { "type": "string", "pattern": "^T-[0-9]{4,}$" },
+                        { "type": "null" }
+                    ]
+                }
+            }
+        },
+        "projectRoot": { "type": "string", "minLength": 1 },
+        "detection": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["scaffoldGeneration", "profile", "docsRegistryPresent", "docsRegistryValid", "commandSurfaceDocPresent", "requiredReadingManaged", "managedSectionsPresent", "taskCapsulePresent"],
+            "properties": {
+                "scaffoldGeneration": { "type": "string", "enum": ["pre-0.3", "0.3", "partial-0.3", "unknown"] },
+                "profile": { "type": "string", "enum": ["basic", "standard", "governed", "hadara-dev"] },
+                "docsRegistryPresent": { "type": "boolean" },
+                "docsRegistryValid": { "type": "boolean" },
+                "commandSurfaceDocPresent": { "type": "boolean" },
+                "requiredReadingManaged": { "type": "boolean" },
+                "managedSectionsPresent": { "type": "boolean" },
+                "taskCapsulePresent": {
+                    "anyOf": [
+                        { "type": "boolean" },
+                        { "type": "null" }
+                    ]
+                }
+            }
+        },
+        "summary": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["planned", "changed", "skipped", "beforeHash"],
+            "properties": {
+                "planned": { "type": "integer" },
+                "changed": { "type": "integer" },
+                "skipped": { "type": "integer" },
+                "beforeHash": {
+                    "anyOf": [
+                        { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+                        { "type": "null" }
+                    ]
+                }
+            }
+        },
+        "actions": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/action" }
+        },
+        "issues": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/issue" }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["id", "path", "status", "summary"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 },
+                "status": { "type": "string", "enum": ["planned", "created", "updated", "skipped"] },
+                "summary": { "type": "string", "minLength": 1 },
+                "before": { "type": "string" },
+                "after": { "type": "string" },
+                "expectedBeforeExists": { "type": "boolean" },
+                "expectedBeforeHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+                "afterHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+        },
+        "issue": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["severity", "code", "message"],
+            "properties": {
+                "severity": { "type": "string", "enum": ["error", "warning", "info"] },
+                "code": { "type": "string", "minLength": 1, "pattern": "^[A-Z0-9_:-]+$" },
+                "message": { "type": "string", "minLength": 1 },
+                "path": { "type": "string", "minLength": 1 }
+            }
+        }
+    }
+}

package/dist/schemas/schema-index.json

@@ -197,6 +197,13 @@
             "owner": "protocol/remediation",
             "notes": "Documents dry-run-first protocol remediation plans, report-level before-hash guards, and bounded execute reports."
         },
+        {
+            "id": "hadara.protocol.migration.v1",
+            "path": "src/schemas/protocol-migration.schema.json",
+            "status": "fixture",
+            "owner": "protocol/migration",
+            "notes": "Documents dry-run-first 0.3 protocol migration plans for existing project and selected Task Capsule scopes."
+        },
         {
             "id": "hadara.task.upgrade_scaffold.v1",
             "path": "src/schemas/task-upgrade-scaffold.schema.json",

package/dist/services/capability-registry.js

@@ -701,6 +701,31 @@ exports.HADARA_COMMAND_REGISTRY = [
         related: ['protocol.doctor', 'task.upgrade-scaffold'],
         conflictsWith: []
     }),
+    commandEntry({
+        id: 'protocol.migrate',
+        command: 'hadara protocol migrate --target 0.3.0 [--task <task-id>] [--profile basic|standard|governed|hadara-dev] [--execute --before-hash <hash>] [--json]',
+        summary: 'Preview or apply the 0.3 protocol migration for existing HADARA projects or selected Task Capsules.',
+        canonical: true,
+        appearsInDefaultHelp: false,
+        family: 'docs-governance',
+        scope: 'project',
+        lifecycleStage: 'work',
+        requiredness: 'conditional',
+        writeBoundary: 'shared-doc-write',
+        readOnly: false,
+        risk: 'medium',
+        actor: 'operator',
+        status: 'stable',
+        schemaVersion: 'hadara.protocol.migration.v1',
+        since: '0.3.0-rc.1',
+        docs: ['docs/specs/0.3.0/rc1/00_Protocol_Migration_for_0_3_Adoption.md', 'docs/IMPLEMENTATION_SOP.md'],
+        examples: [
+            example('Preview project migration', 'hadara protocol migrate --target 0.3.0 --json', 'When upgrading a pre-0.3 initialized HADARA project.'),
+            example('Preview task migration', 'hadara protocol migrate --target 0.3.0 --task T-0001 --json', 'When migrating one selected older Task Capsule.')
+        ],
+        related: ['protocol.doctor', 'docs.doctor', 'docs.managed.list', 'init.upgrade'],
+        conflictsWith: []
+    }),
     commandEntry({
         id: 'docs.list',
         command: 'hadara docs list [--status <status>] [--read-when <read-when>] [--json]',

package/dist/services/protocol-migration.js

@@ -0,0 +1,396 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProtocolMigrationReport = createProtocolMigrationReport;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const task_capsule_1 = require("../task/task-capsule");
+const capability_registry_1 = require("./capability-registry");
+const docs_registry_1 = require("./docs-registry");
+const managed_sections_1 = require("./managed-sections");
+function createProtocolMigrationReport(input) {
+    const issues = [];
+    const actions = [];
+    const profile = input.profile ?? detectProfile(input.projectRoot);
+    const detection = detectMigrationState(input.projectRoot, profile, input.taskId);
+    if (input.taskId) {
+        planTaskScopedMigration(input, actions, issues);
+    }
+    else {
+        planProjectScopedMigration(input.projectRoot, profile, actions, issues);
+    }
+    const beforeHash = createPlanHash(actions);
+    if (input.mode === 'execute' && beforeHash)
+        validateBeforeHash(input.beforeHash, beforeHash, issues);
+    if (input.mode === 'execute' && issues.every((issue) => issue.severity !== 'error')) {
+        applyMigrationActions(input.projectRoot, actions, issues);
+    }
+    return {
+        schemaVersion: 'hadara.protocol.migration.v1',
+        command: 'protocol.migrate',
+        ok: issues.every((issue) => issue.severity !== 'error'),
+        mode: input.mode,
+        target: { protocolVersion: input.target },
+        scope: { kind: input.taskId ? 'task' : 'project', taskId: input.taskId ?? null },
+        projectRoot: input.projectRoot,
+        detection,
+        summary: {
+            planned: actions.filter((action) => action.status === 'planned').length,
+            changed: actions.filter((action) => action.status === 'created' || action.status === 'updated').length,
+            skipped: actions.filter((action) => action.status === 'skipped').length,
+            beforeHash
+        },
+        actions,
+        issues
+    };
+}
+function planProjectScopedMigration(projectRoot, profile, actions, issues) {
+    planWrite(projectRoot, actions, 'protocol-version', '.hadara/protocol-version.json', JSON.stringify({
+        schemaVersion: 'hadara.protocol.version.v1',
+        protocolVersion: '0.3.0',
+        source: 'protocol.migrate'
+    }, null, 2) + '\n', 'Record the project protocol version marker for 0.3.0 migration.');
+    const seed = (0, docs_registry_1.createSeedDocumentRegistry)(profile);
+    const registry = mergeExistingRegistry(projectRoot, seed, issues);
+    planWrite(projectRoot, actions, 'docs-registry-json', docs_registry_1.DOCS_REGISTRY_PATH, (0, docs_registry_1.registryJson)(registry), 'Insert or update the 0.3 docs registry seed.');
+    planWrite(projectRoot, actions, 'doc-registry-markdown', 'docs/DOC_REGISTRY.md', (0, docs_registry_1.renderDocRegistryMarkdown)(registry), 'Create managed docs registry Markdown summary.');
+    planWrite(projectRoot, actions, 'command-surface-doc', 'docs/COMMAND_SURFACE.md', renderCommandSurfaceDoc(), 'Create command surface documentation from the command registry.');
+    const sopAfterRows = planRequiredReadingRows(projectRoot, actions, issues);
+    planSopRequiredReadingMarkers(projectRoot, actions, issues, sopAfterRows);
+}
+function planTaskScopedMigration(input, actions, issues) {
+    const task = (0, task_capsule_1.listTaskCapsules)(input.projectRoot).find((candidate) => candidate.id === input.taskId);
+    if (!task) {
+        issues.push({ severity: 'error', code: 'PROTOCOL_MIGRATION_TASK_NOT_FOUND', message: `Task Capsule not found: ${input.taskId}` });
+        return;
+    }
+    const relativeTaskPath = toPortablePath(node_path_1.default.relative(input.projectRoot, task.dir));
+    planEnsureMissingFile(input.projectRoot, actions, 'task-evidence-jsonl', `${relativeTaskPath}/evidence.jsonl`, `Create missing evidence JSONL index for ${task.id}.`, `${relativeTaskPath}/evidence.jsonl already exists; protocol migration preserves existing evidence history.`);
+    planTaskStatusHistoryMarkers(input.projectRoot, `${relativeTaskPath}/TASK.md`, actions, issues);
+}
+function mergeExistingRegistry(projectRoot, seed, issues) {
+    const registryPath = node_path_1.default.join(projectRoot, docs_registry_1.DOCS_REGISTRY_PATH);
+    if (!node_fs_1.default.existsSync(registryPath))
+        return seed;
+    try {
+        const existing = JSON.parse(node_fs_1.default.readFileSync(registryPath, 'utf8'));
+        const existingPaths = new Set(existing.documents.map((doc) => doc.path));
+        const missing = seed.documents.filter((doc) => !existingPaths.has(doc.path));
+        return {
+            ...existing,
+            schemaVersion: 'hadara.docs.registry.v1',
+            registryVersion: Math.max(existing.registryVersion ?? 1, seed.registryVersion),
+            projectProfile: seed.projectProfile,
+            documents: [...existing.documents, ...missing]
+        };
+    }
+    catch (error) {
+        issues.push({
+            severity: 'warning',
+            code: 'PROTOCOL_MIGRATION_REGISTRY_INVALID_JSON',
+            path: docs_registry_1.DOCS_REGISTRY_PATH,
+            message: `Existing docs registry could not be parsed and would be replaced by the ${seed.projectProfile} seed: ${error instanceof Error ? error.message : String(error)}`
+        });
+        return seed;
+    }
+}
+function planRequiredReadingRows(projectRoot, actions, issues) {
+    const relativePath = 'docs/IMPLEMENTATION_SOP.md';
+    const current = readIfExists(node_path_1.default.join(projectRoot, relativePath));
+    if (!current) {
+        actions.push({ id: 'required-reading-cleanup', path: relativePath, status: 'skipped', summary: `${relativePath} is missing; Required Reading cleanup skipped.` });
+        return null;
+    }
+    if (!current.includes('| Document | When to Read | Purpose |')) {
+        issues.push({ severity: 'warning', code: 'PROTOCOL_MIGRATION_REQUIRED_READING_TABLE_MISSING', path: relativePath, message: 'SOP Required Reading table was not found.' });
+        actions.push({ id: 'required-reading-cleanup', path: relativePath, status: 'skipped', summary: `${relativePath} has no canonical Required Reading table.` });
+        return null;
+    }
+    let next = current;
+    const rows = [
+        ['`docs/DOC_REGISTRY.md`', 'Docs governance or migration work', 'Readable projection of the 0.3 document registry.'],
+        ['`docs/COMMAND_SURFACE.md`', 'Command surface, lifecycle, or migration work', 'Registry-backed command portfolio and lifecycle entry points.']
+    ];
+    for (const row of rows) {
+        if (!next.includes(row[0]))
+            next = insertTableRow(next, '| Document | When to Read | Purpose |', formatTableRow(row));
+    }
+    if (next === current) {
+        actions.push({ id: 'required-reading-cleanup', path: relativePath, status: 'skipped', summary: `${relativePath} already includes 0.3 docs governance rows.` });
+        return current;
+    }
+    addPlannedAction(actions, {
+        id: 'required-reading-cleanup',
+        path: relativePath,
+        before: current,
+        after: next,
+        expectedBeforeExists: true
+    }, 'Add 0.3 docs governance rows to SOP Required Reading.');
+    return next;
+}
+function planSopRequiredReadingMarkers(projectRoot, actions, issues, plannedBase) {
+    const relativePath = 'docs/IMPLEMENTATION_SOP.md';
+    const current = plannedBase ?? readIfExists(node_path_1.default.join(projectRoot, relativePath));
+    if (!current || current.includes('hadara:managed:start required-reading')) {
+        actions.push({
+            id: 'managed-required-reading-marker',
+            path: relativePath,
+            status: 'skipped',
+            summary: current ? `${relativePath} already has a managed Required Reading marker.` : `${relativePath} is missing; managed marker skipped.`
+        });
+        return;
+    }
+    const replaced = wrapContiguousTable(current, '| Document | When to Read | Purpose |', 'required-reading', {
+        schema: 'hadara.managedSection.v1',
+        owner: 'protocol.migrate',
+        kind: 'markdown-table',
+        mode: 'insert-row',
+        version: 1,
+        required: true,
+        closeSourceRole: 'included'
+    });
+    if (!replaced) {
+        issues.push({ severity: 'warning', code: 'PROTOCOL_MIGRATION_MANAGED_MARKER_UNSUPPORTED', path: relativePath, message: 'Could not safely wrap the SOP Required Reading table in managed markers.' });
+        actions.push({ id: 'managed-required-reading-marker', path: relativePath, status: 'skipped', summary: `${relativePath} Required Reading table could not be safely wrapped.` });
+        return;
+    }
+    addPlannedAction(actions, {
+        id: 'managed-required-reading-marker',
+        path: relativePath,
+        before: current,
+        after: replaced,
+        expectedBeforeExists: true
+    }, 'Insert managed section markers around SOP Required Reading.');
+}
+function planTaskStatusHistoryMarkers(projectRoot, relativePath, actions, issues) {
+    const current = readIfExists(node_path_1.default.join(projectRoot, relativePath));
+    if (!current) {
+        actions.push({ id: 'task-status-history-marker', path: relativePath, status: 'skipped', summary: `${relativePath} is missing.` });
+        return;
+    }
+    if (current.includes('hadara:managed:start task-status-history')) {
+        actions.push({ id: 'task-status-history-marker', path: relativePath, status: 'skipped', summary: `${relativePath} already has managed task status history markers.` });
+        return;
+    }
+    const replaced = wrapContiguousTable(current, '| Time | Status | Reason | Evidence |', 'task-status-history', {
+        schema: 'hadara.managedSection.v1',
+        owner: 'task.finish',
+        kind: 'markdown-table',
+        mode: 'update-row',
+        version: 1,
+        required: true,
+        closeSourceRole: 'included'
+    });
+    if (!replaced) {
+        issues.push({ severity: 'warning', code: 'PROTOCOL_MIGRATION_TASK_STATUS_TABLE_MISSING', path: relativePath, message: 'Could not find the Task Status History table to wrap.' });
+        actions.push({ id: 'task-status-history-marker', path: relativePath, status: 'skipped', summary: `${relativePath} has no canonical status-history table.` });
+        return;
+    }
+    addPlannedAction(actions, {
+        id: 'task-status-history-marker',
+        path: relativePath,
+        before: current,
+        after: replaced,
+        expectedBeforeExists: true
+    }, 'Insert managed section markers around task status history.');
+}
+function planWrite(projectRoot, actions, id, relativePath, content, summary) {
+    const absolutePath = node_path_1.default.join(projectRoot, relativePath);
+    const exists = node_fs_1.default.existsSync(absolutePath);
+    const current = readIfExists(absolutePath);
+    if (exists && current === content) {
+        actions.push({ id, path: relativePath, status: 'skipped', summary: `${relativePath} already matches the 0.3 migration output.` });
+        return;
+    }
+    addPlannedAction(actions, {
+        id,
+        path: relativePath,
+        before: current,
+        after: content,
+        expectedBeforeExists: exists
+    }, summary);
+}
+function planEnsureMissingFile(projectRoot, actions, id, relativePath, createSummary, existsSummary) {
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, relativePath))) {
+        actions.push({ id, path: relativePath, status: 'skipped', summary: existsSummary });
+        return;
+    }
+    addPlannedAction(actions, {
+        id,
+        path: relativePath,
+        before: '',
+        after: '',
+        expectedBeforeExists: false
+    }, createSummary);
+}
+function addPlannedAction(actions, write, summary) {
+    actions.push({
+        id: write.id,
+        path: write.path,
+        status: 'planned',
+        summary,
+        before: write.before,
+        after: write.after,
+        expectedBeforeExists: write.expectedBeforeExists,
+        expectedBeforeHash: hashContent(write.before),
+        afterHash: hashContent(write.after)
+    });
+}
+function applyMigrationActions(projectRoot, actions, issues) {
+    for (const action of actions) {
+        if (action.status !== 'planned' || action.after === undefined || action.expectedBeforeHash === undefined)
+            continue;
+        const absolutePath = node_path_1.default.join(projectRoot, action.path);
+        const currentExists = node_fs_1.default.existsSync(absolutePath);
+        const current = readIfExists(absolutePath);
+        if (currentExists !== (action.expectedBeforeExists ?? false) || hashContent(current) !== action.expectedBeforeHash) {
+            action.status = 'skipped';
+            issues.push({ severity: 'error', code: 'PROTOCOL_MIGRATION_WRITE_CONFLICT', path: action.path, message: `${action.path} changed after dry-run planning; rerun migration dry-run.` });
+            continue;
+        }
+        const tmp = node_path_1.default.join(node_path_1.default.dirname(absolutePath), `.hadara-migrate-${process.pid}-${Date.now()}-${node_path_1.default.basename(absolutePath)}`);
+        try {
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(absolutePath), { recursive: true });
+            node_fs_1.default.writeFileSync(tmp, action.after, { encoding: 'utf8', flag: 'wx' });
+            node_fs_1.default.renameSync(tmp, absolutePath);
+            action.status = currentExists ? 'updated' : 'created';
+        }
+        catch (error) {
+            if (node_fs_1.default.existsSync(tmp))
+                node_fs_1.default.rmSync(tmp, { force: true });
+            action.status = 'skipped';
+            issues.push({ severity: 'error', code: 'PROTOCOL_MIGRATION_ATOMIC_WRITE_FAILED', path: action.path, message: `Could not write ${action.path}: ${error instanceof Error ? error.message : String(error)}` });
+        }
+    }
+}
+function validateBeforeHash(beforeHash, expected, issues) {
+    if (!beforeHash) {
+        issues.push({ severity: 'error', code: 'PROTOCOL_MIGRATION_BEFORE_HASH_REQUIRED', message: `Execute mode requires --before-hash ${expected} from the reviewed dry-run report.` });
+    }
+    else if (beforeHash !== expected) {
+        issues.push({ severity: 'error', code: 'PROTOCOL_MIGRATION_BEFORE_HASH_MISMATCH', message: 'The supplied --before-hash does not match the current migration plan; rerun dry-run.' });
+    }
+}
+function detectMigrationState(projectRoot, profile, taskId) {
+    const registryPresent = node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, docs_registry_1.DOCS_REGISTRY_PATH));
+    const registryValid = registryPresent && canParseJson(node_path_1.default.join(projectRoot, docs_registry_1.DOCS_REGISTRY_PATH));
+    const commandSurfaceDocPresent = node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, 'docs/COMMAND_SURFACE.md'));
+    const sop = readIfExists(node_path_1.default.join(projectRoot, 'docs/IMPLEMENTATION_SOP.md'));
+    const requiredReadingManaged = sop.includes('hadara:managed:start required-reading');
+    const managedSectionsPresent = ['docs/TASK_BOARD.md', 'docs/PROJECT_STATE.md', 'docs/AGENT_HANDOFF.md', 'docs/IMPLEMENTATION_SOP.md', 'docs/DOC_REGISTRY.md']
+        .some((target) => readIfExists(node_path_1.default.join(projectRoot, target)).includes('hadara:managed:start'));
+    const taskCapsulePresent = taskId ? (0, task_capsule_1.listTaskCapsules)(projectRoot).some((candidate) => candidate.id === taskId) : null;
+    const migratedSignals = [registryPresent, registryValid, commandSurfaceDocPresent, requiredReadingManaged, managedSectionsPresent].filter(Boolean).length;
+    const scaffoldGeneration = migratedSignals >= 4 ? '0.3' : migratedSignals > 0 ? 'partial-0.3' : node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, 'AGENTS.md')) ? 'pre-0.3' : 'unknown';
+    return {
+        scaffoldGeneration,
+        profile,
+        docsRegistryPresent: registryPresent,
+        docsRegistryValid: registryValid,
+        commandSurfaceDocPresent,
+        requiredReadingManaged,
+        managedSectionsPresent,
+        taskCapsulePresent
+    };
+}
+function detectProfile(projectRoot) {
+    const state = readIfExists(node_path_1.default.join(projectRoot, 'docs/PROJECT_STATE.md'));
+    const declared = state.match(/\|\s*HADARA Profile\s*\|\s*(basic|standard|governed|hadara-dev)\s*\|/)?.[1];
+    if (declared === 'basic' || declared === 'standard' || declared === 'governed' || declared === 'hadara-dev')
+        return declared;
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, 'docs/SECURITY_MODEL.md')))
+        return 'governed';
+    if (node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, 'docs/ARCHITECTURE.md')))
+        return 'standard';
+    return 'basic';
+}
+function renderCommandSurfaceDoc() {
+    const rows = capability_registry_1.HADARA_COMMAND_REGISTRY
+        .filter((entry) => entry.canonical && entry.status === 'stable')
+        .map((entry) => formatTableRow([
+        `\`${entry.id}\``,
+        `\`${entry.command.replace(/\|/g, '/')}\``,
+        entry.family,
+        entry.requiredness,
+        entry.writeBoundary
+    ]));
+    const table = ['| ID | Command | Family | Requiredness | Write Boundary |', '|---|---|---|---|---|', ...rows].join('\n');
+    return [
+        '# COMMAND_SURFACE',
+        '',
+        'This document is generated from the HADARA command registry by `hadara protocol migrate`.',
+        '',
+        (0, managed_sections_1.managedSectionBlock)('command-surface-registry', {
+            schema: 'hadara.managedSection.v1',
+            owner: 'protocol.migrate',
+            kind: 'markdown-table',
+            mode: 'replace',
+            version: 1,
+            required: true,
+            closeSourceRole: 'included'
+        }, table),
+        ''
+    ].join('\n');
+}
+function wrapContiguousTable(content, header, sectionId, metadata) {
+    const lines = content.split('\n');
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start < 0)
+        return null;
+    let end = start;
+    while (end < lines.length && lines[end].startsWith('|'))
+        end += 1;
+    const body = lines.slice(start, end).join('\n');
+    const block = (0, managed_sections_1.managedSectionBlock)(sectionId, metadata, body);
+    lines.splice(start, end - start, ...block.split('\n'));
+    return lines.join('\n');
+}
+function insertTableRow(content, header, row) {
+    const lines = content.split('\n');
+    const headerIndex = lines.findIndex((line) => line.trim() === header);
+    if (headerIndex < 0)
+        return content;
+    let insertAt = headerIndex + 2;
+    while (insertAt < lines.length && lines[insertAt].startsWith('|'))
+        insertAt += 1;
+    lines.splice(insertAt, 0, row);
+    return lines.join('\n');
+}
+function formatTableRow(cells) {
+    return `| ${cells.map((cell) => cell.replace(/\|/g, '/')).join(' | ')} |`;
+}
+function createPlanHash(actions) {
+    const planned = actions
+        .filter((action) => action.status === 'planned')
+        .map((action) => ({
+        id: action.id,
+        path: action.path,
+        expectedBeforeExists: action.expectedBeforeExists ?? null,
+        expectedBeforeHash: action.expectedBeforeHash ?? null,
+        afterHash: action.afterHash ?? null
+    }));
+    if (planned.length === 0)
+        return null;
+    return hashContent(JSON.stringify(planned));
+}
+function hashContent(content) {
+    return node_crypto_1.default.createHash('sha256').update(content).digest('hex');
+}
+function readIfExists(absolutePath) {
+    return node_fs_1.default.existsSync(absolutePath) ? node_fs_1.default.readFileSync(absolutePath, 'utf8') : '';
+}
+function canParseJson(absolutePath) {
+    try {
+        JSON.parse(node_fs_1.default.readFileSync(absolutePath, 'utf8'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toPortablePath(value) {
+    return value.replace(/\\/g, '/');
+}

package/dist/services/release-artifact.js

@@ -30,11 +30,11 @@ const RELEASE_PACKAGE_KEYWORDS = [
 ];
 const RELEASE_PACKAGE_REPOSITORY = {
     type: 'git',
-    url: 'git+https://github.com/ictseoyoungmin/HADARA-dev.git'
+    url: 'git+https://github.com/ictseoyoungmin/HADARA.git'
 };
-const RELEASE_PACKAGE_HOMEPAGE = 'https://github.com/ictseoyoungmin/HADARA-dev#readme';
+const RELEASE_PACKAGE_HOMEPAGE = 'https://github.com/ictseoyoungmin/HADARA#readme';
 const RELEASE_PACKAGE_BUGS = {
-    url: 'https://github.com/ictseoyoungmin/HADARA-dev/issues'
+    url: 'https://github.com/ictseoyoungmin/HADARA/issues'
 };
 const requiredFiles = ['package.json', 'README.md', 'LICENSE', 'dist/cli/main.js'];
 const allowedRoots = ['dist/', 'README.md', 'LICENSE', 'package.json'];

package/dist/task/task-finish.js

@@ -418,6 +418,13 @@ function appendStatusHistoryDone(content) {
     const prefix = content.slice(0, start);
     const suffix = content.slice(end);
     const row = `| ${new Date().toISOString().slice(0, 10)} | Done | Finished task capsule. | \`hadara task finish --execute\` |`;
+    const managedEnd = '<!-- hadara:managed:end task-status-history -->';
+    const managedEndIndex = section.indexOf(managedEnd);
+    if (managedEndIndex >= 0) {
+        const beforeMarker = section.slice(0, managedEndIndex).replace(/[ \t\r\n]+$/, '');
+        const afterMarker = section.slice(managedEndIndex);
+        return `${prefix}${beforeMarker}\n${row}\n${afterMarker}${suffix}`;
+    }
     const separator = section.endsWith('\n') ? '' : '\n';
     return `${prefix}${section}${separator}${row}\n${suffix}`;
 }

package/package.json

@@ -1,9 +1,33 @@
 {
   "name": "hadara",
-  "version": "0.3.0-rc.0",
+  "version": "0.3.0-rc.1",
   "private": false,
   "license": "MIT",
-  "description": "HADARA: portable agentic development workbench",
+  "description": "Portable AI-assisted development workbench for evidence-backed task capsules, handoffs, and release gates.",
+  "keywords": [
+    "ai",
+    "agent",
+    "agents",
+    "coding-agent",
+    "developer-tools",
+    "cli",
+    "workflow",
+    "automation",
+    "task-management",
+    "evidence",
+    "handoff",
+    "release-management",
+    "mcp",
+    "hadara"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ictseoyoungmin/HADARA.git"
+  },
+  "homepage": "https://github.com/ictseoyoungmin/HADARA#readme",
+  "bugs": {
+    "url": "https://github.com/ictseoyoungmin/HADARA/issues"
+  },
   "bin": {
     "hadara": "./dist/cli/main.js"
   },