CHANGELOG.json

{
    "index": [
        "summary",
        "entries"
    ],
    "content": {
        "summary": "SocratexAI pipeline product changelog.",
        "entries": [
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "script_fallback",
                "change": "Added script fallback discipline and runtime status detection."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "roi_bias",
                "change": "Added ROI Bias and ROI Picks for review, planning, finish, and recommendation workflows."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "project_profile",
                "change": "Added Project Profile Interview and profile-aware known-solutions filtering."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "branch_scoped_workflow",
                "change": "Added branch-scoped mode with committed directives and local prompt-language branch memory under ignored/ai-socratex."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "post_setup_activation",
                "change": "Added explicit activation handoff so agents switch to installed SOCRATEX.md after setup, import, migration, or update."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "activation_check",
                "change": "Added first-prompt activation verification to confirm installed rules, communication format, emoji rules, and workflow-specific rules are loaded."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "update_protocol",
                "change": "Added an explicit pipeline update protocol so agents resolve update source, run the correct updater, audit, and reactivate the installed pipeline."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "removal_protocol",
                "change": "Added a bounded remover script and removal protocol so agents uninstall SocratexAI through tooling instead of manual deletion."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "task_work_tracking",
                "change": "Added broad-task micro-task tracking and structured JSON document movement discipline."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "json_agent_docs",
                "change": "Migrated durable agent-facing pipeline documents from Markdown to JSON while keeping public docs, adapter entrypoints, and scratch templates in Markdown."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "reinitialization_and_changelog_config",
                "change": "Added changelog opt-in configuration, missing-only reinitialization, and update flow support for newly introduced initialized artifacts."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "legacy-shell_first_setup",
                "change": "Added legacy shell-first setup guidance, runtime metadata, and an install helper with unsupported-platform fallback recommendations."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "non_code_json_and_known_solutions",
                "change": "Switched standardized non-code project memory to JSON and added explicit known-solutions, borrowed-practices guidance for non-code packs."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "epistemic_skeptic_profile",
                "change": "Added an optional truth-first discussion communication profile with skepticism, evidence separation, confidence levels, tables when useful, and validate-criticize-advise ordering."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "non_code_tool_first_json",
                "change": "Extended tool-first JSON discipline to non-code project packs and shared project memory workflows."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "non_code_user_facing_markdown",
                "change": "Restored Markdown for non-code user-facing state, plan, backlog, decision, issue, journal, review, todo, bug, and changelog templates while keeping agent-only files in JSON."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-28",
                "feature": "docs_role_index",
                "change": "Added DOCS.json templates and installation rules so agents use a document role index before reading, creating, renaming, or updating project documents."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-29",
                "feature": "git_batch_finishers",
                "change": "Added git-derived batch task finalization with finish_task normalization/cache/index refresh, a finish_subtask commit/push wrapper, commit_task compatibility delegation, and LF-stable document cache writes."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "pipeline_featurelist_update_guard",
                "change": "Added a pipeline feature-list guard that runs only for pipeline-owned changes. Hooked the guard into check_task.py and run_final_task_checks.py so changes under tools/core/project/templates/adapters require pipeline_featurelist.json updates. Kept ordinary project-task paths out of the guard so normal work does not need feature-list edits. Why: Pipeline improvements should update the feature manifest, while ordinary project work should not be burdened by source-pipeline bookkeeping."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "ignored_directory_gitignore_contract",
                "change": "Added /ignored/ to source .gitignore and audit coverage so ignored pipeline working files remain outside version control. Why: The pipeline contract is that ignored/ is local working memory, not versioned project state."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "author_metadata",
                "change": "Added SocratexDevSolutions as the public SocratexPipeline author in README and LICENSE metadata. Why: Public pipeline distribution should identify the author/owner clearly without embedding personal identity references in reusable pipeline sources."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "self_describing_learning_issues",
                "change": "Expanded prefilled GitHub learning issues with self-contained instructions. Added issue fields for what AI learned, changed scripts or files, reporter notes, tool behavior, and maintainer promotion steps. Updated source feature list, update protocol, and recommendation docs for self-describing learning intake. Why: Learning issues should be understandable without attachments and should tell maintainers exactly what to review and how to promote reusable features."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "prefilled_github_issue_learning_intake",
                "change": "Replaced token-based GitHub Issue publishing with a no-token prefilled GitHub Issue URL workflow. Added open_pipeline_learning_issue.py as the only supported public network intake path for pipeline improvement reports. Marked local learning/inbox JSON reports as ignored working artifacts and updated protocol, recommendation, audit, and source feature IDs. Why: Public pipeline improvement intake should not require embedded write credentials or a hosted endpoint."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "github_issue_learning_inbox",
                "change": "Added structured pipeline learning reports for project feature intake. Added GitHub Issue publisher that creates or updates one SocratexPipeline Learning Inbox issue and skips duplicate reports by hash. Updated update protocol, agent contract, audit coverage, source feature list, and recommendation docs for GitHub-Issue-based learning intake. Why: Cross-project pipeline learning needs a durable network inbox that agents can read later without spamming separate notifications."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "pipeline_featurelist_sync_and_learning",
                "change": "Added sync_pipeline_featurelist.py to generate installed project pipeline_featurelist.json files with same/missing/extra comparison against the installed source manifest. Added learn_pipeline_features.py so the source pipeline can inspect feature IDs from any project and selectively add reusable non-project-specific features to the canonical source manifest. Hooked pipeline featurelist sync into initialization, import, update, and reinitialization flows so new and refreshed projects get instance-style comparison manifests automatically. Updated update protocol and agent contract so SocratexPipeline learns reusable features from instances first, then propagates them through future updates. Why: SocratexPipeline should learn reusable pipeline behavior from any project instance and then teach other projects through the canonical source feature list and sync flow."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "semantic_pipeline_feature_ids",
                "change": "Expanded source pipeline_featurelist.json with semantic capability IDs for future-first steering, DDD-ADIV, borrowed-before-invented, script-first execution, automation repair before manual recovery, and evidence-driven debugging. Why: The source manifest should define canonical pipeline behavior, not only canonical tools."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "compact_pipeline_featurelist",
                "change": "Simplified pipeline_featurelist.json to a source-only canonical feature-id list with no project-instance references or redundant descriptions. Why: SocratexPipeline is the source pipeline and should not know about any specific instance that consumes it."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "generic_done_and_doctor_pipeline",
                "change": "Added generic tools/repo/finalize_task_check_commit_push.py, tools/repo/check_toolchain_health.py, UTF-8 write helpers, and check_utf8_writes.py to the source pipeline. Updated code workflow, Git rules, command docs, pack instructions, and agent contract so Git-backed code work closes through tools/repo/finalize_task_check_commit_push.py and repeatable finalizer failures are fixed in tooling. Updated pipeline_featurelist.json so reusable features are source-owned while project-specific helpers remain outside the reusable source pipeline. Why: Reusable pipeline improvements should live in SocratexPipeline, while only project/domain-specific domain-specific automation should remain in its owning project."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-04-30",
                "feature": "pipeline_featurelist_manifest",
                "change": "Added root pipeline_featurelist.json to track source pipeline features and compare them against installed child projects. Updated changelog helper to support CHANGELOG.json entries instead of assuming Markdown changelog format. Why: Source pipeline upgrades need a machine-readable feature manifest and a working changelog writer for JSON changelog files."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-01",
                "feature": "priority_workflow_and_team_roles",
                "change": "Added reusable WORKFLOW.json and on-demand team role templates for product, technical, performance, experience, and pipeline review. Hooked them into initialization, import, reinitialization, DOCS templates, code workflow routing, agent contract, README, public bootstrap, and pipeline_featurelist.json. Why: Long-running Codex workspaces need owner-written priority steering and role-specific review lenses without loading every role as default context."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-01",
                "feature": "compiled_agent_instruction_layer",
                "change": "Added generated AI-compiled Codex instructions, a recompile command, a drift check, finalizer integration, audit coverage, README/bootstrap guidance, and feature-list tracking. Why: Human-editable source instructions and agent-optimized runtime instructions need separate layers so Codex can start from compact, English, ordered context without making generated files a second source of truth."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-01",
                "feature": "manual_codex_workspace_eval_framework",
                "change": "Added a manual eval framework for comparing baseline Codex behavior against with-pipeline behavior across priority conflict handling, low-friction adoption, on-demand team lenses, finalizer discipline, document ownership, compiled instruction handling, and three-tier user fit. Added a structural eval checker, README guidance, quality-gate entry, audit coverage, and feature-list tracking. Why: SocratexPipeline needs reusable validation artifacts so maintainers and users can check whether packaged best practices create observable behavior improvements instead of only describing a good workflow."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-01",
                "feature": "private_working_memory_cache_boundary",
                "change": "Excluded ignored/ private working files from generated document cache indexing and added audit coverage so local pitch, planning, scratch, and private strategy files cannot leak into tracked cache artifacts. Why: Public SocratexPipeline users should be able to update from Git without receiving maintainer-private working material."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "context_tagged_knowledge_prelude",
                "change": "Added tools/knowledge/context_tags.py and a workflow rule requiring substantive commands and questions to derive prompt tags, query compiled knowledge notes, and load relevant context before answer or execution. Why: Compiled knowledge should actively route ordinary agent work instead of only serving broad startup or manual tag queries."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "code_task_engineering_context_loader",
                "change": "Added tools/knowledge/knowledge_code_context.py as the canonical source-pipeline helper for loading code-task engineering standards. The helper checks compiled knowledge freshness, returns the engineering/coding/architecture rule slice, supports optional named views, keeps JSON output parseable, and falls back to compiled JSON knowledge files when SQLite select fails. Why: Code-quality preload should be a scriptable workflow primitive, not a long command agents must reconstruct from memory."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "code_task_engineering_standards_preload",
                "change": "Added code-task engineering standards preload as a source pipeline feature. Code workflow now requires agents to load compiled engineering, coding, and architecture rules before implementation, refactor, bugfix, or code review work, and tools/knowledge/knowledge_code_context.py provides a canonical wrapper with SQLite check, broad rule selection, optional named views, and JSON-file fallback support. Why: Professional code work should keep project architecture, ownership, readability, diagnostics, verification, and best-practice rules active in context instead of relying on visible chat memory."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "knowledge_and_engineering_eval_coverage",
                "change": "Expanded the manual eval framework with scenarios for code engineering context preload, compiled knowledge freshness and fallback, knowledge entry lifecycle, and pipeline update artifact synchronization. Updated eval result placeholders, the eval checker, README scope, source feature list, and local baseline runbook prompts. Why: Recent knowledge-layer and engineering-context features need eval coverage before baseline and with-pipeline comparisons are meaningful."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "private_working_memory_knowledge_boundary",
                "change": "Excluded ignored/ private working files from compiled knowledge discovery and added audit coverage for generated knowledge manifest and file fallback tables. Why: local eval runs, pitch notes, scratch plans, and maintainer-private material must not leak into tracked AI-compiled knowledge artifacts used by public pipeline consumers."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "context_tagged_prelude_eval_coverage",
                "change": "Added eval coverage for the context-tagged knowledge prelude, including a public prompt, expected behaviors, result placeholders, checker registration, README scope update, source feature-list entry, and local baseline-runbook prompt. Why: Prompt-derived context tags are now a distinct pipeline promise and should be measured separately from broad engineering preload and knowledge freshness/fallback behavior."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "routing_eval_freeze",
                "change": "Promoted task-type routing and unknown-task workflow routing into the source code-project pack and workflow template, added final eval scenarios for those routing behaviors, and documented an eval freeze with a real-usage failure taxonomy. Why: The pipeline is moving from build-out to daily use, so eval coverage should focus on whole-workflow behavior and future eval additions should come from repeated real failures rather than every new implementation detail."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-02",
                "feature": "normalized_compiled_content_hashes",
                "change": "Changed compiled knowledge and compiled instruction freshness checks to use normalized text-content hashes instead of raw byte hashes. The normalized hash removes UTF-8 BOM, folds CRLF/CR to LF, trims trailing spaces and tabs per line, and ignores excess final blank lines while preserving indentation and interior whitespace. Why: compiled outputs should rebuild on meaningful source changes without false drift from line endings or editor cleanup, and timestamps or fully whitespace-stripped hashes are not safe enough for source freshness."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "cheap_idempotent_pipeline_update",
                "change": "Updated PUBLIC-BOOTSTRAP.md so raw-link setup documents the cheap Git update command as the default. Added FullVerify and ReinitializeNew as explicit opt-ins and records update_source/public_bootstrap_url in PIPELINE-CONFIG.json during setup. Why: Users who install from the public bootstrap link should receive the low-budget update path without needing a separate source-pipeline explanation."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "canonical_index_content_metadata_document_schema",
                "change": "Promoted index/content/metadata from a child-project convention into the canonical source pipeline feature manifest shape. Moved source pipeline_featurelist.json feature IDs under content.features and artifact contracts under content.feature_contracts with backward-compatible readers for older root manifests. Why: Feature comparison and synchronization should be a stable low-cost structured document operation, not a project-specific exception."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "legacy_feature_manifest_update_recovery",
                "change": "Preserve project-owned index/content/metadata featurelist shape during cheap child pipeline updates. Recover list-document output when target DOCS.json declares pipeline_featurelist.json as a canonical project document. Why: Old or partially updated child workspaces should update cheaply without manual manifest migration or losing local feature descriptions."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "cheap_idempotent_pipeline_update",
                "change": "Hardened featurelist learning and sync scripts to read both current root features manifests and older index/content instance manifests. This lets cheap updates recover older child projects instead of failing before replacing their root featurelist comparison file. Why: Old SocratexPipeline children may still have pre-v3 or project-shaped featurelists, so update intake must normalize them cheaply instead of assuming the newest schema."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "cheap_idempotent_pipeline_update",
                "change": "Made update_pipeline_from_link.py cheap by default: managed mirror, featurelist sync, directive refresh, and feature-contract check now run without rebuilding knowledge or full audit unless -FullVerify is passed. Added Auto/LocalPath/Zip/Git source modes with shallow Git clone support and documented Git as the preferred public update source. Updated feature contracts and script metadata so cheap update behavior is tracked as a synchronized source-to-child feature. Why: Low-limit child projects should be able to update old SocratexAI installs cheaply and predictably while preserving project-owned configuration and memory."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "feature_artifact_contracts",
                "change": "Added feature artifact contracts to pipeline_featurelist.json while preserving the compact features index for cheap comparison. Added check_pipeline_feature_contracts.py and wired it into audit/update guards so pipeline-owned changes must map to a feature contract. Updated feature learning and instance sync so upstream promotion requires contracts and instance extra-feature contracts are preserved. Why: Feature IDs alone allowed source and child pipelines to look synchronized while required scripts, catalogs, docs, templates, or cleanup logic could be missing."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "command_script_named_execution",
                "change": "Added the remaining recent command-script and workflow-cleanup improvements to the source feature manifest. Why: The feature manifest should reflect that commands now name execution scripts directly and WORKFLOW keeps current reusable rules instead of historical upgrade pass state."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "self_describing_script_name_catalog",
                "change": "Renamed ambiguous source-pipeline scripts to self-describing names and updated command, flow, workflow, pack, and documentation references to the new names. Why: The default SCRIPTS index is loaded without descriptions, so script names must be clear enough for agents to choose the right tool from the name alone."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-05",
                "feature": "json_tool_hardening_and_document_tools",
                "change": "Promoted child-project-proven JSON document tooling into the source pipeline, including list-style JSON read/edit wrappers, file/stdin value inputs for complex JSON payloads, SCRIPTS.json input/output contracts, and default tool-error hardening rules in WORKFLOW and ENGINEERING. Why: source-pipeline agents should fix repeatable script friction in the owning tool or contract instead of carrying fragile manual workarounds between projects."
            },
            {
                "date": "2026-05-05",
                "type": "feature",
                "feature": "categorized_tool_scripts",
                "change": "Moved source pipeline scripts from one flat tools directory into categorized tools/<category>/ folders and updated SCRIPTS.json, path references, templates, and compiled-context inputs to use the categorized paths. Why: the reusable pipeline should mirror the maintainable script ownership pattern already proven in a child project, while keeping a compact script index for agents."
            },
            {
                "date": "2026-05-05",
                "type": "feature",
                "feature": "managed_pipeline_package_mirror_sync",
                "change": "Added a managed package mirror sync for SocratexAI updates and imports. Child updates now remove obsolete files inside source-owned package paths before copying the new source package, so structural changes such as categorized tools are preserved instead of leaving stale flat files behind."
            },
            {
                "date": "2026-05-05",
                "type": "feature",
                "feature": "full_update_artifact_parity_contract",
                "change": "Documented full update parity as a source pipeline feature: feature promotion is not complete unless the required scripts, templates, general documents, compiled context inputs, and update/audit contracts are promoted with the feature ID."
            },
            {
                "date": "2026-05-05",
                "type": "feature",
                "feature": "managed_pipeline_root_catalog_sync",
                "change": "Extended managed package sync to include source root routing catalogs such as DOCS.json, WORKFLOW.json, COMMANDS.json, FLOWS.json, SCRIPTS.json, and CHANGELOG.json so installed child pipelines receive the full executable pipeline contract, not only tools and templates."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-06",
                "feature": "communication_profile_text_registry",
                "change": "Added core/communication-profiles/*.txt as the source of truth for communication profiles, with standard, epistemic, friendly, and teacher profiles plus setup/initializer discovery. Why: communication behavior should be editable as separate named text profiles instead of duplicated prose in scripts and contracts."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-06",
                "feature": "canonical_index_content_metadata_document_schema",
                "change": "Hardened PUBLIC-BOOTSTRAP.md and core/UPDATE-PROTOCOL.json so setup/update/upgrade agents must validate current file contracts before writing structured documents. Documented that canonical JSON list documents use index/content/metadata, index only mirrors content keys/titles, and plan/state/queue/catalog files are structured operational data rather than narrative prose. Added mandatory script-use guidance for upgrade work: run relevant document/feature-contract tooling or report blocked/degraded mode before claiming completion. Extended feature contracts so cheap update and canonical document schema cover FILE-FORMATS.json, json_list_doc.py, normalization, audit, and global-over-local enforcement. Why: A real pipeline update on another machine showed five failure modes: stale shape copying, skipped format contracts, skipped validation scripts, narrative treatment of plan/state files, and local settings overriding pipeline/global requirements."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-20",
                "feature": "predictable_load_lightweight_architecture",
                "change": "Added a global programming directive for predictable-load lightweight architecture: implementation, bugfix, log review, and performance diagnosis now check whether a behavior will scale by count/frequency/storage/I/O/runtime pressure and prefer data/query/batch/pool/prewarm helper contracts over heavyweight framework primitives as the default broad model. Also added template-parity workflow rules so reusable source-pipeline improvements update starter templates and feature contracts when future child projects should inherit the behavior. Why: predictable future load should be designed lightly from the start instead of relying on later expensive refactors or symptom micro-optimizations."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-20",
                "feature": "better_version_now_future_proof_engineering",
                "change": "Expanded the predictable-load directive into a broader better-version-now programming philosophy. Agents now check per task whether a modest upfront improvement should be made across clean code, DDD-ADIV, architecture, security, data ownership, contracts, migrations, diagnostics, verification, and performance; borrowed/proven patterns should be considered before invented systems, with an explicit overengineering check when the better version becomes large or speculative. Why: future-proofing should prevent known expensive refactors and debt repayment across all programming work, not only FPS-sensitive paths."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "pipeline_featurelist_instance_generation",
                "change": "Fixed sync_pipeline_featurelist.py so instance manifests preserve source feature_contracts in addition to local extra contracts. Why: Riftbound finalization exposed that feature IDs synced without their source contracts, causing artifact contract checks to fail after package sync."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "grouped_fragmented_task_state_handoff",
                "change": "Added grouped fragmented-task execution guidance and a grouped_task_handoff.py helper. Broad tasks can now be split into user-approved groups and bounded sub-tasks; sub-tasks inside an approved group can continue automatically through a durable handoff JSON and next-subtask prompt, with escalation rules for scope, product direction, verification failures, destructive/external actions, and incomplete handoff state. Why: large Codex tasks need external STATE/PLAN memory and automation between sub-tasks without forcing manual continue after every small fragment."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "borrowed_before_invented",
                "change": "Renamed the borrowed-before-bespoke directive wording and feature ID to borrowed-before-invented / borrowed-vs-invented in active source knowledge, helper tags, gates, and feature contracts. Why: The directive is about checking known borrowed solutions before inventing a custom one; 'invented' matches the user-facing concept better than 'bespoke'."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "directive_hierarchy_context_budget",
                "change": "Reclassified workflow, docs-workflow, DDD-ADIV, source-of-truth, research/web-research, borrowed-before-invented, and lightweight-futureproof knowledge entries as Tier 1 directives rather than Tier 2 content. Why: These entries are direction-setting reminders that should shape agent thinking before routed implementation content is selected."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "directive_hierarchy_context_budget",
                "change": "Added knowledge_tier_check.py and knowledge_tier_report.py so source and child projects can fail missing context_tier metadata mechanically and summarize knowledge entries by tier/category. Why: Full tier migrations need a repeatable checker instead of manual grep/counts, especially when child projects preserve local SocratexAI knowledge overrides."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "directive_hierarchy_context_budget",
                "change": "Completed the source knowledge-tier migration by adding explicit context_tier metadata to SocratexAI engineering knowledge entries and code starter template entries; updated the directive hierarchy feature contract so future tier queries rely on source metadata rather than compiler defaults. Why: Tiered context routing should be migration-tool-friendly and queryable from source JSON nodes, not inferred only during compilation."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "ai_native_code_contract_headers",
                "change": "Added the AI-native code contract header standard to ENGINEERING and the code template. Added a gamedev contextual action for applying the standard to runtime/gameplay/diagnostic/layer-boundary files. Added ai_native_contract_dry_run.py plus script and feature contracts so projects can plan per-system rollout without mass source rewrites. Why: Human/AI/hybrid code maintenance needs concise source ownership, diagnostic taxonomy, and layer-purity contracts, but broad rollout should be planned per system instead of adding stale boilerplate everywhere."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "task_flow_audit_closure",
                "change": "Hardened task_flow_audit.py with -ProjectRoot so installed child-project wrappers audit the child repository diff/changelog instead of the embedded SocratexAI package. Why: Riftbound wrapper dry-run exposed that the managed package script otherwise resolved its own package root and reported zero changed paths."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "task_flow_audit_closure",
                "change": "Added artifact-based task-flow closure audit as a reusable flow subroutine and repo script; final checks now print the checklist, including loaded route, selected flow, closure evidence, changelog truth, tool-failure response, and tool-vs-manual discipline. Complex/high-risk tasks now get a changelog-driven adversarial review prompt that checks whether the diff actually implements the changelog claim and whether verification or future-debt risk remains. Why: Task closure should be provable from artifacts instead of prose, while heavier adversarial review should stay conditional."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "profile_gated_better_version_now_directive",
                "change": "Made the better-version-now and predictable-load directives more generic and profile-gated. The global contract now avoids gamedev-specific wording, code workflow scales the directive by task size and project_profile, legacy/sunset/custom-framework surgical fixes are explicitly kept surgical, and gamedev/business/realtime examples live in profile-specific or code-pack guidance. Why: future-proofing should guide all programming work without causing legacy tickets or business CRUD changes to receive inappropriate gamedev-style architecture suggestions."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "sensitive_reference_leak_smoke",
                "change": "Added check_sensitive_reference_leaks.py to the source quality gate and script catalog, removed private project/person references from reusable pipeline sources, replaced private reference-project wording with neutral child-project/reference-project terminology, and renamed the maintainer-only reference upgrade script to upgrade_from_reference_project.py. Why: source pipeline artifacts should preserve reusable lessons without leaking private project names, personal identity references, or project-specific maintainer workflow names."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "foreign_legacy_code_communication_profile",
                "change": "Added core/communication-profiles/foreign_legacy_code.txt as a fifth communication profile alongside standard, epistemic, friendly, and teacher. Inherits epistemic baseline (1 thought per line, tables, certainty levels, validate-then-criticize-then-advise, no mirror, challenge assumptions) and adds three foreign/legacy-specific rules: business-storytelling end-of-task report, explicit unknown-unknown surfacing, and manual test scenarios for non-safe-auto-test paths. AGENT-CONTRACT.json communication_profiles listing updated. Why: epistemic style alone does not cover the storytelling layer needed for ticket comments and PR descriptions on foreign business code, nor does it forbid extrapolation from name conventions in absence of explicit specs."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-21",
                "feature": "foreign_legacy_business_work_model",
                "change": "Added a third work model alongside default code pack and SocratexGamedev: profiles/SocratexForeignLegacy/WORKFLOW.json. Targets foreign or legacy business codebases where the agent does not fully know the domain, the codebase is messy, and the user is the domain reviewer plus tester. Defines an 8-phase task lifecycle (Read, Decide, Plan, Implement, Report, Test, Joint Verification, Handoff), language- and company-agnostic, with business-storytelling end-of-task reports, explicit unknown-unknown surfacing, and manual test scenarios for what cannot be safely auto-tested. PR/ticket/deployment lifecycle stays user-owned. Why: legacy/foreign business work has a fundamentally different shape than greenfield code or gamedev — agent does not own domain knowledge or testing infrastructure, so the work model must front-load reading + planning, defer architecture decisions, and produce paste-ready handoff text instead of initiating shared-system writes."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "pipeline_package_json_format_exception",
                "change": "Listed PIPELINE-PACKAGE.json as an explicit generated direct-schema exception in JSON-FORMAT-CONTRACT.json and recorded the package-manifest exception in the canonical data-document feature contract. Why: Riftbound embedded audit showed the managed package manifest is generated operational data, not a canonical source document."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "json_format_contract_managed_package_sync",
                "change": "Added JSON-FORMAT-CONTRACT.json to managed package sync and pipeline-owned root path checks so installed child pipelines receive and enforce the canonical JSON format contract. Why: Riftbound update smoke failed because source feature contracts required the format contract inside the installed SocratexAI package, but the mirror sync did not copy it."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "canonical_data_document_templates",
                "change": "Canonicalized source changelog and starter JSON templates as index/content/metadata data documents, narrowed direct-schema exceptions to eval protocols, and made setup/import/changelog/workspace/task/design-context tooling canonical-aware. Why: Reusable pipeline upgrades should propagate stronger machine-readable templates to child projects instead of preserving flat starter schemas."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "knowledge_context_tier_hierarchy",
                "change": "Added explicit all-tiered success status to knowledge tier reports. Why: Pass 0I requires successful tier scans to say directly that every knowledge entry is tiered while preserving structured counts and exit-code behavior."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "feature_artifact_contracts",
                "change": "Skipped source_only required path and doc existence checks when validating installed child SocratexAI packages. Why: Child package updates remove source-only maintainer files such as TODO.md, so package checks should not require those source repo artifacts."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "ai_native_code_contract_headers",
                "change": "Excluded local toolchain and vendored runtime folders from ai_native_contract_dry_run.py candidates. Why: Pass 0H dry-run in Riftbound showed Tools/Python312 and python-installer files as false positives; rollout planning must focus on project-owned systems."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "pipeline_update_and_removal_protocols",
                "change": "Fixed existing-project import closure for fresh business/code projects: import_existing_project.py now builds the installed document cache before compiling knowledge, and compiles knowledge after the final imported PIPELINE-CONFIG.json is written. Why: child imports should immediately pass audit_docs and feature-contract checks without a manual cache/knowledge repair step."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "git_batch_finishers",
                "change": "Fixed installed child-project task checks and finalizers so package-owned tools resolve the target Git worktree separately from the installed SocratexAI package root. Normalization, changed-file discovery, line indexing, task snapshots, task-flow audit, output snapshots, and explicit quality commands now run against the child project root while still loading scripts from the package. Why: business/code child projects should be able to run check_task and finalizers without tools looking for project files inside SocratexAI/."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "changelog_oldest_first_contract",
                "change": "Standardized SocratexAI CHANGELOG.json as oldest-first and added audit/helper enforcement so JSON changelog entries are appended in chronological order. Why: The source pipeline should use one changelog ordering convention; oldest-first is easier to append and matches the project Markdown changelog policy."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-22",
                "feature": "continue_user_clarification_gate",
                "change": "Added CONTINUE-flow clarification checkpoint. Why: CONTINUE should not mean guessing through missing user information, product direction, or meaningful implementation choices."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "json_node_edit_tools",
                "change": "Added full-node-path JSON edit tooling with nested list operations, slash-separated paths for keys containing dots, wrapper help, and script-first JSON structural edit guidance. Why: Agents need a reliable way to reorder, move, delete, insert, and line-edit JSON nodes without manual structural patches."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "featurelist_behavior_contract_details",
                "change": "Clarified feature contracts for CONTINUE clarification checkpoints and script-first JSON structural edit tooling, including SCRIPTS metadata and workflow directive requirements. Why: The reusable feature list should preserve not only file presence but also the behavioral rules agents must follow."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "pipeline_sweep_upgrade_tool",
                "change": "Added a Python-first pipeline sweep runner with legacy shell wrapper, config template, catalog metadata, and feature contract for repeatable cross-project update/smoke sweeps. Why: Manual source-to-child upgrade sweeps were relying on agent memory instead of a reusable tool."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "python_first_pipeline_migration",
                "change": "Added Python-first runtime, update, managed-package sync, feature-contract, document-audit, compiled-context-anchor, tier-check, and featurelist-sync entrypoints, and moved pipeline_sweep.py to call Python smoke/update commands. Why: SocratexPipeline should not require a permanent legacy shell compatibility layer for update and smoke automation."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "python_first_audit_fallback",
                "change": "Made document audit prefer the Python compiled-context checker when it exists. Why: Installed child packages should use the Python-first smoke path instead of the old broad legacy shell freshness check during finalization."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "python_first_pipeline_migration_evidence",
                "change": "Tightened feature contracts so legacy shell-to-Python migration claims require successor/deferred mapping plus executed source and child smoke verification. Why: A reduced legacy shell reference count is not enough evidence that migrated tools behave correctly."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-23",
                "feature": "portable_json_tooling_pack",
                "change": "Moved generic JSON manipulation and JSON audit helpers into tools/json as a portable pack with a dedicated README and smoke test, and updated script catalog, feature contracts, workflow guidance, and quality-gate references. Why: JSON tooling should be easy to copy between projects and separate from higher-level document routing/cache workflow."
            },
            {
                "version": "0.2.0-alpha",
                "date": "2026-05-24",
                "feature": "license_metadata",
                "change": "Relicensed SocratexAI source distribution from MIT to Apache License 2.0. Added NOTICE with copyright attribution and MIT history boundary. Included NOTICE in managed package sync and feature contracts so child project updates receive current legal metadata. Why: Apache 2.0 matches the public adoption strategy for corporate users and adds an explicit patent grant while preserving earlier MIT forks under their original terms."
            },
            {
                "version": "1.1",
                "date": "2026-05-24",
                "feature": "public_portfolio_release",
                "change": "Prepared SocratexPipeline for public portfolio positioning as version 1.1. Updated README positioning around legacy-code AI workflows, source provenance, human-owned lifecycle, feature contracts, managed updates, and the public bootstrap link. Removed the pre-launch donation placeholder from README. Why: The repository is now intended to function as a public project, portfolio artifact, and adoption surface rather than a private internal pipeline snapshot."
            },
            {
                "version": "1.1",
                "date": "2026-07-11",
                "feature": "memory_mode_selection",
                "change": "Add workflow.memory_mode axis: project_scoped vs task_scoped Why: Ticket-driven deploy-and-forget work has no durable project home; a per-project DECISIONS.json fragments per ticket and dies on archive, so durable knowledge (decisions, rationale, constraints, READ-FIRST gotchas) must fold into the unit STATE. project_scoped keeps the full memory model with a project decision log and end-of-unit promotion. New project/code/MEMORY-MODE.json contract; conditional core/MEMORY-MODEL.json; per-profile defaults (BusinessDev=task_scoped, Gamedev=project_scoped)."
            },
            {
                "version": "1.1",
                "date": "2026-07-13",
                "feature": "socratex_business_dev_work_profile",
                "change": "Add SocratexBusinessDev work profile: the main company- and language-agnostic 'how to do things' router (single WORKFLOW.json — task-type router, per-flow reminders, shared engineering capsules). foreign_legacy_code becomes its communication subprofile. Retire the SocratexForeignLegacy 8-phase work model (removed profiles/SocratexForeignLegacy/ and the foreign_legacy_business_work_model feature contract); its lifecycle and behavioral rules were migrated verbatim into SocratexBusinessDev (content.lifecycle, content.workflow_handoff) and the eng_* capsules, and into foreign_legacy_code.txt. Why: one source of truth for how to work on business dev, instead of rules scattered across CLAUDE.md, workflow files, and agent memory."
            }
        ]
    },
    "metadata": {
        "schema": "socratex-data-document/v1",
        "title": "Changelog",
        "role": "Source pipeline changelog registry."
    }
}