enginery 0.1.0__tar.gz

enginery-0.1.0/.approval_tests_temp/.gitignore

@@ -0,0 +1 @@
+*

enginery-0.1.0/.approval_tests_temp/approve_all.py

@@ -0,0 +1,72 @@
+#! /usr/bin/env python3
+
+##########
+# to run:
+#   python approve_all.py
+# more at:
+#   https://github.com/approvals/ApprovalTests.CommonScripts/blob/main/docs/how_to/run.md
+##########
+
+import pathlib
+from typing import Callable, List, Tuple
+
+SCRIPT_DIR = pathlib.Path(__file__).parent
+
+
+def load_failed_comparisons() -> List[str]:
+    return (SCRIPT_DIR / ".failed_comparison.log").read_text().splitlines()
+
+
+def move(a: str, b: str) -> None:
+    pathlib.Path(a).replace(b)
+
+
+def approve_all(
+    failed_comparison_loader: Callable[[], List[str]] = load_failed_comparisons,
+    mover: Callable[[str, str], None] = move,
+    system_out: Callable[[str], None] = print,
+) -> None:
+    failures = []
+    successes = []
+    failed_comparisons = failed_comparison_loader()
+    for line in failed_comparisons:
+        from_, to = line.split(" -> ")  # rename these
+        try:
+            mover(from_, to)
+            successes.append(pathlib.Path(to))
+        except Exception as e:
+            failures.append((pathlib.Path(to), str(e)))
+    report(failed_comparisons, failures, successes, system_out)
+
+
+def report(
+    failed_comparisons: List[str],
+    failures: List[Tuple[pathlib.Path, str]],
+    successes: List[pathlib.Path],
+    system_out: Callable[[str], None],
+) -> None:
+    if len(failed_comparisons) == 1:
+        system_out("Mismatched file found.")
+    elif len(failed_comparisons) == 0:
+        system_out("No mismatched files found.")
+
+    else:
+        system_out("Mismatched files found.")
+    if len(successes):
+        system_out("Updating:")
+        for approved_file in successes:
+            system_out(f"  - {approved_file.name}")
+    if len(failures):
+        system_out("Failed to update:")
+        for approved_file, reason in failures:
+            system_out(f"  - {approved_file.name}")
+            system_out(f"    Reason: {reason}")
+    system_out("")
+    if len(successes) == 1:
+        system_out("Approved 1 file.")
+    else:
+        system_out(f"Approved {len(successes)} files.")
+
+
+if __name__ == "__main__":
+    approve_all()

enginery-0.1.0/.approval_tests_temp/remove_abandoned_files.py

@@ -0,0 +1,94 @@
+#! /usr/bin/env python3
+
+##########
+# to run:
+#   python remove_abandoned_files.py
+# more at:
+#   https://github.com/approvals/ApprovalTests.CommonScripts/blob/main/docs/how_to/run.md
+##########
+
+from enum import Enum
+from pathlib import Path
+from typing import Callable, List
+
+SCRIPT_DIR = Path(__file__).parent
+
+
+class Mode(Enum):
+    DELETE_WITHOUT_PROMPTING = 1
+    PROMPT = 2
+    DRY_RUN = 3
+
+
+def delete_file(path: Path) -> None:
+    path.unlink(missing_ok=True)
+
+
+def load_touched_files() -> List[str]:
+    return (SCRIPT_DIR / ".approved_files.log").read_text().splitlines()
+
+
+def get_all_approved_files() -> List[str]:
+    return list(map(str, SCRIPT_DIR.parent.rglob("*.approved.*")))
+
+
+def remove_abandoned_files(
+    *,
+    mode: Mode,
+    load_touched_files: Callable[[], List[str]] = load_touched_files,
+    get_all_approved_files: Callable[[], List[str]] = get_all_approved_files,
+    delete: Callable[[Path], None] = delete_file,
+    system_out: Callable[[str], None] = print,
+    get_input: Callable[[], str] = input,
+) -> None:
+    touched_files = [Path(file).as_posix() for file in load_touched_files()]
+    all_approved_files = [Path(file).as_posix() for file in get_all_approved_files()]
+
+    stray_files = [
+        Path(file) for file in all_approved_files if file not in touched_files
+    ]
+    report_dry_run(system_out, stray_files)
+
+    if len(stray_files) and should_delete(mode, system_out, get_input):
+        for stray_file in stray_files:
+            delete(stray_file)
+        report_final_status(system_out, stray_files)
+    else:
+        system_out("No files were deleted.")
+
+
+def should_delete(
+    mode: Mode, system_out: Callable[[str], None], get_input: Callable[[], str] = input
+) -> bool:
+    if mode == Mode.PROMPT:
+        system_out("Delete? [Y/n]")
+        response = get_input()
+        return response in ["Y", "y", ""]
+    elif mode == Mode.DELETE_WITHOUT_PROMPTING:
+        return True
+    elif mode == Mode.DRY_RUN:
+        return False
+
+    return False
+
+
+def report_dry_run(system_out: Callable[[str], None], stray_files: List[Path]) -> None:
+    if not len(stray_files):
+        system_out("No unused `.approved.` files found.\n")
+        return
+
+    system_out("Unused `.approved.` files found.\n")
+
+    for stray_file in stray_files:
+        system_out(f" - {stray_file.name} (in {stray_file.parent.as_posix()}/)")
+
+
+def report_final_status(
+    system_out: Callable[[str], None], stray_files: List[Path]
+) -> None:
+    system_out("")
+    system_out(f"Deleted {len(stray_files)} files.")
+
+
+if __name__ == "__main__":
+    remove_abandoned_files(mode=Mode.PROMPT)

enginery-0.1.0/.archex/index.meta

@@ -0,0 +1 @@
+{"cache_key": "53243fc5019d45df30d4da01c89d5d6612874ef655da32e0ed5b4f7edeb6a6fa", "created_at": "1784494872.124852", "resolved_commit": "6ef46dba88be597fe8cb37ed7e03fa7923b5464a", "source_identity": "/Users/druk/WorkSpace/AetherForge/Enginery", "stable_identity": ""}

enginery-0.1.0/.archex/metadata.json

@@ -0,0 +1,4 @@
+{
+  "archex_version": "0.19.1",
+  "created_at": "2026-07-15T02:12:52.998778+00:00"
+}

enginery-0.1.0/.archex/settings.toml

@@ -0,0 +1,16 @@
+[project]
+mode = "local"
+
+[index]
+cache_dir = ".archex"
+languages = []
+vector = false
+splade = false
+module_prefilter = false
+delta_threshold = 0.5
+
+[dogfood]
+tasks_dir = "benchmarks/tasks"
+output_dir = ".archex/dogfood"
+default_task_prefix = "archex_"
+strategies = ["raw_files", "raw_grepped", "archex_query"]

enginery-0.1.0/.claude/anatomy.md

@@ -0,0 +1,23 @@
+# Project Anatomy
+
+Auto-generated file index. One line per file with description and token estimate.
+
+docs/analysis.md                                   | analysis.md                                                  | ~6865 tokens
+.docs/02_PRODUCT_DIRECTION.md                      | 02_PRODUCT_DIRECTION.md                                      | ~4192 tokens
+.docs/DEVELOPMENT_PLAN.md                          | DEVELOPMENT_PLAN.md                                          | ~12318 tokens
+.docs/EXECUTION_PROMPTS.md                         | EXECUTION_PROMPTS.md                                         | ~19915 tokens
+docs/strategy.md                                   | strategy.md                                                  | ~1751 tokens
+```
+.gitignore                                         | .gitignore                                                   | ~1157 tokens
+docs/design.md                                     | design.md                                                    | ~8503 tokens
+docs/overview.md                                   | overview.md                                                  | ~5426 tokens
+docs/pitch.md                                      | pitch.md                                                     | ~4636 tokens
+docs/workflows.md                                  | workflows.md                                                 | ~4405 tokens
+LICENSE                                            | LICENSE                                                      | ~2839 tokens
+README.md                                          | README.md                                                    | ~71 tokens
+docs/analysis.md                                   | analysis.md                                                  | ~6865 tokens
+.docs/02_PRODUCT_DIRECTION.md                      | 02_PRODUCT_DIRECTION.md                                      | ~4192 tokens
+.docs/DEVELOPMENT_PLAN.md                          | DEVELOPMENT_PLAN.md                                          | ~12318 tokens
+.docs/EXECUTION_PROMPTS.md                         | EXECUTION_PROMPTS.md                                         | ~19915 tokens
+docs/strategy.md                                   | strategy.md                                                  | ~1751 tokens
+```

enginery-0.1.0/.docs/01_VIDEO_ANALYSIS.md

@@ -0,0 +1,314 @@
+# Video Analysis: Agentic Engineering Beyond Loops
+
+**Source:** [“FORGET Loop Engineering. Agentic Engineering is about THIS”](https://www.youtube.com/watch?v=VQy50fuxI34) by IndyDevDan  
+**Video date:** 2026-07-13  
+**Analysis date:** 2026-07-13  
+**Duration:** 34:18
+
+## 1. Scope and method
+
+This analysis uses the English transcript and video metadata. It does not independently reconstruct every diagram or on-screen visual. Automatic captions contain transcription errors, including “conbon” for Kanban and corrupted product or harness names. Technical conclusions below use the surrounding context rather than preserving obvious caption errors.
+
+The analysis separates:
+
+1. claims made in the video;
+2. deductions needed to turn those claims into an engineering system;
+3. limitations and risks not resolved by the video.
+
+## 2. Executive summary
+
+The video rejects “loop engineering” as an adequate name for AI-assisted software development. Its actual thesis is that engineering teams should build **AI developer workflows** and eventually **software factories** that combine three actors:
+
+- engineers;
+- agents;
+- deterministic code.
+
+The engineer’s highest-leverage work moves from directly changing the product to designing and improving the system that produces product changes. A ticket enters the factory, a router selects an appropriate workflow, the system creates isolated execution environments, agents and deterministic checks perform the work, failures route into bounded repair, and human review remains at policy-defined boundaries.
+
+The loop is only one control-flow primitive. A production workflow also needs routing, branching, parallelism, state, isolation, validation, escalation, human authority, cost control, recovery, and termination.
+
+The video’s strongest idea is “building the system that builds the system.” Its main omission is governance of that meta-system. It does not define how workflow changes are versioned, evaluated, promoted, observed, or rolled back. A complete agentic engineering product must add that governed self-improvement mechanism.
+
+## 3. Core claims
+
+### 3.1 Three actors create engineering value
+
+At [03:39](https://www.youtube.com/watch?v=VQy50fuxI34&t=219s), the video identifies engineers, agents, and code as the three actors of engineering value creation. Agentic engineering means placing each actor at the correct point in the workflow.
+
+The allocation rule implied by the video:
+
+| Actor | Best suited to | Weakness to manage |
+|---|---|---|
+| Engineer | intent, accountability, judgment, exception handling, final authority | scarce attention and throughput |
+| Agent | interpretation, planning, synthesis, implementation, diagnosis, review | probabilistic output, context sensitivity, variable cost |
+| Deterministic code | parsing, calculation, validation, state transitions, repeatable operations | limited to behavior that can be specified |
+
+The video explicitly reminds viewers that code is fast, repeatable, and free of token cost. This matters because agent-heavy systems often ask a model to rediscover facts that a program could compute reliably.
+
+### 3.2 The useful unit is a workflow, not a loop
+
+At [06:40](https://www.youtube.com/watch?v=VQy50fuxI34&t=400s), the video acknowledges the test-and-repair loop but argues that more is happening around it. At [22:52](https://www.youtube.com/watch?v=VQy50fuxI34&t=1372s), it states directly that the target is an AI developer workflow.
+
+A loop describes repetition:
+
+```text
+build -> test -> repair -> test -> ...
+```
+
+A workflow describes the complete information and authority flow:
+
+```text
+intake -> qualify -> classify -> route -> isolate -> plan -> execute
+       -> validate -> repair or escalate -> review -> deliver -> observe
+```
+
+The distinction is substantive. A workflow can contain loops, but also branches, joins, human gates, failure terminals, external side effects, and multiple execution actors.
+
+### 3.3 Humans constrain the beginning and end
+
+At [28:10](https://www.youtube.com/watch?v=VQy50fuxI34&t=1690s), the video frames planning and review as the two human constraints around an increasingly autonomous middle.
+
+This should not be interpreted as “humans always approve exactly twice.” The stronger engineering interpretation is:
+
+- humans establish or approve intent where policy requires it;
+- humans retain authority over outcomes and exceptions;
+- low-risk intermediate work can execute without attention;
+- additional human gates appear when risk, ambiguity, missing evidence, or external authority requires them.
+
+A fixed human-at-the-start-and-end pattern is too coarse for production incidents, deployments, security-sensitive changes, or workflow self-modification.
+
+### 3.4 Tickets become factory inputs
+
+At [19:33](https://www.youtube.com/watch?v=VQy50fuxI34&t=1173s), the illustrative factory begins when a Kanban ticket lands:
+
+1. mark the ticket in progress;
+2. route the work;
+3. inspect the codebase and determine the required workflow;
+4. create an isolated execution environment;
+5. choose models and agent roles appropriate to work type, price, performance, and speed;
+6. build;
+7. run lint and CI/CD;
+8. review under the applicable human policy;
+9. ship or escalate.
+
+The video distinguishes chores, features, and hotfixes. It argues against using the most expensive multi-agent workflow for every task.
+
+### 3.5 Sandboxes enable scale
+
+At [20:01](https://www.youtube.com/watch?v=VQy50fuxI34&t=1201s), the video places sandbox creation before execution. It later describes multiple agents racing independently toward a production fix.
+
+The useful requirement is not “run many agents.” It is:
+
+- isolate concurrent work;
+- bind each attempt to explicit inputs;
+- prevent workspace collisions;
+- collect comparable evidence;
+- cancel losing or invalid attempts;
+- reconcile only selected outputs.
+
+A git worktree provides workspace separation but not hostile-process containment. A production system must state which guarantee its backend actually provides.
+
+### 3.6 Route work by risk, cost, and required quality
+
+At [20:28](https://www.youtube.com/watch?v=VQy50fuxI34&t=1228s), the video describes selecting different workflows and model roles for a chore, feature, or hotfix. A workhorse model may implement, while stronger planners or scouts protect against missing important context.
+
+This implies a router that considers more than ticket type:
+
+- risk;
+- ambiguity;
+- affected surface;
+- required evidence;
+- urgency;
+- reversibility;
+- model and compute budget;
+- human authority;
+- repository policy;
+- historical performance of candidate workflows.
+
+Routing itself must be explainable and versioned. Otherwise workflow selection becomes an unreviewable agent judgment.
+
+### 3.7 Engineers move to the agentic layer
+
+At [22:16](https://www.youtube.com/watch?v=VQy50fuxI34&t=1336s), the video calls the central thesis “building the system that builds the system.” The engineer works increasingly on the agentic layer rather than directly on the application layer.
+
+The defensible version of this claim is not that strong engineers never touch product code. It is that their compounding effort goes into reusable production machinery:
+
+- context acquisition;
+- routing;
+- workflow definitions;
+- prompts and skills;
+- deterministic validators;
+- policies;
+- evidence contracts;
+- provider integrations;
+- evaluation sets;
+- recovery procedures.
+
+Direct product work remains necessary for novel, poorly understood, or high-risk changes. Those cases also teach the factory what it cannot yet automate.
+
+### 3.8 Start manually, then extract the stable workflow
+
+At [28:40](https://www.youtube.com/watch?v=VQy50fuxI34&t=1720s), the video recommends starting with simple skill-based workflows and personally stepping through every node. Once productionizing, stable code should be separated from skills so information flow and guardrails become explicit.
+
+This is a critical anti-premature-automation rule:
+
+1. perform the workflow with agent assistance;
+2. observe real transitions and exceptions;
+3. identify repeatable behavior;
+4. encode repeatable behavior in deterministic code;
+5. retain agent judgment only where ambiguity remains;
+6. validate the automated workflow against real cases.
+
+Automation designed before observing the work encodes assumptions instead of operations.
+
+## 4. Conceptual workflow reconstructed from the video
+
+```mermaid
+flowchart LR
+    Intent[Human or organizational intent] --> Ticket[Ticket or work item]
+    Ticket --> Qualify[Qualify and normalize]
+    Qualify --> Router[Factory router]
+    Router --> Workspace[Create isolated workspace]
+    Workspace --> Workflow[Select AI developer workflow]
+    Workflow --> Agents[Agent execution]
+    Workflow --> Code[Deterministic operations]
+    Agents --> Validate[Validation]
+    Code --> Validate
+    Validate -->|repairable failure| Agents
+    Validate -->|insufficient context or authority| Human[Human decision]
+    Validate -->|pass| Review[Engineering or policy review]
+    Review -->|approve| Deliver[PR, release, or deployment]
+    Review -->|revise| Agents
+    Deliver --> Outcome[Observe outcome]
+```
+
+The video explicitly covers the flow through delivery. A complete system must add the outcome-to-factory-change path described in Section 6.
+
+## 5. What the video gets right
+
+### 5.1 It restores deterministic software to agentic systems
+
+The industry often treats every workflow step as a prompt. The video correctly treats ordinary code as a first-class actor. This reduces cost, variance, and context load.
+
+### 5.2 It shifts attention from prompts to systems
+
+A strong prompt cannot compensate for missing state, weak validation, unsafe permissions, stale CI, ambiguous external side effects, or absent rollback. Workflow engineering addresses the complete operating environment.
+
+### 5.3 It recognizes workload-specific orchestration
+
+A chore, feature, release, and incident differ in urgency, uncertainty, evidence, and authority. Routing them through different workflows is more important than optimizing one generic agent loop.
+
+### 5.4 It treats compute as scalable but not uniform
+
+Parallel agents and sandboxes can trade compute for speed or confidence. The video also notes that expensive workflows should not be used indiscriminately.
+
+### 5.5 It identifies meta-engineering as the compounding layer
+
+Reusable improvements to the factory affect every future work item. This creates compounding returns unavailable from one-off prompt or code changes.
+
+## 6. Missing requirements needed for a complete system
+
+### 6.1 Durable state
+
+The video uses diagrams as if nodes transition reliably, but does not define what happens when the coordinator, agent, machine, or external provider fails. The workflow needs persistent state independent of conversation history.
+
+### 6.2 Evidence contracts
+
+“Tests pass” is not enough. A system must bind evidence to the exact repository revision, workflow version, environment, and policy decision. Stale green CI cannot approve a newer commit.
+
+### 6.3 Idempotency and reconciliation
+
+Opening a PR, merging, publishing, and deploying are non-idempotent external actions. If a process loses the response after performing an action, it must inspect the external system before retrying.
+
+### 6.4 Policy-scoped autonomy
+
+The video anticipates dropping human review as confidence grows. A safe implementation must grant autonomy per action and risk class, not through a global auto mode.
+
+### 6.5 Security and credential boundaries
+
+An isolated workspace does not automatically protect the host or production systems. Credentials require explicit scope, policy, redaction, and expiry.
+
+### 6.6 Workflow and asset versioning
+
+Changing a prompt, router, model, skill, validator, or policy can change outcomes. Runs must bind exact versions so regressions can be traced and prior behavior replayed.
+
+### 6.7 Outcome observation
+
+A PR can pass every check and still create an escaped defect. Workflow completion and real-world outcome must remain distinct.
+
+### 6.8 Evaluation against comparable cohorts
+
+Factory improvements require baseline-versus-candidate comparison across compatible work. One aggregate success score invites metric gaming and selection bias.
+
+### 6.9 Governed self-improvement
+
+The system that builds the system must not mutate active behavior online. It should:
+
+1. observe recurring failures and interventions;
+2. form a falsifiable improvement hypothesis;
+3. create a candidate factory-asset version;
+4. replay historical and adversarial cases;
+5. compare candidate and baseline;
+6. reject safety or evidence regressions;
+7. request approval;
+8. canary the candidate;
+9. promote or roll back.
+
+This is the missing mechanism that turns the video’s philosophy into an accountable engineering system.
+
+## 7. Risks in taking the rhetoric literally
+
+### 7.1 “The best teams never touch the product”
+
+Taken literally, this disconnects factory designers from novel product behavior and user feedback. The useful interpretation is that repeated direct work should become workflow capability, while unfamiliar work remains a source of learning.
+
+### 7.2 “Knowing the system works so well you do not have to look”
+
+Trust must come from observable, version-bound evidence and outcome monitoring. Absence of human attention is not proof of reliability.
+
+### 7.3 Parallel agents racing for the first answer
+
+The fastest output is not necessarily the safest or best output. Selection must use evidence and declared objectives. Parallelism also increases cost and correlated failure when workers share the same assumptions.
+
+### 7.4 Zero-touch execution
+
+Zero-touch should be an earned property of specific low-risk actions under measured workflow versions. It should not be a product-wide operating mode.
+
+### 7.5 “Sandbox” as a security claim
+
+Worktrees isolate changes, not processes. Containers improve containment but still require secrets, egress, kernel, and supply-chain controls. Every backend must state its guarantees precisely.
+
+## 8. Implications for the product
+
+The product derived from this philosophy should own:
+
+- normalized work intake;
+- workflow definition and routing;
+- durable state;
+- workspace lifecycle;
+- agent-harness coordination;
+- deterministic execution;
+- evidence collection and verification;
+- policy decisions;
+- human interventions;
+- external side-effect reconciliation;
+- outcome tracking;
+- factory-change evaluation and promotion.
+
+It should delegate actual coding-agent behavior, issue-tracker UX, source hosting, CI execution, release destinations, and deployment platforms through adapters.
+
+The resulting product, Enginery, is an agentic engineering control plane, not a prompt collection and not a coding agent.
+
+## 9. Relationship to companion documents
+
+- [`02_PRODUCT_DIRECTION.md`](02_PRODUCT_DIRECTION.md) records the repository and product-boundary decision.
+- [`03_SYSTEM_DESIGN.md`](03_SYSTEM_DESIGN.md) specifies the approved architecture, domain model, policies, workflows, and acceptance criteria.
+
+## 10. Source links
+
+- [Video](https://www.youtube.com/watch?v=VQy50fuxI34)
+- [Ticket and software-factory example, 19:33](https://www.youtube.com/watch?v=VQy50fuxI34&t=1173s)
+- [“Building the system that builds the system,” 22:16](https://www.youtube.com/watch?v=VQy50fuxI34&t=1336s)
+- [Workflow rather than loop, 22:52](https://www.youtube.com/watch?v=VQy50fuxI34&t=1372s)
+- [Planning and review boundaries, 28:10](https://www.youtube.com/watch?v=VQy50fuxI34&t=1690s)
+- [Start with skills and extract deterministic code, 28:40](https://www.youtube.com/watch?v=VQy50fuxI34&t=1720s)